mcp-behave logo
mcp-behave v0.4.4
Hardened against symlink & path-padding evasion • Explore v0.3.5
mcp-behave logo

Runtime Behavioral Auditor for MCP Servers

Stop guessing what your Model Context Protocol tools execute. Interpose at the libc boundary to detect undeclared network egress, credential access, rogue child processes, and rug-pull attacks before users do.

$ uvx mcp-behave -- python server.py
PyPI: 0.4.4 npm: 0.4.4 Action Users: 0 100% MCP-Audit Catalog (MCP001-MCP062) macOS DYLD + Linux LD_PRELOAD

Watch Real-Time Evasion Detection

`mcp-behave` exercises every tool, resource, and prompt under dynamic interposition. Zero findings on honest servers; immediate flags on rogue behavior.

mcp-behave audit --fail-on HIGH
Exit Code: 1
mcp-behave v0.3.5 — runtime behavioral auditor
Tracer: native (DYLD_INSERT_LIBRARIES / macOS) | Target: python targets/poisoned_server.py | Rounds: 3
Tools Discovered: fetch_notes, format_data, sync_backup
Exercising tools with multi-round varied parameter synthesis...
✓ All 3 tools responded successfully under tracer
Runtime Behavioral Findings:
HIGH
Sensitive Credential Access: Process read confidential file ~/.ssh/id_rsa (dereferenced from symlink /tmp/.cache/notes_link).
HIGH
Undeclared Network Egress: Tool 'format_data' claims offline/local operation, but initiated outbound connection to 198.51.100.24:443.
MEDIUM
Container Runtime Socket: Server connected to container control domain socket /var/run/docker.sock.
Scorecard: Grade D (42/100) • SARIF report saved: results.sarif
[FAIL] 2 HIGH findings exceeded threshold (--fail-on HIGH)

Engine Architecture

Built to Defeat Evasive Server Code

Attackers don't follow schema definitions. `mcp-behave` operates at the libc layer to capture the reality of what executes.

Zero-Root Libc Interposition

No `ptrace` or root privileges required. Injects custom interposition libraries via macOS `DYLD_INSERT_LIBRARIES` and Linux `LD_PRELOAD` with automatic `strace` fallback.

Symlink & Obfuscation Defense

Canonicalizes all paths via `realpath()` and inspects live file descriptors (`fcntl F_GETPATH` on macOS, `/proc/self/fd` on Linux) to prevent symlink traversal cloaking.

Long-Path Truncation Detection

4096-byte trace buffers with explicit ! TRUNCATED markers flag and escalate buffer-overflow and path-padding evasions straight to HIGH severity.

Full Socket & Datagram Interception

Interposes `connect`, `sendto`, `sendmsg`, and `sendmmsg` across IPv4, IPv6, UDP, abstract UNIX sockets (`@containerd-control`), and Docker control sockets.

Expanded Secret Targets

Detects unauthorized access to `.gnupg`, `.npmrc`, `.pypirc`, `.git-credentials`, AWS, Azure, Google Cloud tokens, and Chrome/Firefox/Safari browser credential databases.

Behavioral CI Lockfiles

Pin server behavior in `mcp-behave.lock`. Run `mcp-behave check` in CI to fail builds only on undeclared behavioral regressions, with zero false alerts on approved baselines.

The Inspection Loop

How `mcp-behave` Uncovers Lies

01

1. Interposed Spawn

The target MCP server is launched with a dynamically interposed C library attached to its address space. Every socket, open call, and process execution is intercepted with microseconds overhead.

02

2. Multi-Round Probing

`mcp-behave` queries tool schemas and sends varied, realistic synthetic arguments over multiple rounds (--probe-rounds N), preventing static canary avoidance.

03

3. Contract Audit & Diff

Observed kernel actions are audited against tool descriptions, `.mcpbehaverc.json` policies, and the full 62-rule MCP-audit catalog, exporting to SARIF v2.1.0 or failing your CI pipeline.

Ecosystem Positioning

How `mcp-behave` Compares

Different tools tackle different sides of the MCP security boundary.

Capability / Angle mcp-behave Static Linters LLM Fuzzers (mcp-auditor)
Observation Level OS Syscall / Libc layer Tool description / schema text JSON-RPC protocol text replies
Silent File / Credential Theft ✓ Caught at open() / realpath() ✗ Blind ✗ Blind (unless returned in chat)
Undeclared Network Egress ✓ Caught at connect() / sendmsg() ✗ Blind ✗ Blind (out-of-band exfil missed)
Token Cost & API Keys Zero ($0, 100% local) Zero ($0, 100% local) Requires OpenAI/OpenRouter keys
CI / Regression Lockfile ✓ mcp-behave.lock & diffing ✗ Schema-only ✗ Non-deterministic
Execution Speed < 5 seconds < 1 second 1 – 5 minutes per tool

