wardn 0.1.0.dev0

Bounded, auditable action governor for LLM agents — a policy gate between an MCP client and its servers.

wardn

Bounded, auditable action governor for LLM agents — a policy gate between an MCP client and its servers. Every tool call is allowed, denied, or quarantined by a rule you declared; run-wide budgets cap total side-effects with loud refusals; and every attempt lands in an append-only, timestamp-free, byte-deterministic ledger that replays offline and diffs in CI.

wardn bounds and audits. It does not sandbox, and it is not a content-safety product.

Status

Pre-release — M2 (adoptable, CI-integrable) is built. The proxy governs one or more real MCP servers over stdio; wardn review decides quarantined calls from any terminal; wardn replay reproduces every decision offline; wardn revert undoes declared-reversible effects from the ledger file alone; and wardn diff turns two ledgers into a CI verdict — exit 4 the moment governed activity drifts. Two identical runs emit byte-identical ledgers, including against the real @modelcontextprotocol/server-filesystem.

Not yet on PyPI — install from a clone (pip install .). The roadmap, locked decisions, and spike record live in TODO.md.

The gap

Permission systems exist (per-client allow/ask/deny rules), approval services exist, security gateways exist, eval-time diffs exist. But none of them owns the middle: side-effect governance that is declared (a policy file, not scattered client settings), bounded ("at most 2 writes", not just "ask"), and auditable — emitted as a single deterministic artifact a CI job can diff with an exit code.

That artifact is the whole point of wardn. A permission prompt leaves no record. An observability stream isn't deterministic. wardn's ledger is both: the decision log and the drift detector, one file.

The core idea: one ledger, three uses

Every attempt — allowed, denied, quarantined, refused by a budget — is one recorded event stream: what was attempted, which rule matched, how the call was classified (and by what authority), what was decided, why, and what came back.

• Read it forward → the audit report. Every side-effect, explained.
• Replay it (wardn replay) → the decisions, reproduced offline from policy + file alone. A tampered ledger or a swapped policy refuses loudly.
• Replay it inverted (wardn revert) → the undo. Declared-reversible effects are reverted from the file alone — the undo call was resolved and recorded at capture time, so revert needs no policy, only the ledger and a live server. If the world drifted since the run, revert refuses rather than guesses.

And because the file is byte-deterministic — no timestamps, no PIDs, no nonces — wardn diff yesterday.jsonl today.jsonl is a CI gate: same policy, same attempts, same decisions, or exit 4.

Quick look

A policy is an ordered list of rules, first match wins, with a mandatory explicit default — a policy that doesn't say what happens to unmatched calls is invalid:

{
  "format": "wardn-policy/1",
  "default": "deny",
  "budget": {"max_calls": 20, "max_writes": 5, "max_spend": 1.0},
  "approval_timeout_s": 300,
  "rules": [
    {
      "id": "allow-reads",
      "match": {"server": "filesystem", "tool": "read_text_file"},
      "effect": "read",
      "disposition": "allow",
      "reason": "reads are harmless here"
    },
    {
      "id": "bound-writes",
      "match": {"server": "filesystem", "tool": "write_file",
                "args": {"path": {"path_prefix": "/work/out/"}}},
      "effect": "write",
      "disposition": "allow",
      "bound": {"max_calls": 2},
      "cost_per_call": 0.1,
      "capture": {"tool": "read_text_file", "args_from": {"path": "path"}},
      "inverse": {"tool": "write_file",
                  "args": {"path": "$args.path", "content": "$capture.value"},
                  "expect": "$args.content"},
      "reason": "writes capped at 2, under out/ only, pre-state captured"
    },
    {
      "id": "quarantine-moves",
      "match": {"server": "filesystem", "tool": "move_file"},
      "effect": "destructive",
      "disposition": "quarantine",
      "reason": "moves need a human"
    }
  ]
}

Put wardn between your client and the server — the client config points at wardn, wardn spawns the real server:

{
  "mcpServers": {
    "filesystem": {
      "command": "wardn",
      "args": ["proxy", "--policy", "policy.json", "--ledger", "run.jsonl",
               "--", "npx", "-y", "@modelcontextprotocol/server-filesystem",
               "/work"]
    }
  }
}

The agent now reads freely, gets its third write refused loudly (an error result naming the rule and the bound — the agent can read why and adapt), and blocks on move_file until someone, in any terminal, runs:

$ wardn review list --queue run.jsonl.queue.json
q6  move_file  {"source":"/work/report.txt","destination":"/work/old.txt"}  rule=quarantine-moves  — moves need a human

$ wardn review approve q6 --queue run.jsonl.queue.json --by phiwir
q6: approve by phiwir

Afterwards, the run is a file:

$ wardn replay --policy policy.json --ledger run.jsonl
replayed 8 attempt(s) — every decision reproduced by this policy

$ wardn revert --ledger run.jsonl -- npx -y @modelcontextprotocol/server-filesystem /work
applied 2 undo(s) — revert ledger: run.jsonl.revert.jsonl

$ wardn diff approved/run.jsonl run.jsonl && echo "no drift"

Several servers can sit behind one gate — wardn proxy --servers servers.json takes a file in the same shape as an MCP client config, and rules match on the server's name. See docs/concepts.md for what multi-server mode honestly does and doesn't proxy.

What wardn is not

• Not a sandbox. wardn is a policy gate in front of cooperative transports. A hostile server, or a client that bypasses the proxy, is out of scope — and argument constraints are string constraints: path_prefix: "out/" happily matches out/../secret.txt. wardn does not resolve paths; that is a sandbox's job. Never treat a wardn policy as an isolation boundary.
• Not content safety. wardn governs side-effects, not text. Prompt injection defense is a different layer.
• No LLM anywhere in the enforcement path. A decision is a pure function of policy + request + recorded approvals. Ever.
• No measured spend. max_spend refuses on arithmetic over declared costs (cost_per_call), never on billing APIs — wardn cannot observe real spend and doesn't pretend to.

Docs

• docs/concepts.md — rules, dispositions, bounds, classification, quarantine, capture/revert, and the determinism claim stated precisely (including its honest asterisks).
• docs/policy-format.md — wardn-policy/1, normative.
• docs/ledger-format.md — wardn-ledger/1, the compatibility contract. The ledger format and the proxy CLI are the two things wardn promises stability for.
• docs/ci.md — the CI story: budgets as drift tripwires, wardn diff as the gate.
• docs/embedding.md — the engine API for non-MCP embeddings: govern_call in front of any tool-calling boundary.

Family

Sibling to agentrec (records what models say) and mendr (repairs what data got wrong) — wardn governs what agents do. Same ethos: declared, bounded, recorded; the record is the product; no LLM anywhere in the enforcement path.