{"_id":"@arunmm8335/mcpguard","name":"@arunmm8335/mcpguard","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@arunmm8335/mcpguard","version":"0.1.0","description":"Security scanner for MCP servers — detect tool poisoning, malicious code patterns, and supply-chain risks before your AI agents execute them.","type":"module","bin":{"mcpguard":"dist/cli.js"},"main":"dist/index.js","publishConfig":{"access":"public"},"scripts":{"build":"tsc","dev":"tsx src/cli.ts","test":"vitest run","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","security","scanner","supply-chain","ai-agents","tool-poisoning","prompt-injection","sast","cli"],"license":"MIT","author":{"name":"arunmm8335"},"homepage":"https://github.com/arunmm8335/mcp-guard#readme","repository":{"type":"git","url":"git+https://github.com/arunmm8335/mcp-guard.git"},"bugs":{"url":"https://github.com/arunmm8335/mcp-guard/issues"},"engines":{"node":">=18"},"dependencies":{"commander":"^13.1.0","picocolors":"^1.1.1","yaml":"^2.7.0"},"devDependencies":{"@types/node":"^22.13.0","tsx":"^4.19.0","typescript":"^5.7.0","vitest":"^3.0.0"},"_id":"@arunmm8335/mcpguard@0.1.0","gitHead":"711dad96b1899ebf43066a5c46f12a6a135622a9","types":"./dist/index.d.ts","_nodeVersion":"22.15.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-v/ZRT8jhNOsgBbrW9q9zQ57N6mp+8RyIJFNrVnv6FWjGt+SiHKtp3j34qjsHr6boMfN3tMO5QZWHABaiHuuYMQ==","shasum":"1ebcc2327b6e7127dc2e76891446b45ebe15ce12","tarball":"https://registry.npmjs.org/@arunmm8335/mcpguard/-/mcpguard-0.1.0.tgz","fileCount":35,"unpackedSize":91436,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDaweUFuq/S0rRnddjRTaFnVh4VV2CpAJjs/LwQY0boqgIhAM+FLqFQ83uI3AwNJGjfTD80SfdLvFnSLXgJfbw1FCnM"}]},"_npmUser":{"name":"arunmm8335","email":"arunmyageri26@gmail.com"},"directories":{},"maintainers":[{"name":"arunmm8335","email":"arunmyageri26@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcpguard_0.1.0_1784191822622_0.11935365688300847"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-16T08:50:22.445Z","0.1.0":"2026-07-16T08:50:22.746Z","modified":"2026-07-16T08:50:22.901Z"},"maintainers":[{"name":"arunmm8335","email":"arunmyageri26@gmail.com"}],"description":"Security scanner for MCP servers — detect tool poisoning, malicious code patterns, and supply-chain risks before your AI agents execute them.","homepage":"https://github.com/arunmm8335/mcp-guard#readme","keywords":["mcp","model-context-protocol","security","scanner","supply-chain","ai-agents","tool-poisoning","prompt-injection","sast","cli"],"repository":{"type":"git","url":"git+https://github.com/arunmm8335/mcp-guard.git"},"author":{"name":"arunmm8335"},"bugs":{"url":"https://github.com/arunmm8335/mcp-guard/issues"},"license":"MIT","readme":"# mcpguard\n\nSecurity scanner for **MCP (Model Context Protocol) servers**. It inspects a server *before* your AI agent connects to it and flags the two things that actually get people hurt:\n\n1. **Tool poisoning** — hidden instructions smuggled into tool names and descriptions (the metadata an agent blindly trusts). Prompt-injection, concealment directives, credential lures, cross-tool hijacking, invisible Unicode.\n2. **Malicious / dangerous code** — shell execution, credential-file access, environment harvesting, hardcoded exfiltration endpoints, install-script hooks, obfuscated payloads, reverse shells.\n\nIt works on a local directory, a published npm package, or a GitHub repo, and prints a letter grade (A–F) plus every finding with a file and line. There is a `--json` mode and a `--fail-on` gate for CI.\n\n> Why this exists: a July 2026 scan of 36,527 public MCP servers found ~67% carry serious security flaws, and 9 of 11 public registries accepted a proof-of-concept malicious server. MCP adoption exploded before its safety layer existed. mcpguard is the start of that layer.\n\n### Tried against real servers\n\nRun against popular published servers (as of July 2026), the scanner grades clean servers A and surfaces exactly the behaviors worth a human's attention:\n\n| Server (npm) | Grade | Notes |\n| --- | --- | --- |\n| `@modelcontextprotocol/server-filesystem` | A | 14 tools extracted, no findings |\n| `@notionhq/notion-mcp-server` | A | 33 tools, no findings |\n| `firecrawl-mcp` | A | 26 tools, no findings |\n| `@upstash/context7-mcp` | A | clean |\n| `figma-developer-mcp` | A | clean |\n| `@modelcontextprotocol/server-everything` | B | flags a tool that serializes `process.env` |\n| `mcp-server-fetch` (an npx canary) | B | flags a `postinstall` hook + host fingerprinting |\n\nTuning these runs drove several precision fixes now covered by tests: scanning compiled `dist/` when a package ships no `src/`, ignoring test files and commented-out code, and not misreading regex `.exec()`, loopback IPs, or embedded base64 images as attacks.\n\n### The state of MCP security on npm\n\nWe scanned the **150 most-downloaded MCP server packages on npm**: **69% grade A**, but **16% land at D or F**, and 4 packages read well-known credential files. See the full breakdown in [`report/REPORT.md`](./report/REPORT.md), regenerate with `node scripts/registry-report.mjs`.\n\n## Install / run\n\n```bash\n# install the CLI (published under a scoped name; the command is `mcpguard`)\nnpm install -g @arunmm8335/mcpguard\nmcpguard scan <target>\n\n# or run without installing\nnpx @arunmm8335/mcpguard scan <target>\n```\n\nFrom source:\n\n```bash\nnpm install\nnpm run build\nnode dist/cli.js scan <target>\n```\n\n## Usage\n\n```bash\n# a local server checkout\nmcpguard scan ./my-server\n\n# a published npm package\nmcpguard scan npm:some-mcp-server\n\n# a GitHub repo (shorthand or full URL)\nmcpguard scan owner/repo\nmcpguard scan https://github.com/owner/repo.git\n\n# machine-readable output\nmcpguard scan ./my-server --json\n\n# CI gate: exit non-zero at grade D or worse (default is D)\nmcpguard scan ./my-server --fail-on C\n```\n\n### Lock & verify (rug-pull detection)\n\nScanning tells you a server is safe *today*. The bigger risk is a **rug pull**: a server you already approved silently changing its tool descriptions or code afterwards. `lock` pins the approved state to a content hash; `verify` re-scans and fails when anything drifted.\n\n```bash\n# Approve servers: pins code + tool descriptions to mcpguard.lock.json\nmcpguard lock ./my-server npm:some-mcp-server owner/repo\n\n# In CI / before startup: re-scan every locked server and fail on drift\nmcpguard verify\nmcpguard verify --json          # machine-readable diff\nmcpguard verify --file custom.lock.json\n```\n\n`verify` exits non-zero if any locked server changed. A changed or removed **tool description** is flagged as a `RUG PULL` (the metadata your agent trusts was altered after approval); code edits, added/removed files, and grade regressions are reported too.\n\n```\nmcpguard verify\n\n RUG PULL  ./my-server\n           tool description changed: get_forecast\n           code changed: index.js\n           grade A -> F\n\n1 server(s) drifted from the lockfile. Review before trusting them.\n```\n\nCommit `mcpguard.lock.json` to your repo so every teammate and CI run enforces the same approved set.\n\n## Use in CI (GitHub Actions)\n\nThis repo ships a composite action. Commit your `mcpguard.lock.json`, then fail the build whenever a dependency server drifts:\n\n```yaml\n- uses: your-org/mcpguard@v0\n  with:\n    mode: verify          # default; checks mcpguard.lock.json for drift\n\n# or grade a specific server on every PR:\n- uses: your-org/mcpguard@v0\n  with:\n    mode: scan\n    target: npm:some-mcp-server\n    fail-on: C\n```\n\nOr call the CLI directly in any pipeline: `npx @arunmm8335/mcpguard verify`.\n\n### Example\n\n```\nmcpguard scan: ./suspicious-server\n1 files scanned · 2 tools found · 7 findings\n\n CRITICAL  TD001 instruction-override (tool-poisoning)\n           Tool \"summarize_notes\": Tool description attempts to override the agent's instructions.\n           index.js:5\n           match: Ignore all previous instructions\n ...\nGrade: F  (score 0/100)\nDo not install this server without a manual security review.\n```\n\n## How it works\n\nThe scan is static and fast (no code is executed):\n\n1. **Resolve** the target to a local directory (`src/resolve.ts`) — clones or `npm pack`s remote targets.\n2. **Collect** source files, skipping `node_modules`, build output, and large blobs (`src/collect.ts`).\n3. **Extract** tool names and descriptions from the dominant MCP styles: TS/JS SDK `server.tool(...)` / `registerTool(...)`, object-literal / JSON manifests, and Python `@mcp.tool()` decorators and `Tool(...)` constructors (`src/extract.ts`).\n4. **Match** two rule packs (`rules/*.yaml`) — one against tool descriptions, one against code (`src/scan.ts`).\n5. **Grade**: severity-weighted score, with any critical tool-poisoning finding forcing an automatic F.\n\n## Rules\n\nRules are plain YAML in [`rules/`](./rules), so they're easy to review and extend:\n\n- [`tool-poisoning.yaml`](./rules/tool-poisoning.yaml) — applied to tool descriptions.\n- [`malicious-code.yaml`](./rules/malicious-code.yaml) — applied to source code.\n\nEach rule has an id, severity, human-readable description, and a regex `pattern`. A code match is *evidence to review*, not proof of malice — the grade weighs it accordingly.\n\n## Development\n\n```bash\nnpm test        # vitest, runs against fixtures in test/fixtures\nnpm run build   # tsc -> dist/\n```\n\nTest fixtures cover a benign server (expects grade A), a tool-poisoned server, and a malicious-code server.\n\n## Roadmap\n\nPhase 1 (scanner) and Phase 2 (lockfile + rug-pull `verify`) are implemented. Planned next:\n\n- **Trust registry + monitoring** — continuously re-scan the ecosystem, archive versions, alert on changes.\n- **Runtime proxy** — enforce the lockfile and strip injected instructions at call time, with an audit log.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-019552d13992cd01acb25b726ffeb5d5"}