wardproof 0.1.0__py3-none-any.whl

wardproof/__init__.py

@@ -0,0 +1,40 @@
+"""Wardproof, local-first, verifiable defensive AI agent swarms."""
+
+from wardproof.agents.base import BaseDefensiveAgent
+from wardproof.agents.detector import DetectorAgent
+from wardproof.agents.responder import ResponderAgent
+from wardproof.agents.verifier import VerifierAgent
+from wardproof.audit.ledger import AuditLedger
+from wardproof.orchestration.engine import (
+    CircuitBreaker,
+    Outcome,
+    SwarmOrchestrator,
+    Watchdog,
+)
+from wardproof.orchestration.factory import build_default_swarm
+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.1.0"
+__all__ = [
+    "Event",
+    "Decision",
+    "Finding",
+    "Verdict",
+    "Severity",
+    "AuditLedger",
+    "BaseDefensiveAgent",
+    "DetectorAgent",
+    "VerifierAgent",
+    "ResponderAgent",
+    "SwarmOrchestrator",
+    "Watchdog",
+    "CircuitBreaker",
+    "Outcome",
+    "build_default_swarm",
+    "PermissionBroker",
+    "ToolGrant",
+    "SandboxExecutor",
+    "ToolRegistry",
+]

wardproof/agents/__init__.py

@@ -0,0 +1,14 @@
+"""Defensive agents: Detector, Verifier, Responder, and the base class."""
+
+from wardproof.agents.base import BaseDefensiveAgent
+from wardproof.agents.detector import DetectorAgent
+from wardproof.agents.responder import ResponderAgent, Response
+from wardproof.agents.verifier import VerifierAgent
+
+__all__ = [
+    "BaseDefensiveAgent",
+    "DetectorAgent",
+    "VerifierAgent",
+    "ResponderAgent",
+    "Response",
+]

wardproof/agents/base.py

