Layer 02 · Feature field guide

Every capability, and its trade-offs.

What each layer does, why it's needed, where you'd reach for it — and the honest limits. No feature here is described without what it costs you.

The mental model

Layered like a real firewall — default-deny where it counts.

Every scan runs the same pipeline: a target becomes an artifact, rules produce findings, and a policy turns findings into a verdict you can gate on. Nothing is executed to be scanned.

input
Target
dir · file · .zip
→
loaders
Artifact
files + declared tools
→
engine
Rules
signatures + structural
→
output
Findings
severity + framework refs
→
policy
Verdict
allow · warn · block

INBOUND Trust what you install

Inspect a third-party artifact before it runs, hold low-provenance sources to a stricter bar, catch silent rug-pull updates, and contain execution at the kernel level when you do run it.

OUTBOUND Harden what you deploy

An agent you ship can be abused by its own users — excessive agency, broken authorization. Scan your app for those classes, then enforce the fix at request time with an embeddable guardrail.

TIER 01 · STATIC

Pre-install inspection

Read the code, manifests and model-facing text without ever executing them — safe to point straight at untrusted content.

Static scanner & install gate

afw scan · verify · install ./artifact

Why it's needed. Most agents/skills come from strangers, like npm packages or browser extensions. You need to know what an artifact does before granting it your machine and your credentials.

Use cases
  • Vet a skill you downloaded before copying it into ~/.claude/skills
  • Gate installs so a BLOCK verdict refuses to copy the artifact
  • Fail a CI pipeline on any high-risk finding

Pros

  • Never executes code — safe on untrusted input
  • Fast, offline, zero required dependencies
  • Text / JSON / SARIF output; shell-friendly exit codes

Cons

  • Signature/heuristic based — a novel or heavily obfuscated payload can slip past
  • Can false-positive on legitimate but scary-looking code
  • Sees intent in text, not actual runtime behavior

Broad detection coverage

afw rules # 59 detections · 23 categories

Why it's needed. Attacks don't come in one shape. Coverage has to span credential theft, exfiltration, obfuscation, prompt injection, tool/memory poisoning, deserialization, typosquatting and more — under one policy.

Catches, among others
Secret & credential theft SEC Data exfiltration NET Obfuscation / dynamic exec OBF Prompt injection PI Tool poisoning TPZ Memory poisoning MEM Unsafe deserialization DES Hidden Unicode HID Typosquatting TYP Auto-fetch exfil NET-007

Pros

  • Wide, real-world-driven rule set out of the box
  • Adding a new signature is usually one line
  • Every finding cites its category and severity

Cons

  • Breadth is not completeness — new classes need new rules
  • More rules means more tuning to keep noise down
TIER 02 · STATEFUL

Rug-pull defense

The attack static scanning can't see on its own: an artifact that's clean today and malicious after an update. Pin what you approved, re-check every change.

Baseline pinning & drift detection

afw pin · verify --baseline afw.lock

Why it's needed. Supply-chain attacks ship clean and mutate later (the Postmark BCC incident, insider updates). A previously-approved tool whose permissions or description silently change is, by itself, the alarm — even with no known-bad signature.

Use cases
  • Approve a skill once, then diff every future update against the lock
  • Catch a new tool grant or mutated tool description after an "innocent" bump
  • Enforce "no silent permission creep" in a shared agent repo

Pros

  • Detects clean-then-malicious changes signatures miss
  • A permission/description change alone raises an alert
  • Purely local state — one afw.lock file

Cons

  • Only as good as the baseline you approved in the first place
  • Store the lock where the artifact can't rewrite it
  • Needs re-pin discipline after you review a legitimate diff

Web UI

afw serve --open # 127.0.0.1

Why it's needed. Not everyone lives in a terminal. A reviewer, a security lead, or a teammate should be able to drag-drop a folder and read the verdict, trust tier and evidence without learning a CLI.

Use cases
  • Hand a non-CLI teammate a way to vet an artifact
  • Quick visual triage of findings with evidence + remediation
  • Demo the tool without touching a shell

Pros

  • Loopback-only, token-protected JSON API
  • Nothing is uploaded or executed — runs entirely locally
  • Path-traversal-safe uploads

