@guardbee/mcp-server-auditor 0.1.0 → 0.1.1

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 +4 -3
package/README.md CHANGED
@@ -1,34 +1,36 @@
1
1
  # @guardbee/mcp-server-auditor
2
2
 
3
- MCP (Model Context Protocol) sunucusu — **başka MCP server'ların** tool tanımlarını güvensiz kalıplar için tarar.
3
+ **🇬🇧 English** | [🇹🇷 Türkçe](TR.md)
4
4
 
5
- `ai-code-scanner` genel LLM/AI entegrasyon koduna bakarken, bu paket özellikle bir MCP server'ın kendisine bakar: `server.tool(...)` ile tanımlanan bir tool ne kadar yetkili, parametreleri ne kadar gevşek, handler'ı hangi tehlikeli sink'lere (shell/dosya sistemi/HTTP/SQL) doğrudan tool girdisi geçiriyor. MCP ekosistemi hızla büyüyor ama bu server'ların güvenlik denetimi için yaygın bir araç henüz yok.
5
+ An MCP (Model Context Protocol) server that scans **other MCP servers'** tool definitions for insecure patterns.
6
6
 
7
- > Bu paket varsayılan olarak kullanım telemetrisi gönderir (tool adı + kısa parametreler, taranan kod hiçbir zaman dahil değil — bkz. [`@guardbee/mcp-telemetry`](../telemetry/README.md)). Kapatmak için `GUARDBEE_TELEMETRY=0`.
7
+ While `ai-code-scanner` looks at general LLM/AI integration code, this package specifically looks at an MCP server itself: how privileged a tool defined via `server.tool(...)` is, how loose its parameters are, which dangerous sinks (shell/filesystem/HTTP/SQL) its handler passes tool input into directly. The MCP ecosystem is growing fast, but there's no common tool yet for auditing these servers' security.
8
+
9
+ > This package sends usage telemetry by default (tool name + short parameters, the scanned code is never included — see [`@guardbee/mcp-telemetry`](../telemetry/README.md)). Disable with `GUARDBEE_TELEMETRY=0`.
8
10
 
9
11
  ```
10
- Claude ──► mcp-server-auditor ──► Bir MCP server'ın kaynak kodu
12
+ Claude ──► mcp-server-auditor ──► An MCP server's source code
11
13
  │
12
- ├─ Excessive agency (execSync(input.command), "run_shell" adlı bir tool)
14
+ ├─ Excessive agency (execSync(input.command), a tool named "run_shell")
13
15
  ├─ Unsafe input (fetch(input.url) → SSRF, SQL string interpolation)
14
- ├─ Loose schema (bir parametre z.any()/z.unknown() tipinde)
15
- ├─ Secrets exposure (şema default'unda sabit API key, process.env'in tamamı)
16
+ ├─ Loose schema (a parameter typed z.any()/z.unknown())
17
+ ├─ Secrets exposure (a hardcoded API key in a schema default, the entire process.env)
16
18
  └─ Network exposure (wildcard CORS)
17
19
  ```
18
20
 
19
21
  ---
20
22
 
21
- ## Özellikler
23
+ ## Features
22
24
 
23
- - **10 kalıp, 5 kategori** — excessive-agency, unsafe-input, loose-schema, secrets-exposure, network-exposure
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 (GitHub Code Scanning vb.)
26
- - `guardbee.yml` ile config dosyası desteği
27
- - 32 unit test — her kalıp için hem pozitif hem negatif (yanlış-pozitif) senaryo
25
+ - **10 patterns, 5 categories** — excessive-agency, unsafe-input, loose-schema, secrets-exposure, network-exposure
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 (GitHub Code Scanning, etc.)
28
+ - Config file support via `guardbee.yml`
29
+ - 32 unit tests — a positive and a negative (false-positive) scenario for every pattern
28
30
 
29
31
  ---
30
32
 
31
- ## Hızlı Başlangıç
33
+ ## Quick Start
32
34
 
33
35
  ### Claude Desktop / MCP Client
34
36
 
@@ -53,35 +55,35 @@ npx @guardbee/mcp-server-auditor scan ./src --fail-on=high --format=sarif > resu
53
55
 
54
56
  ## MCP Tools
55
57
 
56
- | Tool | Açıklama |
58
+ | Tool | Description |
57
59
  |------|----------|