@@ -0,0 +1,90 @@
+"""Base class for every defensive agent in the swarm.
+
+Lifecycle of ``process(event)``:
+    1. run_guardrails  -> deterministic Findings, each recorded to the ledger
+    2. decide          -> subclass turns Findings (+ optional LLM 2nd opinion)
+                          into a Decision
+    3. the Decision itself is recorded to the ledger
+
+Key principles baked in here:
+  * Guardrails run first and always, with or without an LLM.
+  * Every step is written to an append-only audit ledger the agent does not own.
+  * The agent's own LLM is treated as UNTRUSTED, subclasses must never let it
+    downgrade a hard guardrail signal (see DetectorAgent / VerifierAgent).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from wardproof.audit.ledger import AuditLedger
+from wardproof.guardrails.base import Guardrail
+from wardproof.llm.base import LLMClient
+from wardproof.llm.null import NullLLM
+from wardproof.schema import Decision, Event, Finding
+
+
+class BaseDefensiveAgent(ABC):
+    role: str = "agent"
+
+    def __init__(
+        self,
+        agent_id: str,
+        *,
+        guardrails: list[Guardrail] | None = None,
+        ledger: AuditLedger | None = None,
+        llm: LLMClient | None = None,
+    ) -> None:
+        self.agent_id = agent_id
+        self.guardrails = guardrails or []
+        self.ledger = ledger or AuditLedger()
+        self.llm = llm or NullLLM()
+
+    def run_guardrails(self, event: Event) -> list[Finding]:
+        findings: list[Finding] = []
+        for guard in self.guardrails:
+            if not guard.applies_to(event):
+                continue
+            finding = guard.inspect(event)
+            findings.append(finding)
+            if finding.triggered:
+                self.ledger.append(
+                    actor=self.agent_id,
+                    action="guardrail_triggered",
+                    data={
+                        "event_id": event.id,
+                        "guardrail": finding.guardrail,
+                        "risk": finding.risk,
+                        "severity": finding.severity.value,
+                        "reason": finding.reason,
+                    },
+                )
+        return findings
+
+    @abstractmethod
+    def decide(self, event: Event, findings: list[Finding]) -> Decision: ...
+
+    def process(self, event: Event) -> Decision:
+        findings = self.run_guardrails(event)
+        decision = self.decide(event, findings)
+        self.ledger.append(
+            actor=self.agent_id,
+            action="decision",
+            data={
+                "event_id": event.id,
+                "verdict": decision.verdict.value,
+                "risk": decision.risk,
+                "rationale": decision.rationale,
+                "role": self.role,
+            },
+        )
+        return decision
+
+    # Convenience for subclasses that want an LLM second opinion safely.
+    def _llm_opinion(self, system: str, user: str) -> str:
+        if not self.llm.available:
+            return ""
+        try:
+            return self.llm.complete(system, user)
+        except Exception:  # pragma: no cover - never let the LLM crash defence
+            return ""

wardproof/agents/detector.py

@@ -0,0 +1,70 @@
+"""Detector, first-pass triage.
+
+Aggregates guardrail findings into a single risk score and maps it to a verdict
+using two thresholds. The LLM (if any) may only *raise* concern, never lower it:
+its suggestion is clamped so it cannot pull risk below the deterministic floor.
+"""
+
+from __future__ import annotations
+
+from wardproof.agents.base import BaseDefensiveAgent
+from wardproof.schema import Decision, Event, Finding, Verdict, max_severity
+
+_SYSTEM = (
+    "You are a security detector. Given an event, reply with a single float "
+    "0.0-1.0 estimating how likely it is malicious. Reply with ONLY the number."
+)
+
+
+class DetectorAgent(BaseDefensiveAgent):
+    role = "detector"
+
+    def __init__(
+        self, *args: object, low: float = 0.2, high: float = 0.6, **kwargs: object
+    ) -> None:
+        super().__init__(*args, **kwargs)  # type: ignore[arg-type]
+        self.low = low
+        self.high = high
+
+    def _deterministic_risk(self, findings: list[Finding]) -> float:
+        if not findings:
+            return 0.0
+        return max((f.risk for f in findings), default=0.0)
+
+    def _llm_adjust(self, event: Event, floor: float) -> float:
+        raw = self._llm_opinion(_SYSTEM, event.content[:2000])
+        if not raw:
+            return floor
+        try:
+            guess = float(raw.strip().split()[0])
+        except (ValueError, IndexError):
+            return floor
+        # LLM may only escalate. Never trust it to reduce risk.
+        return max(floor, min(1.0, guess))
+
+    def decide(self, event: Event, findings: list[Finding]) -> Decision:
+        floor = self._deterministic_risk(findings)
+        risk = self._llm_adjust(event, floor)
+        triggered = [f for f in findings if f.triggered]
+        severity = max_severity([f.severity for f in triggered]) if triggered else None
+
+        if risk >= self.high:
+            verdict = (
+                Verdict.QUARANTINE if event.kind in ("memory_write", "tool_call") else Verdict.BLOCK
+            )
+        elif risk >= self.low:
+            verdict = Verdict.ESCALATE
+        else:
+            verdict = Verdict.ALLOW
+
+        reasons = "; ".join(f.reason for f in triggered) or "no guardrail signal"
+        rationale = f"risk={risk:.2f} (floor={floor:.2f}); {reasons}"
+        return Decision(
+            agent_id=self.agent_id,
+            event_id=event.id,
+            verdict=verdict,
+            risk=risk,
+            findings=findings,
+            rationale=rationale,
+            metadata={"severity": severity.value if severity else "info"},
+        )

wardproof/agents/responder.py

@@ -0,0 +1,88 @@
+"""Responder, turns a verdict into a concrete action.
+
+Mapping:
+    ALLOW       -> pass through, no action
+    SANITIZE    -> return cleaned content (strip injection markers)
+    ESCALATE    -> hand to a human review queue (here: record + flag)
+    QUARANTINE  -> invoke a mitigation tool (e.g. quarantine_chunk, freeze_account)
+    BLOCK       -> invoke a mitigation tool and refuse
+
+The Responder is the only agent allowed to *act*, and it acts through the
+sandbox executor so every mitigation is itself permission-checked and audited.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from wardproof.audit.ledger import AuditLedger
+from wardproof.guardrails.prompt_injection import strip_injection
+from wardproof.llm.base import LLMClient
+from wardproof.llm.null import NullLLM
+from wardproof.sandbox.executor import SandboxExecutor
+from wardproof.schema import Decision, Event, Verdict
+
+
+@dataclass
+class Response:
+    action: str
+    detail: str
+    payload: Any = None
+
+
+class ResponderAgent:
+    role = "responder"
+
+    def __init__(
+        self,
+        agent_id: str,
+        *,
+        ledger: AuditLedger | None = None,
+        executor: SandboxExecutor | None = None,
+        mitigations: dict[Verdict, str] | None = None,
+        llm: LLMClient | None = None,
+    ) -> None:
+        self.agent_id = agent_id
+        self.ledger = ledger or AuditLedger()
+        self.executor = executor
+        self.llm = llm or NullLLM()
+        # Which sandbox tool to call for BLOCK / QUARANTINE verdicts.
+        self.mitigations = mitigations or {}
+
+    def _mitigate(self, event: Event, verdict: Verdict) -> Response:
+        tool = self.mitigations.get(verdict)
+        if tool and self.executor is not None:
+            result = self.executor.run(
+                self.agent_id,
+                tool,
+                {"event_id": event.id, "source": event.source},
+            )
+            detail = f"ran mitigation '{tool}': {result}"
+        else:
+            detail = f"{verdict.value} (no mitigation tool configured)"
+        return Response(action=verdict.value, detail=detail)
+
+    def respond(self, event: Event, decision: Decision) -> Response:
+        v = decision.verdict
+        if v == Verdict.ALLOW:
+            resp = Response("allow", "passed through")
+        elif v == Verdict.SANITIZE:
+            cleaned = strip_injection(event.content)
+            resp = Response("sanitize", "stripped injection markers", payload=cleaned)
+        elif v == Verdict.ESCALATE:
+            resp = Response("escalate", "queued for human review")
+        else:  # QUARANTINE or BLOCK
+            resp = self._mitigate(event, v)
+
+        self.ledger.append(
+            actor=self.agent_id,
+            action="response",
+            data={
+                "event_id": event.id,
+                "verdict": v.value,
+                "action": resp.action,
+                "detail": resp.detail,
+            },
+        )
+        return resp