Cons

  • Local single-user by design — not a hosted service
  • Same detection limits as the CLI underneath
TIER 03 · PROVENANCE

Trust zones

Like a firewall's trust zones, treat unknown sources with more suspicion — assign each artifact a trust tier and match it against threat intel.

Trust tiers from provenance

UNTRUSTED · DECLARED · PINNED · VERIFIED

Why it's needed. An unsigned artifact from nowhere shouldn't get the same benefit of the doubt as one you've cryptographically verified. Risk-proportionate policy means low-trust artifacts clear a stricter bar automatically.

Use cases
  • Auto-tighten the block threshold for unsigned / unpinned artifacts
  • Verify a maintainer signature against an expected identity
  • Reward artifacts carrying an SBOM or attestation

Pros

  • Cheap signal that shapes policy without extra work
  • Optional cryptographic verification with --identity

Cons

  • Provenance detection isn't proof unless you verify signatures
  • A signed artifact can still be malicious — trust ≠ safety

Threat-intel / IoC feeds

afw scan --intel ./my-iocs/

Why it's needed. Some artifacts are already known-bad. Matching name, file hash, contacted domain and signer identity against indicator lists catches a threat you've seen before — without phoning home.

Use cases
  • Block artifacts whose hash or domain is on your blocklist
  • Flag a revoked or impersonated signer identity
  • Ship org-specific IoCs to every developer's machine

Pros

  • Fully offline — JSON or plain-text feeds, nothing leaves the box
  • Pluggable; auto-loads feeds from your config dir

Cons

  • Reactive by nature — only catches known-bad indicators
  • Only as current as the feeds you supply (seed is intentionally minimal)
TIER 04 · RUNTIME

Contain what runs

Static scanning can't stop a payload it didn't recognise. The runtime layer never needs to trust the code — it controls what the running process can reach and say.

Egress firewall + outbound DLP

afw run --allow "*.github.com" -- cmd

Why it's needed. The point of most malicious payloads is to phone out — to a webhook, a paste site, an attacker host. A default-deny egress allowlist turns "exfiltrate anywhere" into "reach nothing but what I approved."

Use cases
  • Run an untrusted agent that should only reach one API
  • Fail CI if a build step tries any off-allowlist connection
  • Block a plaintext request that carries a secret, even to an allowed host

Pros

  • Default-deny; everything off the allowlist gets a logged 403
  • --fail-on-egress for CI enforcement
  • Built-in DLP blocks secrets leaving in plaintext bodies

Cons

  • Proxy-based — only governs clients that honor HTTP(S)_PROXY
  • A raw socket that ignores the proxy bypasses it (use --isolate)
  • HTTPS bodies stay opaque to DLP

MCP tool-call proxy

afw mcp-proxy --action redact -- server

Why it's needed. An MCP server sits between your agent and real tools. It can hide directives in tool descriptions, siphon secrets in call arguments, or inject instructions in results. You want eyes on that JSON-RPC channel live.

Use cases
  • Inspect an unfamiliar MCP server's traffic in real time
  • Redact secrets in tool-call arguments instead of blocking
  • Block tool-poisoning descriptions before they reach the model

Pros

  • Catches poisoning, secret egress and injected results at the wire
  • Forward, redact or block per --action
  • Findings to stderr — stdout stays a clean JSON-RPC channel

Cons

  • Only covers servers you actually route through it
  • Adds a hop; can't inspect transports it doesn't sit on

Kernel network isolation

afw run --isolate -- bash setup.sh

Why it's needed. For an untrusted install hook, a proxy allowlist isn't enough — the script can open a raw socket. A kernel network namespace with no external interface means it physically cannot reach any host, even as root inside.

Use cases
  • Run a sketchy setup.sh with zero network, guaranteed
  • Execute build/postinstall hooks that shouldn't touch the net
  • Contain a tool you don't trust not to try raw sockets

Pros

  • Bypass-proof — no interface, so raw sockets fail too
  • Refuses to run rather than run unprotected
  • Pure unshare + stdlib; bubblewrap optional

