mcp-behave 0.0.0-stage → 0.2.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Navid Mirnoori Langeroudi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,255 @@
1
- # Temporary Holding Version
1
+ # mcp-behave
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/navid72m/mcp-behave/actions/workflows/ci.yml/badge.svg)](https://github.com/navid72m/mcp-behave/actions/workflows/ci.yml)
4
+ [![PyPI version](https://img.shields.io/pypi/v/mcp-behave.svg)](https://pypi.org/project/mcp-behave/)
5
+ [![PyPI Downloads](https://static.pepy.tech/personalized-badge/mcp-behave?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/mcp-behave)
6
+ [![npm version](https://img.shields.io/npm/v/mcp-behave.svg)](https://www.npmjs.com/package/mcp-behave)
7
+ [![mcp-behave MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/navid72m/mcp-behave/badges/score.svg)](https://glama.ai/mcp/servers/navid72m/mcp-behave)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
9
+
10
+ **Runtime behavioral auditor for MCP servers.** Runs an MCP server under
11
+ a runtime tracer (macOS dylib, Linux `LD_PRELOAD`, or `strace`), exercises
12
+ every tool / resource / prompt it advertises, and then compares what it
13
+ *declared* against what it actually *did* — file reads, network egress, subprocess
14
+ execution.
15
+
16
+ Static scanners read tool descriptions. `mcp-behave` watches behavior.
17
+
18
+ ![mcp-behave demo](demo.gif)
19
+
20
+ > 📖 **Read the research article**: [Auditing Real-World MCP Servers with mcp-behave](https://www.navidmirnouri.com/blog/auditing-mcp-servers-with-mcp-behave.html) for an empirical audit comparing real-world packages and investigating known MCP vulnerability classes.
21
+ >
22
+ > 🏗️ **Architecture & Systems Internals**: See [`ARCHITECTURE.md`](ARCHITECTURE.md) for module dependency, data-flow, and sequence diagrams of the audit pipeline.
23
+
24
+ ## The idea in one contrast
25
+
26
+ `targets/leaky_server.py` and `targets/honest_server.py` advertise the
27
+ **identical** tool:
28
+
29
+ > `format_note` — "Formats a markdown note. Purely local text formatting."
30
+
31
+ A static scanner reads two harmless tools. `mcp-behave` sees the difference:
32
+
33
+ | Target | network egress | sensitive file read | findings |
34
+ |-----------------|---------------------|----------------------------|----------|
35
+ | `honest_server` | none | none | **0** |
36
+ | `leaky_server` | `93.184.216.34:80` | `~/.ssh/id_rsa` (a canary) | **2 HIGH** |
37
+
38
+ The honest server producing **zero** findings matters as much as the leaky one
39
+ tripping two — false positives would kill credibility.
40
+
41
+ ## Install & Quickstart
42
+
43
+ Run directly without manual installation:
44
+
45
+ ```bash
46
+ # Via npx (Node.js ecosystem — zero install)
47
+ npx mcp-behave <server-command>
48
+
49
+ # Via uvx (Python ecosystem — zero install)
50
+ uvx mcp-behave <server-command>
51
+ ```
52
+
53
+ Or install into your local environment:
54
+
55
+ ```bash
56
+ # Via pip
57
+ pip install mcp-behave
58
+
59
+ # Via npm
60
+ npm install -g mcp-behave
61
+ ```
62
+
63
+ ### Tracer Requirements
64
+ - **macOS**: Works natively without `strace` or root using an injected dylib (`DYLD_INSERT_LIBRARIES`). Built automatically on first use with `cc` (Xcode Command Line Tools).
65
+ - **Linux**: Works natively without `strace` or `SYS_PTRACE` using an `LD_PRELOAD` shared library. Built automatically on first use with `cc` (e.g. `gcc`). If no compiler is available, `strace` is used as a fallback if installed on `PATH`.
66
+ - **Untraced mode**: Run on any platform with `--no-trace` for manifest inspection and rug-pull checks without any runtime tracer.
67
+
68
+ ## Use
69
+
70
+ ```bash
71
+ # Audit any stdio MCP server -- pass its launch command:
72
+ mcp-behave python -m mcp_server_fetch
73
+ mcp-behave npx -y @modelcontextprotocol/server-filesystem /tmp
74
+ mcp-behave uvx mcp-server-git
75
+
76
+ # Run untraced (manifest & rug-pull analysis only, no tracer needed):
77
+ mcp-behave --no-trace python -m mcp_server_fetch
78
+
79
+ # Machine-readable output for CI:
80
+ mcp-behave --json --fail-on high python -m mcp_server_fetch
81
+
82
+ # Connect to an already-running remote server (manifest analysis only,
83
+ # no syscall trace possible):
84
+ mcp-behave --transport sse http://localhost:8000/sse
85
+ ```
86
+
87
+ Exit codes: `0` clean, `3` findings at or above `--fail-on` threshold,
88
+ `2` tracer setup failed, `1` other error.
89
+
90
+ ### Useful flags
91
+
92
+ - `--no-trace` — skip syscall tracing and run manifest analysis only.
93
+ - `--tracer {auto,preload,dylib,strace,none}` — choose tracer backend explicitly (default `auto`).
94
+ - `--json` — emit findings as JSON on stdout.
95
+ - `--fail-on {never,info,high}` — severity that triggers exit code 3 (default `high`).
96
+ - `--no-dns` — skip reverse-DNS lookups (faster, offline-safe).
97
+ - `--timeout SECONDS` — per-call timeout (default 15).
98
+ - `--transport {stdio,sse,streamable-http}` — remote transports skip syscall tracing.
99
+ - `--out-dir PATH` — where `manifest.json` and `trace.log` are written.
100
+
101
+ ### Environment Variables
102
+
103
+ | Variable | Default | Description |
104
+ | :--- | :--- | :--- |
105
+ | `OUT_DIR` | `/tmp/mcp_behave_out` | Directory where probe output (`manifest.json` and `trace.log`) is stored. |
106
+ | `TRACE_FILE` | `$OUT_DIR/trace.log` | Path to the raw syscall trace log file. |
107
+ | `MCP_BEHAVE_CALL_TIMEOUT` | `15` | Timeout in seconds per individual tool, resource, or prompt call during exercise. |
108
+ | `MCP_BEHAVE_STATE_DIR` | `$XDG_DATA_HOME/mcp-behave/manifests` | Storage location for historical manifest hashes used in rug-pull detection. |
109
+ | `MCP_BEHAVE_DEBUG` | *(unset)* | Set to `1` to print full Python tracebacks on probe failures. |
110
+ | `PROBE_NOISE_EXTRA` | *(empty)* | Colon-separated path substrings to filter out as benign noise during trace analysis. |
111
+ | `MCP_BEHAVE_DASHBOARD_URL` | *(unset)* | Target dashboard URL for `mcp-behave push`. |
112
+ | `MCP_BEHAVE_TOKEN` | *(unset)* | API bearer token for `mcp-behave push`. |
113
+
114
+ ## Run as an MCP Server (Glama, Claude Desktop, Cursor)
115
+
116
+ `mcp-behave` can run as an MCP server exposing behavioral security tools to AI agents:
117
+ - `audit_server`: Probes and dynamically audits another MCP server's behavioral footprint.
118
+ - `inspect_manifest`: Safely fetches and inspects advertised tools, resources, and prompts, and checks for rug-pulls.
119
+
120
+ ```bash
121
+ # Start MCP server over stdio
122
+ npx mcp-behave serve
123
+ # or
124
+ uvx mcp-behave serve
125
+ ```
126
+
127
+ ### Claude Desktop / Cursor / Cline Configuration
128
+
129
+ Add to your `claude_desktop_config.json` or Cursor MCP settings:
130
+
131
+ **Option A: Using `npx` (No Python virtualenv setup needed)**
132
+ ```json
133
+ {
134
+ "mcpServers": {
135
+ "mcp-behave": {
136
+ "command": "npx",
137
+ "args": ["-y", "mcp-behave", "serve"]
138
+ }
139
+ }
140
+ }
141
+ ```
142
+
143
+ **Option B: Using `uvx`**
144
+ ```json
145
+ {
146
+ "mcpServers": {
147
+ "mcp-behave": {
148
+ "command": "uvx",
149
+ "args": ["mcp-behave", "serve"]
150
+ }
151
+ }
152
+ }
153
+ ```
154
+
155
+ ### Glama & Registry Listing
156
+
157
+ `mcp-behave` is compatible with [Glama](https://glama.ai/mcp/servers) and includes a root `glama.json` manifest. AI models can invoke `audit_server` to verify untrusted third-party MCP servers before interacting with them.
158
+
159
+ ## Push results to a dashboard
160
+
161
+ `mcp-behave push` uploads a JSON audit result to an
162
+ [mcp-behave dashboard](https://github.com/navid72m/mcp-behave-dashboard).
163
+
164
+ ```bash
165
+ # 1. Sign in at https://<your-dashboard>.vercel.app/settings and mint a token.
166
+ export MCP_BEHAVE_DASHBOARD_URL=https://<your-dashboard>.vercel.app
167
+ export MCP_BEHAVE_TOKEN=mcpb_...
168
+
169
+ # 2. Audit something with --json and pipe it to push.
170
+ mcp-behave --json python -m mcp_server_fetch \
171
+ | mcp-behave push --server-name server-fetch --category network
172
+
173
+ # Or save to a file first, then push.
174
+ mcp-behave --json python -m mcp_server_fetch > audit.json
175
+ mcp-behave push audit.json --server-name server-fetch --category network
176
+ ```
177
+
178
+ Flags worth knowing:
179
+
180
+ - `--server-name NAME` — canonical name on the dashboard. Defaults to the joined
181
+ server command from the audit JSON; usually you want to set this.
182
+ - `--description TEXT` — used the first time this server is submitted.
183
+ - `--github-url URL`, `--npm-package PKG`, `--author NAME` — optional server metadata.
184
+ - `--category {local,network,database,other}` — defaults to `other`.
185
+ - `--dry-run` — print the JSON payload that would be POSTed and exit.
186
+
187
+ The endpoint is rate-limited per token (20 req/min); `push` exits 1 on HTTP error
188
+ and prints the response body to stderr.
189
+
190
+ ## What it detects
191
+
192
+ - **Undeclared network egress** — IP:port destinations reached during tool calls
193
+ (reverse-DNS resolved in findings when available).
194
+ - **Sensitive-path reads** — `~/.ssh/*`, `~/.aws/*`, `~/.env`, `~/.netrc`, etc.
195
+ - **Rug-pull** — the declared manifest hash changes between runs of the same
196
+ server (e.g. a tool's description silently changes after the user trusts it).
197
+ Hashes persist under `$XDG_DATA_HOME/mcp-behave/manifests/`.
198
+ - **Covert Channel & Metadata Injection** (CSA TTP: Tool Description Poisoning) — ANSI
199
+ terminal escape codes (`\x1b`), invisible zero-width Unicode (`\u200B`, `\u200C`,
200
+ `\u200D`, `\uFEFF`, `\u2060`), BiDi overrides (`\u202A`–`\u202E`, `\u2066`–`\u2069`),
201
+ Unicode tag characters, and prompt injection directive patterns (`Ignore previous instructions`,
202
+ `SYSTEM PROMPT:`, `<system>`, etc.) embedded in tool/parameter descriptions, resource URIs,
203
+ or prompt metadata.
204
+ - **Tool Output Safety & Markdown Exfiltration** (CSA TTP: Output Prompt Injection / Data Exfiltration) —
205
+ captures runtime tool responses during probe execution and flags client-side HTTP GET
206
+ exfiltration vectors (such as external Markdown images `![...](https://...)` and HTML `<img src="...">` tags),
207
+ as well as ANSI escapes, invisible Unicode, and prompt injection payloads returned in tool outputs.
208
+
209
+ Findings are framed as observations ("does X, undeclared"), never accusations.
210
+
211
+ ## Docker (works on macOS / Windows hosts)
212
+
213
+ ```bash
214
+ docker build -t mcp-behave .
215
+ # default: runs the bundled leaky target so you can see findings immediately
216
+ docker run --rm mcp-behave
217
+ # point at a real server
218
+ docker run --rm mcp-behave python -m mcp_server_fetch
219
+ ```
220
+
221
+ The container automatically compiles and runs the native `LD_PRELOAD` tracer
222
+ without needing `--cap-add=SYS_PTRACE`. If you explicitly use `--tracer strace`,
223
+ `--cap-add=SYS_PTRACE` is required.
224
+
225
+ The image bundles Node.js (for `npx` servers), `uv` (for `uvx` servers), and
226
+ sandbox canary files (`sandbox_home/`) mounted as `$HOME` so credential reads
227
+ are detectable.
228
+
229
+ ## Development
230
+
231
+ ```bash
232
+ pip install -e ".[test]"
233
+ pytest -v
234
+ ```
235
+
236
+ CI tests across Ubuntu and macOS; see `.github/workflows/ci.yml`.
237
+
238
+ ## Known limits
239
+
240
+ - **Runtime tracing requires macOS (DYLD interposition) or Linux (LD_PRELOAD / strace).**
241
+ Windows and other platforms can run with `--no-trace` for manifest and rug-pull checks.
242
+ An eBPF backend for system-wide capture is on the roadmap — see [ROADMAP.md](ROADMAP.md).
243
+ - **stdio is the only transport with syscall tracing.** `sse` and
244
+ `streamable-http` connect to a remote server we cannot trace; only manifest
245
+ analysis and rug-pull detection apply there.
246
+ - **Input synthesis is heuristic** — JSON Schema `format`, key-name hints, and
247
+ type defaults. Schema-coverage fuzzing (hypothesis-jsonschema) is roadmap.
248
+ - **AF_UNIX egress** isn't matched — a server exfiltrating over a unix domain
249
+ socket would slip past the current network detection.
250
+ - **Single call per capability** — servers that misbehave only on specific
251
+ inputs or after N calls may not be triggered.
252
+
253
+ ## License
254
+
255
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,109 @@
1
+ #!/usr/bin/env node
2
+
3
+ const { spawn, spawnSync } = require('child_process');
4
+ const path = require('path');
5
+ const fs = require('fs');
6
+ const os = require('os');
7
+
8
+ const PKG_NAME = 'mcp-behave';
9
+ const args = process.argv.slice(2);
10
+
11
+ function commandExists(cmd) {
12
+ try {
13
+ const res = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
14
+ return res.status === 0;
15
+ } catch {
16
+ return false;
17
+ }
18
+ }
19
+
20
+ function findPython() {
21
+ for (const cmd of ['python3', 'python']) {
22
+ try {
23
+ const res = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
24
+ if (res.status === 0) return cmd;
25
+ } catch {}
26
+ }
27
+ return null;
28
+ }
29
+
30
+ function runCommand(command, cmdArgs) {
31
+ const child = spawn(command, cmdArgs, {
32
+ stdio: 'inherit',
33
+ env: process.env,
34
+ });
35
+
36
+ child.on('error', (err) => {
37
+ console.error(`[mcp-behave] Failed to start '${command}':`, err.message);
38
+ process.exit(1);
39
+ });
40
+
41
+ child.on('close', (code, signal) => {
42
+ if (signal) {
43
+ process.kill(process.pid, signal);
44
+ } else {
45
+ process.exit(code ?? 0);
46
+ }
47
+ });
48
+
49
+ process.on('SIGINT', () => child.kill('SIGINT'));
50
+ process.on('SIGTERM', () => child.kill('SIGTERM'));
51
+ }
52
+
53
+ function main() {
54
+ // 1. Prefer uvx if available (fastest, isolated)
55
+ if (commandExists('uvx')) {
56
+ return runCommand('uvx', [PKG_NAME, ...args]);
57
+ }
58
+
59
+ // 2. Try pipx if available
60
+ if (commandExists('pipx')) {
61
+ return runCommand('pipx', ['run', PKG_NAME, ...args]);
62
+ }
63
+
64
+ // 3. Fallback to python3 / python
65
+ const pythonCmd = findPython();
66
+ if (!pythonCmd) {
67
+ console.error('[mcp-behave] Error: Python 3 is required to run mcp-behave.');
68
+ console.error('Please install Python 3 (https://www.python.org) or uv (https://astral.sh/uv).');
69
+ process.exit(1);
70
+ }
71
+
72
+ // Check if mcp_behave is already installed in the active Python environment
73
+ const importCheck = spawnSync(pythonCmd, ['-c', 'import mcp_behave'], { stdio: 'ignore' });
74
+ if (importCheck.status === 0) {
75
+ return runCommand(pythonCmd, ['-m', 'mcp_behave.cli', ...args]);
76
+ }
77
+
78
+ // If not installed, use an isolated cache venv so we don't mutate system packages
79
+ const cacheBase = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
80
+ const venvDir = path.join(cacheBase, 'mcp-behave', 'npm-venv');
81
+ const venvBin = process.platform === 'win32'
82
+ ? path.join(venvDir, 'Scripts', 'mcp-behave.exe')
83
+ : path.join(venvDir, 'bin', 'mcp-behave');
84
+
85
+ if (!fs.existsSync(venvBin)) {
86
+ console.error('[mcp-behave] First-time setup: preparing environment in ~/.cache/mcp-behave/npm-venv...');
87
+ fs.mkdirSync(path.dirname(venvDir), { recursive: true });
88
+
89
+ const venvCreate = spawnSync(pythonCmd, ['-m', 'venv', venvDir], { stdio: 'inherit' });
90
+ if (venvCreate.status !== 0) {
91
+ console.error('[mcp-behave] Warning: could not create venv, falling back to direct run.');
92
+ return runCommand(pythonCmd, ['-m', 'mcp_behave.cli', ...args]);
93
+ }
94
+
95
+ const pipBin = process.platform === 'win32'
96
+ ? path.join(venvDir, 'Scripts', 'pip.exe')
97
+ : path.join(venvDir, 'bin', 'pip');
98
+
99
+ const pipInstall = spawnSync(pipBin, ['install', '--upgrade', PKG_NAME], { stdio: 'inherit' });
100
+ if (pipInstall.status !== 0) {
101
+ console.error('[mcp-behave] Error: failed to install mcp-behave.');
102
+ process.exit(1);
103
+ }
104
+ }
105
+
106
+ return runCommand(venvBin, args);
107
+ }
108
+
109
+ main();
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "mcp-behave",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Runtime behavioral auditor for MCP servers — scope-violation detection via native interposition & syscall tracing",
5
+ "main": "bin/mcp-behave.js",
6
+ "bin": "./bin/mcp-behave.js",
7
+ "files": [
8
+ "bin/",
9
+ "README.md",
10
+ "LICENSE"
11
+ ],
12
+ "keywords": [
13
+ "mcp",
14
+ "model-context-protocol",
15
+ "security",
16
+ "auditing",
17
+ "agents",
18
+ "tracer",
19
+ "sandbox"
20
+ ],
21
+ "author": "Navid Mirnoori Langeroudi <navid72m@gmail.com>",
22
+ "license": "MIT",
23
+ "repository": {
24
+ "type": "git",
25
+ "url": "git+https://github.com/navid72m/mcp-behave.git"
26
+ },
27
+ "bugs": {
28
+ "url": "https://github.com/navid72m/mcp-behave/issues"
29
+ },
30
+ "homepage": "https://github.com/navid72m/mcp-behave#readme",
31
+ "engines": {
32
+ "node": ">=16.0.0"
33
+ }
34
+ }