agent-firewall-security 1.0.0__py3-none-any.whl

agent_firewall_security-1.0.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: agent-firewall-security
+Version: 1.0.0
+Summary: Security and authorization layer for AI agents and automated tool use.
+Project-URL: Homepage, https://github.com/Shubhbhangoo/agent-firewall
+Project-URL: Repository, https://github.com/Shubhbhangoo/agent-firewall
+Project-URL: Issues, https://github.com/Shubhbhangoo/agent-firewall/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: mcp>=2.0
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+
+ Agent Firewall
+
+Security and authorization infrastructure for AI agents and automated tool use.
+
+Agent Firewall provides a capability-based security layer between agents and the actions they are allowed to perform.
+
+## v1.0
+
+Agent Firewall v1.0 is the first stable release.
+
+### Core security
+
+- Capability-based authorization
+- Cryptographic capability verification
+- Capability attenuation
+- Capability delegation
+- Capability revocation
+- Replay protection
+- Lifecycle recording
+- Expiration enforcement
+- Issuer trust management
+- Signing-key rotation
+- Key retirement
+- Fail-closed authorization semantics
+
+### Persistent security state
+
+v1.0 supports persistent managed signing keys and issuer trust state.
+
+```python
+import os
+
+from firewall.sdk import FirewallSDK
+
+master_key = os.urandom(32)
+
+sdk = FirewallSDK(
+    key_store_path="firewall-keys.db",
+    master_key=master_key,
+)
+
+sdk.generate_key("key-1")
+
+capability = sdk.issue(
+    agent="agent-a",
+    capability="payments.send",
+)
+
+Private signing keys are encrypted at rest.
+
+The master key is supplied by the application and is never stored by Agent Firewall.
+
+Key rotation
+sdk.rotate_key("key-2")
+
+Rotation creates a new active signing key and retires the previous one.
+
+Previously issued capabilities are not automatically revoked.
+
+Issuer trust
+sdk.trust_issuer("issuer-a")
+sdk.revoke_issuer("issuer-a")
+
+Issuer trust state can survive SDK restart when persistent key storage is enabled.
+
+Legacy issuance
+
+The existing direct-key API remains supported:
+
+sdk.issue(
+    private_key=private_key,
+    agent="agent-a",
+    capability="payments.send",
+)
+CLI
+firewall init
+firewall validate
+firewall inspect-token
+firewall explain
+Security testing
+
+The project includes:
+
+unit tests
+integration tests
+property-based tests
+state-machine tests
+persistence failure tests
+adapter interoperability tests
+benchmark coverage
+
+The CI security matrix runs the complete test suite on Python 3.10, 3.11, and 3.12.
+
+Installation
+pip install agent-firewall
+Documentation
+
+See:
+
+docs/v1.0-api-contract.md
+docs/v1.0-security.md
+docs/v1.0-key-management.md
+
+### `CHANGELOG.md`
+
+Create or update:
+
+```md
+# Changelog
+
+All notable changes to Agent Firewall are documented here.
+
+## [1.0.0] - 2026-08-23
+
+### Added
+
+- Stable v1.0 public API contract
+- Managed capability signing keys
+- Signing-key rotation
+- Signing-key retirement
+- Persistent encrypted signing-key storage
+- Persistent issuer trust state
+- Issuer trust and revocation management
+- Persistent lifecycle and revocation support
+- Generic tool adapter
+- OpenAI tool adapter
+- Anthropic tool adapter
+- Capability normalization
+- Capability explanation and denial reporting
+- CLI commands:
+  - `firewall init`
+  - `firewall validate`
+  - `firewall inspect-token`
+  - `firewall explain`
+- Property-based security tests
+- Lifecycle state-machine security tests
+- Persistence failure and corruption tests
+- CI security regression matrix
+- Python 3.10, 3.11, and 3.12 CI coverage
+- v1.0 security and key-management documentation
+
+### Security
+
+- Authorization fails closed when critical security state cannot be verified.
+- Persistent key-store failures do not silently fall back to cached or newly generated signing authority.
+- Retiring or rotating a key does not implicitly grant or revoke capability authority.
+- Revoked, expired, replayed, and denied capabilities cannot transition into successful use.
+- Private signing-key material is encrypted at rest in persistent storage.
+
+### Compatibility
+
+- Existing direct `private_key=` capability issuance remains supported.
+- v0.9 CLI commands remain available.
+- Existing adapter security semantics continue to use the same authorization core.