58
- | `scan_text` | Verilen bir metin/kod parçasını tarar |
59
- | `scan_file` | Tek bir dosyayı tarar |
60
- | `scan_directory` | Bir dizini 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/code snippet |
61
+ | `scan_file` | Scans a single file |
62
+ | `scan_directory` | Recursively scans a directory (`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
- | excessive-agency | `shell_exec_from_tool_input` | critical | Tool handler'ı, tool girdisini doğrudan `execSync`/`spawn` gibi bir shell çağrısına geçiriyor |
70
- | excessive-agency | `eval_of_tool_input` | critical | Tool girdisi `eval()`/`new Function()` ile kod olarak çalıştırılıyor |
71
- | excessive-agency | `unrestricted_shell_tool_name` | high | Tool adı (`run_shell`, `execute_sql` vb.) doğrudan shell/SQL çalıştırma yetkisi ima ediyor |
72
- | unsafe-input | `fs_write_from_raw_tool_input` | high | Tool girdisindeki bir path, doğrulama olmadan dosya yazma/silme çağrısına geçiyor (path traversal) |
73
- | unsafe-input | `ssrf_fetch_from_tool_input` | high | Tool girdisindeki bir URL, allowlist olmadan doğrudan `fetch`/`axios`'a geçiyor (SSRF) |
74
- | unsafe-input | `sql_injection_via_tool_input` | critical | Tool girdisi bir SQL string'ine template-literal ile enjekte ediliyor |
75
- | loose-schema | `overly_permissive_tool_schema` | medium | Bir tool parametresi `z.any()`/`z.unknown()` tipinde — her şeyi kabul ediyor |
76
- | secrets-exposure | `hardcoded_secret_in_tool_schema` | critical | Credential-benzeri bir şema alanının default değeri sabit bir literal |
77
- | secrets-exposure | `full_env_exposed_to_tool_caller` | critical | `process.env`'in tamamı spread/stringify/return ediliyor (tek bir named değişken değil) |
78
- | network-exposure | `permissive_cors_on_server` | medium | Wildcard CORS (`Access-Control-Allow-Origin: *`) ya da opsiyonsuz `cors()` |
79
-
80
- Bunlar **heuristic** bulgulardır — tam bir AST/tip analizi değil, statik metin kalıbı taraması yapar. Düşük yanlış-pozitif oranı için tasarlandı ama her bulgu yine de manuel gözden geçirilmelidir.
71
+ | excessive-agency | `shell_exec_from_tool_input` | critical | A tool handler passes tool input directly into a shell call like `execSync`/`spawn` |
72
+ | excessive-agency | `eval_of_tool_input` | critical | Tool input is executed as code via `eval()`/`new Function()` |
73
+ | excessive-agency | `unrestricted_shell_tool_name` | high | A tool name (`run_shell`, `execute_sql`, etc.) implies shell/SQL execution directly |
74
+ | unsafe-input | `fs_write_from_raw_tool_input` | high | A path from tool input flows into a file write/delete call with no validation (path traversal) |
75
+ | unsafe-input | `ssrf_fetch_from_tool_input` | high | A URL from tool input flows directly into `fetch`/`axios` with no allowlist (SSRF) |
76
+ | unsafe-input | `sql_injection_via_tool_input` | critical | Tool input is interpolated into a SQL string via a template literal |
77
+ | loose-schema | `overly_permissive_tool_schema` | medium | A tool parameter is typed `z.any()`/`z.unknown()` — accepts anything |
78
+ | secrets-exposure | `hardcoded_secret_in_tool_schema` | critical | A credential-shaped schema field's default value is a hardcoded literal |
79
+ | secrets-exposure | `full_env_exposed_to_tool_caller` | critical | The entire `process.env` is spread/stringified/returned (not one named variable) |
80
+ | network-exposure | `permissive_cors_on_server` | medium | Wildcard CORS (`Access-Control-Allow-Origin: *`) or `cors()` with no options |
81
+
82
+ These are **heuristic** findings — a static text-pattern scan, not a full AST/type analysis. Designed for a low false-positive rate, 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
  mcp-server-auditor:
@@ -94,15 +96,15 @@ mcp-server-auditor:
94
96
 
95
97
  ---
96
98
 
97
- ## Geliştirme
99
+ ## Development
98
100
 
99
101
  ```bash
100
102
  npm run build
101
- npm test # 32 unit test
103
+ npm test # 32 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-server-auditor
2
+
3
+ [🇬🇧 English](README.md) | **🇹🇷 Türkçe**
4
+
5
+ MCP (Model Context Protocol) sunucusu — **başka MCP server'ların** tool tanımlarını güvensiz kalıplar için tarar.
6
+
7
+ `ai-code-scanner` genel LLM/AI entegrasyon koduna bakarken, bu paket özellikle bir MCP server'ın kendisine bakar: `server.tool(...)` ile tanımlanan bir tool ne kadar yetkili, parametreleri ne kadar gevşek, handler'ı hangi tehlikeli sink'lere (shell/dosya sistemi/HTTP/SQL) doğrudan tool girdisi geçiriyor. MCP ekosistemi hızla büyüyor ama bu server'ların güvenlik denetimi için yaygın bir araç henüz yok.
8
+
9
+ > Bu paket varsayılan olarak kullanım telemetrisi gönderir (tool adı + kısa parametreler, taranan kod hiçbir zaman dahil değil — bkz. [`@guardbee/mcp-telemetry`](../telemetry/TR.md)). Kapatmak için `GUARDBEE_TELEMETRY=0`.
10
+
11
+ ```
12
+ Claude ──► mcp-server-auditor ──► Bir MCP server'ın kaynak kodu
13
+ │
14
+ ├─ Excessive agency (execSync(input.command), "run_shell" adlı bir tool)
15
+ ├─ Unsafe input (fetch(input.url) → SSRF, SQL string interpolation)
16
+ ├─ Loose schema (bir parametre z.any()/z.unknown() tipinde)
17
+ ├─ Secrets exposure (şema default'unda sabit API key, process.env'in tamamı)
18
+ └─ Network exposure (wildcard CORS)
19
+ ```
20
+
21
+ ---
22
+
23
+ ## Özellikler
24
+
25
+ - **10 kalıp, 5 kategori** — excessive-agency, unsafe-input, loose-schema, secrets-exposure, network-exposure
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 (GitHub Code Scanning vb.)
28
+ - `guardbee.yml` ile config dosyası desteği
29
+ - 32 unit test — her kalıp için hem pozitif hem negatif (yanlış-pozitif) senaryo
30
+
31
+ ---
32
+
33
+ ## Hızlı Başlangıç
34
+
35
+ ### Claude Desktop / MCP Client
36
+
37
+ ```json
38
+ {
39
+ "mcpServers": {
40
+ "guardbee-mcp-server-auditor": {
41
+ "command": "npx",
42
+ "args": ["-y", "@guardbee/mcp-server-auditor"]
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ### CLI (CI/CD)
49
+
50
+ ```bash
51
+ npx @guardbee/mcp-server-auditor scan ./src --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/kod parçasını tarar |
61
+ | `scan_file` | Tek bir dosyayı tarar |
62
+ | `scan_directory` | Bir dizini 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
+ | excessive-agency | `shell_exec_from_tool_input` | critical | Tool handler'ı, tool girdisini doğrudan `execSync`/`spawn` gibi bir shell çağrısına geçiriyor |
72
+ | excessive-agency | `eval_of_tool_input` | critical | Tool girdisi `eval()`/`new Function()` ile kod olarak çalıştırılıyor |
73
+ | excessive-agency | `unrestricted_shell_tool_name` | high | Tool adı (`run_shell`, `execute_sql` vb.) doğrudan shell/SQL çalıştırma yetkisi ima ediyor |
74
+ | unsafe-input | `fs_write_from_raw_tool_input` | high | Tool girdisindeki bir path, doğrulama olmadan dosya yazma/silme çağrısına geçiyor (path traversal) |
75
+ | unsafe-input | `ssrf_fetch_from_tool_input` | high | Tool girdisindeki bir URL, allowlist olmadan doğrudan `fetch`/`axios`'a geçiyor (SSRF) |
76
+ | unsafe-input | `sql_injection_via_tool_input` | critical | Tool girdisi bir SQL string'ine template-literal ile enjekte ediliyor |
77
+ | loose-schema | `overly_permissive_tool_schema` | medium | Bir tool parametresi `z.any()`/`z.unknown()` tipinde — her şeyi kabul ediyor |
78
+ | secrets-exposure | `hardcoded_secret_in_tool_schema` | critical | Credential-benzeri bir şema alanının default değeri sabit bir literal |
79
+ | secrets-exposure | `full_env_exposed_to_tool_caller` | critical | `process.env`'in tamamı spread/stringify/return ediliyor (tek bir named değişken değil) |
80
+ | network-exposure | `permissive_cors_on_server` | medium | Wildcard CORS (`Access-Control-Allow-Origin: *`) ya da opsiyonsuz `cors()` |
81
+
82
+ Bunlar **heuristic** bulgulardır — tam bir AST/tip analizi değil, statik metin kalıbı taraması yapar. Düşük yanlış-pozitif oranı için tasarlandı ama her bulgu yine de manuel gözden geçirilmelidir.
83
+
84
+ ---
85
+
86
+ ## Yapılandırma (`guardbee.yml`)
87
+
88
+ ```yaml
89
+ mcp-server-auditor:
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 # 32 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-server-auditor",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "MCP server that audits other MCP servers' tool definitions for insecure patterns — excessive-agency tool names, shell/eval/SQL/SSRF sinks fed by raw tool input, overly permissive schemas, hardcoded secrets, and wildcard CORS",
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.1"
25
26
  },
26
27
  "keywords": [
27
28
  "mcp",