wardproof/agents/verifier.py

@@ -0,0 +1,93 @@
+"""Verifier, independent second opinion + detector integrity check.
+
+The Verifier exists to catch two failure modes:
+  1. The event really is malicious and slipped past (false negative).
+  2. The Detector ITSELF has been compromised/poisoned and is rubber-stamping
+     dangerous events (insider/collusion). If the Detector said ALLOW while the
+     deterministic guardrails clearly fired high risk, that is an integrity
+     alarm, we quarantine and flag it loudly.
+
+It re-runs its own guardrails rather than trusting the Detector's findings.
+"""
+
+from __future__ import annotations
+
+from wardproof.agents.base import BaseDefensiveAgent
+from wardproof.schema import (
+    Decision,
+    Event,
+    Finding,
+    Verdict,
+    max_severity,
+    stricter_verdict,
+)
+
+
+class VerifierAgent(BaseDefensiveAgent):
+    role = "verifier"
+
+    def __init__(self, *args: object, high: float = 0.6, **kwargs: object) -> None:
+        super().__init__(*args, **kwargs)  # type: ignore[arg-type]
+        self.high = high
+
+    def decide(self, event: Event, findings: list[Finding]) -> Decision:
+        # Independent verdict from this agent's own guardrail pass.
+        risk = max((f.risk for f in findings if f.triggered), default=0.0)
+        if risk >= self.high:
+            verdict = (
+                Verdict.QUARANTINE if event.kind in ("memory_write", "tool_call") else Verdict.BLOCK
+            )
+        elif risk > 0.0:
+            verdict = Verdict.ESCALATE
+        else:
+            verdict = Verdict.ALLOW
+        triggered = [f for f in findings if f.triggered]
+        sev = max_severity([f.severity for f in triggered]) if triggered else None
+        rationale = f"independent risk={risk:.2f}"
+        return Decision(
+            self.agent_id,
+            event.id,
+            verdict,
+            risk,
+            findings,
+            rationale,
+            metadata={"severity": sev.value if sev else "info"},
+        )
+
+    def verify(self, event: Event, detector_decision: Decision) -> Decision:
+        """Cross-check a Detector's decision. Fail-closed: combine to the
+        stricter verdict, and raise an integrity alarm on suspicious leniency."""
+        own = self.process(event)
+        combined = stricter_verdict(own.verdict, detector_decision.verdict)
+        integrity_alarm = False
+
+        # Detector said it's fine, but the deterministic floor says otherwise.
+        if detector_decision.verdict == Verdict.ALLOW and own.risk >= self.high:
+            integrity_alarm = True
+            combined = stricter_verdict(combined, Verdict.QUARANTINE)
+            self.ledger.append(
+                actor=self.agent_id,
+                action="integrity_alarm",
+                data={
+                    "event_id": event.id,
+                    "suspect_agent": detector_decision.agent_id,
+                    "detector_verdict": detector_decision.verdict.value,
+                    "verifier_risk": own.risk,
+                    "note": "detector allowed a high-risk event; possible compromise",
+                },
+            )
+
+        risk = max(own.risk, detector_decision.risk)
+        rationale = (
+            f"verifier={own.verdict.value} detector={detector_decision.verdict.value} "
+            f"-> {combined.value}" + (" [INTEGRITY ALARM]" if integrity_alarm else "")
+        )
+        return Decision(
+            agent_id=self.agent_id,
+            event_id=event.id,
+            verdict=combined,
+            risk=risk,
+            findings=own.findings,
+            rationale=rationale,
+            metadata={"integrity_alarm": integrity_alarm},
+        )