agent_firewall_security-1.0.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+firewall/__init__.py,sha256=14LJj6z-Gtjt5nrtVX9CCnAkK3wZSkaMXXFMHHAqi7A,1462
+firewall/attenuation.py,sha256=qH8BO76yV18yjwo9g-0_zrrWn9KczNIepQXgL0Dp61g,4580
+firewall/authorization.py,sha256=qLIZOxLArYhzuI4cKuKoYs4nfyabCA5R5Zy9nwHURQU,5053
+firewall/capability.py,sha256=fBwU7LXO_YvA6ArwuM8ikNFGwGkJqH9Quamx4U0z4l4,6808
+firewall/cli.py,sha256=N_YTFrrMWFUsvPu7neu-1gkai-a2OvK2jpNS5HeFvPc,7250
+firewall/delegation.py,sha256=eaglhsP4a-fq0uiJZj9bQ7T_7x4PhamybJZvu3s_Iv8,5747
+firewall/engine.py,sha256=52mhEF1TbB4NU21eVWdSkegKKPDRJ4mXNeU0ddBb-1w,51396
+firewall/evidence.py,sha256=S5IYz6HA0-3uIIsNADnw3xpXZL8id3c-yQl8I8d5fjA,5571
+firewall/explain.py,sha256=iKjpmE0OjdPQ9gUMPFjxCEPBCKUFAGyo_QiStCNU5V4,3773
+firewall/http.py,sha256=OHgZ5r4-Atn3DT5P4K98LF705YyJ9-tqQRsOJveEvSA,12097
+firewall/identity.py,sha256=wEo5tqsgRqGZdjGSU3WgmLhk4VuqHykeUm2bTsO93M8,11566
+firewall/key_management.py,sha256=DfG4ntrB2SRJ3LLMT-zp5nVaBbCefo4pzlFBHNlzHUY,14194
+firewall/key_store.py,sha256=IuJhFdCsTTAyOSuOpY0XWfcfQEfo6y0ApQ8flZDxZRE,19743
+firewall/lifecycle.py,sha256=6jVuaE5cNS7NR2t75kOEZb8D1RRwKd2ax9p-B9QZQ1g,6178
+firewall/lifecycle_store.py,sha256=UtBwGV2nQj23w1ujSyvbHaOyTksaW7Ve4XuAQcFsf90,15721
+firewall/mcp.py,sha256=a9iIhNAfJlbYFCQkeIV9ZUlUtkS9eLGvwEAZVkhz2rM,6123
+firewall/namespace.py,sha256=FyvFy48bTrAj8uYyiwLsKSlzS7EphXPYCbONTLgZppQ,3898
+firewall/protect.py,sha256=0a4Q3C_ImoXVWNTBBvQWqRcdMS8oJ4mk_pCcRbVzBzY,1594
+firewall/replay.py,sha256=YwAJr1e9GmtTXG8UwK1nb8v8JwQJL2fD95sm8L985OY,3308
+firewall/revocation.py,sha256=GVoC6XCsK1CNwv93JaY_Ccx2R4jOn7Jt7FynSDnXdjQ,9368
+firewall/revocation_store.py,sha256=GlN4xpYa_fctadIgXJvIIHgQ_Q1Zy7-emAoiBA8l5L4,7366
+firewall/sdk.py,sha256=dqRLg_L2ZEEO-nA3zA9ysDzkjxKSvIJSQBhQ49z0H3w,31781
+firewall/tools.py,sha256=e6U8-QaSq1I2V4__ennRkm0Bn7JiWDfsILpxygcqNXw,3844
+firewall/transport.py,sha256=_Rc-RXzHmUEuHhKtDh-e59qOZATdaZH1k5RnPijPsK8,4431
+firewall/adapters/__init__.py,sha256=X-YTiKltfmNe1D059IayH0He17g78CWPXcqvu_4GDPg,485
+firewall/adapters/anthropic.py,sha256=J1sVsaA7TlUAX6DiRlxWD44LzjsnUg3YKMIZ8gyyAX0,7612
+firewall/adapters/generic.py,sha256=-Yk7IIQfDslFKGelYFGLp3gWMGu7lnMRGmPp0M9u4xk,5348
+firewall/adapters/normalize.py,sha256=B6wPyrR_BfkIV84SlpeHvUhuRsLcipqwG89L-67C4lk,2392
+firewall/adapters/openai.py,sha256=A_zjAul82qXwXQs0f2nMhTuIofRRMy-EVDThnanIbU0,8701
+agent_firewall_security-1.0.0.dist-info/METADATA,sha256=rwGijSu8DtBumClmYJ_2Ts_ToneYVojQ8SUDeEARGn4,4494
+agent_firewall_security-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agent_firewall_security-1.0.0.dist-info/entry_points.txt,sha256=ATMBlCNaTTSfEWeCo_NhmiEfc0e6BSt-51c4fAUsCNk,47
+agent_firewall_security-1.0.0.dist-info/top_level.txt,sha256=eCyrxLxHgVZSGULyFkPUP0MBc5YLd2aBS7nRRC-kUac,9
+agent_firewall_security-1.0.0.dist-info/RECORD,,