Cons

  • Needs Linux namespace support (some locked-down CI can't)
  • Zero network breaks anything that legitimately needs it

Bypass-proof allowlisting

afw run --isolate --allow host -- cmd

Why it's needed. Sometimes you need both: reach exactly these hosts and nothing else, with no way to escape it. A no-IP namespace whose egress is brokered through a Unix-socket proxy gives allowlisting that a raw socket can't dodge.

Use cases
  • Let an untrusted agent reach one API and truly nothing else
  • Strongest containment for a tool you must run but can't trust
  • Hard-scope egress in a hostile-input pipeline

Pros

  • Kernel-enforced allowlist — a raw socket simply gets no network
  • A UDS crosses the namespace boundary; IP traffic can't
  • --fail-on-egress still applies

Cons

  • Linux / unshare only; more moving parts
  • An allowed host can still legitimately receive data
DIRECTION · OUTBOUND

Harden the agents you deploy

The other direction of trust: an agent you ship, abused by its own users. Scan your app for the classes that keep showing up in the wild — then actually enforce the fix.

Deployed-agent detections

afw scan ./my-agent-app

Why it's needed. Two real bugs recur: a bot with excessive agency (the "food-ordering bot runs Python" case) and broken authorization (the expensive call fires before the quota check — the Bolt.new refresh exploit). Catch them in your own code before you ship.

Use cases
  • Flag a chatbot that will run arbitrary code or has no topic scope
  • Flag a model invoked before the credit/authz check (TOCTOU)
  • Flag a limit enforced only client-side

Pros

  • Maps to OWASP LLM06, CWE-367 TOCTOU, API BFLA
  • Runs in the same scan/CI flow as inbound checks

Cons

  • Static — pattern-based, can miss framework-specific shapes
  • Detection is not enforcement — pair with the guardrail

Runtime guardrail library

from agentfirewall.guardrails import …

Why it's needed. Detecting the bug doesn't stop it. An embeddable guard enforces the fix at request time: reserve quota atomically before the agent runs (a refresh can't replay), confine tools to an allowlist, and refuse untrusted-derived data from driving sensitive actions.

Use cases
  • Kill the refresh/replay token-burn with idempotent check-before-act
  • Deny run_python / off-scope tool calls at dispatch
  • Taint retrieved docs so they can't drive email/http/sql sinks

Pros

  • Actually enforces the fix, not just detects it
  • CaMeL-style taint guard against indirect prompt injection
  • Embeddable, zero-dependency, refunds on failure

Cons

  • Bundled quota/idempotency stores are single-process references — back with Redis/DB in prod
  • Taint requires you to wrap untrusted data yourself
  • Only as strong as the scope policy you define
PLATFORM · DX

How you run & report it

The plumbing that makes the detections usable in a real workflow — pipelines, dashboards, and a shared vocabulary for auditors.

CI gate & machine outputs

uses: mmedabo/agentfirewall@v1

Why it's needed. Security that only runs on a laptop gets skipped. A reusable GitHub Action plus SARIF/JSON output puts the firewall on every push and into your existing dashboards.

Use cases
  • Fail a PR that adds a BLOCK-worthy skill or agent
  • Upload SARIF to GitHub code-scanning
  • Feed JSON findings into your own automation

Pros

  • One-line action; exit codes designed for shell & CI
  • SARIF / JSON / text formats out of the box

Cons

  • SARIF viewing needs a compatible platform
  • Policy tuning needed to avoid noisy build failures

Framework mapping

OWASP LLM · ASI · MITRE ATLAS · SLSA · CWE

Why it's needed. "This looks bad" doesn't survive an audit. Every finding cites an industry framework, giving security teams a shared language and a mapping they can defend to compliance.

Use cases
  • Map findings to OWASP Top 10 for LLM / Agentic (ASI01–ASI10)
  • Reference MITRE ATLAS techniques in a report
  • Tie supply-chain findings to SLSA / CWE

Pros

  • Audit- and compliance-friendly out of the box
  • Shared vocabulary across security & dev teams

Cons

  • Mappings are guidance, not certification
  • Frameworks evolve — references track a point in time

The honest caveat. AIAgentFirewall is defence in depth, not a single guarantee. The static tiers read artifacts and can miss a novel payload; the runtime tiers contain execution but depend on the kernel features available to you. It helps you make an informed trust decision about third-party AI agents — it does not replace reading the code yourself for anything sensitive.