toolwall 0.2.2__tar.gz → 0.3.0__tar.gz

{toolwall-0.2.2 → toolwall-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: toolwall
-Version: 0.2.2
-Summary: Fail-closed firewall for AI agent tool calls: schema + policy gate before any tool executes
+Version: 0.3.0
+Summary: Security gateway for AI agent tool calls: fail-closed schema + policy + secret-detection gate before any tool executes
 Project-URL: Homepage, https://github.com/Dev-Saif-Ops/toolwall
 Author: Mohammad Safwan Athar
 License: MIT
-Keywords: agents,ai,guardrails,llm,mcp,security,tool-calling
+Keywords: agent-sandbox,agent-security,agents,ai,ai-agent-security,ai-agents,ai-safety,firewall,guardrails,llm,llm-security,mcp,mcp-firewall,mcp-proxy,mcp-security,prompt-injection,secret-detection,security,tool-call-validation,tool-calling
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -27,20 +27,20 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/pypi/l/toolwall.svg)](https://github.com/Dev-Saif-Ops/toolwall/blob/main/toolwall/LICENSE)
 [![Zero dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](https://github.com/Dev-Saif-Ops/toolwall)
 
-**A fail-closed firewall for AI agent tool calls.**
+**The security gateway for AI agent tool calls.**
 
-Structured outputs already guarantee your agent's tool calls are *well-formed*.
-Nothing guarantees they're *allowed*. `toolwall` is the checkpoint that sits between
-the LLM's tool call and execution, and blocks the schema-valid-but-wrong ones.
+Your LLM can generate a *valid* tool call. That doesn't mean it's *safe* to execute.
 
 ```python
 delete_records(filter={})            # perfectly valid JSON. whole table gone.
 send_email(to="attacker@evil.com")   # recipient injected via a poisoned web page
-db_query(limit=10_000_000)           # schema-valid. production melts.
+transfer_money(amount=999999999)     # schema-valid. every field the right type.
+db_query(limit=10_000_000)           # production melts.
 ```
 
-Every one of these passes JSON schema validation. Nothing in the platform stack stops
-them. `toolwall` does.
+Every one of these passes JSON schema validation. Structured outputs, schemas, and
+content moderation all wave them through. `toolwall` is the fail-closed checkpoint
+between the LLM's tool call and execution that blocks them.
 
 ---
 
@@ -56,26 +56,45 @@ calling (and plain dicts). Python 3.10+.
 ## Quickstart
 
 ```python
-from toolwall import Gate, Meter, Policy, Shield, ToolSchema, in_range, not_empty
-
-gate = Gate(default="deny", meter=Meter(), shield=Shield(mode="block"))
-
-gate.register(
-    "db_query", db_query,
-    schema=ToolSchema(required=["q"], types={"q": str, "limit": int}),
-    policy=Policy(constraints={"limit": in_range(1, 100)}),
-)
-gate.register(
-    "delete_records", delete_records,
-    schema=ToolSchema(required=["filter"], types={"filter": dict}),
-    policy=Policy(constraints={"filter": not_empty}, require_approval=True),
-)
-gate.budget(max_calls=20)
-
-result = gate.run(openai_response)   # any provider shape, or a plain dict
-# result.verdict: ALLOW | BLOCK | NEEDS_APPROVAL. Only ALLOW executes.
+from toolwall import ToolWall, Policy, ToolSchema, in_range, not_empty
+
+wall = ToolWall()   # default-deny, secret detection + audit on
+
+wall.register("db_query", db_query,
+              schema=ToolSchema(required=["q"], types={"q": str, "limit": int}),
+              policy=Policy(constraints={"limit": in_range(1, 100)}))
+wall.register("delete_records", delete_records,
+              schema=ToolSchema(required=["filter"], types={"filter": dict}),
+              policy=Policy(constraints={"filter": not_empty}, require_approval=True))
+wall.budget(max_calls=20)
+
+result = wall.call("delete_records", {"filter": {}})
+# result.blocked -> True
+# result.reason  -> "policy violation: arg 'filter' rejected by not_empty"
+
+results = wall.guard(openai_response)   # or gate a raw OpenAI/Anthropic/Gemini response
 ```
 
+Only an `ALLOW` verdict runs the tool. `Gate` is the lower-level primitive underneath.
+
+## What it stops
+
+```python
+wall.call("delete_records", {"filter": {}})
+# BLOCKED: policy violation: arg 'filter' rejected by not_empty
+
+wall.call("send_email", {"to": "ops@ourco.com", "body": "aws key AKIA..."})
+# BLOCKED: secret detected (aws-access-key) in arg 'body'
+
+wall.call("db_query", {"q": "everything", "limit": 10_000_000})
+# BLOCKED: policy violation: arg 'limit' rejected by in_range(1, 100)
+
+wall.call("run_shell", {"cmd": "..."})
+# BLOCKED: unknown tool: 'run_shell'
+```
+
+Everything not explicitly allowed is blocked. That is the whole idea.
+
 ## What it does
 
 - **Fail-closed gate**: unknown tool, schema violation, policy violation, budget hit,

{toolwall-0.2.2 → toolwall-0.3.0}/README.md

@@ -5,20 +5,20 @@
 [![License: MIT](https://img.shields.io/pypi/l/toolwall.svg)](https://github.com/Dev-Saif-Ops/toolwall/blob/main/toolwall/LICENSE)
 [![Zero dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](https://github.com/Dev-Saif-Ops/toolwall)
 
-**A fail-closed firewall for AI agent tool calls.**
+**The security gateway for AI agent tool calls.**
 
-Structured outputs already guarantee your agent's tool calls are *well-formed*.
-Nothing guarantees they're *allowed*. `toolwall` is the checkpoint that sits between
-the LLM's tool call and execution, and blocks the schema-valid-but-wrong ones.
+Your LLM can generate a *valid* tool call. That doesn't mean it's *safe* to execute.
 
 ```python
 delete_records(filter={})            # perfectly valid JSON. whole table gone.
 send_email(to="attacker@evil.com")   # recipient injected via a poisoned web page
-db_query(limit=10_000_000)           # schema-valid. production melts.
+transfer_money(amount=999999999)     # schema-valid. every field the right type.
+db_query(limit=10_000_000)           # production melts.
 ```
 
-Every one of these passes JSON schema validation. Nothing in the platform stack stops
-them. `toolwall` does.
+Every one of these passes JSON schema validation. Structured outputs, schemas, and
+content moderation all wave them through. `toolwall` is the fail-closed checkpoint
+between the LLM's tool call and execution that blocks them.
 
 ---
 
@@ -34,26 +34,45 @@ calling (and plain dicts). Python 3.10+.
 ## Quickstart
 
 ```python
-from toolwall import Gate, Meter, Policy, Shield, ToolSchema, in_range, not_empty
-
-gate = Gate(default="deny", meter=Meter(), shield=Shield(mode="block"))
-
-gate.register(
-    "db_query", db_query,
-    schema=ToolSchema(required=["q"], types={"q": str, "limit": int}),
-    policy=Policy(constraints={"limit": in_range(1, 100)}),
-)
-gate.register(
-    "delete_records", delete_records,
-    schema=ToolSchema(required=["filter"], types={"filter": dict}),
-    policy=Policy(constraints={"filter": not_empty}, require_approval=True),
-)
-gate.budget(max_calls=20)
-
-result = gate.run(openai_response)   # any provider shape, or a plain dict
-# result.verdict: ALLOW | BLOCK | NEEDS_APPROVAL. Only ALLOW executes.
+from toolwall import ToolWall, Policy, ToolSchema, in_range, not_empty
+
+wall = ToolWall()   # default-deny, secret detection + audit on
+
+wall.register("db_query", db_query,
+              schema=ToolSchema(required=["q"], types={"q": str, "limit": int}),
+              policy=Policy(constraints={"limit": in_range(1, 100)}))
+wall.register("delete_records", delete_records,
+              schema=ToolSchema(required=["filter"], types={"filter": dict}),
+              policy=Policy(constraints={"filter": not_empty}, require_approval=True))
+wall.budget(max_calls=20)
+
+result = wall.call("delete_records", {"filter": {}})
+# result.blocked -> True
+# result.reason  -> "policy violation: arg 'filter' rejected by not_empty"
+
+results = wall.guard(openai_response)   # or gate a raw OpenAI/Anthropic/Gemini response
 ```
 
+Only an `ALLOW` verdict runs the tool. `Gate` is the lower-level primitive underneath.
+
+## What it stops
+
+```python
+wall.call("delete_records", {"filter": {}})
+# BLOCKED: policy violation: arg 'filter' rejected by not_empty
+
+wall.call("send_email", {"to": "ops@ourco.com", "body": "aws key AKIA..."})
+# BLOCKED: secret detected (aws-access-key) in arg 'body'
+
+wall.call("db_query", {"q": "everything", "limit": 10_000_000})
+# BLOCKED: policy violation: arg 'limit' rejected by in_range(1, 100)
+
+wall.call("run_shell", {"cmd": "..."})
+# BLOCKED: unknown tool: 'run_shell'
+```
+
+Everything not explicitly allowed is blocked. That is the whole idea.
+
 ## What it does
 
 - **Fail-closed gate**: unknown tool, schema violation, policy violation, budget hit,

{toolwall-0.2.2 → toolwall-0.3.0}/pyproject.toml

@@ -6,13 +6,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "toolwall"
-version = "0.2.2"
-description = "Fail-closed firewall for AI agent tool calls: schema + policy gate before any tool executes"
+version = "0.3.0"
+description = "Security gateway for AI agent tool calls: fail-closed schema + policy + secret-detection gate before any tool executes"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"
 authors = [{ name = "Mohammad Safwan Athar" }]
-keywords = ["ai", "agents", "llm", "tool-calling", "guardrails", "security", "mcp"]
+keywords = [
+    "ai", "agents", "ai-agents", "llm", "llm-security", "ai-agent-security",
+    "agent-security", "tool-calling", "tool-call-validation", "guardrails",
+    "security", "ai-safety", "mcp", "mcp-security", "mcp-firewall", "mcp-proxy",
+    "prompt-injection", "secret-detection", "agent-sandbox", "firewall",
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",

{toolwall-0.2.2 → toolwall-0.3.0}/src/toolwall/__init__.py

@@ -5,6 +5,7 @@ toolwall guarantees they're allowed.
 """
 
 from toolwall.gate import Gate, GateResult, ToolRegistry, Verdict
+from toolwall.wall import ToolWall
 from toolwall.intake import IntakeError, ToolCall, parse_tool_calls
 from toolwall.meter import Meter, RunEvent, RunReport, extract_usage
 from toolwall.policy import (
@@ -22,9 +23,10 @@ from toolwall.shield import Finding, Shield
 from toolwall.suggest import suggest_policies
 from toolwall.mcp_guard import GuardedCall, MCPGuard, to_mcp_error
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
 __all__ = [
+    "ToolWall",
     "Gate",
     "GateResult",
     "Verdict",

{toolwall-0.2.2 → toolwall-0.3.0}/src/toolwall/gate.py

@@ -91,6 +91,19 @@ class GateResult:
     def allowed(self) -> bool:
         return self.verdict is Verdict.ALLOW
 
+    @property
+    def blocked(self) -> bool:
+        return self.verdict is Verdict.BLOCK
+
+    @property
+    def needs_approval(self) -> bool:
+        return self.verdict is Verdict.NEEDS_APPROVAL
+
+    @property
+    def reason(self) -> str | None:
+        """First human-readable reason for a block/hold, or None when allowed."""
+        return self.reasons[0] if self.reasons else None
+
 
 class Gate:
     """Fail-closed gate.

toolwall-0.3.0/src/toolwall/wall.py

@@ -0,0 +1,122 @@
+"""ToolWall: the one-line entry point.
+
+`Gate` is the low-level primitive (verdicts, execution split, meter wiring).
+`ToolWall` is the ergonomic facade most users want: it wires a Gate with a
+Shield and a Meter already attached, and gives you `register` + `call`.
+
+    from toolwall import ToolWall, Policy, ToolSchema, not_empty
+
+    wall = ToolWall()                      # default-deny, secret detection + audit on
+    wall.register("get_user", get_user, schema=ToolSchema(required=["id"]))
+    wall.register("delete_user", delete_user, policy=Policy(require_approval=True))
+
+    result = wall.call("get_user", {"id": "123"})       # ALLOW -> runs
+    result = wall.call("delete_user", {"id": "123"})    # held for approval
+    if result.blocked:
+        print(result.reason)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from toolwall.gate import ApprovalHandler, DefaultMode, Gate, GateResult
+from toolwall.meter import Meter
+from toolwall.policy import Policy
+from toolwall.schema import ToolSchema
+from toolwall.shield import Shield
+
+ToolFn = Callable[..., Any]
+
+
+class ToolWall:
+    """Fail-closed security gateway for AI agent tool calls.
+
+    Args:
+        default: "deny" (registered tools still need a schema) or "allow".
+        detect_secrets: attach a Shield. True blocks secrets in tool args;
+            pass redact=True to replace them with placeholders instead.
+        redact: if detecting secrets, redact instead of block.
+        audit: attach a Meter so every verdict is recorded and exportable.
+        approval: handler called when a tool needs approval; return True to run.
+    """
+
+    def __init__(
+        self,
+        *,
+        default: DefaultMode = "deny",
+        detect_secrets: bool = True,
+        redact: bool = False,
+        audit: bool = True,
+        approval: ApprovalHandler | None = None,
+    ):
+        shield = Shield(mode="redact" if redact else "block") if detect_secrets else None
+        meter = Meter() if audit else None
+        self.gate = Gate(default=default, meter=meter, shield=shield, approval=approval)
+
+    # -- setup (chainable) ---------------------------------------------------
+
+    def register(
+        self,
+        name: str,
+        fn: ToolFn,
+        *,
+        schema: ToolSchema | None = None,
+        policy: Policy | None = None,
+        infer_schema: bool = False,
+    ) -> "ToolWall":
+        self.gate.register(name, fn, schema, policy=policy, infer_schema=infer_schema)
+        return self
+
+    def budget(
+        self,
+        *,
+        max_calls: int | None = None,
+        max_calls_per_tool: int | None = None,
+        max_usd: float | None = None,
+    ) -> "ToolWall":
+        self.gate.budget(
+            max_calls=max_calls, max_calls_per_tool=max_calls_per_tool, max_usd=max_usd
+        )
+        return self
+
+    def approve_with(self, handler: ApprovalHandler) -> "ToolWall":
+        self.gate.approval = handler
+        return self
+
+    # -- use -----------------------------------------------------------------
+
+    def call(self, name: str, args: dict[str, Any] | None = None) -> GateResult:
+        """Check the call and execute it only if allowed."""
+        return self.gate.run({"name": name, "args": args or {}})
+
+    def check(self, name: str, args: dict[str, Any] | None = None) -> GateResult:
+        """Return the verdict without executing anything."""
+        return self.gate.check({"name": name, "args": args or {}})
+
+    def guard(self, response: Any) -> list[GateResult]:
+        """Gate a raw LLM response (OpenAI/Anthropic/Gemini), possibly many calls."""
+        return self.gate.run_all(response)
+
+    # -- dry-run + reporting -------------------------------------------------
+
+    @property
+    def dry_run(self) -> bool:
+        return self.gate.dry_run
+
+    @dry_run.setter
+    def dry_run(self, value: bool) -> None:
+        self.gate.dry_run = value
+
+    def report(self) -> dict[str, Any]:
+        return self.gate.report()
+
+    def export(self, json_path: str, csv_path: str | None = None) -> dict[str, Any]:
+        if self.gate.meter is None:
+            raise ValueError("no audit meter attached (ToolWall was built with audit=False)")
+        return self.gate.meter.export(json_path, csv_path)
+
+    @property
+    def meter(self) -> Meter | None:
+        return self.gate.meter