mcp-wallfacer

Runtime fuzzing & invariant testing for MCP servers — catch crashes, hangs, schema drift, race conditions, and state leaks before they ship.

mcp-wallfacer is the only runtime testing harness purpose-built for Model Context Protocol servers. It connects over stdio or Streamable HTTP, fuzzes tools with schema-driven adversarial payloads, validates responses against declared output schemas, evaluates user-defined YAML invariants and multi-step sequences, and stress-tests for concurrency races and session-state leaks — then stores every finding as a reproducible JSON record under .wallfacer/corpus/.

It complements static scanners (Snyk Agent Scan, Cisco MCP Scanner, Enkrypt) by exercising observable runtime behaviour instead of inspecting source code or tool descriptions. Run it in CI as a branch-protection gate, or locally before publishing your server.

What it catches

A seven-bug demo server is included at examples/python_server/ — running every wallfacer mode against it surfaces every kind above.

Quickstart

# 1. Install (pick any of the five paths — they all serve the same binary)
cargo install mcp-wallfacer            # Rust toolchain
npm install -g mcp-wallfacer           # npm wrapper
pip install mcp-wallfacer              # pip wrapper

# 2. Generate a config + sample invariants in your project
wallfacer init

# 3. Verify the connection
wallfacer doctor

# 4. Run the security baseline (auth + authorization + path-traversal +
#    injection-sql/shell + prompt-injection + secrets-leakage)
wallfacer property --pack security

Findings stream to stdout (Human / JSON / SARIF) and persist as JSON under .wallfacer/corpus/<tool>/<finding-id>.json with the seed and exact tool call needed for reproduction. Sensitive headers, environment variables, and payload fields (Authorization, Cookie, *-token, password, api_key, ...) are redacted on persistence — see docs/security.md.

Install

Five canonical channels, one binary. Full details in docs/install.md.

The npm and pip wrappers are thin launchers that download the matching prebuilt binary from the GitHub release at install / first-run time; the underlying CLI is byte-identical to a cargo install build of the same version. The crates.io package is mcp-wallfacer; the installed binary is wallfacer.

CI usage

# .github/workflows/wallfacer.yml
name: Wallfacer
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: lacausecrypto/mcp-wallfacer@v0.8.1
        with:
          pack-all: "true"          # or pack: "security\nstateful"
          config: wallfacer.toml
          format: sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ${{ steps.run.outputs.findings-sarif }}

Commands

Rule packs

17 invariant packs ship embedded in the binary. Discover them with wallfacer pack list; render the auto-generated reference into docs/packs/ with cargo run -p wallfacer-tools -- gen-pack-docs.

When to use which pack

# Single pack
wallfacer property --pack secrets-leakage

# Multiple packs (deduped by canonical invariant name)
wallfacer property --pack auth --pack error-shape

# Every embedded pack
wallfacer property --pack-all

# Override a pack's tool-name parameter for your codebase
wallfacer property --pack auth --param whoami_tool=getCurrentUser

Persist overrides in wallfacer.toml:

[packs.auth]
whoami_tool = "getCurrentUser"
list_resources_tool = "myListResources"

[packs.stateful]
create_tool = "create_record"
delete_tool = "delete_record"
read_tool = "read_record"

Customise a pack: wallfacer pack init <name> copies the embedded YAML to packs/<name>.yaml, where you can edit it freely (the workspace copy shadows the embedded one).

Configuration

[target]
kind = "stdio"                # or "http"
command = "python3"
args = ["server.py"]
timeout_ms = 5000

# HTTP target — ${VAR} is expanded against the process env at load
# time (use $$ to keep a literal $).
# kind = "http"
# url = "http://localhost:8000/mcp"
# [target.headers]
# Authorization = "Bearer ${WALLFACER_BEARER}"

[output]
corpus_dir = ".wallfacer/corpus"
lock_timeout_ms = 30000

[allow_destructive]
# Regex allowlist for tools the destructive classifier would
# otherwise refuse to invoke (matched against tool name).
tools = ["^logs_.*$"]

[destructive]
# Add custom destructive patterns on top of the built-in keyword
# detector (delete / drop / destroy / ...). Set
# `replace_defaults = true` to opt out of the built-ins.
patterns = ["^remove_.*$"]
replace_defaults = false

[severity]
# Override the default per-kind severity. Useful when concurrency
# races are not security-critical for your tool surface.
state_leak = "medium"

Example

examples/python_server/ ships a seven-bug Python MCP server that exercises every FindingKind (Crash, Hang, SchemaViolation, PropertyFailure, ProtocolError, StateLeak, SequenceFailure). The Phase F + L acceptance suite gates CI against this fixture.

cd examples/python_server
wallfacer fuzz
wallfacer differential --learn && wallfacer differential
wallfacer property --pack-all
wallfacer torture --mode state-leak
wallfacer corpus list

A parallel HTTP fixture lives at examples/python_server/server_http.py — same buggy tools served over POST /mcp, used by the Phase M end-to-end test.

Documentation

• docs/architecture.md — workspace layout, plan lifecycle, reproducibility contract.
• docs/security.md — redaction model, file permissions, replay unredaction, threat model.
• docs/sequences.md — multi-step DSL, substitution rules, reconnect policy.
• docs/http-target.md — Streamable HTTP transport, env-var headers, fixture.
• docs/install.md — every install path, with troubleshooting.
• docs/real-world.md — running packs against external MCP servers, reporting upstream.
• docs/packs/ — auto-generated reference for every embedded pack.
• API: https://docs.rs/wallfacer-core.

Roadmap

• v0.2 ✅ — workspace hardening, full JSON Schema generation, plan layer, property DSL v2, robustness pass, DX & docs.
• v0.3 ✅ — embedded rule pack library (15 packs), for_each_tool directive, multi-pack composition, real-world validation methodology.
• v0.4 ✅ — sequence-aware property testing (stateful, auth-flow packs), HTTP transport CI-gated, distribution to npm + pip + GitHub Action Marketplace.
• v0.5 ✅ — wallfacer suggest (auto-detect which packs apply), wallfacer coverage (tool × pack matrix + --strict CI gate), wallfacer report --html (self-contained dashboard).
• v0.6 ✅ — stateful fuzzing with persistent corpus + 90/10 mutate-vs-random (fuzz --corpus-feedback), mcp-spec-conformance pack (validates the MCP wire-format itself), context-poisoning pack (detects malicious servers planting prompt injections), $.tool.{name,description,annotations} DSL extension.
• v0.7 ✅ — sequence corpus seeding (cross-pollinates fuzz + sequences), HTTP fault injection fixture (502 / 504 / FIN-empty / FIN-mid / slow), real input shrinker (corpus minimize --replay, delta-debug), real-world campaign across 6 popular OSS MCPs (clean-bill of health, methodology in docs/real-world-findings.md).
• v0.8 ✅ — wallfacer property --max-tools / --include / --exclude (scales packs to large servers), torture mode confirmed under HTTP faults, per-invariant shrinking (corpus minimize --replay --invariants <path>), flakiness tracker (fuzz --runs N --aggregate tags stable / flaky / one-shot), prompt-injection-v2 pack (50 variants spanning jailbreak / chain-of-thought / multilingual / encoded-payload / formatting-trick attacks).
• v0.9 — continued real-world campaign on large MCPs (now unblocked by --max-tools), grammar DSL for user-defined prompt-injection variants, sequence-aware shrinker (delta-debug across sequence steps).

Contributing

Issues, PRs, and pack contributions welcome. See CONTRIBUTING.md if it exists, otherwise open a discussion on the issues page.

License

Dual-licensed under MIT or Apache-2.0, at your option.