Skip to content

guard for agents

Choose a tag to compare

@avijeetsingh1 avijeetsingh1 released this 10 Aug 05:05
· 2466 commits to main since this release

Added

  • emem-guard: a signed allow/deny server for AI inference checkpoints. Anthropic's Inference hooks hold every governed prompt for a verdict before the model runs, and the named destinations all evaluate CONTENT. None can evaluate whether a claim about the physical world still holds. This does.

    Nine checkpoints from one engine, and the same evidence yields the same verdict through every one. Seven of the nine belong to no vendor, because a gate reachable only through one company's product is a gate for that company's customers:

    Route | Reaches -- | -- POST /verdict | any agent, on any model, through any framework POST /verdict/mcp | any MCP host or proxy, gating a tool call or a tool result POST /verdict/openai | anything holding an OpenAI-compatible client POST /verdict/cloudevent | CloudEvents 1.0 producers POST /verdict/policy | OPA-compatible clients, Envoy external authorisation POST /verdict/batch | many transcripts at once, for scanning an archive GET /log/entry/{leaf} | anyone checking a verdict without trusting the issuer POST /verdict/anthropic-hook | claude.ai, Cowork, Claude Code in a Claude Enterprise org POST /verdict/claude-code | Platform API, Bedrock and Vertex agents Inference hooks cannot see

    GET /.well-known/emem-guard.json publishes every route, deny code, remedy and the reason grammar, so a cold agent integrates without prose. A test asserts every advertised route answers and that the open ones outnumber the vendor ones.

    Every verdict is signed and appended to a hash-chained log BEFORE it is returned. Signatures prove each verdict genuine; the chain proves none were removed. emem-guard --audit verifies any log and exits non-zero on a tampered or missing entry.

    Denials are machine-first so an agent can self-correct: EMEM-GUARD DENY <CODE> token=<token> fix=<fix> leaf=<leaf>. The grammar is fixed; when a denial has more to say, the native route returns it structured.

    A token the guard has not cached is never a denial. Geo restriction ships off, since it needs an operator's own cell64 list to mean anything.

    Claim gating is implemented, measured, and still off by default. It is the one rule that fires on absence: a transcript that cites nothing and still asserts a measurable quantity about a place or a time. Four clauses, each of which can only remove firings. The discriminator is a unit table where every row names the band from GET /v1/bands that reports it, so the gate only fires on claims the node could have verified had they been cited, and 800 ms, 10 MB and $4.2bn never reach it. Measured over this repository's own documentation: 3 firings in 8739 sentences across 8 files, a rate of 0.034%, two of them the detector's own positive test fixtures and so the rule working rather than false positives. The corpus found two real defects on the way, a citation key and a model name both read as years, and both are now pinned by tests.

    Shadow mode is what makes turning it on a decision rather than a guess. --shadow runs every rule, signs and logs what it WOULD have done, and blocks nobody; --report and GET /log/report read the count back off the same append-only file an auditor reads. The verdict preimage domain moves to emem.guard.verdict.v2 to bind mode and evaluated, because a report claiming how often a rule would have fired is only worth anything if the operator could not edit the answer afterwards.

    On the responder, POST /v1/guard/verdict answers with the same engine over the shared corpus, advisory and blocking nothing, and GET /v1/guard/selfhost serves the whole self-host procedure as markdown. MCP tools emem_guard_verdict and emem_guard_selfhost. Walk the procedure with real output at /guard.

    The plugin chassis (WS-H). A PolicyModule trait, so everyone else's detection runs here and gets the half none of them ship. Two declarations decide where a module may run and neither is taken on trust: a module declaring slow never runs on the enforcing path, a module declaring fast that exceeds 50 ms three times is demoted by the registry and stops being able to block, and a module declaring digests_only is handed a different slice so it cannot read text rather than being asked not to. --modules-no-text withholds text from every module for a relay where it may not cross a boundary. The log records module id, version and an evidence digest, never the matched content, and ModuleVerdict::deny hashes the evidence at the constructor so an author cannot leak it by accident. The loaded set's digest enters the verdict preimage, which moves to emem.guard.verdict.v3: without it an operator could change detectors and the same signed record would describe two different evaluations. GET /modules publishes what is loaded and what it has actually cost.

    Two reference modules, neither of them a detection engine. secret-patterns is in-process and narrow: every shape is a fixed prefix plus an exact length, so a match is not a judgement call. A test fixture caught that Slack and Stripe key lengths are not fixed, so the rule could never have matched them; both are dropped with the reason recorded rather than relaxed into an entropy heuristic. webhook:<url> wraps any classifier and abstains on timeout, because turning a sidecar's outage into a blocked request makes an operator less reliable for having added a control.

    The conformance suite (WS-E). emem-guard --conformance <url> runs twelve checks against a running deployment over the wire, exits non-zero on any failure, and prints what breaks in production rather than restating itself. It found one on its first run, in this server: a 9 MB body returned 413, because axum's DefaultBodyLimit of 2 MB wins over the tower-http layer set to 10 MB. The docs, the comment and the layer all said 10 MB and the socket said 413. No unit test could have caught it; they drive the router directly and never send a body that large.

    Not yet pointed at a live organisation.