agent_firewall_security-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_firewall_security-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+firewall = firewall.cli:main

agent_firewall_security-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+firewall

firewall/__init__.py

@@ -0,0 +1,80 @@
+from .engine import (
+    Firewall,
+    Decision,
+)
+
+from .sdk import (
+    FirewallSDK,
+)
+
+from .capability import (
+    Capability,
+    CapabilityVerifier,
+    capability_fingerprint,
+    generate_capability_key_pair,
+    sign_capability,
+)
+
+from .delegation import (
+    Delegation,
+)
+
+from .revocation import (
+    RevocationRegistry,
+    RevocationRecord,
+    RevocationError,
+    AlreadyRevokedError,
+    InvalidFingerprintError,
+    RevokedCapabilityError,
+)
+
+from .lifecycle import (
+    LifecycleEvent,
+    LifecycleEventType,
+    LifecycleRecorder,
+)
+
+from .lifecycle_store import (
+    LifecycleStore,
+    LifecycleStoreError,
+    LifecycleStoreClosedError,
+    SQLiteLifecycleStore,
+)
+
+__all__ = [
+    # Engine
+    "Firewall",
+    "Decision",
+
+    # SDK
+    "FirewallSDK",
+
+    # Capabilities
+    "Capability",
+    "CapabilityVerifier",
+    "capability_fingerprint",
+    "generate_capability_key_pair",
+    "sign_capability",
+
+    # Delegation
+    "Delegation",
+
+    # Revocation
+    "RevocationRegistry",
+    "RevocationRecord",
+    "RevocationError",
+    "AlreadyRevokedError",
+    "InvalidFingerprintError",
+    "RevokedCapabilityError",
+
+    # Lifecycle
+    "LifecycleEvent",
+    "LifecycleEventType",
+    "LifecycleRecorder",
+
+    # Lifecycle persistence
+    "LifecycleStore",
+    "LifecycleStoreError",
+    "LifecycleStoreClosedError",
+    "SQLiteLifecycleStore",
+]

firewall/adapters/__init__.py

@@ -0,0 +1,30 @@
+from .generic import (
+    GenericToolAdapter,
+    GenericToolCall,
+    generic_tool,
+)
+
+from .openai import (
+    OpenAITool,
+    openai_tool,
+)
+
+from .anthropic import (
+    AnthropicTool,
+    anthropic_tool,
+)
+
+from .normalize import (
+    normalize_tool_call,
+)
+
+__all__ = [
+    "GenericToolAdapter",
+    "GenericToolCall",
+    "generic_tool",
+    "OpenAITool",
+    "openai_tool",
+    "AnthropicTool",
+    "anthropic_tool",
+    "normalize_tool_call",
+]