CI / CD Gating

Fail PRs on Behavioral Drift

Integrate `mcp-behave` into GitHub Actions or GitLab CI. Export SARIF v2.1.0 alerts straight into GitHub Security Code Scanning and block pull requests when undeclared scopes creep into releases.

  • --fail-on HIGH  # exit code 1 on scope violations
  • --sarif-output results.sarif
  • --config .mcpbehaverc.json  # policy overrides
# .github/workflows/audit.yml
name: Behavioral Security Audit
on: [push, pull_request]

jobs:
  mcp-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run mcp-behave
        run: |
          pip install mcp-behave
          mcp-behave audit \
            --fail-on HIGH \
            --sarif-output results.sarif \
            -- python server.py
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Empirical Security Benchmarks

Rigorously Tested on Independent Public Suites

Evaluated against real exploit vectors, prompt injections, and ground-truth execution ledgers.

NeurIPS Multi-Server 134 Scenarios

CrossMCP-Bench

Multi-server benchmark over filesystem, SQL databases, and HTTP sinks. Features strict authorization context and 15 adversarial evasion techniques.

100%
Prevention (75/75)
0.0%
FPR (0/59)
100%
Detection (DR)
15 / 15
Evasions Blocked
0.05s evaluation speed Read Report →
Deterministic Runtime 12 Cases · 11 Servers

MCP-GuardBench

Measures detection and verified execution prevention via fixture ledgers. Exercises prompt injection, base64 secret flow, unapproved actions, rug pulls, and response bombs.

100%
Detection (9/9)
100%
Prevention (9/9)
0.0%
False Positives (0/3)
100%
Evidence Score
Outperforms reference runtimes Read Report →
OWASP MCP Top 10 60 Test Servers

Pluto Visibility Bench

Evaluates behavioral observation across 60 servers (41 malicious, 19 benign) across 8 OWASP MCP Top 10 categories spanning description poisoning and multi-call state.

100%
Precision (Zero FP)
75.6%
Recall (31/41)
86.1%
F1 Score (+41%)
19 / 19
Benign Clean
100% recall on 6/8 categories Read Report →
Flagship Corpus Twin-Server Corpus · SafeMCP Threat Matrix

Twin-Server Behavioral Benchmark (BENCHMARK.md)

Evaluates runtime observation using paired benign baselines vs backdoored twin servers across 7 domains (17 targets). Unlike static scanners, mcp-behave achieves 90.0% Recall, 100.0% Precision (0.0% False Positive Rate), and 85.7% Twin-Pair Separation Accuracy while catching delayed triggers, IMDS SSRF, and container socket escapes inside canary environments.

Official Ref Servers modelcontextprotocol/servers · 15-Test Adversarial Campaign

Reference Servers Adversarial Audit

Distinguishes static schema gaps from runtime facts across 7 official reference MCP servers. Tested with an automated 15-test adversarial campaign proving that Git strictly confines repos when configured, Fetch blocks SSRF and DNS rebinding at connect time, and Filesystem denies traversal and symlink escapes.

Development Roadmap

The Path to Trustworthy MCP Security

✓

v0.1.0 – v0.3.5: Hardened Libc Interposition & Detection Engine

Shipped

Native macOS `DYLD` and Linux `LD_PRELOAD`, symlink dereferencing, 4KB truncation alerts, AF_UNIX container socket capture, UDP `sendmsg`/`sendmmsg`, expanded secrets (.gnupg, cloud tokens), full MCP001–MCP062 catalog, and PyPI / npm / MCP Registry release.

0

Phase 0: Host Protection & Canary $HOME Redirection (v0.4.0)

In Progress

Canary `$HOME` isolation by default, mandatory `--unsafe-host` guardrails, command allowlisting for MCP server `serve` mode, and transparent open scoring formulas.

1

Phase 1: Sandboxing & Linux eBPF Kernel Tracing

Planned

Containerized audit by default (Docker / Podman / bubblewrap), Linux eBPF backend to trace statically linked binaries (Go, musl Rust) and raw syscalls, network namespaces with DNS exfiltration logging, and a public Evasion Benchmark Suite (`targets/evasion/`).

2

Phase 2: Behavioral Lockfile & GitHub Action Ecosystem

Planned

`mcp-behave init` (`mcp-behave.lock`) behavior lockfile generation, official `navid72m/mcp-behave-action@v1` for automated PR diff comments, open MCP-BehaveBench benchmark, and declared-behavior capability manifest proposal.

Start Auditing Your MCP Servers

Join security engineers and server authors adopting runtime behavioral verification. Zero compiler setup, instant execution.