Changed

  • CI gates a running system, not just the source. Two new jobs. guard-conformance builds the guard, starts it, runs the twelve-check suite against a real socket and audits the log it wrote. parity runs the MCP/REST matrix sgozfgkr built and handed back three rounds ago: twelve cases comparing facts at (band, value) rather than envelopes, with an identical refusal on both paths counted as a pass. 12 of 12 have parity against production. Building it surfaced a third harness bug of our own: an MCP tool error is a SUCCESSFUL JSON-RPC envelope carrying isError and a prose body, so parsing before checking the flag reads a refusal as an answer.

  • The seven memory verbs carry the service prefix: emem_memory_view, emem_memory_create, emem_memory_str_replace, emem_memory_insert, emem_memory_delete, emem_memory_rename, emem_memory_list_by_kind. 98 of 105 tools already did; these did not, and three of them are DESTRUCTIVE while sharing a name with Claude's own memory tool, so a host with both loaded had two different memory_delete and no way to tell which one a model meant.

    Nothing breaks today. The bare spellings still dispatch; they are only no longer advertised. They are removed in 3.0. Signatures are unaffected: the attester preimage binds a bare verb (create, delete), never the tool name, so no receipt or stored write is touched.

  • outputSchema on eleven tools, declared only where the promise can be kept. The MCP spec binds it to returning conforming structuredContent on every call, and this responder drops that mirror when the two-copy envelope would breach the wire budget. Tools that can exceed it stay undeclared; tools that declare one now keep their mirror (slimming both copies rather than dropping it), so the descriptor cannot come to lie. emem_locate stays undeclared on purpose: its response runs to ~20 KB, so a mirror would only fit by halving the payload, and a caller would get less data in exchange for a shape it could already read off the response.

Fixed

  • The FactCid schema rejected every fact_cid this responder serves. components/schemas/FactCid described the cid as blake3(canonical_cbor(fact))[..16], 26 characters, with an example that was an IPFS CIDv1 and did not satisfy even that description. It is 52 characters: the full 32-byte digest, untruncated. That schema is $ref'd by Receipt.fact_cids, Fact.fact_cid, FindSimilarResp and VerifyResp, so an agent generating a validator from our own machine surface would have rejected the cid on every core response. Measured against live recall: 28 of 28 real cids validate now, 0 of 28 would have validated before. It now carries pattern, minLength and maxLength, so it validates rather than describes.

  • The homepage claimed every token shape "resolves the same way, verifies the same way". It does not, and the protocol already said so: the MCP instructions call an entity token "a shared reference rather than shared bytes". fact_cid hashes the complete canonical-CBOR body at the full 32 bytes; entity_cid hashes an identity anchor and bundle_cid hashes a citation list, both truncated to 16; emem:cell: is an address rather than a digest and nothing verifies until a fact hangs on it. The homepage now states what each shape binds, because that difference decides what a citation proves.

  • /verify said fact CIDs were 32 characters, in the lede and in the input placeholder a reader is looking at while pasting one. They are 52.

  • The counts gate matched phrasings, not numbers. sync_counts.py claims in its own docstring to assert the number rather than remember a wording, but the tool-count pattern required a parenthesis, so ARCHITECTURE_NOTES.md drifted to a colon-form 104 / 15 / 89 and CI stayed green. Widened to accept both forms; it caught the stale line immediately. That file also claimed no CI workflow ran the gate, which stopped being true when the gate was wired into CI.

  • llms.txt listed five of the nine token shapes. The agent-facing discovery surface named fact, bundle, entity, trace and attestation and omitted cell, raster, cube and rasterset, so an agent reading it learned a smaller protocol than the one being served.


release-2 1 0