fimil-pentest-core 0.4.0

Open-source agent loop, validator, and payload library for Fimil's autonomous pentest engine.

fimil-pentest-core

Open-source agent core and payload library for Fimil's autonomous pentest engine.

What this is

This package ships the deployment-config-free subset of the Fimil pentest engine:

• Marker allocation (fimil_pentest_core.markers) — cryptographic, run-scoped markers for deterministic exploit validation.
• Payload library (fimil_pentest_core.payloads) — a Pydantic-validated YAML schema and ~125 curated payloads across fifteen vectors covering the OWASP Top 10 baseline plus the Aikido-superset Phase 5 vectors:
  • OWASP Top 10 baseline (v0.1.x): XSS, SQLi, SSRF, IDOR, authz, mass-assignment, prompt-injection (chat + structured)
  • Phase 5 superset (v0.3.0): SSTI (Jinja2 / Twig / Freemarker / Velocity / ERB), LDAP injection, XPath injection, XXE, command injection, path traversal, JWT attacks, insecure deserialization
• SSTI engine fingerprint table (fimil_pentest_core.payloads.ssti.engines.yaml) — per-engine differential probes for the validator's engine-detection layer. Source-of-truth for the §13 decision 14 spec commitment.

The host application — Fimil-dev/fimil — provides everything else: the LLM agent loop, the deterministic validator, the scope guard (DNS pinning + IP allowlist + kill-switch), the redaction layer, and the persistence repositories.

Install

pip install fimil-pentest-core

Quickstart

import uuid
from fimil_pentest_core import markers, load_all_payloads

# 1) Allocate a fresh marker for a run.
run_id = uuid.uuid4()
policy_snapshot = {"oob_base_url": "https://oob.example.com"}
marker, oob_url = markers.allocate(run_id, policy_snapshot)
# marker == "<8-hex-prefix>.<128-bit-hex>"
# oob_url == "https://oob.example.com/<marker>"

# 2) Load the curated payload library.
all_payloads = load_all_payloads()
# {'xss': [...], 'sqli': [...], 'ssrf': [...], ...}

xss_payloads = all_payloads["xss"]
for entry in xss_payloads:
    print(entry.id, entry.template, entry.severity)

Schema

Each payload YAML is validated by PayloadEntry:

vector: xss
id: script-tag-injection
template: "<script>alert({{marker}})</script>"
applies_to:
  methods: [GET, POST]
  param_hints: [q, search, query, message]
expected_signal: xss_executable
severity: high
references: [CWE-79, OWASP-A03]

Five model validators enforce hard constraints at load time:

• SSRF baked-URL guard — any SSRF template containing http://, file://, gopher://, or a numeric IPv4 literal fails to load. Only {{oob_url}} substitution is permitted.
• XXE / insecure_deserialization OOB-only guard — mirrors the SSRF rule. Well-known XML namespace URIs (W3C, SOAP, OOXML, OASIS, OpenGIS) are scrubbed before scanning so they don't trip the no-baked-URL guard.
• Command-injection metacharacter whitelist — payload templates may contain only the curated set ;|&`$() plus alphanumerics / spaces / ._/-\. Baked-in IPs and URL schemes outside {{oob_url}} are rejected.
• SSTI engine field requirement — vector: ssti payloads must declare which engine they target.
• Boolean-differential pair requirement — expected_signal ending in _boolean_diff (SQLi, LDAP, XPath) requires a paired negative_template so the validator can run the differential.

Vector taxonomy

Vector	OWASP	CWE	Validator type
xss	A03:2021	CWE-79	Parse-tree executable-context match
sqli	A03:2021	CWE-89	Boolean / time-based differential
ssrf	A10:2021	CWE-918	OOB callback within window
idor	A01:2021	CWE-639	Cross-account session three-signal
authz	A01:2021	CWE-285	Cross-account PII differential
mass_assignment	A08:2021	CWE-915	Read-back persistence
prompt_injection	LLM01	CWE-1427	Chat refusal differential / structured schema violation
ssti	A03:2021	CWE-1336	Per-engine differential math-eval (5 engines)
ldap	A03:2021	CWE-90	Boolean differential row-count
xpath	A03:2021	CWE-643	Boolean differential row-count
xxe	A05:2021	CWE-611	OOB callback within window
command_injection	A03:2021	CWE-78	OOB callback / time-delta
path_traversal	A01:2021	CWE-22	File-content fingerprint regex
jwt	A02:2021	CWE-347	alg-none / weak-HMAC / kid-injection
insecure_deserialization	A08:2021	CWE-502	OOB callback within window

License

Apache 2.0. See LICENSE.

Contributing

This is the open-source core; the host application is closed-source. Issues and PRs welcome for:

• New payloads (must include CWE/OWASP references and pass SSRF / SQLi schema constraints)
• Additional vectors (coordinate with Fimil-dev/fimil maintainers — host validators must land in lockstep)
• Schema improvements (PR with regression test)

Roadmap

• v0.1.x — payload library + markers
• v0.2.0 — extract agent_loop + validator from Fimil-dev/fimil (pending the AIP-4.4 PyPI cut-over per docs/operations/os-extraction-runbook.md §2.5 in the host repo)
• v0.3.0 — Phase 5 vector expansion: SSTI (5 engines), LDAP, XPath, XXE, command injection, path traversal, JWT, insecure deserialization (this release)
• v0.4.0+ — browser-driven testing primitives (Playwright tool wrapper)

See CHANGELOG.md for per-release detail and Fimil-dev/fimil issue tracker for upstream coordination.