wardproof/audit/__init__.py

@@ -0,0 +1,5 @@
+"""Tamper-evident, append-only audit ledger (hash chain + optional signatures)."""
+
+from wardproof.audit.ledger import AuditEntry, AuditLedger
+
+__all__ = ["AuditLedger", "AuditEntry"]

wardproof/audit/ledger.py

@@ -0,0 +1,158 @@
+"""Tamper-evident audit ledger.
+
+Two layers of integrity, both optional to set up but always verifiable:
+  1. Hash chain  -> stdlib only (hashlib). Detects any mutation/reordering/deletion.
+  2. Ed25519 signatures -> requires `cryptography`. Proves WHO appended each entry.
+
+Design rule: the ledger is append-only and lives OUTSIDE the agents it audits.
+An agent can write to it but must never be able to rewrite history.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+import os
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+        Ed25519PrivateKey,
+        Ed25519PublicKey,
+    )
+
+    _HAS_CRYPTO = True
+except Exception:  # pragma: no cover - optional dependency
+    _HAS_CRYPTO = False
+
+GENESIS_HASH = "0" * 64
+
+
+def _canonical(data: Any) -> str:
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), default=str)
+
+
+@dataclass
+class AuditEntry:
+    index: int
+    ts: float
+    actor: str
+    action: str
+    data: dict[str, Any]
+    prev_hash: str
+    entry_hash: str
+    signature: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)
+
+
+class AuditLedger:
+    def __init__(
+        self,
+        signing_key_path: str | os.PathLike[str] | None = None,
+        jsonl_path: str | os.PathLike[str] | None = None,
+    ) -> None:
+        self._lock = threading.Lock()
+        self._entries: list[AuditEntry] = []
+        self._jsonl_path = Path(jsonl_path) if jsonl_path else None
+        self._priv: Any = None
+        self._pub_hex: str | None = None
+        if signing_key_path is not None:
+            self._load_or_create_key(Path(signing_key_path))
+
+    # ---- signing key management ----
+    def _load_or_create_key(self, path: Path) -> None:
+        if not _HAS_CRYPTO:
+            raise RuntimeError(
+                "Signing requested but 'cryptography' is not installed. "
+                "Install with: pip install wardproof[crypto]"
+            )
+        if path.exists():
+            self._priv = Ed25519PrivateKey.from_private_bytes(path.read_bytes())
+        else:
+            self._priv = Ed25519PrivateKey.generate()
+            raw = self._priv.private_bytes(
+                serialization.Encoding.Raw,
+                serialization.PrivateFormat.Raw,
+                serialization.NoEncryption(),
+            )
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(raw)
+            os.chmod(path, 0o600)
+        self._pub_hex = (
+            self._priv.public_key()
+            .public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+            .hex()
+        )
+
+    @property
+    def public_key_hex(self) -> str | None:
+        return self._pub_hex
+
+    # ---- core ----
+    def _compute_hash(
+        self,
+        index: int,
+        ts: float,
+        actor: str,
+        action: str,
+        data: dict[str, Any],
+        prev_hash: str,
+    ) -> str:
+        payload = f"{index}|{ts:.6f}|{actor}|{action}|{_canonical(data)}|{prev_hash}"
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+    def append(self, actor: str, action: str, data: dict[str, Any] | None = None) -> AuditEntry:
+        with self._lock:
+            index = len(self._entries)
+            prev_hash = self._entries[-1].entry_hash if self._entries else GENESIS_HASH
+            ts = time.time()
+            data = data or {}
+            entry_hash = self._compute_hash(index, ts, actor, action, data, prev_hash)
+            signature = None
+            if self._priv is not None:
+                signature = self._priv.sign(entry_hash.encode("utf-8")).hex()
+            entry = AuditEntry(index, ts, actor, action, data, prev_hash, entry_hash, signature)
+            self._entries.append(entry)
+            if self._jsonl_path is not None:
+                with self._jsonl_path.open("a", encoding="utf-8") as fh:
+                    fh.write(_canonical(entry.to_dict()) + "\n")
+            return entry
+
+    @property
+    def entries(self) -> list[AuditEntry]:
+        return list(self._entries)
+
+    def verify(self, public_key_hex: str | None = None) -> tuple[bool, str]:
+        """Recompute the whole chain and (if a key is known) check signatures."""
+        pub_hex = public_key_hex or self._pub_hex
+        pub: Any = None
+        if pub_hex and _HAS_CRYPTO:
+            pub = Ed25519PublicKey.from_public_bytes(bytes.fromhex(pub_hex))
+        prev = GENESIS_HASH
+        for e in self._entries:
+            expect = self._compute_hash(e.index, e.ts, e.actor, e.action, e.data, prev)
+            if expect != e.entry_hash:
+                return False, f"hash mismatch at index {e.index}"
+            if e.prev_hash != prev:
+                return False, f"broken chain link at index {e.index}"
+            if e.signature is not None and pub is not None:
+                try:
+                    pub.verify(bytes.fromhex(e.signature), e.entry_hash.encode("utf-8"))
+                except InvalidSignature:
+                    return False, f"invalid signature at index {e.index}"
+            prev = e.entry_hash
+        return True, f"verified {len(self._entries)} entries"
+
+    def export_jsonl(self, path: str | os.PathLike[str]) -> None:
+        with Path(path).open("w", encoding="utf-8") as fh:
+            for e in self._entries:
+                fh.write(_canonical(e.to_dict()) + "\n")

wardproof/cli.py

@@ -0,0 +1,37 @@
+"""Minimal CLI. Primary job: independently verify an exported audit ledger."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from wardproof.audit.ledger import AuditEntry, AuditLedger
+
+
+def _verify_file(path: str, pub: str | None) -> int:
+    ledger = AuditLedger()
+    for line in Path(path).read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        ledger._entries.append(AuditEntry(**json.loads(line)))  # noqa: SLF001
+    ok, detail = ledger.verify(public_key_hex=pub)
+    print(("OK: " if ok else "FAIL: ") + detail)
+    return 0 if ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="wardproof")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    vp = sub.add_parser("verify-ledger", help="verify integrity of a JSONL audit ledger")
+    vp.add_argument("path")
+    vp.add_argument("--pubkey", default=None, help="hex Ed25519 public key for signature check")
+    args = parser.parse_args(argv)
+    if args.cmd == "verify-ledger":
+        return _verify_file(args.path, args.pubkey)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wardproof/config.py

