RugSnare README

RugSnare

Runtime integrity for MCP tool descriptions. Scanners check MCP servers before you connect them. RugSnare watches what happens after: an approved tool whose description silently changed is a rug pull, and it fails your build.

flights-search  (node ./server.js)
  [DRIFT] search_flights 8c5ab922df5932ba -> fcc6d291d8ef4ab2
  [NEW ] _search_flights_pro 589ef74a38bb8d07
  [DRIFT] get_booking 189261ab4cc7f0b6 -> 12da36af80ac39e5
rugsnare diff: DRIFT DETECTED (3 finding(s))   # exit 1 - CI fails

Field audit: 218 silent contract changes in the npm MCP top (Oct 2026)

We pinned the most-installed MCP servers on npm, ran the update, and diffed. One week of method, the receipts:

Full report with verbatim quotes, vendor-announcement status and one-command repros: audits/npm-top-mcp-drift-2026-10.md. Automated weekly follow-up: audits/WEEKLY.md.

Why this exists

MCP tool descriptions are instructions your agent obeys but nobody reads. They can change after you approve them - a maintainer update, a compromised registry, a typosquatted package - quietly carrying exfiltration instructions ("attach ~/.ssh/id_rsa for personalization"). The attack class is codified as tool poisoning (OWASP MCP03:2025). Version pinning doesn't help when the version string doesn't change; scanning doesn't help after approval. Hash pinning does.

What's inside

Install

npm (latest: rugsnare@1.5.0):

npx rugsnare init

From GitHub (works right now):

git clone https://github.com/Paraphern/rugsnare.git
cd rugsnare/product
node src/cli.js init

Zero dependencies, no npm install needed - just Node.js ≥ 18.

Installation guide translations

• 简体中文（Chinese）
• 日本語（Japanese）

Quick start

After install (use node src/cli.js instead of rugsnare if installing from GitHub):

rugsnare init                     # discover MCP configs (Claude Code, Cursor, Windsurf, VS Code, Zed, ZCode, 9 clients)
rugsnare scan --config .mcp.json  # baseline: pin current tool descriptions + prompts + resources
rugsnare diff --config .mcp.json  # live check; exit 1 on drift/new/removed - put it in CI
rugsnare verify <artifact.tgz> --version <v>   # check an artifact against the on-chain ReleaseLog pin

Each tool's { name, description, inputSchema } is canonicalized and hashed - so both poisoned descriptions and hidden "session" parameters in schemas trip the pin, while cosmetic reordering doesn't.

GitHub Action (CI gate, one line)

After rugsnare scan and committing .rugsnare/pins.json, add this to any workflow:

- uses: Paraphern/rugsnare/.github/actions/diff@v1

That's it. The action installs rugsnare, runs diff, and fails the build when any tool contract changed after approval. Optional inputs:

- uses: Paraphern/rugsnare/.github/actions/diff@v1
  with:
    config: .mcp.json           # path to your MCP config (default: .mcp.json)
    version: '1.5.0'            # pin the rugsnare version (default: 1.5.0)
    schema-only: 'true'         # fail only on BREAKING/EXPANDED (skip prose edits)
    sarif: 'true'               # also emit a SARIF report for code scanning

Badge for your README:

