fimil-pentest-core 0.1.0

Open-source agent core + 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 39 curated payloads across seven vectors:
  • XSS (executable-context reflection)
  • SQLi (boolean and time-based)
  • SSRF ({{oob_url}}-substituted, IP-literal-forbidden)
  • IDOR (cross-account session swaps)
  • Authn/authz bypass (BOLA, vertical privilege escalation)
  • Mass-assignment (privilege flag injection)
  • Prompt-injection (chat differential refusal + structured JSON-schema violation)

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. Those modules will land here as v0.2.0 once the relevant Protocols (RunRepository, ScopeGuardProtocol, LLMProvider, Redactor) are extracted.

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]

Two 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.
• SQLi boolean differential — expected_signal: sqli_boolean_diff requires a paired negative_template (the false complement) 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

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 (this release)
• v0.2.0 — extract agent_loop + validator from Fimil-dev/fimil once RunRepository, ScopeGuardProtocol, LLMProvider, and Redactor Protocols land
• v0.3.0+ — browser-driven testing primitives (Playwright tool wrapper)

See Fimil-dev/fimil issue tracker for upstream coordination.