@@ -0,0 +1,28 @@
+"""Typed configuration. Fork-friendly: override defaults in one place."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class WardproofConfig:
+    model: str = "llama3.1"
+    ollama_url: str = "http://localhost:11434"
+    detector_low: float = 0.2
+    detector_high: float = 0.6
+    signing_key_path: str | None = None
+    ledger_path: str | None = None
+
+    @classmethod
+    def from_env(cls) -> WardproofConfig:
+        base = cls()
+        return cls(
+            model=os.getenv("WARDPROOF_MODEL", base.model),
+            ollama_url=os.getenv("WARDPROOF_OLLAMA_URL", base.ollama_url),
+            detector_low=float(os.getenv("WARDPROOF_DETECTOR_LOW", base.detector_low)),
+            detector_high=float(os.getenv("WARDPROOF_DETECTOR_HIGH", base.detector_high)),
+            signing_key_path=os.getenv("WARDPROOF_SIGNING_KEY"),
+            ledger_path=os.getenv("WARDPROOF_LEDGER_PATH"),
+        )

wardproof/guardrails/__init__.py

@@ -0,0 +1,17 @@
+"""Deterministic guardrails, the first line of defence (no LLM required)."""
+
+from wardproof.guardrails.base import Guardrail
+from wardproof.guardrails.memory_poisoning import MemoryPoisoningGuardrail
+from wardproof.guardrails.prompt_injection import (
+    PromptInjectionGuardrail,
+    strip_injection,
+)
+from wardproof.guardrails.tool_misuse import ToolMisuseGuardrail
+
+__all__ = [
+    "Guardrail",
+    "PromptInjectionGuardrail",
+    "ToolMisuseGuardrail",
+    "MemoryPoisoningGuardrail",
+    "strip_injection",
+]