@guardbee/mcp-prompt-injection-scanner 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +39 -37
  2. package/TR.md +110 -0
  3. package/package.json +6 -4
package/README.md CHANGED
@@ -1,34 +1,36 @@
1
1
  # @guardbee/mcp-prompt-injection-scanner
2
2
 
3
- MCP (Model Context Protocol) sunucusu — **içeriği** (RAG chunk'ı, scrape edilmiş bir web sayfası, bir doküman) dolaylı (indirect) prompt injection payload'ları için tarar.
3
+ **🇬🇧 English** | [🇹🇷 Türkçe](TR.md)
4
4
 
5
- `ai-code-scanner` ve `mcp-server-auditor` kod tarıyor; bu paket **veri** tarıyor. Klasik prompt injection kullanıcının kendisi kötü niyetli bir prompt yazar; dolaylı (indirect) prompt injection'da saldırgan modele hiç konuşmaz — bunun yerine modelin okuyacağı bir belgeye, web sayfasına ya da tool sonucuna talimat gömer. Model bu içeriği bir RAG retrieval'ı ya da bir web fetch sonucunda context'ine aldığı anda, gömülü talimat kullanıcının kendi talimatlarıyla aynı yetkiye sahip görünür.
5
+ An MCP (Model Context Protocol) server that scans **content** — a RAG chunk, a scraped web page, a document — for indirect prompt injection payloads.
6
6
 
7
- > Bu paket varsayılan olarak kullanım telemetrisi gönderir (tool adı + kısa parametreler, taranan içerik hiçbir zaman dahil değil — bkz. [`@guardbee/mcp-telemetry`](../telemetry/README.md)). Kapatmak için `GUARDBEE_TELEMETRY=0`.
7
+ `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.
8
+
9
+ > This package sends usage telemetry by default (tool name + short parameters, the scanned content is never included — see [`@guardbee/mcp-telemetry`](../telemetry/README.md)). Disable with `GUARDBEE_TELEMETRY=0`.
8
10
 
9
11
  ```
10
- Web sayfası/RAG dokümanı ──► prompt-injection-scanner ──► LLM context'i
12
+ Web page/RAG document ──► prompt-injection-scanner ──► LLM context
11
13
  │
12
14
  ├─ Instruction override ("ignore all previous instructions")
13
15
  ├─ Role spoofing ("System:", <|im_start|>, [INST])
14
- ├─ Hidden text (zero-width karakter, display:none + talimat, HTML yorumu)
16
+ ├─ Hidden text (zero-width characters, display:none + instruction, HTML comment)
15
17
  ├─ Direct address ("Dear AI, ...")
16
- └─ Exfiltration (system prompt sızdırma isteği, data → URL talimatı, template'li img beacon)
18
+ └─ Exfiltration (system prompt extraction request, data → URL instruction, templated img beacon)
17
19
  ```
18
20
 
19
21
  ---
20
22
 
21
- ## Özellikler
23
+ ## Features
22
24
 
23
- - **10 kalıp, 5 kategori** — instruction-override, role-spoofing, hidden-text, direct-address, exfiltration
24
- - Her bulguda **neden riskli olduğu ve ne yapılması gerektiği** (`recommendation`) — sadece "bulundu" demez
25
- - SARIF 2.1.0 çıktısı — CI/CD entegrasyonu (bir knowledge-base repo'sunu PR'da otomatik tarama gibi)
26
- - `guardbee.yml` ile config dosyası desteği
27
- - 30 unit test — her kalıp için hem pozitif hem negatif (yanlış-pozitif) senaryo; özellikle emoji ZWJ dizileri ve normal `display:none` modal'ları gibi bilinen yanlış-pozitif kaynakları ayrıca test edilir
25
+ - **10 patterns, 5 categories** — instruction-override, role-spoofing, hidden-text, direct-address, exfiltration
26
+ - Every finding includes **why it's risky and what to do about it** (`recommendation`) — not just "found it"
27
+ - SARIF 2.1.0 output — CI/CD integration (e.g. auto-scanning a knowledge-base repo on every PR)
28
+ - Config file support via `guardbee.yml`
29
+ - 30 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
28
30
 
29
31
  ---
30
32
 
31
- ## Hızlı Başlangıç
33
+ ## Quick Start
32
34
 
33
35
  ### Claude Desktop / MCP Client
34
36
 
@@ -43,7 +45,7 @@ Web sayfası/RAG dokümanı ──► prompt-injection-scanner ──► LLM con
43
45
  }
44
46
  ```
45
47
 
46
- ### CLI (CI/CD — örn. bir RAG knowledge-base reposunu her PR'da tara)
48
+ ### CLI (CI/CD — e.g. scan a RAG knowledge-base repo on every PR)
47
49
 
48
50
  ```bash
49
51
  npx @guardbee/mcp-prompt-injection-scanner scan ./knowledge-base --fail-on=high --format=sarif > results.sarif
@@ -53,35 +55,35 @@ npx @guardbee/mcp-prompt-injection-scanner scan ./knowledge-base --fail-on=high
53
55
 
54
56
  ## MCP Tools
55
57
 
56
- | Tool | Açıklama |
58
+ | Tool | Description |
57
59
  |------|----------|
58
- | `scan_text` | Verilen bir metin/doküman parçasını tarar |
59
- | `scan_file` | Tek bir dosyayı tarar |
60
- | `scan_directory` | Bir dizini (örn. RAG knowledge base) recursive tarar (`node_modules`, `.git`, `dist` otomatik atlanır) |
61
- | `list_patterns` | Desteklenen tüm kalıpları kategoriye göre listeler |
60
+ | `scan_text` | Scans a given text/document snippet |
61
+ | `scan_file` | Scans a single file |
62
+ | `scan_directory` | Recursively scans a directory (e.g. a RAG knowledge base) (`node_modules`, `.git`, `dist` skipped automatically) |
63
+ | `list_patterns` | Lists all supported patterns by category |
62
64
 
63
65
  ---
64
66
 
65
- ## Tespit Edilen Kalıplar
67
+ ## Detected Patterns
66
68
 
67
- | Kategori | Kalıp | Önem | Ne demek |
69
+ | Category | Pattern | Severity | What it means |
68
70
  |---|---|---|---|
69
- | instruction-override | `instruction_override_phrase` | high | "ignore/disregard/forget previous instructions" gibi klasik bir override cümlesi |
70
- | role-spoofing | `system_role_spoof` | medium | İçerikte satır başında sahte bir "System:" rol etiketi |
71
- | role-spoofing | `chat_template_marker_injection` | high | Ham chat-template kontrol token'ları (`<\|im_start\|>`, `[INST]`) içerikte |
72
- | hidden-text | `hidden_zero_width_chars` | medium | Zero-width space/word-joiner (U+200B/U+2060) — insan gözünden gizli metin |
73
- | hidden-text | `css_hidden_text_with_instruction` | high | `display:none`/beyaz-üzerine-beyaz bir element, içinde talimat-benzeri dil |
74
- | hidden-text | `html_comment_instruction` | high | HTML yorumu içinde talimat-benzeri dil |
75
- | direct-address | `direct_address_to_ai` | medium | İçerik doğrudan "the AI"/"the assistant"a hitap ediyor |
76
- | exfiltration | `exfiltration_url_template_in_image` | high | Markdown görsel URL'inde `{{...}}`/`${...}` template — data-exfil beacon |
77
- | exfiltration | `reveal_system_prompt_request` | high | Modele system prompt'unu ifşa etmesini isteyen bir cümle |
78
- | exfiltration | `send_data_to_url_instruction` | critical | Modele veriyi bir dış URL'e göndermesini emreden açık bir talimat |
79
-
80
- Bunlar **heuristic** bulgulardır — anlam/niyet analizi değil, statik metin kalıbı taraması yapar. Düşük yanlış-pozitif oranı için tasarlandı (örn. emoji ZWJ dizileri ve normal `display:none` modal'ları özellikle hariç tutuldu) ama her bulgu yine de manuel gözden geçirilmelidir.
71
+ | instruction-override | `instruction_override_phrase` | high | A classic override phrase like "ignore/disregard/forget previous instructions" |
72
+ | role-spoofing | `system_role_spoof` | medium | A fake "System:" role label at the start of a line in the content |
73
+ | role-spoofing | `chat_template_marker_injection` | high | Raw chat-template control tokens (`<\|im_start\|>`, `[INST]`) in the content |
74
+ | hidden-text | `hidden_zero_width_chars` | medium | Zero-width space/word-joiner (U+200B/U+2060) — text hidden from a human reviewer |
75
+ | hidden-text | `css_hidden_text_with_instruction` | high | A `display:none`/white-on-white element containing instruction-like language |
76
+ | hidden-text | `html_comment_instruction` | high | An HTML comment containing instruction-like language |
77
+ | direct-address | `direct_address_to_ai` | medium | The content directly addresses "the AI"/"the assistant" |
78
+ | exfiltration | `exfiltration_url_template_in_image` | high | A markdown image URL with a `{{...}}`/`${...}` template — a data-exfil beacon |
79
+ | exfiltration | `reveal_system_prompt_request` | high | A sentence asking the model to reveal its system prompt |
80
+ | exfiltration | `send_data_to_url_instruction` | critical | An explicit instruction ordering the model to send data to an external URL |
81
+
82
+ 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.
81
83
 
82
84
  ---
83
85
 
84
- ## Yapılandırma (`guardbee.yml`)
86
+ ## Configuration (`guardbee.yml`)
85
87
 
86
88
  ```yaml
87
89
  prompt-injection-scanner:
@@ -94,15 +96,15 @@ prompt-injection-scanner:
94
96
 
95
97
  ---
96
98
 
97
- ## Geliştirme
99
+ ## Development
98
100
 
99
101
  ```bash
100
102
  npm run build
101
- npm test # 30 unit test
103
+ npm test # 30 unit tests
102
104
  ```
103
105
 
104
106
  ---
105
107
 
106
- ## Lisans
108
+ ## License
107
109
 
108
110
  MIT — [GuardBee](https://guardbee.ai)
package/TR.md ADDED
@@ -0,0 +1,110 @@
1
+ # @guardbee/mcp-prompt-injection-scanner
2
+
3
+ [🇬🇧 English](README.md) | **🇹🇷 Türkçe**
4
+
5
+ MCP (Model Context Protocol) sunucusu — **içeriği** (RAG chunk'ı, scrape edilmiş bir web sayfası, bir doküman) dolaylı (indirect) prompt injection payload'ları için tarar.
6
+
7
+ `ai-code-scanner` ve `mcp-server-auditor` kod tarıyor; bu paket **veri** tarıyor. Klasik prompt injection kullanıcının kendisi kötü niyetli bir prompt yazar; dolaylı (indirect) prompt injection'da saldırgan modele hiç konuşmaz — bunun yerine modelin okuyacağı bir belgeye, web sayfasına ya da tool sonucuna talimat gömer. Model bu içeriği bir RAG retrieval'ı ya da bir web fetch sonucunda context'ine aldığı anda, gömülü talimat kullanıcının kendi talimatlarıyla aynı yetkiye sahip görünür.
8
+
9
+ > Bu paket varsayılan olarak kullanım telemetrisi gönderir (tool adı + kısa parametreler, taranan içerik hiçbir zaman dahil değil — bkz. [`@guardbee/mcp-telemetry`](../telemetry/TR.md)). Kapatmak için `GUARDBEE_TELEMETRY=0`.
10
+
11
+ ```
12
+ Web sayfası/RAG dokümanı ──► prompt-injection-scanner ──► LLM context'i
13
+ │
14
+ ├─ Instruction override ("ignore all previous instructions")
15
+ ├─ Role spoofing ("System:", <|im_start|>, [INST])
16
+ ├─ Hidden text (zero-width karakter, display:none + talimat, HTML yorumu)
17
+ ├─ Direct address ("Dear AI, ...")
18
+ └─ Exfiltration (system prompt sızdırma isteği, data → URL talimatı, template'li img beacon)
19
+ ```
20
+
21
+ ---
22
+
23
+ ## Özellikler
24
+
25
+ - **10 kalıp, 5 kategori** — instruction-override, role-spoofing, hidden-text, direct-address, exfiltration
26
+ - Her bulguda **neden riskli olduğu ve ne yapılması gerektiği** (`recommendation`) — sadece "bulundu" demez
27
+ - SARIF 2.1.0 çıktısı — CI/CD entegrasyonu (bir knowledge-base repo'sunu PR'da otomatik tarama gibi)
28
+ - `guardbee.yml` ile config dosyası desteği
29
+ - 30 unit test — her kalıp için hem pozitif hem negatif (yanlış-pozitif) senaryo; özellikle emoji ZWJ dizileri ve normal `display:none` modal'ları gibi bilinen yanlış-pozitif kaynakları ayrıca test edilir
30
+
31
+ ---
32
+
33
+ ## Hızlı Başlangıç
34
+
35
+ ### Claude Desktop / MCP Client
36
+
37
+ ```json
38
+ {
39
+ "mcpServers": {
40
+ "guardbee-prompt-injection-scanner": {
41
+ "command": "npx",
42
+ "args": ["-y", "@guardbee/mcp-prompt-injection-scanner"]
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ### CLI (CI/CD — örn. bir RAG knowledge-base reposunu her PR'da tara)
49
+
50
+ ```bash
51
+ npx @guardbee/mcp-prompt-injection-scanner scan ./knowledge-base --fail-on=high --format=sarif > results.sarif
52
+ ```
53
+
54
+ ---
55
+
56
+ ## MCP Tools
57
+
58
+ | Tool | Açıklama |
59
+ |------|----------|
60
+ | `scan_text` | Verilen bir metin/doküman parçasını tarar |
61
+ | `scan_file` | Tek bir dosyayı tarar |
62
+ | `scan_directory` | Bir dizini (örn. RAG knowledge base) recursive tarar (`node_modules`, `.git`, `dist` otomatik atlanır) |
63
+ | `list_patterns` | Desteklenen tüm kalıpları kategoriye göre listeler |
64
+
65
+ ---
66
+
67
+ ## Tespit Edilen Kalıplar
68
+
69
+ | Kategori | Kalıp | Önem | Ne demek |
70
+ |---|---|---|---|
71
+ | instruction-override | `instruction_override_phrase` | high | "ignore/disregard/forget previous instructions" gibi klasik bir override cümlesi |
72
+ | role-spoofing | `system_role_spoof` | medium | İçerikte satır başında sahte bir "System:" rol etiketi |
73
+ | role-spoofing | `chat_template_marker_injection` | high | Ham chat-template kontrol token'ları (`<\|im_start\|>`, `[INST]`) içerikte |
74
+ | hidden-text | `hidden_zero_width_chars` | medium | Zero-width space/word-joiner (U+200B/U+2060) — insan gözünden gizli metin |
75
+ | hidden-text | `css_hidden_text_with_instruction` | high | `display:none`/beyaz-üzerine-beyaz bir element, içinde talimat-benzeri dil |
76
+ | hidden-text | `html_comment_instruction` | high | HTML yorumu içinde talimat-benzeri dil |
77
+ | direct-address | `direct_address_to_ai` | medium | İçerik doğrudan "the AI"/"the assistant"a hitap ediyor |
78
+ | exfiltration | `exfiltration_url_template_in_image` | high | Markdown görsel URL'inde `{{...}}`/`${...}` template — data-exfil beacon |
79
+ | exfiltration | `reveal_system_prompt_request` | high | Modele system prompt'unu ifşa etmesini isteyen bir cümle |
80
+ | exfiltration | `send_data_to_url_instruction` | critical | Modele veriyi bir dış URL'e göndermesini emreden açık bir talimat |
81
+
82
+ Bunlar **heuristic** bulgulardır — anlam/niyet analizi değil, statik metin kalıbı taraması yapar. Düşük yanlış-pozitif oranı için tasarlandı (örn. emoji ZWJ dizileri ve normal `display:none` modal'ları özellikle hariç tutuldu) ama her bulgu yine de manuel gözden geçirilmelidir.
83
+
84
+ ---
85
+
86
+ ## Yapılandırma (`guardbee.yml`)
87
+
88
+ ```yaml
89
+ prompt-injection-scanner:
90
+ fail-on: high # any | critical | high | medium | low | none
91
+ max-files: 5000
92
+ exclude:
93
+ - "**/*.test.ts"
94
+ - "fixtures/"
95
+ ```
96
+
97
+ ---
98
+
99
+ ## Geliştirme
100
+
101
+ ```bash
102
+ npm run build
103
+ npm test # 30 unit test
104
+ ```
105
+
106
+ ---
107
+
108
+ ## Lisans
109
+
110
+ MIT — [GuardBee](https://guardbee.ai)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guardbee/mcp-prompt-injection-scanner",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "MCP server that scans documents, scraped pages, and RAG content for indirect prompt injection payloads — instruction-override phrases, spoofed chat-template roles, hidden/invisible text, content addressing the AI directly, and data-exfiltration attempts",
5
5
  "type": "module",
6
6
  "bin": {
@@ -16,12 +16,13 @@
16
16
  },
17
17
  "files": [
18
18
  "dist",
19
- "README.md"
19
+ "README.md",
20
+ "TR.md"
20
21
  ],
21
22
  "dependencies": {
22
23
  "@modelcontextprotocol/sdk": "^1.0.0",
23
24
  "zod": "^4.5.4",
24
- "@guardbee/mcp-telemetry": "^0.1.0"
25
+ "@guardbee/mcp-telemetry": "^0.1.2"
25
26
  },
26
27
  "keywords": [
27
28
  "mcp",
@@ -36,7 +37,8 @@
36
37
  "license": "MIT",
37
38
  "repository": {
38
39
  "type": "git",
39
- "url": "https://github.com/GuardBee/guardbee-mcp.git"
40
+ "url": "https://github.com/GuardBee/guardbee-mcp.git",
41
+ "directory": "packages/prompt-injection-scanner"
40
42
  },
41
43
  "scripts": {
42
44
  "build": "tsc",