firewall/adapters/anthropic.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from firewall.adapters.generic import (
+    GenericToolCall,
+)
+from firewall.capability import Capability
+from firewall.sdk import FirewallSDK
+from firewall.tools import ProtectedTool
+
+
+class AnthropicTool:
+    """
+    Thin Anthropic-style tool adapter.
+
+    Expected tool-call shape:
+
+    {
+        "id": "toolu_123",
+        "name": "send_payment",
+        "input": {
+            "amount": 50
+        }
+    }
+
+    Authorization is delegated to FirewallSDK.
+    """
+
+    def __init__(
+        self,
+        *,
+        sdk: FirewallSDK,
+        capability: Capability,
+        handler: Callable[..., Any],
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        input_schema: Optional[dict] = None,
+        action: Optional[str] = None,
+        request_builder: Optional[
+            Callable[[dict[str, Any]], dict[str, Any]]
+        ] = None,
+    ):
+        if not isinstance(
+            sdk,
+            FirewallSDK,
+        ):
+            raise TypeError(
+                "sdk must be a FirewallSDK"
+            )
+
+        if not isinstance(
+            capability,
+            Capability,
+        ):
+            raise TypeError(
+                "capability must be a Capability"
+            )
+
+        if not callable(handler):
+            raise TypeError(
+                "handler must be callable"
+            )
+
+        if name is None:
+            name = getattr(
+                handler,
+                "__name__",
+                None,
+            )
+
+        if not isinstance(
+            name,
+            str,
+        ):
+            raise TypeError(
+                "name must be a string"
+            )
+
+        name = name.strip()
+
+        if not name:
+            raise ValueError(
+                "name cannot be empty"
+            )
+
+        if description is None:
+            description = (
+                getattr(
+                    handler,
+                    "__doc__",
+                    None,
+                )
+                or ""
+            )
+
+        if not isinstance(
+            description,
+            str,
+        ):
+            raise TypeError(
+                "description must be a string"
+            )
+
+        if input_schema is None:
+            input_schema = {
+                "type": "object",
+                "properties": {},
+            }
+
+        if not isinstance(
+            input_schema,
+            dict,
+        ):
+            raise TypeError(
+                "input_schema must be a dictionary"
+            )
+
+        if (
+            action is not None
+            and not isinstance(
+                action,
+                str,
+            )
+        ):
+            raise TypeError(
+                "action must be a string"
+            )
+
+        if (
+            action is not None
+            and not action.strip()
+        ):
+            raise ValueError(
+                "action cannot be empty"
+            )
+
+        if (
+            request_builder is not None
+            and not callable(request_builder)
+        ):
+            raise TypeError(
+                "request_builder must be callable"
+            )
+
+        self.sdk = sdk
+        self.capability = capability
+        self.name = name
+        self.description = description
+        self.input_schema = dict(
+            input_schema
+        )
+        self.action = action
+        self.request_builder = (
+            request_builder
+        )
+
+        self.tool = ProtectedTool(
+            sdk=sdk,
+            capability=capability,
+            handler=handler,
+            action=action,
+        )
+
+    # ========================================================
+    # Anthropic tool definition
+    # ========================================================
+
+    def definition(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": dict(
+                self.input_schema
+            ),
+        }
+
+    # ========================================================
+    # Normalize
+    # ========================================================
+
+    def normalize(
+        self,
+        call: dict,
+    ) -> GenericToolCall:
+        if not isinstance(
+            call,
+            dict,
+        ):
+            raise TypeError(
+                "call must be a dictionary"
+            )
+
+        name = call.get(
+            "name"
+        )
+
+        if name != self.name:
+            raise ValueError(
+                "tool call name does not match adapter"
+            )
+
+        arguments = call.get(
+            "input",
+            {},
+        )
+
+        if not isinstance(
+            arguments,
+            dict,
+        ):
+            raise TypeError(
+                "tool call input must be a dictionary"
+            )
+
+        return GenericToolCall(
+            name=name,
+            arguments=dict(
+                arguments
+            ),
+        )
+
+    # ========================================================
+    # Authorization
+    # ========================================================
+
+    def authorize(
+        self,
+        call: dict,
+    ):
+        normalized = self.normalize(
+            call
+        )
+
+        arguments = normalized.arguments
+
+        if self.request_builder is not None:
+            request = self.request_builder(
+                arguments
+            )
+
+            if not isinstance(
+                request,
+                dict,
+            ):
+                raise TypeError(
+                    "request_builder must return a dictionary"
+                )
+        else:
+            request = {
+                "tool": normalized.name,
+                "input": dict(
+                    arguments
+                ),
+            }
+
+        action = (
+            self.action
+            or self.capability.capability
+        )
+
+        return self.sdk.authorize(
+            self.capability,
+            action,
+            request,
+        )
+
+    # ========================================================
+    # Execute
+    # ========================================================
+
+    def execute(
+        self,
+        call: dict,
+    ):
+        normalized = self.normalize(
+            call
+        )
+
+        result = self.authorize(
+            call
+        )
+
+        if not result.allowed:
+            raise PermissionError(
+                result.reason
+            )
+
+        return self.tool.handler(
+            **normalized.arguments
+        )
+
+    def __call__(
+        self,
+        call: dict,
+    ):
+        return self.execute(
+            call
+        )
+
+
+def anthropic_tool(
+    *,
+    sdk: FirewallSDK,
+    capability: Capability,
+    handler: Callable[..., Any],
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    input_schema: Optional[dict] = None,
+    action: Optional[str] = None,
+    request_builder: Optional[
+        Callable[[dict[str, Any]], dict[str, Any]]
+    ] = None,
+) -> AnthropicTool:
+    return AnthropicTool(
+        sdk=sdk,
+        capability=capability,
+        handler=handler,
+        name=name,
+        description=description,
+        input_schema=input_schema,
+        action=action,
+        request_builder=request_builder,
+    )