wardproof 0.3.3__tar.gz → 0.3.4__tar.gz

{wardproof-0.3.3 → wardproof-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wardproof
-Version: 0.3.3
+Version: 0.3.4
 Summary: Local-first, verifiable defensive AI agent swarms that protect other AI agent systems.
 Project-URL: Homepage, https://wardproof.xyz
 Project-URL: Repository, https://github.com/Impossible-Mission-Force/wardproof
@@ -74,7 +74,7 @@ It is deliberately **small, transparent, and forkable**. The security core has
 **zero third-party dependencies** and runs **fully offline**, with a local
 model via Ollama, or with no model at all.
 
-> **Status: v0.3.1.** The deterministic core is built, tested, and benchmarked
+> **Status: v0.3.4.** The deterministic core is built, tested, and benchmarked
 > (see [Benchmark](#benchmark)), and ships dedicated guards for x402 agent
 > payments, on-chain transfers, MCP tool calls, and skill/tool definitions, a
 > controls-to-standards map (OWASP Agentic Top 10, OWASP LLM 2025, MITRE ATLAS,
@@ -210,7 +210,7 @@ gate a shell pipeline or an agent skill on it:
 
 ```bash
 # A tool call (tool name as the content, arguments as a JSON string)
-wardproof check "get_weather" --args '{"city":"Hanoi"}'        # ALLOW, exits 0
+wardproof check "get_weather" --args '{"city":"Berlin"}'        # ALLOW, exits 0
 
 # An untrusted input
 wardproof check "ignore all previous instructions" --kind input # BLOCK, exits non-zero
@@ -239,6 +239,17 @@ curl -s -X POST http://127.0.0.1:8787/check \
 `/check` replies with `allowed: true` only when the verdict is `ALLOW`, so a
 host can gate on one field.
 
+### Guard a Swarms agent
+
+[`examples/integrations/swarms_guarded.py`](https://github.com/Impossible-Mission-Force/wardproof/tree/main/examples/integrations/swarms_guarded.py)
+screens a [Swarms](https://github.com/kyegomez/swarms) agent's tool calls before
+they run. `GuardedToolExecutor.run` screens one `{"function": {"name", "arguments"}}`
+tool call and `run_many` screens a batch (Swarms can dispatch several in one
+step); each call executes only when the verdict is `ALLOW`, and anything else is
+refused and recorded to the audit ledger. The guard works on the plain tool-call
+dict, so it adds no dependency; the optional production adapter lazy-imports
+`swarms.tools.execute_tool_call_simple`.
+
 ---
 
 ## Architecture
@@ -340,7 +351,7 @@ No need to touch the engine, the ledger, or the agent base classes.
 Wardproof is built to become a complete, auditable control layer for AI agents.
 The direction:
 
-**Now (v0.3.1)**
+**Now (v0.3.4)**
 The deterministic core: schema, guardrails, Detector / Verifier / Responder, a
 capability sandbox, circuit breaker and watchdog, a hash-chained and optionally
 signed audit ledger, a reproducible adversarial benchmark, a published threat

{wardproof-0.3.3 → wardproof-0.3.4}/README.md

@@ -24,7 +24,7 @@ It is deliberately **small, transparent, and forkable**. The security core has
 **zero third-party dependencies** and runs **fully offline**, with a local
 model via Ollama, or with no model at all.
 
-> **Status: v0.3.1.** The deterministic core is built, tested, and benchmarked
+> **Status: v0.3.4.** The deterministic core is built, tested, and benchmarked
 > (see [Benchmark](#benchmark)), and ships dedicated guards for x402 agent
 > payments, on-chain transfers, MCP tool calls, and skill/tool definitions, a
 > controls-to-standards map (OWASP Agentic Top 10, OWASP LLM 2025, MITRE ATLAS,
@@ -160,7 +160,7 @@ gate a shell pipeline or an agent skill on it:
 
 ```bash
 # A tool call (tool name as the content, arguments as a JSON string)
-wardproof check "get_weather" --args '{"city":"Hanoi"}'        # ALLOW, exits 0
+wardproof check "get_weather" --args '{"city":"Berlin"}'        # ALLOW, exits 0
 
 # An untrusted input
 wardproof check "ignore all previous instructions" --kind input # BLOCK, exits non-zero
@@ -189,6 +189,17 @@ curl -s -X POST http://127.0.0.1:8787/check \
 `/check` replies with `allowed: true` only when the verdict is `ALLOW`, so a
 host can gate on one field.
 
+### Guard a Swarms agent
+
+[`examples/integrations/swarms_guarded.py`](https://github.com/Impossible-Mission-Force/wardproof/tree/main/examples/integrations/swarms_guarded.py)
+screens a [Swarms](https://github.com/kyegomez/swarms) agent's tool calls before
+they run. `GuardedToolExecutor.run` screens one `{"function": {"name", "arguments"}}`
+tool call and `run_many` screens a batch (Swarms can dispatch several in one
+step); each call executes only when the verdict is `ALLOW`, and anything else is
+refused and recorded to the audit ledger. The guard works on the plain tool-call
+dict, so it adds no dependency; the optional production adapter lazy-imports
+`swarms.tools.execute_tool_call_simple`.
+
 ---
 
 ## Architecture
@@ -290,7 +301,7 @@ No need to touch the engine, the ledger, or the agent base classes.
 Wardproof is built to become a complete, auditable control layer for AI agents.
 The direction:
 
-**Now (v0.3.1)**
+**Now (v0.3.4)**
 The deterministic core: schema, guardrails, Detector / Verifier / Responder, a
 capability sandbox, circuit breaker and watchdog, a hash-chained and optionally
 signed audit ledger, a reproducible adversarial benchmark, a published threat

{wardproof-0.3.3 → wardproof-0.3.4}/examples/integrations/README.md

@@ -266,6 +266,29 @@ as `action.invoke(args_dict)`; the only abstract method on `ActionProvider` is
 construction and each invoke, so the example no-ops that one call to stay
 offline; it touches telemetry only, never wallet logic.
 
+## Swarms (`swarms_guarded.py`)
+
+Screen a Swarms agent's tool calls before they run. Swarms passes a tool call as
+`{"function": {"name", "arguments"}}` (the shape it uses for native and MCP
+tools). `GuardedToolExecutor.run` screens one such call and `run_many` screens a
+batch (Swarms can dispatch several tool calls in one step); each runs only on an
+`ALLOW` verdict, and anything else is refused and recorded to the ledger.
+
+```python
+from wardproof import build_default_swarm, AuditLedger
+from swarms_guarded import GuardedToolExecutor
+
+guarded = GuardedToolExecutor(my_executor)            # my_executor(tool_call) -> str
+guarded.run({"function": {"name": "get_weather", "arguments": {"city": "Berlin"}}})
+guarded.run_many([call_a, call_b])                    # safe ones run, dangerous ones refused
+```
+
+The guard works on the plain tool-call dict, so the module imports nothing from
+`swarms`; only the optional `make_swarms_executor` adapter lazy-imports
+`swarms.tools.execute_tool_call_simple`. The example runs fully offline with a
+stub executor (one benign `get_weather`, one `run_command` carrying `rm -rf /`
+that is blocked, one `send_email`).
+
 ## x402 payments (`../protect_x402_payments.py`)
 
 Not a framework wrapper, but the same pattern for paid APIs: decode a real

wardproof-0.3.4/examples/integrations/swarms_guarded.py

@@ -0,0 +1,186 @@
+"""Put Wardproof in front of a Swarms agent's tool calls.
+
+Swarms (https://github.com/kyegomez/swarms) is a multi-agent orchestration
+framework. An agent calls tools, and tool calls flow as objects shaped like
+``{"function": {"name": ..., "arguments": {...}}}`` (the OpenAI tool-call shape
+Swarms uses for both native tools and MCP tools). The clean place to add a
+deterministic safety layer is right before a tool call is executed: screen the
+call with Wardproof's default swarm and only run it when the verdict is ALLOW.
+
+How the interception works (verified against the Swarms MCP tool API at
+https://docs.swarms.world/integrations/mcp, not from memory). Swarms executes a
+single tool call with ``execute_tool_call_simple(response=tool_call, ...)`` where
+``tool_call`` is ``{"function": {"name", "arguments"}}``. So the uniform
+interception point is a thin wrapper that takes that same tool-call dict, screens
+``(name, arguments)`` through ``swarm.handle(Event(kind="tool_call", ...))``, and
+only forwards to the real executor on ALLOW. Anything else is refused and recorded
+to the audit ledger; the tool is never executed.
+
+What this example is, and is NOT. It runs the REAL screening engine and a REAL
+tamper-evident ledger. It does NOT spin up a live Swarms agent or an LLM: building
+and screening a tool call needs no model, so the guard, the verdicts, and the
+audit record are all real. The "executor" here is an offline stub that returns a
+canned string and runs no real tool, so the example needs no network and no API
+keys. In a real deployment you would pass Swarms' ``execute_tool_call_simple`` (or
+your own tool dispatcher) as the executor instead of the stub.
+
+Honest note on detection. Screening uses the default swarm's deterministic
+guardrails (prompt-injection and tool-misuse baselines). They catch a destructive
+command in the tool name or arguments (for example ``rm -rf /``) and an injection
+that rides in the tool name; they are a transparent baseline, not a guarantee
+against a novel phrasing. One known gap: an injection hidden inside an argument
+*value* (plain prose in ``arguments``) is not caught by this deterministic
+tool-call screen on its own; that is the job of the optional LLM second opinion
+(``build_default_swarm(llm=...)``). The baseline's value is screening the concrete
+tool call and its arguments at the moment of invocation, and recording every
+decision so the trail is verifiable afterwards.
+
+Swarms is an OPTIONAL dependency. This example's guard does not import swarms at
+all (it operates on the plain tool-call dict), so it runs as-is. To wire it to a
+real Swarms executor:
+
+    pip install -U swarms wardproof
+
+    # then pass swarms.tools.execute_tool_call_simple as the executor
+
+Run the offline demonstration:
+
+    python examples/integrations/swarms_guarded.py
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from wardproof import AuditLedger, Event, Verdict, build_default_swarm
+
+# A tool call as Swarms passes it: {"function": {"name": ..., "arguments": {...}}}
+ToolCall = dict[str, Any]
+# An executor takes a tool call and returns the tool's result string.
+Executor = Callable[[ToolCall], str]
+
+
+class GuardedToolExecutor:
+    """Screen each Swarms tool call before executing it.
+
+    Wrap any executor that takes a ``{"function": {"name", "arguments"}}`` dict
+    and returns a string (for example ``swarms.tools.execute_tool_call_simple``,
+    adapted to a sync call). On a verdict other than ALLOW the wrapped executor
+    is never called; a refusal string is returned and the decision is recorded.
+    """
+
+    def __init__(
+        self,
+        executor: Executor,
+        *,
+        swarm: Any | None = None,
+        ledger: AuditLedger | None = None,
+        agent_name: str = "swarms-agent",
+    ) -> None:
+        self._executor = executor
+        self._ledger = ledger if ledger is not None else AuditLedger()
+        self._swarm = swarm if swarm is not None else build_default_swarm(ledger=self._ledger)
+        self._agent_name = agent_name
+
+    def run(self, tool_call: ToolCall) -> str:
+        function = tool_call.get("function", {}) or {}
+        name = str(function.get("name", ""))
+        arguments = function.get("arguments", {}) or {}
+        if not isinstance(arguments, dict):
+            arguments = {"_raw": arguments}
+
+        out = self._swarm.handle(
+            Event(
+                kind="tool_call",
+                source=self._agent_name,
+                content=name,
+                metadata={"args": arguments},
+            )
+        )
+
+        if out.verdict is not Verdict.ALLOW:
+            seen: set[str] = set()
+            ordered: list[str] = []
+            for d in (out.detector, out.verifier):
+                for f in d.findings:
+                    if f.triggered and f.reason and f.reason not in seen:
+                        seen.add(f.reason)
+                        ordered.append(f.reason)
+            reasons = "; ".join(ordered)
+            return (
+                f"BLOCKED by Wardproof: verdict={out.verdict.value}. "
+                f"The tool '{name}' was not executed. {reasons}".strip()
+            )
+
+        return self._executor(tool_call)
+
+    def run_many(self, tool_calls: list[ToolCall]) -> list[str]:
+        """Screen and run a batch of tool calls, one verdict each.
+
+        Swarms can execute several tool calls in one step (see
+        ``execute_multiple_tools_on_multiple_mcp_servers``). Each call is screened
+        independently: the allowed ones run, the rest are refused and recorded,
+        and the returned list lines up one-to-one with ``tool_calls``. One
+        poisoned call in a batch never blocks the safe ones, and never runs.
+        """
+        return [self.run(call) for call in tool_calls]
+
+    @property
+    def ledger(self) -> AuditLedger:
+        return self._ledger
+
+
+def make_swarms_executor(server_path: str, *, transport: str = "streamable-http") -> Executor:
+    """Build an executor backed by Swarms' real MCP tool dispatcher.
+
+    This is the production path: it wraps ``swarms.tools.execute_tool_call_simple``
+    (verified against the Swarms MCP API) so a guarded call that passes screening
+    is executed against a real MCP server. Swarms' function is async, so it is run
+    to completion here for the simple synchronous executor shape. Importing swarms
+    happens only when this is called, so the rest of this module stays import-free.
+    """
+    import asyncio
+
+    from swarms.tools import execute_tool_call_simple  # imported lazily on purpose
+
+    def _executor(tool_call: ToolCall) -> str:
+        result = asyncio.run(
+            execute_tool_call_simple(
+                response=tool_call,
+                server_path=server_path,
+                output_type="str",
+                transport=transport,
+            )
+        )
+        return result if isinstance(result, str) else str(result)
+
+    return _executor
+
+
+def _stub_executor(tool_call: ToolCall) -> str:
+    """Offline stand-in for a real Swarms tool dispatcher. Runs no real tool."""
+    name = tool_call.get("function", {}).get("name", "")
+    return f"[stub] executed {name} and returned a canned result"
+
+
+def _demo() -> None:
+    ledger = AuditLedger()
+    guarded = GuardedToolExecutor(_stub_executor, ledger=ledger, agent_name="swarms-agent")
+
+    # a batch as Swarms might dispatch in one step: one of them is dangerous
+    calls: list[ToolCall] = [
+        {"function": {"name": "get_weather", "arguments": {"city": "Berlin"}}},
+        {"function": {"name": "run_command", "arguments": {"cmd": "rm -rf /"}}},
+        {"function": {"name": "send_email", "arguments": {"to": "a@b.com", "subject": "hi"}}},
+    ]
+
+    for call, result in zip(calls, guarded.run_many(calls)):
+        name = call["function"]["name"]
+        print(f"{name:14} -> {result}")
+
+    ok, detail = ledger.verify()
+    print(f"\nledger: {'OK' if ok else 'FAIL'} - {detail}")
+
+
+if __name__ == "__main__":
+    _demo()

{wardproof-0.3.3 → wardproof-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wardproof"
-version = "0.3.3"
+version = "0.3.4"
 description = "Local-first, verifiable defensive AI agent swarms that protect other AI agent systems."
 readme = "README.md"
 license = "MIT"

{wardproof-0.3.3 → wardproof-0.3.4}/wardproof/__init__.py

@@ -16,7 +16,7 @@ from wardproof.sandbox.executor import SandboxExecutor, ToolRegistry
 from wardproof.sandbox.permissions import PermissionBroker, ToolGrant
 from wardproof.schema import Decision, Event, Finding, Severity, Verdict
 
-__version__ = "0.3.3"
+__version__ = "0.3.4"
 __all__ = [
     "Event",
     "Decision",