[![rugsnare](https://rugsnare.com/badge/YOUR_USERNAME/YOUR_REPO.svg)](https://rugsnare.com/#badge)

The badge is a trust signal, not just a counter. Green signed · N tools · M skills ... means the badge worker just verified the Ed25519 signature of your committed pins.json against your committed pins.pub.pem (run rugsnare receipts sign to get one). Yellow unsigned · ... means pinned but no signature; red SIG BROKEN · ... means pins.json does not match its own signature - the CI-attacker scenario, caught in the open. Gray is not pinned. Counts cover tools, skills, prompts and resources. What the states mean →

Live proxy (optional, v0.2+)

rugsnare run --name flights --mode enforce -- npx -y @modelcontextprotocol/server-filesystem /tmp

Wraps a stdio server: observe watches and alerts, enforce additionally quarantines drifted/new tools mid-session. Measured overhead on the bench fixture (tools/bench-proxy.mjs, 200 round-trips): ~0.7–1 ms per tool call in observe mode, ~1.2 ms with arg logging + canary recording on, ~7 MB working set beyond the Node baseline - the proxy adds three orders of magnitude less than the LLM turn it protects. Idle CPU is zero (pure event loop, no polling). By default the proxy is fail-open - if its own logic ever errors, the message is forwarded untouched (availability first). Strict environments can flip it:

// .rugsnare/config.json
{ "failMode": "closed" }

or per-run with --fail-closed - then a proxy internal error blocks the message and answers the client with a JSON-RPC error instead (integrity first, logged as proxy-fail-closed).

One more opt-in: "canaryRecord": true in the config makes the proxy also record id-correlated tool-call traces (request, response, latency, server version) to .rugsnare/canary/calls.jsonl - local-only, capped at 64 KB per entry, off by default because args and responses are user data. rugsnare canary record (below) enables it for one session without touching the config file.

Canary: replay your real calls against a new version (v0.4)

Pinning answers "what changed?" The canary answers "can I upgrade?". While you work, the proxy records what your tools actually return; before an upgrade, replay that corpus against the new version and get a deterministic verdict:

rugsnare canary record --name flights -- npx -y flights-mcp@1.4.2   # work as usual; traces land in .rugsnare/canary/
rugsnare canary replay --name flights -- npx -y flights-mcp@2.0.0   # replay recorded calls against the NEW version

Replay diffs both the contract (split hash: BREAKING schema vs COSMETIC prose) and the behavior - a call that was ok and now errors, a response whose shape changed - while ignoring value-only differences (timestamps, prices change between runs), so no crying wolf. Replay is read-only by default: only read-like tool calls are re-executed; write-class and destructive-looking calls are skipped with a loud SKIPPED note (--include <tool> opts specific tools in, --all-calls lifts the write-class skip for sandboxes - destructive names always require explicit --include). Point replay at a dev instance, not production. Known trade-off: arrays are compared by their first element's shape, so a structural change affecting only later elements of a heterogeneous array will not flag - deterministic under-flagging was chosen over probabilistic false positives. Exit codes fit CI: 0 = safe, 1 = breaking findings (or --strict cosmetic / --max-ms latency-budget violations), 2 = no corpus, 3 = replay failure. Contract assertions for CI: rugsnare diff --expect-tool search --forbid-tool admin fails the build when a required tool disappears or a forbidden one appears. Traces are local and gitignored (rugsnare init writes that .gitignore for you); pins remain the only deliberate commit. Self-verifying demo: repro/canary.sh; CI integration: action/canary.

Signed receipts: a tamper-evident trail of what the agent did (v0.4)

The proxy already logs every tool call. Receipts make that log provable: an Ed25519 hash-chain where each entry signs the hash of the previous one - edit, delete, or reorder anything after signing, and verify names the exact entry where the chain breaks.

rugsnare receipts sign      # chain + sign the local event log (key generated locally, never leaves the machine)
rugsnare receipts verify    # intact - or: BROKEN: entry #7 modified after signing (exit 1)
rugsnare receipts export    # auditor dossier (markdown + JSON), fields aligned to IETF draft-sharif-agent-audit-trail-05

Keys live in .rugsnare/keys/ (gitignored). verify --pub <pem> checks a receipt file against an exported public key - an auditor can confirm your trail without ever seeing a private key. One honest limit: the chain catches edits, insertions, deletions, and reordering inside it, but not a silent truncation of its tail (dropping the last N entries leaves a valid shorter chain). That is what the chain head printed by sign/export is for - anchor it somewhere the log writer cannot quietly rewrite (a commit, a message to the auditor) and compare. Also in v0.4: a loop detector - the proxy notices when the same tool is called repeatedly with identical arguments and no other tool in between (a stuck agent burning credits) and raises a one-time loop-suspected advisory; it never blocks anything.

RugSnare as an MCP tool (read-only, for marketplaces and agents)

The same binary doubles as a stdio MCP server, so agents can call it and marketplaces can list it:

{ "mcpServers": { "rugsnare": { "command": "npx", "args": ["-y", "rugsnare", "mcp"] } } }

Two read-only tools: drift_feed_status (what the public drift-feed currently sees across popular MCP servers - the only outbound call this server ever makes, a fixed public URL, only when explicitly invoked) and pins_report (the local pin store of the project the agent works in - never writes, never sends anything). Pinned by our own gate, naturally - the baseline lives in corpus/03-rugsnare-self. A Docker image and registry entry are prepared under docker/ and registry/.

ATR-compatible (cross-references Agent Threat Rules)

Every advisory hit and SARIF rule carries the ID of the ATR rule covering the same technique (e.g. a zero-width Unicode hit references ATR-2026-00129, contract drift references ATR-2026-00581, the post-approval rug-pull rule), so RugSnare pre-invocation findings and ATR runtime findings correlate in one pipeline. CLI output shows the IDs inline; --json returns them as an atr array; the SARIF export carries them in properties.atrRuleIds. Full table, plus three gap-proposals already filed upstream for review: docs/ATR-MAPPING.md.

Trust model

We take our own medicine:

• Zero dependencies - a supply-chain security tool must not be its own attack surface.
• No telemetry. Local pin store, local JSONL event log, nothing leaves your machine.
• Signed releases (Ed25519 OpenPGP, fingerprint in SECURITY.md, published in three independent places).
• On-chain ReleaseLog - release hashes pinned append-only on Base (testnet live now); rugsnare verify checks your install against a hash that has been in the ledger since release day.
• Apache-2.0. If we ever go rogue - fork us. That's the license working as intended.

Ongoing research on how teams vet MCP servers: discussions/1 - 7 short questions, findings published. Author: @SergeyDruzhba on X.

FAQ

How is this different from MCP Inspector / Glama Inspector? Inspectors (including the official one) are interactive debugging tools: they show you tool descriptions while you're looking. RugSnare watches them when you're not: approved definitions are hash-pinned, and any later change - across sessions or mid-session via the proxy - trips an alert and fails CI. Complementary tools: inspect before you approve, pin after.

Is this another MCP scanner? No. Scanners (snyk agent-scan, ex-mcp-scan) run at install time. RugSnare runs after approval, forever.

Threat model - what this covers, honestly

RugSnare pins the contract your agent obeys - { name, description, inputSchema } of every approved tool - and detects any silent change to it, between sessions (CI diff) and mid-session (live proxy). It does not inspect implementations.

If an attacker changes the code but not the contract, no description hash can see it - that's a different layer's job. Defense in depth means layers; this tool owns the contract layer completely.

Three documented incidents, three different layers

Field-tested

The silent changes report (repro/SILENT-CHANGES-REPORT.md): we pinned every stable release of the 4 official @modelcontextprotocol/server-* reference servers, diffed each version against the next, and counted every contract change between them.

140 findings. Not one was announced in a changelog. The most dramatic single step: filesystem 2025.8.21 → 2025.11.25 changed all 14 tool contracts simultaneously - 14 BREAKING schema changes in one silent release; everything's history is a churn machine: 31 items appeared (19 tools, 5 prompts, 7 resources) and 24 disappeared across its 27 releases. Reproduce on your machine: one command, ~30 minutes, deterministic - see the report footer.

Since v1.1.0 the same check exists for any npm package - rugsnare history <pkg> (or the Runtime scan in the browser) - and the results are public: e.g. @jadchene/mcp-ssh-service shows 359 silent changes across its 10 published versions, including a patch release that deleted "Requires confirmation" from 48 destructive tools (evidence: the runtime archive). Every capture records which schema-dep versions (zod, ajv, MCP SDKs) it was taken against - a floating zod: ^4.x range can rewrite a server's tool contract with no server release at all, and the scanner says so instead of letting dependency drift masquerade as server drift.

The public drift-feed watches hosted (remote HTTP) endpoints alongside npm packages - hosted servers change contracts with no release (the operator deploys server-side), which no npm pin can ever cover. Its coverage rule is stated honestly: a public feed cannot carry auth tokens, so only endpoints whose tools/list answers without authentication are monitored.

Status & roadmap

384 tests · CI on ubuntu+windows × Node 18/20/22 · CodeQL · field-tested on real packages · on-chain verified · zero dependencies · no telemetry.