wardproof 0.3.4__tar.gz → 0.3.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wardproof
-Version: 0.3.4
+Version: 0.3.6
 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.4.** The deterministic core is built, tested, and benchmarked
+> **Status: v0.3.6.** 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,
@@ -351,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.4)**
+**Now (v0.3.6)**
 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
@@ -365,7 +365,7 @@ STIX 2.1 ledger export; screening harnesses for the public AgentDojo and
 InjecAgent suites; and drop-in integration examples for OpenAI and Anthropic tool
 calling, CrewAI, LangGraph, MCP, and Coinbase AgentKit, plus Venice AI as an
 optional escalate-only second-opinion backend (alongside the existing Ollama
-backend).
+backend). The local screening service can require a bearer token, rate-limit per client, and cap request size, all from the standard library.
 
 **Next**
 - A bundled local semantic detection layer that ships by default alongside the

{wardproof-0.3.4 → wardproof-0.3.6}/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.4.** The deterministic core is built, tested, and benchmarked
+> **Status: v0.3.6.** 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,
@@ -301,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.4)**
+**Now (v0.3.6)**
 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
@@ -315,7 +315,7 @@ STIX 2.1 ledger export; screening harnesses for the public AgentDojo and
 InjecAgent suites; and drop-in integration examples for OpenAI and Anthropic tool
 calling, CrewAI, LangGraph, MCP, and Coinbase AgentKit, plus Venice AI as an
 optional escalate-only second-opinion backend (alongside the existing Ollama
-backend).
+backend). The local screening service can require a bearer token, rate-limit per client, and cap request size, all from the standard library.
 
 **Next**
 - A bundled local semantic detection layer that ships by default alongside the

{wardproof-0.3.4 → wardproof-0.3.6}/examples/integrations/swarms_guarded.py

@@ -50,7 +50,8 @@ Run the offline demonstration:
 
 from __future__ import annotations
 
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 from wardproof import AuditLedger, Event, Verdict, build_default_swarm
 
@@ -174,7 +175,7 @@ def _demo() -> None:
         {"function": {"name": "send_email", "arguments": {"to": "a@b.com", "subject": "hi"}}},
     ]
 
-    for call, result in zip(calls, guarded.run_many(calls)):
+    for call, result in zip(calls, guarded.run_many(calls), strict=True):
         name = call["function"]["name"]
         print(f"{name:14} -> {result}")
 

wardproof-0.3.6/examples/integrations/wardproof-guard.js

