Threat Model
What mcpwall protects against, what it doesn’t, and the assumptions it makes. This document is intentionally transparent. Security tools that hide their limitations aren’t security tools.
What mcpwall is
mcpwall is a rule-based request firewall for MCP tool calls. It sits as a transparent stdio proxy between your AI coding tool (Claude Code, Cursor, etc.) and the MCP server. Every JSON-RPC message from the client passes through the policy engine before reaching the server.
Rules are YAML, evaluated top-to-bottom, first match wins. Actions are allow, deny, or ask. No AI, no cloud, no network calls. Deterministic: same input + same rules = same output.
Bidirectional scanning: mcpwall inspects both requests (client → server) and responses (server → client). Outbound rules can redact leaked secrets, block prompt injection patterns, and flag suspicious content.
What mcpwall inspects
| Boundary | Inspected? | Detail |
|---|---|---|
| Client → Server (stdin) | Inspected | Every JSON-RPC message evaluated against policy rules |
| Server → Client (stdout) | Inspected | Responses evaluated against outbound rules. Secrets redacted, injection blocked. (v0.2.0) |
| Server stderr | Not inspected | Inherited by child process; passes through to parent stderr |
| Environment variables | Not inspected | Inherited from parent process; spawned server receives full env |
| Server side effects | Not inspected | File I/O, network calls, and other actions by the server process itself |
| Config files | At load time | Validated with Zod at startup; not re-verified during execution |
Attack classes mitigated
The 8 default deny rules and supporting engine features cover these attack classes out of the box. Custom rules can extend coverage further.
| Attack class | Status | Default rule |
|---|---|---|
| SSH key theft | Covered | block-ssh-keys |
| .env file access | Covered | block-env-files |
| Credential file access | Covered | block-credentials |
| Browser data theft | Covered | block-browser-data |
| Destructive commands | Covered | block-destructive-commands |
| Pipe-to-shell (curl|bash) | Covered | block-pipe-to-shell |
| Reverse shells | Covered | block-reverse-shells |
| Secret/API key leakage | Covered | block-secret-leakage |
| JSON-RPC batch bypass | Mitigated | n/a |
| ReDoS in config | Mitigated | — |
| Symlink path traversal | Mitigated | — |
| Process crash on bad input | Mitigated | — |
Known limitations
These are attack classes that mcpwall does not yet mitigate. Some are planned for future versions; others are out of scope by design.
| Attack class | Severity | Status |
|---|---|---|
| Response-side attacks | HIGH | Covered |
| Base64/URL encoding bypass | HIGH | Not covered |
| Rate limiting / DoS | HIGH | Not covered |
| Tool description poisoning | MEDIUM | Not covered |
| Prompt injection | MEDIUM | Not covered |
| Unicode/homograph tricks | MEDIUM | Not covered |
| Shell metacharacter bypass | MEDIUM | Partial |
| DNS exfiltration | MEDIUM | Not covered |
| Environment variable leakage | MEDIUM | Out of scope |
| Deep nesting stack overflow | LOW | Partial |
| Config tampering (TOCTOU) | LOW | Not covered |
| Log tampering | LOW | Not covered |
| Timing side-channels | LOW | Not covered |
The 8 built-in deny rules
These rules ship with mcpwall and apply automatically. No configuration needed. They match against tools/call requests and scan all argument values recursively using the _any_value matcher.
What must be true
mcpwall’s security guarantees depend on these assumptions holding. If any are violated, the threat model changes.
Module-by-module
Evaluates rules top-to-bottom, first match wins. Supports glob, regex, not_under, and _any_value matchers. Recursive scanning walks all argument values including arrays and nested objects.
Limitation: Recursive scanning (deepMatchAny) has no max-depth limit. Extremely deep nesting could cause a stack overflow. The 10MB line buffer limits total message size but not depth.
10 built-in patterns (AWS, GitHub, OpenAI, Anthropic, Stripe, private keys, JWT, Slack, database URLs). Pre-compiled regexes with optional Shannon entropy threshold to reduce false positives.
Limitation: Pattern-based only. Custom API key formats not matching built-in patterns will not be detected unless added by the user. No base64/URL decoding before matching.
Line-buffered parser with 10MB max line limit. Handles both single messages and JSON-RPC batch arrays. Each batch item validated individually (jsonrpc: "2.0" check).
Limitation: Oversized lines are discarded with a stderr warning. Incomplete JSON is silently forwarded (tolerant of non-JSON-RPC traffic).
Spawns the MCP server as a child process. Inbound path: evaluate each message, deny or forward. Outbound path: log and forward (no filtering). Batch handling evaluates each message individually; denied messages return JSON-RPC errors.
Limitation: On parsing/evaluation errors, the raw line is forwarded to maintain the connection. Signal handling forwards SIGINT/SIGTERM to child with SIGKILL escalation after 5 seconds.
Writes structured JSONL entries to daily-rotated files + stderr. Arguments for denied calls are redacted ([REDACTED]) to prevent secret leakage in logs.
Safeguard: No log signing or integrity verification. No size-based rotation (daily only). Write errors degrade gracefully to stderr-only logging.
Loads YAML config with Zod validation. Merges project config over global config (project rules take priority). Variable substitution for ${HOME}, ${PROJECT_DIR}, ~/.
Safeguard: Falls back to hardcoded default rules if files not found. ReDoS detection applied to all regex patterns at load time. Variable substitution is simple text replacement (no eval).
Where mcpwall fits
mcpwall is one layer in a defense-in-depth strategy. It is not a complete security solution on its own. We recommend combining it with:
What’s coming
| Feature | Version | Addresses |
|---|---|---|
| Response inspection Shipped | v0.2.0 | Outbound rules scan responses for secrets (redact), prompt injection (block), zero-width chars, and large payloads (flag) |
| Tool integrity / rug pull detection | v0.3.0 | Hash tool descriptions at first use, detect changes on subsequent calls |
| HTTP/SSE proxy mode | v0.3-0.4 | Support remote MCP servers over HTTP/SSE, not just stdio |
| Rate limiting | v0.4.0 | Throttle excessive tool calls within configurable time windows |
Found something?
If you find a security vulnerability in mcpwall, please report it responsibly. Email info@behrens-ai.de or open a security advisory on GitHub.
This threat model is maintained alongside the codebase and updated with each release. The source is at github.com/behrensd/mcpwall.