mcp-behave 0.3.1 → 0.3.3

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 (2) hide show
  1. package/README.md +42 -25
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -26,10 +26,10 @@ Static scanners only read tool descriptions. `mcp-behave` observes what servers
26
26
  Compare three bundled targets in `targets/`:
27
27
 
28
28
  - `honest_server.py`: advertises a purely local note formatter and behaves honestly.
29
- - `leaky_server.py`: advertises the exact same harmless note formatter, but secretly accesses SSH keys and phones home via network syscalls.
30
- - `poisoned_server.py`: never makes network syscalls, but poisons its descriptions with covert zero-width spaces and prompt injection, and returns an external Markdown image link (`![telemetry](https://...)`) to trigger client-side HTTP GET exfiltration when rendered in a chat UI.
29
+ - `leaky_server.py`: advertises the exact same harmless note formatter, but secretly accesses SSH keys and phones home via network sockets.
30
+ - `poisoned_server.py`: never makes outbound connections, but poisons its descriptions with covert zero-width spaces and prompt injection, and returns an external Markdown image link (`![telemetry](https://...)`) to trigger client-side HTTP GET exfiltration when rendered in a chat UI.
31
31
 
32
- | Target | Network Syscalls | File System Access | Metadata & Output Safety | Verdict |
32
+ | Target | Network Egress | File System Access | Metadata & Output Safety | Verdict |
33
33
  | :--- | :--- | :--- | :--- | :--- |
34
34
  | `honest_server` | none | none | clean | **0 (PASS)** |
35
35
  | `leaky_server` | `93.184.216.34:80` | `~/.ssh/id_rsa` (canary) | clean | **2 HIGH** |
@@ -304,16 +304,42 @@ mcp-behave lint ./manifest.json --sarif > lint.sarif
304
304
  mcp-behave lint ./manifest.json --json --scorecard