@@ -0,0 +1,122 @@
+// wardproof-guard.js
+//
+// Integration pattern suggested in a thread with Bankr (@bankrbot):
+// https://x.com/bankrbot/status/2062101930273599518
+//
+// Thin client + Express middleware that screens an agent's tool calls and
+// untrusted inputs through a running `wardproof serve` instance before they
+// run. The wardproof engine is the source of truth; this file embeds no rules.
+//
+// Fail-closed: anything other than a clean allow (a network error, a timeout,
+// a non-200 response, a malformed body, or a verdict that is not "allow")
+// raises WardproofBlocked, so a failure never silently lets an action through.
+//
+// Wire shape (wardproof serve 0.3.6):
+//   POST /check  with  Authorization: Bearer <token>  content-type application/json
+//   request:  { kind: "tool_call"|"input", content: string, source?: string, args?: object }
+//   response: { verdict: string, allowed: boolean, risk: number, reasons: string[] }
+//   verdict is lowercase ("allow" | "block" | "quarantine" | "escalate" | "sanitize").
+//   The decision is taken from `allowed` (a boolean), so verdict casing never matters.
+
+class WardproofBlocked extends Error {
+  constructor(verdict, reasons, data) {
+    super(`wardproof blocked: ${verdict} ${JSON.stringify(reasons || [])}`);
+    this.name = "WardproofBlocked";
+    this.verdict = verdict;
+    this.reasons = reasons || [];
+    this.data = data || null;
+  }
+}
+
+function makeGuard({ url, token, timeoutMs = 5000 }) {
+  if (!url) throw new Error("makeGuard: url is required (the wardproof serve address)");
+  const base = url.replace(/\/+$/, "");
+
+  async function check(payload) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    let res;
+    try {
+      const headers = { "content-type": "application/json" };
+      if (token) headers["authorization"] = `Bearer ${token}`;
+      res = await fetch(`${base}/check`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+    } catch (err) {
+      // network error or timeout: fail closed
+      throw new WardproofBlocked("UNREACHABLE", [`fetch: ${err.message}`], null);
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new WardproofBlocked(`HTTP_${res.status}`, [text.slice(0, 200)], null);
+    }
+
+    let data;
+    try {
+      data = await res.json();
+    } catch (err) {
+      throw new WardproofBlocked("BAD_RESPONSE", ["response was not valid JSON"], null);
+    }
+
+    if (!data || typeof data.allowed !== "boolean") {
+      throw new WardproofBlocked("BAD_RESPONSE", ["missing boolean 'allowed' field"], data);
+    }
+
+    // the engine's decision; do not second-guess it locally
+    if (data.allowed !== true) {
+      throw new WardproofBlocked(data.verdict || "block", data.reasons || [], data);
+    }
+
+    return data; // { verdict, allowed: true, risk, reasons }
+  }
+
+  // wrap an arbitrary async tool function so its call is screened first
+  function wrap(toolName, fn) {
+    return async function screened(args) {
+      await check({ kind: "tool_call", content: toolName, args: args || {} });
+      return fn(args);
+    };
+  }
+
+  // screen a piece of untrusted text before feeding it to the model
+  async function screenInput(text, meta) {
+    return check({ kind: "input", content: String(text), args: meta || {} });
+  }
+
+  return { check, wrap, screenInput, WardproofBlocked };
+}
+
+// Optional Express middleware: screen the request body (or a picked field)
+// before the handler runs. Returns 403 with the verdict and reasons on block.
+function wardproofMiddleware({ url, token, kind = "input", pick }) {
+  const guard = makeGuard({ url, token });
+  return async function (req, res, next) {
+    try {
+      const content = pick ? pick(req) : req.body;
+      await guard.check({
+        kind,
+        content: typeof content === "string" ? content : JSON.stringify(content || {}),
+        args: { path: req.path, method: req.method },
+      });
+      next();
+    } catch (err) {
+      if (err instanceof WardproofBlocked) {
+        return res.status(403).json({
+          error: "wardproof_blocked",
+          verdict: err.verdict,
+          reasons: err.reasons,
+        });
+      }
+      next(err);
+    }
+  };
+}
+
+module.exports = { makeGuard, wardproofMiddleware, WardproofBlocked };

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

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

{wardproof-0.3.4 → wardproof-0.3.6}/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.4"
+__version__ = "0.3.6"
 __all__ = [
     "Event",
     "Decision",

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

@@ -104,6 +104,25 @@ def main(argv: list[str] | None = None) -> int:
     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)")
+    rp.add_argument(
+        "--token",
+        default=None,
+        help="require this bearer token on /check (or set WARDPROOF_TOKEN)",
+    )
+    rp.add_argument(
+        "--rate-limit",
+        type=int,
+        default=0,
+        dest="rate_limit",
+        help="max /check requests per client per second (0 disables)",
+    )
+    rp.add_argument(
+        "--max-body",
+        type=int,
+        default=256 * 1024,
+        dest="max_body",
+        help="reject a /check body larger than this many bytes",
+    )
     args = parser.parse_args(argv)
     if args.cmd == "verify-ledger":
         return _verify_file(args.path, args.pubkey)
@@ -114,7 +133,13 @@ def main(argv: list[str] | None = None) -> int:
     if args.cmd == "serve":
         from wardproof.server import serve
 
-        serve(host=args.host, port=args.port)
+        serve(
+            host=args.host,
+            port=args.port,
+            token=args.token,
+            rate_limit=args.rate_limit,
+            max_body=args.max_body,
+        )
         return 0
     return 1
 

wardproof-0.3.6/wardproof/server.py

