How every piece works.

Architecture & data flow

Every scan runs one pipeline. Loaders turn a target into an Artifact; the rule engine produces findings; the policy turns findings into a verdict. Nothing is executed to be inspected.

The two rule kinds

Most detections are regex signatures — easy to audit and extend (adding one is usually a single compile_sig(...) call). Structural rules handle what regex can't: prompt-injection phrasing, invisible-Unicode and entropy analysis, permission overreach, and stateful baseline diffing.

The four defense tiers

Modelled on a real firewall's layered stack. The first three read artifacts and never execute them; the runtime tier controls what a running process can reach and say.

Commands & flags

Every command takes a directory, a single file, or a .zip. Exit codes: 0 allow/warn · 2 block · 1 error.

Common flags

# output & policy
--format text|json|sarif      # sarif → GitHub code-scanning
--policy <file>                # JSON/YAML policy file
--strict                      # block on MEDIUM and above
--fail-on <SEVERITY>           # custom block threshold
--ignore <RULE_ID>             # suppress a rule or category
--baseline <lock>             # diff against a pinned afw.lock

# trust & intel
--intel <path>                 # add IoC feeds (JSON or names/domains/hashes/signers .txt)
--no-intel                    # disable the bundled seed feed
--verify-signatures --identity <id>   # cryptographic provenance
--no-tighten-untrusted        # don't penalise unsigned artifacts

# runtime containment (afw run)
--allow <host>  --allow-port <n>  --allow-loopback
--isolate                     # kernel network namespace (zero-network)
--fail-on-egress              # exit non-zero if anything was blocked

Trust tiers

Each artifact gets a tier from the provenance the scanner can find. Low-trust artifacts are held to a stricter policy automatically (unless you pass --no-tighten-untrusted).

Policy & verdicts

Findings have a severity — INFO · LOW · MEDIUM · HIGH · CRITICAL — and the policy maps them to ALLOW, WARN or BLOCK. Default blocks on HIGH+.

# policy.yaml
block_severity: HIGH          # INFO | LOW | MEDIUM | HIGH | CRITICAL
warn_severity: LOW
ignore: [AFW-PERM-002]      # accept an expected finding
warn_only_categories: [install-hook]
tighten_untrusted: true      # stricter bar for unsigned/unpinned

Policy files are JSON or YAML (the simple schema needs no dependency; pip install AIAgentFirewall[yaml] for full YAML). Output formats: text (colourised), json (the ScanResult schema), sarif (code-scanning dashboards).

Detection catalogue

All 59 detections across 23 categories, each mapped to an industry framework. IDs ending in -* are structural rules that emit a family of findings; varies means severity depends on what's matched.

No detection matches that filter.

Framework glossary

Every finding cites at least one industry framework, so findings map to a language security teams already use.

Guardrails API (outbound)

Detection finds the deployed-agent bugs; agentfirewall.guardrails enforces the fix at request time. Zero-dependency, embeddable.

from agentfirewall.guardrails import (
    InputGuard, ScopePolicy, PreconditionGate, InMemoryQuota, taint,
)

# Confine the agent to its business tools; deny code exec.
guard = InputGuard(ScopePolicy.for_tools("search_menu", "place_order"))
# Reserve quota BEFORE the agent runs, idempotent by request id.
gate  = PreconditionGate(InMemoryQuota(balances={"user-1": 5}))

def handle_chat(user_id, prompt, request_id):
    guard.check_input(prompt).raise_if_blocked()
    return gate.run(user_id, lambda: agent.run(prompt),
                    idempotency_key=request_id)   # refresh can't replay

# Taint untrusted-derived data so it can't drive sensitive sinks.
retrieved = taint(vector_store.query(q))
guard.check_tool_call("send_email", {"body": retrieved}).raise_if_blocked()  # BLOCKED

Source docs & extending

The Markdown docs in the repo go deeper on internals and process.

Adding a detection

A regex detection is usually one line in agentfirewall/rules/signatures.py:

compile_sig(
    "AFW-NET-099", "Contacts my-bad-host", Severity.HIGH,
    r"my-bad-host\.example",
    "Reaches a known-bad host.",
    "Remove this network call.",
)

For non-regex logic, subclass Rule in rules/structural.py and register it. See CONTRIBUTING.md.