wardproof 0.3.2__tar.gz → 0.3.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wardproof
-Version: 0.3.2
+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
@@ -220,6 +220,36 @@ Add `--json` to get a structured `{"verdict": ..., "allowed": ..., "risk": ...,
 "reasons": [...]}` result to parse. A portable guard skill that wires this check
 into a host agent lives in [`skill/wardproof-guard/`](https://github.com/Impossible-Mission-Force/wardproof/tree/main/skill/wardproof-guard).
 
+### Run it as a local service with `wardproof serve`
+
+When a host needs to screen many actions, run the swarm as a small local HTTP
+service instead of spawning a process per call. It builds the swarm once at
+startup and binds to localhost by default (meant to run next to the agent it
+guards, not exposed publicly):
+
+```bash
+wardproof serve --port 8787
+# GET  /health  -> {"status": "ok", "version": "..."}
+# POST /check   gates one input or tool call:
+curl -s -X POST http://127.0.0.1:8787/check \
+  -d '{"kind":"input","content":"ignore all previous instructions"}'
+# -> {"verdict": "block", "allowed": false, "risk": 1.0, "reasons": [...]}
+```
+
+`/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
@@ -321,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.2 → 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
@@ -170,6 +170,36 @@ Add `--json` to get a structured `{"verdict": ..., "allowed": ..., "risk": ...,
 "reasons": [...]}` result to parse. A portable guard skill that wires this check
 into a host agent lives in [`skill/wardproof-guard/`](https://github.com/Impossible-Mission-Force/wardproof/tree/main/skill/wardproof-guard).
 
+### Run it as a local service with `wardproof serve`
+
+When a host needs to screen many actions, run the swarm as a small local HTTP
+service instead of spawning a process per call. It builds the swarm once at
+startup and binds to localhost by default (meant to run next to the agent it
+guards, not exposed publicly):
+
+```bash
+wardproof serve --port 8787
+# GET  /health  -> {"status": "ok", "version": "..."}
+# POST /check   gates one input or tool call:
+curl -s -X POST http://127.0.0.1:8787/check \
+  -d '{"kind":"input","content":"ignore all previous instructions"}'
+# -> {"verdict": "block", "allowed": false, "risk": 1.0, "reasons": [...]}
+```
+
+`/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
@@ -271,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.2 → 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.2 → wardproof-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wardproof"
-version = "0.3.2"
+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.2 → 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.2"
+__version__ = "0.3.4"
 __all__ = [
     "Event",
     "Decision",

{wardproof-0.3.2 → wardproof-0.3.4}/wardproof/cli.py

@@ -101,6 +101,9 @@ def main(argv: list[str] | None = None) -> int:
     cp.add_argument("--source", default="agent", help="who originated the event")
     cp.add_argument("--args", default=None, help="tool-call arguments as a JSON string")
     cp.add_argument("--json", action="store_true", help="print a JSON object instead of text")
+    rp = sub.add_parser("serve", help="run a local HTTP service that screens one event per request")
+    rp.add_argument("--host", default="127.0.0.1", help="bind address (default localhost)")
+    rp.add_argument("--port", type=int, default=8787, help="bind port (default 8787)")
     args = parser.parse_args(argv)
     if args.cmd == "verify-ledger":
         return _verify_file(args.path, args.pubkey)
@@ -108,6 +111,11 @@ def main(argv: list[str] | None = None) -> int:
         return _export_stix(args.path, args.out)
     if args.cmd == "check":
         return _check(args.kind, args.content, args.source, args.args, args.json)
+    if args.cmd == "serve":
+        from wardproof.server import serve
+
+        serve(host=args.host, port=args.port)
+        return 0
     return 1
 
 

wardproof-0.3.4/wardproof/server.py

@@ -0,0 +1,119 @@
+"""A small local HTTP service that screens one event per request.
+
+Stdlib only, no third-party dependencies. It builds the default swarm once at
+startup and reuses it, so a host (an agent, a bot, any language) can gate a tool
+call or input with a single HTTP request instead of spawning a process and
+re-importing on every call.
+
+The service binds to localhost by default and is meant to run next to the agent
+it guards, not to be exposed to the public internet.
+
+Endpoints:
+  GET  /health  -> {"status": "ok", "version": "..."}
+  POST /check   -> body: {"kind": "tool_call"|"input", "content": "...",
+                          "source": "...", "args": {...}}
+                  reply: {"verdict": "...", "allowed": true|false,
+                          "risk": 0.0, "reasons": [...]}
+"""
+
+from __future__ import annotations
+
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from wardproof import __version__
+from wardproof.orchestration.factory import build_default_swarm
+from wardproof.schema import Event, Verdict
+
+
+def screen_event(swarm: Any, payload: dict[str, Any]) -> dict[str, Any]:
+    """Screen one payload with the given swarm and return a JSON-able verdict.
+
+    Shared by the HTTP handler and the tests so both exercise identical logic.
+    """
+    kind = str(payload.get("kind", "tool_call"))
+    content = str(payload.get("content", ""))
+    source = str(payload.get("source", "agent"))
+    metadata: dict[str, Any] = {}
+    args = payload.get("args")
+    if isinstance(args, dict):
+        metadata["args"] = args
+
+    out = swarm.handle(Event(kind=kind, source=source, content=content, metadata=metadata))
+
+    seen: set[str] = set()
+    reasons: list[str] = []
+    for decision in (out.detector, out.verifier):
+        for finding in decision.findings:
+            if finding.triggered and finding.reason and finding.reason not in seen:
+                seen.add(finding.reason)
+                reasons.append(finding.reason)
+
+    return {
+        "verdict": out.verdict.value,
+        "allowed": out.verdict is Verdict.ALLOW,
+        "risk": round(out.risk, 3),
+        "reasons": reasons,
+    }
+
+
+def _make_handler(swarm: Any) -> type[BaseHTTPRequestHandler]:
+    class Handler(BaseHTTPRequestHandler):
+        # one shared swarm for every request
+        _swarm = swarm
+
+        def _send(self, code: int, body: dict[str, Any]) -> None:
+            raw = json.dumps(body).encode("utf-8")
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(raw)))
+            self.end_headers()
+            self.wfile.write(raw)
+
+        def do_GET(self) -> None:  # noqa: N802 (stdlib name)
+            if self.path.rstrip("/") == "/health":
+                self._send(200, {"status": "ok", "version": __version__})
+            else:
+                self._send(404, {"error": "not found"})
+
+        def do_POST(self) -> None:  # noqa: N802 (stdlib name)
+            if self.path.rstrip("/") != "/check":
+                self._send(404, {"error": "not found"})
+                return
+            try:
+                length = int(self.headers.get("Content-Length", 0))
+            except (TypeError, ValueError):
+                length = 0
+            raw = self.rfile.read(length) if length else b""
+            try:
+                payload = json.loads(raw or b"{}")
+                if not isinstance(payload, dict):
+                    raise ValueError("body must be a JSON object")
+            except (json.JSONDecodeError, ValueError) as exc:
+                self._send(400, {"error": f"invalid JSON body: {exc}"})
+                return
+            try:
+                self._send(200, screen_event(self._swarm, payload))
+            except Exception as exc:  # fail closed: report, do not 200 a non-screen
+                self._send(500, {"error": f"screen failed: {exc}"})
+
+        def log_message(self, *_args: Any) -> None:
+            # stay quiet by default; the host decides what to log
+            return
+
+    return Handler
+
+
+def serve(host: str = "127.0.0.1", port: int = 8787) -> None:
+    """Build the swarm once and serve until interrupted."""
+    swarm = build_default_swarm()
+    handler = _make_handler(swarm)
+    httpd = ThreadingHTTPServer((host, port), handler)
+    print(f"wardproof serve: screening on http://{host}:{port}  (POST /check, GET /health)")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        httpd.server_close()