RugSnare

RugSnare

218 silent contract changes found in the npm MCP top (Oct 2026) — not one announced in a changelog. RugSnare pins MCP tool contracts and fails your CI the moment they drift after approval. Scanners check servers *before* you connect them; RugSnare watches what happens *after* — an approved tool whose description silently changed is a rug pull.

★ Caught a drift? Star the repo — github.com/Paraphern/rugsnare

rugsnare scan --config .mcp.json   # pin the contracts you approved

rugsnare diff --config .mcp.json # exit 1 the moment anything drifts

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](audits/npm-top-mcp-drift-2026-10.md). Automated weekly follow-up: audits/WEEKLY.md.

Independent measurements

Our audit is not a lone number. Two third-party datasets — published with method and caveats, neither affiliated with us — land on the same shape from different angles:

• HISTOR (alexar76) — Zenodo DOI 10.5281/zenodo.23512760, CC BY 4.0, monthly snapshots (also alexar76/histor-mcp-tool-definitions on Hugging Face). Every new npm/PyPI MCP-server release sandboxed and every registry remote read daily: 1,419 of 21,738 packages (6.5%) changed their `tools/list` in four weeks (24 Sep – 20 Oct 2026), and 4,926 of 10,929 remote servers (45%) served a different tool list at least once. It also documents 2,719 digit-only description changes — the churn that argues for a readable field-level diff over a single yes/no hash (discussion: modelcontextprotocol#3431). 26 of our 28 watch-corpus packages appear in the log; 8 changed in that window — consistent with our per-server pages.
• agent-skills-state-2026 (basitalisandhu) — repo. A read-only sample of 2,999 GitHub repos shipping MCP configs: 46.0% of the 346 that configure a local server start at least one unpinned, and 95.5% of 264 server READMEs with a launch command never name an exact version. Its README links our drift-watch corpus as a related dataset.

Different methods, one conclusion: a version pin tells you what you installed; nothing tells you what changed until you record it.

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.1):

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 --version # 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 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