mcp-behave logo
mcp-behave v0.3.5
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.3.5 npm: 0.3.5 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

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.