Agent Firewall

Security and authorization infrastructure for AI agents and automated tool use.

Agent Firewall provides a capability-based security layer between an agent and the actions it is allowed to perform.

v1.3

Agent Firewall v1.3.0 hardens delegated authority by enforcing the complete capability lineage during authorization. A delegated capability is no longer evaluated as an isolated authority: its request must satisfy the child capability and every resolved parent and ancestor capability in its delegation chain.

v1.3 adds effective delegated-authority enforcement, fail-closed ancestor resolution, adversarial escalation testing, and concurrency/race-condition coverage for multi-agent delegation.

The v1.3 security model preserves the distinction between local capability validity and effective authority. Delegation can only preserve or narrow authority. It cannot restore, broaden, or launder authority that an ancestor does not possess.

Installation

Install the v1.3.0 release from PyPI:

pip install agent-firewall-security==1.3.0

The PyPI distribution name is agent-firewall-security and the Python import package is firewall.

from firewall.sdk import FirewallSDK

Quick Start

from firewall.sdk import FirewallSDK

sdk = FirewallSDK()
sdk.generate_key("key-1")

capability = sdk.issue(
    agent="agent-a",
    capability="payments.send",
)

result = sdk.authorize(
    capability,
    "payments.send",
    {},
)

print(result.allowed)

Core Security Model

Agent Firewall uses capabilities as the authority presented for an operation.

Authorization is not granted merely because a capability exists. The firewall verifies capability validity, cryptographic integrity, issuer trust, expiration, revocation state, requested action, constraints, and replay state where applicable.

For delegated capabilities, v1.3 additionally evaluates the effective authority represented by the complete delegation chain.

Effective Delegated Authority

A delegation creates a parent-child authority relationship:

root capability
      |
      v
child capability
      |
      v
grandchild capability

During SDK authorization, the complete resolved chain is evaluated:

child
  -> parent
      -> ancestor
          -> root

The request must satisfy every capability in that chain.

For example:

root:       amount_max = 1000
child:      amount_max = 500
grandchild: amount_max = 250

The effective authority of the grandchild cannot exceed 250, even if an individual descendant were constructed with a broader local constraint.

Namespace restrictions are enforced across the chain as well.

If an expected ancestor cannot be resolved from the SDK capability registry, authorization fails closed with a delegation-chain error rather than treating the descendant as an independent authority.

Delegation Lineage

The runtime DelegationLineage registry tracks:

child fingerprint -> parent fingerprint -> ancestor

The lineage implementation provides parent lookup, complete ancestry traversal, descendant checks, snapshots, cycle detection, maximum-depth enforcement, and thread-safe access.

Revocation remains owned by the SDK revocation registry. Effective authorization consults the resolved delegation chain so revoked ancestors cannot be bypassed by descendants.

Revoking an intermediate delegated capability also invalidates its descendants.

Adversarial Delegation Security

v1.3 explicitly tests attempts to:

• launder broader constraints through nested delegation
• escalate capability namespaces
• escape authority restrictions through deep delegation
• bypass revoked parents
• bypass revoked intermediate capabilities
• contaminate sibling delegation trees
• use unrelated capability trees as ancestors
• authorize with missing ancestor state

These cases are required to fail closed.

Concurrency Security

v1.3 adds race-condition coverage for:

• concurrent authorization
• authorization during revocation
• concurrent sibling authorization
• concurrent delegation registration
• concurrent lineage reads
• concurrent root revocation
• repeated authorization after revocation

The lineage registry uses synchronized access so concurrent reads and writes do not silently corrupt ancestry state.

Security Context

SecurityContext provides optional per-agent runtime controls for cumulative security state, including action counts, cumulative amounts, denial tracking, and capability usage tracking.

This allows policies to account for accumulated activity rather than evaluating every request in isolation.

Semantic Chain Security

Some security decisions cannot be represented by a single request constraint.

For example, a workflow such as:

payments.lookup
payments.prepare
payments.send

can represent a protected semantic outcome even when each individual request is within its own primitive limits.

v1.2 provides an explicit SemanticChainContext and SemanticRule model for deterministic workflow protection.

Semantic state is scoped by agent and explicit chain_id values. Different chains do not inherit each other's semantic history.

Semantic matching can track deterministic resource identity, ordered stages, capability fingerprints, terminal outcomes, and cumulative facts such as amount.

Semantic protection is opt-in. When no semantic context is configured, existing authorization behavior remains unchanged.

Atomic Semantic Authorization

Semantic state transitions use an explicit transaction boundary.

The authorization path is effectively:

primitive authorization
        -> semantic authorization
        -> downstream SecurityContext authorization
        -> semantic commit

If downstream authorization rejects the request, the semantic transaction is aborted rather than leaving a partially committed semantic state.

Concurrent semantic authorization attempts are serialized so a race cannot bypass the semantic guard.

Policy Engine

v1.1 adds explicit policy operators:

• eq
• neq
• in
• not_in
• gte
• lte
• contains

Policies can also be composed with and, or, and not.

Existing v1.0 forms such as amount_max, amount_min, lists, nested constraints, and literal equality remain supported.