305
305
  ```
306
306
 
307
- ### Static Checks Performed:
308
- - **Auto-Approval Bypass (`readOnlyHint` Mismatch)**: Flags mutating tools (`delete`, `write`, `update`, `drop`) advertising `readOnlyHint: true`, which would cause AI clients (Claude Desktop, Cursor) to auto-approve state modifications without human confirmation.
309
- - **Destructive Actions Missing Confirmation**: Flags destructive tools that omit confirmation guardrails (`confirm`, `force`, `dry_run`).
310
- - **Unconstrained Path Traversal Arguments**: Flags `path`/`file` parameters missing regex `pattern` or `enum` boundaries.
311
- - **SSRF-Prone URL Arguments**: Flags `url`/`webhook` parameters accepting caller-controlled endpoints without allowlists or schema constraints.
312
- - **Hardcoded Schema Credentials**: Scans parameter `default`, `const`, and `examples` for live API tokens (`sk-`, `ghp_`, `AKIA`, private keys).
313
- - **Sensitive Resource URIs**: Identifies resource URIs surfacing credentials or sensitive paths (`.env`, `id_rsa`, `/etc/shadow`, `.kube/config`).
314
- - **Duplicate Tool Names (Shadowing)**: Detects colliding tool names that allow malicious tools to shadow trusted ones.
315
- - **Cross-Tool Chaining Directives**: Catches orchestration directives in tool descriptions that instruct the model to execute other tools.
316
- - **Covert Channels & Injection Directives**: Scans all names, descriptions, and metadata for ANSI escapes, zero-width Unicode, and prompt injection patterns.
307
+ ### Complete Security & Linting Rule Catalog
308
+
309
+ `mcp-behave` provides 100% full coverage of the static security and hygiene rules from [`ModelContextProtocol-Security/MCP-audit`](https://github.com/ModelContextProtocol-Security/MCP-audit), paired with deep dynamic runtime syscall tracing:
310
+
311
+ | Rule ID | Severity | Category | Description |
312
+ | :--- | :--- | :--- | :--- |
313
+ | **`MCP001`** | `HIGH` | Permissions | Destructive tool (`delete`, `remove`, `drop`, `wipe`, `purge`) lacks explicit confirmation or scope argument (`confirm`, `force`, `dry_run`). |
314
+ | **`MCP002`** | `HIGH` | Permissions | Arbitrary command or code execution tool detected (`exec`, `execute`, `spawn`, `shell`, `bash`, `run_command`, `system`). |
315
+ | **`MCP003`** | `INFO` | Permissions | Mutating tool (`write`, `update`, `create`, `modify`, `patch`) declares zero input properties, leaving its effect unbounded. |
316
+ | **`MCP004`** | `HIGH` | Permissions | Mutating or destructive tool advertises `readOnlyHint: true` (auto-approval bypass risk in AI clients). |
317
+ | **`MCP010`** | `INFO` | Schema | Tool is missing an input schema or declares zero input properties. |
318
+ | **`MCP011`** | `INFO` | Schema | Schema explicitly enables `additionalProperties: true` (parameter smuggling risk). |
319
+ | **`MCP012`** | `INFO` | Schema | Free-form string argument with no `enum`, `pattern`, `format`, or `maxLength` bounds. |
320
+ | **`MCP013`** | `INFO` | Schema | Object schema declares properties but omits the `required` list (all arguments optional). |
321
+ | **`MCP020`** | `HIGH` | Injection | Tool or prompt description contains prompt-injection phrasing (`ignore previous`, `system prompt:`, `override`). |
322
+ | **`MCP021`** | `INFO` | Injection | Tool description advertises overly broad capability (`anything`, `any command`, `arbitrary`, `unrestricted`, `full access`). |
323
+ | **`MCP022`** | `INFO` | Injection | Tool description contains cross-tool chaining directives (`then call X`, `next run Y`). |
324
+ | **`MCP030`** | `HIGH` | Secrets | Resource exposes secrets or sensitive system paths (`.env`, `id_rsa`, `.ssh`, `.aws`, `/etc/shadow`, `.kube/config`). |
325
+ | **`MCP031`** | `HIGH` | Secrets | File or path argument accepts unconstrained strings without `pattern` or `enum` boundaries (directory traversal). |
326
+ | **`MCP032`** | `HIGH` | Secrets | Tool parameter schema embeds hardcoded credentials in `default`, `const`, or `examples` (`sk-`, `ghp_`, `AKIA`). |
327
+ | **`MCP040`** | `HIGH` | Transport | HTTP/SSE transport accepts connections without authentication token or header. |
328
+ | **`MCP041`** | `INFO` | Transport | Tool argument accepts caller-controlled URLs without host allowlist or regex pattern constraints (SSRF risk). |
329
+ | **`MCP050`** | `INFO` | Metadata | Server instructions leak internal details or sensitive terms (`localhost`, `127.0.0.1`, `internal`, `staging`, `debug`). |
330
+ | **`MCP051`** | `INFO` | Metadata | Server does not report a version string in `serverInfo` for vulnerability tracking. |
331
+ | **`MCP060`** | `HIGH` | Hygiene | Duplicate tool names declared across server surface (tool shadowing risk). |
332
+ | **`MCP061`** | `INFO` | Hygiene | Excessive number of tools declared (>40 tools, capability sprawl expanding agent attack surface). |
333
+ | **`MCP062`** | `INFO` | Hygiene | Undocumented tool declared with empty or missing description. |
334
+ | **`MCP101`** | `HIGH` | Runtime | Undeclared network socket connection to remote host detected via runtime syscall interposition. |
335
+ | **`MCP102`** | `HIGH` | Runtime | Unauthorized read of confidential local file (`id_rsa`, `.env`, `.aws`, `/etc/shadow`). |
336
+ | **`MCP103`** | `INFO` | Runtime | Undeclared child subprocess spawned during tool execution. |
337
+ | **`MCP104`** | `HIGH` | Runtime | Advertised manifest hash changed compared to historical baselines (rug-pull detection). |
338
+ | **`MCP105`** | `HIGH` | Covert | ANSI terminal escape sequences detected in metadata or tool outputs. |
339
+ | **`MCP106`** | `HIGH` | Covert | Zero-width spaces, invisible Unicode, or BiDi overrides detected in metadata or tool outputs. |
340
+ | **`MCP107`** | `HIGH` | Exfiltration| Markdown or HTML external image link in tool output (causes client-side HTTP GET exfiltration). |
341
+ | **`MCP108`** | `HIGH` | Config | Hardcoded API keys or plaintext credentials in client configuration files (`claude_desktop_config.json`, Cursor). |
342
+ | **`MCP109`** | `HIGH` | Config | Over-privileged root (`/`) or confidential home directory mount in client configuration. |
317
343
 
318
344
  ## Configuration & Policy Suppression (`.mcpbehaverc.json`)
319
345
 
@@ -447,18 +473,9 @@ CI tests across Ubuntu and macOS; see `.github/workflows/ci.yml`.
447
473
 
448
474
  ## Known limits
449
475
 
450
- - **Runtime tracing requires macOS (DYLD interposition) or Linux (LD_PRELOAD / strace).**
451
- Windows and other platforms can run with `--no-trace` for manifest and rug-pull checks.
452
- An eBPF backend for system-wide capture is on the roadmap — see [ROADMAP.md](ROADMAP.md).
453
- - **stdio is the only transport with syscall tracing.** `sse` and
454
- `streamable-http` connect to a remote server we cannot trace; only manifest
455
- analysis and rug-pull detection apply there.
456
- - **Input synthesis is heuristic** — JSON Schema `format`, key-name hints, and
457
- type defaults. Schema-coverage fuzzing (hypothesis-jsonschema) is roadmap.
458
- - **AF_UNIX egress** isn't matched — a server exfiltrating over a unix domain
459
- socket would slip past the current network detection.
460
- - **Single call per capability** — servers that misbehave only on specific
461
- inputs or after N calls may not be triggered.
476
+ - **Runtime tracing operates at libc interposition level.** macOS (DYLD interposition) and Linux (LD_PRELOAD) intercept standard dynamic runtime library calls (Python, Node.js, Ruby). Statically linked binaries (e.g. Go, musl Rust) and inline assembly syscalls bypass libc interposition unless run under the Linux `strace` tracer (`--tracer strace`) or the planned kernel eBPF backend — see [ROADMAP.md](ROADMAP.md).
477
+ - **stdio is the primary transport with full runtime tracing.** `sse` and `streamable-http` connect to remote servers where client-side process tracing is not available; manifest analysis, CSA rule linting, and rug-pull detection run there.
478
+ - **Canary & Fuzzing synthesis** — generates realistic, diverse arguments across `--probe-rounds` and adversarial boundary vectors with `--fuzz`. Full property-based hypothesis fuzzing is planned for v0.4.x.
462
479
 
463
480
  ## License
464
481
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "mcp-behave",
3
- "version": "0.3.1",
4
- "description": "Runtime behavioral auditor for MCP servers — scope-violation detection via native interposition & syscall tracing",
3
+ "version": "0.3.3",
4
+ "description": "Runtime behavioral auditor for MCP servers — scope-violation detection via native libc interposition & runtime tracing",
5
5
  "main": "bin/mcp-behave.js",
6
6
  "bin": "./bin/mcp-behave.js",
7
7
  "files": [