prompt-injection-scanner

@guardbee/mcp-prompt-injection-scanner

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

An MCP (Model Context Protocol) server that scans content — a RAG chunk, a scraped web page, a document — for indirect prompt injection payloads.

ai-code-scanner and mcp-server-auditor scan code; this package scans data. In classic prompt injection, the attacker writes a malicious prompt themselves; in indirect prompt injection, the attacker never talks to the model at all — instead they embed instructions in a document, web page, or tool result the model will later read. The moment the model pulls this content into its context via a RAG retrieval or a web fetch, the embedded instruction appears to carry the same authority as the user's own instructions.

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.

Web page/RAG document ──► prompt-injection-scanner ──► LLM context
              │
              ├─ Instruction override   ("ignore all previous instructions", "önceki talimatları yok say")
              ├─ Role spoofing          ("System:", <|im_start|>, [INST], <system>)
              ├─ Hidden text            (zero-width, Unicode tag and bidi characters, display:none + instruction, HTML comment)
              ├─ Direct address         ("Dear AI, ...")
              └─ Exfiltration           (system prompt extraction request, data → URL instruction, templated img beacon)

---

Features

• 17 patterns, 5 categories — instruction-override, role-spoofing, hidden-text, direct-address, exfiltration. English and Turkish phrasing
• The rules live in @guardbee/guard-core, shared with @guardbee/mcp-security-proxy, so a phrase this scanner reports is the same phrase the proxy blocks at runtime
• Every finding includes why it's risky and what to do about it (recommendation) — not just "found it"
• SARIF 2.1.0 output — CI/CD integration (e.g. auto-scanning a knowledge-base repo on every PR)
• Config file support via guardbee.yml
• 45 unit tests — a positive and a negative (false-positive) scenario for every pattern; known false-positive sources like emoji ZWJ sequences and ordinary display:none modals are specifically tested

---

Quick Start

Claude Desktop / MCP Client

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

CLI (CI/CD — e.g. scan a RAG knowledge-base repo on every PR)

npx @guardbee/mcp-prompt-injection-scanner scan ./knowledge-base --fail-on=high --format=sarif > results.sarif

---

MCP Tools

Tool	Description
scan_text	Scans a given text/document snippet
scan_file	Scans a single file
scan_directory	Recursively scans a directory (e.g. a RAG knowledge base) (node_modules, .git, dist skipped automatically)
list_patterns	Lists all supported patterns by category

---

Detected Patterns

Category	Pattern	Severity	What it means
instruction-override	instruction_override_phrase	high	A classic override phrase like "ignore/disregard/forget previous instructions"
instruction-override	instruction_override_tr	high	The Turkish form: "önceki talimatları yok say / unut / görmezden gel"
instruction-override	dan_mode	high	Asks for the "DAN mode" jailbreak persona
instruction-override	bypass_safety	high	Tells the model to bypass or disable its safety measures / guardrails
role-spoofing	system_role_spoof	medium	A fake "System:" role label at the start of a line in the content
role-spoofing	chat_template_marker_injection	high	Raw chat-template control tokens (<|im_start|>, [INST]) in the content
role-spoofing	system_tag	high	A <system> tag that tries to pass data off as a system message
hidden-text	hidden_zero_width_chars	medium	Zero-width space/word-joiner (U+200B/U+2060) — text hidden from a human reviewer
hidden-text	unicode_tag_smuggling	critical	Invisible Unicode tag characters (U+E0000–E007F) carrying hidden text; flag emoji such as 🏴󠁧󠁢󠁥󠁮󠁧󠁿 are excluded
hidden-text	bidi_control_chars	medium	Bidi override/isolate characters that make text display in a different order than it is read
hidden-text	css_hidden_text_with_instruction	high	A display:none/white-on-white element containing instruction-like language
hidden-text	html_comment_instruction	high	An HTML comment containing instruction-like language
direct-address	direct_address_to_ai	medium	The content directly addresses "the AI"/"the assistant"
exfiltration	exfiltration_url_template_in_image	high	A markdown image URL with a {{...}}/${...} template — a data-exfil beacon
exfiltration	reveal_system_prompt_request	high	A sentence asking the model to reveal its system prompt
exfiltration	reveal_system_prompt_tr	high	The Turkish form: "sistem istemini göster"
exfiltration	send_data_to_url_instruction	critical	An explicit instruction ordering the model to send data to an external URL

These are heuristic findings — a static text-pattern scan, not a semantic/intent analysis. Designed for a low false-positive rate (e.g. emoji ZWJ sequences and ordinary display:none modals are specifically excluded), but every finding should still be reviewed manually.

---

Configuration (guardbee.yml)

prompt-injection-scanner:
  fail-on: high       # any | critical | high | medium | low | none
  max-files: 5000
  exclude:
    - ".test.ts"
    - "fixtures/"

---

Development

npm run build
npm test             # 45 unit tests

---

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.