Key Management and Identity Binding

v1.1 managed capabilities include a stable key_id bound into the signed capability data.

Managed capability verification binds:

issuer + key_id + public_key + signature

Rotating a key creates a new key identity for new managed capabilities while existing capabilities remain independently verifiable until they expire or are explicitly revoked.

Persistent Key Storage

Managed signing keys can survive normal SDK restart through encrypted SQLite storage.

import os
from firewall.sdk import FirewallSDK

master_key = os.urandom(32)

sdk = FirewallSDK(
    key_store_path="firewall-keys.db",
    master_key=master_key,
)

Private signing-key material is encrypted at rest. The master key is supplied by the application and is not stored by Agent Firewall.

Persistent Replay Protection

v1.1 can persist replay state across SDK restarts:

sdk = FirewallSDK(
    replay_store_path="firewall-replay.db",
)

A consumed nonce remains consumed across normal restart until its validity window expires.

Revocation

sdk.revoke(
    capability,
    reason="compromised",
)

Revocation is one-way. A revoked capability cannot become authorized again because of SDK restart, key rotation, lifecycle history, or cached state.

MCP Security Adapter

The MCP adapter sits at the authorization boundary immediately before a tool is executed.

from firewall.mcp import MCPFirewall

firewall = MCPFirewall(
    sdk,
    require_nonce=True,
)

Denied requests never reach the handler.

Attenuation and Delegation

Capabilities can be attenuated:

child = sdk.attenuate(
    capability,
    private_key,
    constraints={
        "amount_max": 50,
    },
)

Capabilities can also be delegated:

delegation = sdk.delegate(
    capability,
    private_key,
    delegatee="agent-b",
)

v1.3 extends delegation from lineage tracking and revocation propagation to complete effective-authority enforcement during authorization.

Legacy API Compatibility

The direct private-key issuance API remains supported:

sdk.issue(
    private_key=private_key,
    agent="agent-a",
    capability="payments.send",
)

Existing v1.0 capability formats without key_id remain compatible with the legacy verification path.

Adapters

Agent Firewall provides adapters for common tool-call formats while preserving the shared authorization core.

Supported adapters include:

• Generic tool adapter
• MCP firewall adapter
• OpenAI tool adapter
• Anthropic tool adapter

CLI

The public firewall command provides:

firewall init
firewall validate
firewall inspect-token
firewall explain

Show CLI help:

firewall --help

Security Hardening

v1.3 includes dedicated coverage for:

• effective delegated authority
• complete parent and ancestor authorization
• delegation constraint attenuation
• namespace non-escalation
• fail-closed missing ancestor resolution
• delegation cycle and depth protection
• parent and descendant revocation
• adversarial constraint laundering
• deep delegation escalation
• revoked-parent and revoked-intermediate bypasses
• sibling and unrelated-tree isolation
• concurrent authorization and revocation
• concurrent delegation and lineage access
• refusal-state interactions
• replay and fresh-nonce adversarial cases
• adapter authorization boundaries
• persistence and concurrency security invariants

Security Invariants

Important invariants include:

REVOKED  -> USED    forbidden
EXPIRED  -> USED    forbidden
REPLAYED -> USED    forbidden
DENIED   -> USED    forbidden

Delegation invariants include:

child authority > parent authority       forbidden
namespace escalation                     forbidden
revoked ancestor -> descendant authorized forbidden
missing ancestor -> descendant authorized forbidden
delegation cycle                         forbidden
excessive delegation depth               forbidden

Key-management invariants include:

retired key -> new managed issuance     forbidden
rotation    -> old capability invalid  forbidden
store fail  -> fresh authority         forbidden

Semantic-chain invariants include:

different chain_id -> shared semantic state       forbidden
resource mismatch -> matching protected workflow  forbidden
semantic success + downstream failure -> commit   forbidden
concurrent semantic race -> unauthorized bypass  forbidden

Semantic rules are explicit and deterministic. The SDK does not infer semantic intent with an LLM.

Testing

The project includes:

• unit tests
• integration tests
• property-based tests
• state-machine tests
• persistence restart tests
• persistence corruption tests
• policy tests
• concurrency tests
• security fuzzing
• adapter security tests
• delegation-lineage tests
• effective-authority tests
• adversarial escalation tests
• adversarial concurrency tests
• semantic-chain tests
• semantic transaction tests
• final security audit tests
• performance benchmarks

Run the complete suite:

pytest -q

The local v1.3 validation run contains 2,050 passing tests.

Continuous Integration

The security workflow runs the full regression suite across Python 3.10, 3.11, and 3.12, including the v1.3 branch.

Package

PyPI distribution:

agent-firewall-security

v1.3.0 install:

pip install agent-firewall-security==1.3.0

Python import package:

firewall

GitHub repository:

Shubhbhangoo/agent-firewall

Documentation

Additional documentation:

• docs/v1.0-api-contract.md
• docs/v1.0-security.md
• docs/v1.0-key-management.md
• CHANGELOG.md

Version

Current development release:

1.3.0

License

See the repository license file for licensing information.