mcp-behave 0.0.0-stage → 0.1.9
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 +21 -0
- package/README.md +218 -2
- package/bin/mcp-behave.js +109 -0
- package/package.json +32 -4
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,219 @@
|
|
|
1
|
-
#
|
|
1
|
+
# mcp-behave
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://glama.ai/mcp/servers/navid72m/mcp-behave)
|
|
4
|
+
[](https://pepy.tech/projects/mcp-behave)
|
|
5
|
+
|
|
6
|
+
**Runtime behavioral auditor for MCP servers.** Runs an MCP server under
|
|
7
|
+
a runtime tracer (macOS dylib, Linux `LD_PRELOAD`, or `strace`), exercises
|
|
8
|
+
every tool / resource / prompt it advertises, and then compares what it
|
|
9
|
+
*declared* against what it actually *did* — file reads, network egress, subprocess
|
|
10
|
+
execution.
|
|
11
|
+
|
|
12
|
+
Static scanners read tool descriptions. `mcp-behave` watches behavior.
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
> See [`ARCHITECTURE.md`](ARCHITECTURE.md) for module dependency, data-flow, and
|
|
17
|
+
> sequence diagrams of the audit pipeline.
|
|
18
|
+
|
|
19
|
+
## The idea in one contrast
|
|
20
|
+
|
|
21
|
+
`targets/leaky_server.py` and `targets/honest_server.py` advertise the
|
|
22
|
+
**identical** tool:
|
|
23
|
+
|
|
24
|
+
> `format_note` — "Formats a markdown note. Purely local text formatting."
|
|
25
|
+
|
|
26
|
+
A static scanner reads two harmless tools. `mcp-behave` sees the difference:
|
|
27
|
+
|
|
28
|
+
| Target | network egress | sensitive file read | findings |
|
|
29
|
+
|-----------------|---------------------|----------------------------|----------|
|
|
30
|
+
| `honest_server` | none | none | **0** |
|
|
31
|
+
| `leaky_server` | `93.184.216.34:80` | `~/.ssh/id_rsa` (a canary) | **2 HIGH** |
|
|
32
|
+
|
|
33
|
+
The honest server producing **zero** findings matters as much as the leaky one
|
|
34
|
+
tripping two — false positives would kill credibility.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
# Via Python (pip / uv)
|
|
40
|
+
pip install mcp-behave
|
|
41
|
+
# or run directly with uv:
|
|
42
|
+
uvx mcp-behave
|
|
43
|
+
|
|
44
|
+
# Via npm (npx)
|
|
45
|
+
npx mcp-behave
|
|
46
|
+
# or install globally:
|
|
47
|
+
npm install -g mcp-behave
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Tracer Requirements
|
|
51
|
+
- **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).
|
|
52
|
+
- **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`.
|
|
53
|
+
- **Untraced mode**: Run on any platform with `--no-trace` for manifest inspection and rug-pull checks without any runtime tracer.
|
|
54
|
+
|
|
55
|
+
## Use
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Audit any stdio MCP server -- pass its launch command:
|
|
59
|
+
mcp-behave python -m mcp_server_fetch
|
|
60
|
+
mcp-behave npx -y @modelcontextprotocol/server-filesystem /tmp
|
|
61
|
+
mcp-behave uvx mcp-server-git
|
|
62
|
+
|
|
63
|
+
# Run untraced (manifest & rug-pull analysis only, no tracer needed):
|
|
64
|
+
mcp-behave --no-trace python -m mcp_server_fetch
|
|
65
|
+
|
|
66
|
+
# Machine-readable output for CI:
|
|
67
|
+
mcp-behave --json --fail-on high python -m mcp_server_fetch
|
|
68
|
+
|
|
69
|
+
# Connect to an already-running remote server (manifest analysis only,
|
|
70
|
+
# no syscall trace possible):
|
|
71
|
+
mcp-behave --transport sse http://localhost:8000/sse
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Exit codes: `0` clean, `3` findings at or above `--fail-on` threshold,
|
|
75
|
+
`2` tracer setup failed, `1` other error.
|
|
76
|
+
|
|
77
|
+
### Useful flags
|
|
78
|
+
|
|
79
|
+
- `--no-trace` — skip syscall tracing and run manifest analysis only.
|
|
80
|
+
- `--tracer {auto,preload,dylib,strace,none}` — choose tracer backend explicitly (default `auto`).
|
|
81
|
+
- `--json` — emit findings as JSON on stdout.
|
|
82
|
+
- `--fail-on {never,info,high}` — severity that triggers exit code 3 (default `high`).
|
|
83
|
+
- `--no-dns` — skip reverse-DNS lookups (faster, offline-safe).
|
|
84
|
+
- `--timeout SECONDS` — per-call timeout (default 15).
|
|
85
|
+
- `--transport {stdio,sse,streamable-http}` — remote transports skip syscall tracing.
|
|
86
|
+
- `--out-dir PATH` — where `manifest.json` and `trace.log` are written.
|
|
87
|
+
|
|
88
|
+
### Environment Variables
|
|
89
|
+
|
|
90
|
+
| Variable | Default | Description |
|
|
91
|
+
| :--- | :--- | :--- |
|
|
92
|
+
| `OUT_DIR` | `/tmp/mcp_behave_out` | Directory where probe output (`manifest.json` and `trace.log`) is stored. |
|
|
93
|
+
| `TRACE_FILE` | `$OUT_DIR/trace.log` | Path to the raw syscall trace log file. |
|
|
94
|
+
| `MCP_BEHAVE_CALL_TIMEOUT` | `15` | Timeout in seconds per individual tool, resource, or prompt call during exercise. |
|
|
95
|
+
| `MCP_BEHAVE_STATE_DIR` | `$XDG_DATA_HOME/mcp-behave/manifests` | Storage location for historical manifest hashes used in rug-pull detection. |
|
|
96
|
+
| `MCP_BEHAVE_DEBUG` | *(unset)* | Set to `1` to print full Python tracebacks on probe failures. |
|
|
97
|
+
| `PROBE_NOISE_EXTRA` | *(empty)* | Colon-separated path substrings to filter out as benign noise during trace analysis. |
|
|
98
|
+
| `MCP_BEHAVE_DASHBOARD_URL` | *(unset)* | Target dashboard URL for `mcp-behave push`. |
|
|
99
|
+
| `MCP_BEHAVE_TOKEN` | *(unset)* | API bearer token for `mcp-behave push`. |
|
|
100
|
+
|
|
101
|
+
## Run as an MCP Server (Glama, Claude Desktop, Cursor)
|
|
102
|
+
|
|
103
|
+
`mcp-behave` can run as an MCP server exposing behavioral security tools to AI agents:
|
|
104
|
+
- `audit_server`: Probes and dynamically audits another MCP server's behavioral footprint.
|
|
105
|
+
- `inspect_manifest`: Safely fetches and inspects advertised tools, resources, and prompts, and checks for rug-pulls.
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
# Start MCP server over stdio
|
|
109
|
+
mcp-behave serve
|
|
110
|
+
# or
|
|
111
|
+
uvx mcp-behave serve
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
### Claude Desktop / Cursor Configuration
|
|
115
|
+
|
|
116
|
+
Add to your `claude_desktop_config.json` or Cursor MCP settings:
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"mcpServers": {
|
|
121
|
+
"mcp-behave": {
|
|
122
|
+
"command": "uvx",
|
|
123
|
+
"args": ["mcp-behave", "serve"]
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Glama & Registry Listing
|
|
130
|
+
|
|
131
|
+
`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.
|
|
132
|
+
|
|
133
|
+
## Push results to a dashboard
|
|
134
|
+
|
|
135
|
+
`mcp-behave push` uploads a JSON audit result to an
|
|
136
|
+
[mcp-behave dashboard](https://github.com/navid72m/mcp-behave-dashboard).
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
# 1. Sign in at https://<your-dashboard>.vercel.app/settings and mint a token.
|
|
140
|
+
export MCP_BEHAVE_DASHBOARD_URL=https://<your-dashboard>.vercel.app
|
|
141
|
+
export MCP_BEHAVE_TOKEN=mcpb_...
|
|
142
|
+
|
|
143
|
+
# 2. Audit something with --json and pipe it to push.
|
|
144
|
+
mcp-behave --json python -m mcp_server_fetch \
|
|
145
|
+
| mcp-behave push --server-name server-fetch --category network
|
|
146
|
+
|
|
147
|
+
# Or save to a file first, then push.
|
|
148
|
+
mcp-behave --json python -m mcp_server_fetch > audit.json
|
|
149
|
+
mcp-behave push audit.json --server-name server-fetch --category network
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Flags worth knowing:
|
|
153
|
+
|
|
154
|
+
- `--server-name NAME` — canonical name on the dashboard. Defaults to the joined
|
|
155
|
+
server command from the audit JSON; usually you want to set this.
|
|
156
|
+
- `--description TEXT` — used the first time this server is submitted.
|
|
157
|
+
- `--github-url URL`, `--npm-package PKG`, `--author NAME` — optional server metadata.
|
|
158
|
+
- `--category {local,network,database,other}` — defaults to `other`.
|
|
159
|
+
- `--dry-run` — print the JSON payload that would be POSTed and exit.
|
|
160
|
+
|
|
161
|
+
The endpoint is rate-limited per token (20 req/min); `push` exits 1 on HTTP error
|
|
162
|
+
and prints the response body to stderr.
|
|
163
|
+
|
|
164
|
+
## What it detects
|
|
165
|
+
|
|
166
|
+
- **Undeclared network egress** — IP:port destinations reached during tool calls
|
|
167
|
+
(reverse-DNS resolved in findings when available).
|
|
168
|
+
- **Sensitive-path reads** — `~/.ssh/*`, `~/.aws/*`, `~/.env`, `~/.netrc`, etc.
|
|
169
|
+
- **Rug-pull** — the declared manifest hash changes between runs of the same
|
|
170
|
+
server (e.g. a tool's description silently changes after the user trusts it).
|
|
171
|
+
Hashes persist under `$XDG_DATA_HOME/mcp-behave/manifests/`.
|
|
172
|
+
|
|
173
|
+
Findings are framed as observations ("does X, undeclared"), never accusations.
|
|
174
|
+
|
|
175
|
+
## Docker (works on macOS / Windows hosts)
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
docker build -t mcp-behave .
|
|
179
|
+
# default: runs the bundled leaky target so you can see findings immediately
|
|
180
|
+
docker run --rm mcp-behave
|
|
181
|
+
# point at a real server
|
|
182
|
+
docker run --rm mcp-behave python -m mcp_server_fetch
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The container automatically compiles and runs the native `LD_PRELOAD` tracer
|
|
186
|
+
without needing `--cap-add=SYS_PTRACE`. If you explicitly use `--tracer strace`,
|
|
187
|
+
`--cap-add=SYS_PTRACE` is required.
|
|
188
|
+
|
|
189
|
+
The image bundles Node.js (for `npx` servers), `uv` (for `uvx` servers), and
|
|
190
|
+
sandbox canary files (`sandbox_home/`) mounted as `$HOME` so credential reads
|
|
191
|
+
are detectable.
|
|
192
|
+
|
|
193
|
+
## Development
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
pip install -e ".[test]"
|
|
197
|
+
pytest -v
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
CI tests across Ubuntu and macOS; see `.github/workflows/ci.yml`.
|
|
201
|
+
|
|
202
|
+
## Known limits
|
|
203
|
+
|
|
204
|
+
- **Runtime tracing requires macOS (DYLD interposition) or Linux (LD_PRELOAD / strace).**
|
|
205
|
+
Windows and other platforms can run with `--no-trace` for manifest and rug-pull checks.
|
|
206
|
+
An eBPF backend for system-wide capture is on the roadmap — see [ROADMAP.md](ROADMAP.md).
|
|
207
|
+
- **stdio is the only transport with syscall tracing.** `sse` and
|
|
208
|
+
`streamable-http` connect to a remote server we cannot trace; only manifest
|
|
209
|
+
analysis and rug-pull detection apply there.
|
|
210
|
+
- **Input synthesis is heuristic** — JSON Schema `format`, key-name hints, and
|
|
211
|
+
type defaults. Schema-coverage fuzzing (hypothesis-jsonschema) is roadmap.
|
|
212
|
+
- **AF_UNIX egress** isn't matched — a server exfiltrating over a unix domain
|
|
213
|
+
socket would slip past the current network detection.
|
|
214
|
+
- **Single call per capability** — servers that misbehave only on specific
|
|
215
|
+
inputs or after N calls may not be triggered.
|
|
216
|
+
|
|
217
|
+
## License
|
|
218
|
+
|
|
219
|
+
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.9",
|
|
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
|
+
}
|