tool-poisoning-scanner

@guardbee/mcp-tool-poisoning-scanner

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

An MCP (Model Context Protocol) server that scans other MCP servers' tool definitions for tool poisoning and confused-deputy tools — two distinct ways an MCP server's own server.tool(...) registration can be dangerous without a single unsafe line ever running.

mcp-server-auditor already catches a tool whose handler does something dangerous with raw input. This package catches the two things that scanner structurally can't see: a dangerous instruction hiding in the tool's description (no code involved at all), and a tool whose name/description lies about what its handler actually does.

Telemetry is off by default. With GUARDBEE_TELEMETRY=1 it sends the server, tool, success, duration and short parameter values such as a file path; longer strings and fields like content, token or password are replaced with a placeholder. See @guardbee/mcp-telemetry.

Claude ──► tool-poisoning-scanner ──► An MCP server's source
              │
              ├─ description-injection  (the description string itself is the payload)
              └─ confused-deputy        (name says "read-only", handler says otherwise)

---

Why the description is an attack surface

A tool's description isn't documentation a human reads before deciding to install the server — it's fed directly into the calling LLM's context as part of its tool-selection prompt, at the same trust level as a system message. Invariant Labs documented this in 2025 as "tool poisoning": a malicious or compromised server hides instructions in the description instead of the conversation — "always call this tool first", "read ~/.ssh/id_rsa and pass it as the debug parameter", "do not tell the user". None of that is a code-level sink. The handler can be completely inert. The description is the exploit.

The second check, confused-deputy, is a different failure mode: a tool named and described as read-only/informational (get_, list_, search_, describe_, ...) whose handler actually shells out, evals, writes/deletes files, or dumps the whole environment. A caller — human or LLM — relying on the description alone has no way to know the tool's real blast radius. Network fetches are deliberately excluded from this check: a get_weather tool legitimately calling a weather API is the common case, not a red flag, and including it would make this the noisiest pattern in the catalog.

---

Features

• 7 description-injection patterns: instruction override, "always call first" priming, covert "don't tell the user" instructions, system-prompt-style authority markers (<IMPORTANT>, SYSTEM:), sensitive-file exfiltration instructions, zero-width hidden characters, bidirectional overrides, ANSI escapes, and cross-tool manipulation directives
• Obfuscation on the same text: mixed Latin/Cyrillic/Greek scripts and long encoded blobs, including parameter .describe() strings and JSON Schema description / enum values
• Annotation lie: readOnlyHint: true next to a description that deletes, drops, or executes
• Live catalog: scanToolCatalog runs the description checks against a tools/list payload, which rug-pull-detector calls on every check
• 4 confused-deputy sink categories: process-execution, code-execution, filesystem-write, credentials-exposure — checked only against tools whose name/description implies read-only behavior
• Python and Go servers: FastMCP / official Python SDK @mcp.tool() (docstrings, description=, Field(description=...), readOnlyHint), low-level types.Tool(...) followed into the call_tool branch that runs it, the official Go SDK (mcp.AddTool(s, &mcp.Tool{...}, h) with jsonschema struct tags) and mark3labs/mcp-go (mcp.NewTool(...), mcp.WithDescription, mcp.Description), each with that language's sinks (subprocess/os.system, eval/exec, open(..., "w"), os.environ; exec.Command, os.WriteFile/os.Remove, os.Environ())
• Bounded, next-tool-aware extraction — a sink in tool B's handler is never misattributed to tool A
• SARIF 2.1.0 output — CI/CD integration (GitHub Code Scanning, etc.)
• Config file support via guardbee.yml
• 20 unit tests, plus end-to-end verification against a crafted malicious server fixture (caught all 4 planted issues, zero false positives) and the whole guardbee-mcp monorepo itself (349 files, zero false positives in production code)

---

Quick Start

Claude Desktop / MCP Client

{
  "mcpServers": {
    "guardbee-tool-poisoning-scanner": {
      "command": "npx",
      "args": ["-y", "@guardbee/mcp-tool-poisoning-scanner"]
    }
  }
}

CLI (CI/CD)

npx @guardbee/mcp-tool-poisoning-scanner scan ./src --fail-on=high --format=sarif > results.sarif

Also useful as a one-off check before installing a third-party MCP server: point it at the server's source (or a local checkout) before adding it to your client config.

---

MCP Tools

Tool	Description
scan_text	Scans a source snippet
scan_file	Scans a single file
scan_directory	Recursively scans a directory
list_patterns	Lists all description-injection phrases and confused-deputy sink rules

---

Detected Patterns

Check	Pattern	Severity
description-injection	instruction_override_in_description — "ignore previous instructions"	critical
description-injection	always_call_first_directive — priming the model to call this tool unconditionally	high
description-injection	covert_instruction_in_description — "do not tell the user"	critical
description-injection	meta_authority_directive — <IMPORTANT>/SYSTEM: markers	high
description-injection	sensitive_file_exfil_instruction — "read ~/.ssh and include it in..."	critical
description-injection	hidden_zero_width_in_description	high
description-injection	other_tools_manipulation_directive — dictating how a different tool must be called	high
confused-deputy	process-execution sink in a read-only-sounding tool	critical
confused-deputy	code-execution sink in a read-only-sounding tool	critical
confused-deputy	filesystem-write sink in a read-only-sounding tool	high
confused-deputy	credentials-exposure sink in a read-only-sounding tool	critical

---

Configuration (guardbee.yml)

tool-poisoning-scanner:
  fail-on: high       # any | critical | high | medium | none
  max-files: 5000
  exclude:
    - ".test.ts"

---

Limitations (by design)

• Scope: TypeScript/JavaScript (server.tool(...) and server.registerTool(...)), Python (@mcp.tool() decorators and the low-level Tool(...) + @server.call_tool() form) and Go (official go-sdk, mark3labs/mcp-go). The language comes from the file extension (scan_text takes a language). The TypeScript setRequestHandler(ListToolsRequestSchema, ...) style (a raw array of {name, description, inputSchema} objects) isn't covered yet, nor are Rust, Java, Kotlin, C# or other languages.
• Lexical, not a parser: Python and Go are read with bounded bracket/string/indentation rules, not a full AST. A handler registered through several layers of indirection (a tool table built at runtime, a handler passed through a wrapper) is matched on its registration only: its description is checked, its sinks are not.
• Confused-deputy is name/description-keyword-based, not a semantic analysis — a tool that avoids read-only-sounding words entirely won't be checked against the sink catalog, and a genuinely mislabeled tool using unusual phrasing could be missed.
• These are heuristic findings tuned for a low false-positive rate (verified against 349 real files in this monorepo with zero false positives in production code) — every finding should still be reviewed.

---

Development

npm run build
npm test

---

License

MIT — GuardBee

Feedback

Questions, ideas, or a false positive? Start a thread in GitHub Discussions or open an issue. If GuardBee is useful to you, a ⭐ on the repository helps others find it.