@@ -0,0 +1,221 @@
+"""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. For setups where it is reachable by more than one local caller, it
+supports an optional bearer token, a simple per-client rate limit, and a request
+body size cap, all from the standard library.
+
+Endpoints:
+  GET  /health  -> {"status": "ok", "version": "..."}  (never requires a token)
+  POST /check   -> body: {"kind": "tool_call"|"input", "content": "...",
+                          "source": "...", "args": {...}}
+                  reply: {"verdict": "...", "allowed": true|false,
+                          "risk": 0.0, "reasons": [...]}
+
+Hardening (all optional, all stdlib):
+  - token: if set, /check requires "Authorization: Bearer <token>"; the compare
+    is constant-time. A token may also be supplied via the WARDPROOF_TOKEN
+    environment variable.
+  - rate_limit: max requests per client IP per second (0 disables).
+  - max_body: reject a /check body larger than this many bytes (fail closed).
+"""
+
+from __future__ import annotations
+
+import hmac
+import json
+import os
+import sys
+import time
+import traceback
+from collections import defaultdict, deque
+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
+
+# default cap on a /check request body; a screen payload is small
+DEFAULT_MAX_BODY = 256 * 1024
+
+
+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,
+    }
+
+
+class _RateLimiter:
+    """A tiny fixed-window-per-second limiter keyed by client.
+
+    Keeps the timestamps of recent requests per key and rejects once more than
+    ``limit`` fall inside the trailing one-second window. Not distributed and
+    not meant to be; it protects a single local process from a runaway caller.
+    """
+
+    def __init__(self, limit: int) -> None:
+        self.limit = limit
+        self._hits: dict[str, deque[float]] = defaultdict(deque)
+
+    def allow(self, key: str) -> bool:
+        if self.limit <= 0:
+            return True
+        now = time.monotonic()
+        window = self._hits[key]
+        cutoff = now - 1.0
+        while window and window[0] < cutoff:
+            window.popleft()
+        if len(window) >= self.limit:
+            return False
+        window.append(now)
+        return True
+
+
+def _make_handler(
+    swarm: Any,
+    token: str | None,
+    rate_limit: int,
+    max_body: int,
+) -> type[BaseHTTPRequestHandler]:
+    limiter = _RateLimiter(rate_limit)
+
+    class Handler(BaseHTTPRequestHandler):
+        # one shared swarm for every request
+        _swarm = swarm
+        _token = token
+        _limiter = limiter
+        _max_body = max_body
+
+        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 _client_key(self) -> str:
+            addr = self.client_address[0] if self.client_address else "unknown"
+            return str(addr)
+
+        def _authorized(self) -> bool:
+            if not self._token:
+                return True
+            header = self.headers.get("Authorization", "")
+            prefix = "Bearer "
+            if not header.startswith(prefix):
+                return False
+            presented = header[len(prefix):].strip()
+            # constant-time compare to avoid leaking the token by timing
+            return hmac.compare_digest(presented, self._token)
+
+        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
+            if not self._limiter.allow(self._client_key()):
+                self._send(429, {"error": "rate limit exceeded"})
+                return
+            if not self._authorized():
+                self._send(401, {"error": "missing or invalid bearer token"})
+                return
+            try:
+                length = int(self.headers.get("Content-Length", 0))
+            except (TypeError, ValueError):
+                length = 0
+            if length > self._max_body:
+                self._send(413, {"error": "request body too large"})
+                return
+            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:  # fail closed: never 200 a non-screened request
+                # log the real cause for the operator; never leak it to the client
+                print("wardproof serve: screen failed", file=sys.stderr)
+                traceback.print_exc(file=sys.stderr)
+                self._send(500, {"error": "internal error"})
+
+        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,
+    token: str | None = None,
+    rate_limit: int = 0,
+    max_body: int = DEFAULT_MAX_BODY,
+) -> None:
+    """Build the swarm once and serve until interrupted.
+
+    Args:
+        host: bind address; defaults to localhost.
+        port: bind port.
+        token: if set (or if WARDPROOF_TOKEN is set), /check requires a matching
+            "Authorization: Bearer <token>" header.
+        rate_limit: max /check requests per client IP per second; 0 disables.
+        max_body: reject a /check body larger than this many bytes.
+    """
+    token = token or os.environ.get("WARDPROOF_TOKEN") or None
+
+    swarm = build_default_swarm()
+    handler = _make_handler(swarm, token=token, rate_limit=rate_limit, max_body=max_body)
+    httpd = ThreadingHTTPServer((host, port), handler)
+    auth_note = "token required" if token else "no token"
+    print(
+        f"wardproof serve: screening on http://{host}:{port}  "
+        f"(POST /check, GET /health; {auth_note})"
+    )
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        httpd.server_close()

wardproof-0.3.4/wardproof/server.py

@@ -1,119 +0,0 @@
-"""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()