mcp-cage 0.4.0__tar.gz
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.
- mcp_cage-0.4.0/LICENSE +21 -0
- mcp_cage-0.4.0/PKG-INFO +272 -0
- mcp_cage-0.4.0/README.md +245 -0
- mcp_cage-0.4.0/mcp_cage.egg-info/PKG-INFO +272 -0
- mcp_cage-0.4.0/mcp_cage.egg-info/SOURCES.txt +11 -0
- mcp_cage-0.4.0/mcp_cage.egg-info/dependency_links.txt +1 -0
- mcp_cage-0.4.0/mcp_cage.egg-info/entry_points.txt +3 -0
- mcp_cage-0.4.0/mcp_cage.egg-info/top_level.txt +3 -0
- mcp_cage-0.4.0/mcp_cage_cli.py +455 -0
- mcp_cage-0.4.0/mcp_cage_core.py +3799 -0
- mcp_cage-0.4.0/mcp_cage_proxy.py +305 -0
- mcp_cage-0.4.0/pyproject.toml +52 -0
- mcp_cage-0.4.0/setup.cfg +4 -0
mcp_cage-0.4.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nagarajulu Aerakoni
|
|
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.
|
mcp_cage-0.4.0/PKG-INFO
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcp-cage
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Zero-Code Wire & Native-Hook Security Firewall for Claude Code, Cursor, Codex, Gemini CLI & MCP (Gitleaks + Little Snitch for AI Coding Agents)
|
|
5
|
+
Author-email: Nagarajulu Aerakoni <nagarajulu.a@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/nagarajulu/mcp-cage
|
|
8
|
+
Project-URL: Repository, https://github.com/nagarajulu/mcp-cage
|
|
9
|
+
Project-URL: Issues, https://github.com/nagarajulu/mcp-cage/issues
|
|
10
|
+
Keywords: mcp,model-context-protocol,ai-security,agent-security,claude-code,cursor,prompt-injection,llm-security,information-flow-control
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Information Technology
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Security
|
|
22
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Dynamic: license-file
|
|
27
|
+
|
|
28
|
+
# `mcp-cage` 🛡️
|
|
29
|
+
|
|
30
|
+
**Zero-Code Wire & Native-Hook Security Firewall for Claude Code, Cursor, Codex, Gemini CLI & MCP**
|
|
31
|
+
*("Gitleaks + Little Snitch for AI Coding Agents" — 100% Python 3.10+ Standard Library, Zero External Dependencies)*
|
|
32
|
+
|
|
33
|
+
[](https://nagarajulu.github.io/mcp-cage/)
|
|
34
|
+
|
|
35
|
+
[](https://github.com/nagarajulu/mcp-cage/actions/workflows/ci.yml)
|
|
36
|
+
[](https://nagarajulu.github.io/mcp-cage/)
|
|
37
|
+
[](LICENSE)
|
|
38
|
+
[](pyproject.toml)
|
|
39
|
+
[-success.svg)](pyproject.toml)
|
|
40
|
+
|
|
41
|
+
> 🚀 **Try the Live Interactive Web Sandbox in Your Browser:** [**`https://nagarajulu.github.io/mcp-cage/`**](https://nagarajulu.github.io/mcp-cage/)
|
|
42
|
+
> Explore the **5 Integration Modes** (`wrap`, `hook`, `shell`, Python SDK, `mcp-sploit`), inspect the **8-Plane Security Feature Matrix**, replay **V1 Failure vs. v0.3.0 Blocked Exploits** on the live $(P \times U \Rightarrow S)$ graph, and generate copy-paste configs for **Claude Code, Cursor, Gemini CLI, Antigravity (`agy`), Codex, Claude Desktop, and LangGraph**.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Why `mcp-cage`?
|
|
47
|
+
|
|
48
|
+
Modern AI coding agents (**Claude Code**, **Cursor**, **OpenAI Codex CLI**, **Google Gemini CLI**, **Google Antigravity `agy`**, and **Claude Desktop**) combine three capabilities in a single context window:
|
|
49
|
+
|
|
50
|
+
1. **Private Data Access (`[P]`)** — reading `.env`, SSH keys, source code, and production databases.
|
|
51
|
+
2. **Untrusted Content Ingestion (`[U]`)** — reading external GitHub issues/PRs, web pages, and third-party documentation.
|
|
52
|
+
3. **External Egress & State Mutation (`[S]` / `[M]`)** — executing shell commands (`curl`, `git push`), posting Slack/GitHub comments, or mutating configuration files.
|
|
53
|
+
|
|
54
|
+
When all three meet in a single session—Simon Willison's **Lethal Trifecta**—a single indirect prompt injection (`XPIA`) or poisoned MCP tool definition (`MCPTox` / `CurXecute` CVE-2025-54135) can silently exfiltrate credentials or execute arbitrary commands.
|
|
55
|
+
|
|
56
|
+
**`mcp-cage` is a deterministic, OS-process-isolated security reference monitor** that sits across **both** planes of an AI coding agent:
|
|
57
|
+
- **Plane A (MCP JSON-RPC 2.0 Wire Gateway):** Wraps any `stdio` MCP server (`mcp-cage wrap`) to scrub secrets on the wire, pin `tools/list` schemas (`mcp-lock.json`), block `sampling/createMessage` hijacks, and spotlight untrusted outputs.
|
|
58
|
+
- **Plane B (Native Agent Lifecycle Hooks):** Plugs directly into `PreToolUse` / `PostToolUse` / `BeforeTool` / `beforeShellExecution` hooks across Claude Code, Cursor, Gemini CLI, Antigravity (`agy`), and Codex CLI—sharing a single cross-process **SQLite WAL** taint & secret vault.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Core Security Capabilities
|
|
63
|
+
|
|
64
|
+
### 1. Zero-Leak Bidirectional Secret Scrubbing (`BidirectionalSecretScrubber`)
|
|
65
|
+
- Intercepts 11+ credential classes (`OPENAI_KEY`, `ANTHROPIC_KEY`, `AWS_ACCESS_KEY`, `GITHUB_PAT`, `STRIPE_KEY`, `SLACK_TOKEN`, `PRIVATE_KEY_PEM`, `JWT_TOKEN`, `DB_CONN_URI`, JSON/YAML secrets, and `.env` assignments) **before** they enter the LLM context window.
|
|
66
|
+
- Replaces raw secrets on the wire with deterministic placeholders (`<MCP_REDACTED_OPENAI_KEY_1>`) backed by an atomic cross-process **SQLite WAL vault**.
|
|
67
|
+
- Even if Process 1 (`filesystem` MCP or native `Read`) mints a token, Process 2 (`slack` MCP or native `Bash`) immediately blocks any attempt to exfiltrate that placeholder to an unauthorized sink.
|
|
68
|
+
|
|
69
|
+
### 2. Destructive Command, SSRF (`169.254.169.254`) & High-Entropy DNS Exfiltration Firewall
|
|
70
|
+
- **Path & Dotfile Confinement (`CVE-2025-53110` / `CVE-2025-53773` / `CVE-2025-54135`):** Resolves canonical paths (`Path.resolve()`) to block symlink escapes and hard-denies agent writes to `.env`, `.git/hooks/`, `.vscode/settings.json`, `.cursor/mcp.json`, `CLAUDE.md`, and `~/.ssh/`.
|
|
71
|
+
- **Cloud Metadata & Private Network SSRF Guard (`validate_outbound_network_target`):** Deterministically blocks requests to AWS/ECS/GCP/Alibaba/IPv6 cloud metadata (`169.254.169.254`, `169.254.170.2`, `fd00:ec2::254`, `metadata.google.internal`, `100.100.100.200`), loopback (`127.0.0.0/8`, `localhost`, `[::1]`), RFC 1918 private networks, and dangerous non-HTTP schemes (`file://`, `gopher://`, `dict://`, `ftp://`, `ldap://`).
|
|
72
|
+
- **High-Entropy DNS Exfiltration Blocker:** Computes per-label Shannon entropy ($H > 3.9$ bits/char for labels $>28$ chars) and regex signatures to block hex/base64 secret exfiltration over DNS (`<hex32>.attacker.com`).
|
|
73
|
+
|
|
74
|
+
### 3. Lethal-Trifecta Circuit Breaker + MELON Provenance Attribution
|
|
75
|
+
- Tracks monotonic session **Integrity** (`TRUSTED` $\rightarrow$ `ENDORSED` $\rightarrow$ `UNTRUSTED`) and **Confidentiality** (`PUBLIC` $\rightarrow$ `INTERNAL` $\rightarrow$ `CONFIDENTIAL` $\rightarrow$ `SECRET`) across concurrent tool calls using `BEGIN IMMEDIATE` SQLite transactions.
|
|
76
|
+
- **MELON Provenance Attribution:** Extracts URLs, domains, and email addresses from untrusted external inputs (`UNTRUSTED_SOURCE`) and hard-denies any subsequent sink or shell call targeting those untrusted entities (`[PROVENANCE HIJACK BLOCKED]`).
|
|
77
|
+
- **Zero-Fatigue UX:** Distinguishes benign reads (`README.md` + teammate issues stay `ENDORSED`/`PUBLIC`), allows safe workspace-local code edits, and supports **5-minute scoped workspace edit leases** (`LEASE_MUTATOR_5M`) while keeping external egress locked.
|
|
78
|
+
|
|
79
|
+
### 4. `CurXecute` Config Linter (`audit-config`) & `MCPTox` Schema Lockfile Verification
|
|
80
|
+
- **On-the-Wire Tool Sanitization & Rug-Pull Detection (`SchemaLockVerifier`):** Strips `<IMPORTANT>`, `<system>`, HTML comments, and cross-server shadowing directives from `tools/list` descriptions prior to SHA-256 pinning in `mcp-lock.json`.
|
|
81
|
+
- **Workspace Config Auditor (`mcp-cage audit-config`):** Scans `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, and `claude_desktop_config.json` for `CurXecute` relative-path RCE (`./`, `../`, `/tmp/`, `bash -c`, command chaining), hardcoded plaintext API keys in `env` blocks, and unwrapped MCP servers.
|
|
82
|
+
|
|
83
|
+
### 5. Zero-Config Empirical Wire-Level Parameter Guards (`v0.3.0`)
|
|
84
|
+
Automatically enforced out of the box by `MCPCageEngine` (`MCPWireGateway`), `DynamicProfileAwareProxy`, and Plane B hooks:
|
|
85
|
+
- **Runtime Endpoint & Session Re-pointing Guard (`endpoint_repoint_guard`):** Blocks runtime connection-mutation tools (`connect_to_*`, `switch_server`, `set_endpoint`, `configure_connection`) unless explicitly opted in, and blocks mid-session `*_url` + `*_token`/`*_key` repointing to `local`, `localhost`, `127.0.0.1`, `169.254.169.254`, RFC1918, or untrusted hosts as well as raw bearer tokens in LLM context (`GHSA-rvjm-7hvp-f868`).
|
|
86
|
+
- **Embedded POSIX Command Substitution Guard (`path_command_substitution_guard` + `make_workspace_path_guard`):** Inspects `folderPath`, `filePath`, `source_dir`, `app_dir`, `working_directory`, `download_directory`, `destination`, and `path` for `$(...)`, `` `...` ``, and `${...}` even when disguised inside a valid relative workspace path segment (`CWE-78`).
|
|
87
|
+
- **REST URL Path-Segment Traversal Guard (`url_path_segment_guard`):** Blocks `..`, `%2e%2e`, `/`, `%2f`, `\`, `?`, and `#` (including URL-decoded/double-encoded forms) across `*_id`, `*Id`, `*Name`, `scriptName`, `job_id`, `session_id`, `rag_id`, `bucket`, and `repo` before REST URL interpolation (`CWE-22`).
|
|
88
|
+
- **CLI Positional-Argument Flag Injection Guard (`cli_flag_injection_guard`):** Blocks leading `-` / `--` flags (`--upload-pack=`, `--template=`, `--kubeconfig=`, `--token=`, `--output=`) injected into positional resource, directory, or target arguments (`CWE-88`).
|
|
89
|
+
- **Multi-Statement & Clause-Level SQL AST Guard (`sql_safety_guard`):** Strips `--` and `/* ... */` comments (both space-joined and compact to defeat token splitting), detects stacked `;` queries, and enforces SQLi checks across `where_clause`, `order_by`, `filter`, `having`, `sort_by`, and `group_by` (`A4.3` / `A8.1`).
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Empirical Co-Design Evolution (`v0.1.0` → `v0.2.2` → `v0.3.0`)
|
|
94
|
+
|
|
95
|
+
Each `mcp-cage` release translates real-world vulnerability classes uncovered across audited public and Big-Tech MCP servers into general-purpose, zero-config architectural capabilities:
|
|
96
|
+
|
|
97
|
+
| Release | Architectural Milestone | Real-World Audited MCP Servers / Incidents Addressed | Generalized Guard Plane |
|
|
98
|
+
| :--- | :--- | :--- | :--- |
|
|
99
|
+
| **`v0.1.0`** | Dual-Lattice IFC & Wire Prototype | Invariant Labs GitHub MCP Exploit, `MCPTox`, Microsoft Spotlighting, `MELON` | `SessionTaintStateMachine`, `SchemaLockVerifier` (`mcp-lock.json`), randomized datamarking boundaries, `ToxicFlowGraphAnalyzer` (`mcp-sploit`). |
|
|
100
|
+
| **`v0.2.2`** | Cross-Process WAL & Dual-Plane Firewall | `CVE-2025-53110`, `CVE-2025-53773` (Copilot YOLO), `CVE-2025-54135` (`CurXecute`), AWS IMDSv1 SSRF, DNS exfiltration | Shared SQLite WAL `BidirectionalSecretScrubber`, `BEGIN IMMEDIATE` atomic taint, `validate_outbound_network_target` (IMDS/RFC1918/Shannon DNS), `WorkspaceMCPConfigAuditor`, Plane A + Plane B hooks. |
|
|
101
|
+
| **`v0.3.0`** | Empirical Zero-Config Wire Guards | `datalayer/jupyter-mcp-server` (`GHSA-rvjm-7hvp-f868`), Cloud Container Deployment MCP Servers (`CWE-78`), Edge & API Gateway MCP Servers (`CWE-22` REST path-segment traversal), Kubernetes & Infrastructure CLI MCP Servers (`CWE-88` positional flag injection), Enterprise Data Warehouse & Relational SQL MCP Servers (`CWE-89` comment-split & clause injection) | `endpoint_repoint_guard`, `path_command_substitution_guard` + hardened `make_workspace_path_guard`, `url_path_segment_guard`, `cli_flag_injection_guard`, comment-stripping & clause-level `sql_safety_guard`. |
|
|
102
|
+
| **`v0.4.0`** | Wire-DIFC, 4-Slot Canonicalizer, Line-Span WAL & Kernel Sandbox Compiler | Day-0 Non-Collision Tool-Provider Misbinding, Cross-Session Stored XPIA (`CLAUDE.md`), `OverServe` Resource Amplification ($93.88\times$), EFF Diceware Covert Identifiers, Missing OS Kernel Containment | `WireDIFCCanonicalizer` (`S_poison >= 0.45` + 4-Slot Canonicalizer), `PersistentLineSpanProvenance` (`persistent_span_taint`), `DestinationBoundFPEVault`, `CausalStateProgressGovernor`, `SchemaToKernelSandboxCompiler` (`mcp-cage compile-sandbox` Seatbelt SBPL / Landlock), `mcp-cage bench`. |
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Quick Start (Zero Dependencies)
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
git clone https://github.com/nagarajulu/mcp-cage.git
|
|
110
|
+
cd mcp-cage
|
|
111
|
+
pip install -e .
|
|
112
|
+
|
|
113
|
+
# 1. Run the Unified 6-Suite Non-Regression & 9-Plane E2E Verification Runner
|
|
114
|
+
python3 run_all_regression_suites.py
|
|
115
|
+
|
|
116
|
+
# 2. Compile an OS Kernel Seatbelt SBPL (macOS) or Landlock/bwrap (Linux) Sandbox Profile
|
|
117
|
+
mcp-cage compile-sandbox --workspace . --os auto
|
|
118
|
+
|
|
119
|
+
# 3. Audit workspace MCP configs for CurXecute RCE & hardcoded secrets
|
|
120
|
+
mcp-cage audit-config
|
|
121
|
+
|
|
122
|
+
# 4. Run static Toxic-Flow Graph Analysis (mcp-sploit)
|
|
123
|
+
mcp-sploit audit
|
|
124
|
+
|
|
125
|
+
# 5. Day-1 Zero-Friction Onboarding: Start in '--mode shadow' (logs alerts to .mcp-cage/audit.jsonl without blocking)
|
|
126
|
+
# then switch to '--mode enforce' once verified in your workflow:
|
|
127
|
+
mcp-cage wrap --server filesystem --workspace . --mode shadow -- npx -y @modelcontextprotocol/server-filesystem .
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Universal Dual-Plane Integration Guide
|
|
133
|
+
|
|
134
|
+
`mcp-cage` unifies **Plane A (`mcp-cage wrap`)** and **Plane B (`mcp-cage hook`)** against a single shared SQLite WAL database (`.mcp-cage/taint.db`).
|
|
135
|
+
|
|
136
|
+
### 1. Claude Code (`.claude/settings.json` + `.mcp.json`)
|
|
137
|
+
|
|
138
|
+
Add Plane B hooks to `.claude/settings.json`:
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"hooks": {
|
|
142
|
+
"UserPromptSubmit": [
|
|
143
|
+
{
|
|
144
|
+
"hooks": [{ "type": "command", "command": "mcp-cage hook claude UserPromptSubmit --db .mcp-cage/taint.db" }]
|
|
145
|
+
}
|
|
146
|
+
],
|
|
147
|
+
"PreToolUse": [
|
|
148
|
+
{
|
|
149
|
+
"matcher": ".*",
|
|
150
|
+
"hooks": [{ "type": "command", "command": "mcp-cage hook claude PreToolUse --db .mcp-cage/taint.db" }]
|
|
151
|
+
}
|
|
152
|
+
],
|
|
153
|
+
"PostToolUse": [
|
|
154
|
+
{
|
|
155
|
+
"matcher": ".*",
|
|
156
|
+
"hooks": [{ "type": "command", "command": "mcp-cage hook claude PostToolUse --db .mcp-cage/taint.db" }]
|
|
157
|
+
}
|
|
158
|
+
]
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### 2. Cursor (`.cursor/hooks.json` + `.cursor/mcp.json`)
|
|
164
|
+
|
|
165
|
+
Add Plane B hooks to `.cursor/hooks.json`:
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"version": 1,
|
|
169
|
+
"hooks": {
|
|
170
|
+
"beforeReadFile": [{ "command": "mcp-cage hook cursor beforeReadFile --db .mcp-cage/taint.db" }],
|
|
171
|
+
"beforeShellExecution": [{ "command": "mcp-cage hook cursor beforeShellExecution --db .mcp-cage/taint.db" }],
|
|
172
|
+
"beforeMCPExecution": [{ "command": "mcp-cage hook cursor beforeMCPExecution --db .mcp-cage/taint.db" }],
|
|
173
|
+
"afterMCPExecution": [{ "command": "mcp-cage hook cursor afterMCPExecution --db .mcp-cage/taint.db" }]
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### 3. Google Gemini CLI (`.gemini/settings.json`)
|
|
179
|
+
|
|
180
|
+
```json
|
|
181
|
+
{
|
|
182
|
+
"hooks": {
|
|
183
|
+
"SessionStart": [{ "command": "mcp-cage hook gemini SessionStart --db .mcp-cage/taint.db" }],
|
|
184
|
+
"BeforeTool": [{ "command": "mcp-cage hook gemini BeforeTool --db .mcp-cage/taint.db" }],
|
|
185
|
+
"AfterTool": [{ "command": "mcp-cage hook gemini AfterTool --db .mcp-cage/taint.db" }]
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### 4. Google Antigravity CLI (`agy`)
|
|
191
|
+
|
|
192
|
+
Register a wrapped MCP server with `agy`:
|
|
193
|
+
```bash
|
|
194
|
+
agy mcp add filesystem-caged -- mcp-cage wrap \
|
|
195
|
+
--server filesystem \
|
|
196
|
+
--workspace . \
|
|
197
|
+
--state-dir .mcp-cage \
|
|
198
|
+
-- npx -y @modelcontextprotocol/server-filesystem .
|
|
199
|
+
```
|
|
200
|
+
And configure `PreToolUse` / `PostToolUse` hooks using `mcp-cage hook agy PreToolUse --db .mcp-cage/taint.db`.
|
|
201
|
+
|
|
202
|
+
### 5. OpenAI Codex CLI (`~/.codex/hooks.json`)
|
|
203
|
+
|
|
204
|
+
```json
|
|
205
|
+
{
|
|
206
|
+
"hooks": {
|
|
207
|
+
"UserPromptSubmit": [{ "command": "mcp-cage hook codex UserPromptSubmit --db .mcp-cage/taint.db" }],
|
|
208
|
+
"PreToolUse": [{ "command": "mcp-cage hook codex PreToolUse --db .mcp-cage/taint.db" }],
|
|
209
|
+
"PostToolUse": [{ "command": "mcp-cage hook codex PostToolUse --db .mcp-cage/taint.db" }]
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### 6. Claude Desktop / Any `stdio` MCP Host (`claude_desktop_config.json`)
|
|
215
|
+
|
|
216
|
+
Wrap any upstream MCP server with `mcp-cage wrap`:
|
|
217
|
+
```json
|
|
218
|
+
{
|
|
219
|
+
"mcpServers": {
|
|
220
|
+
"filesystem-caged": {
|
|
221
|
+
"command": "mcp-cage",
|
|
222
|
+
"args": [
|
|
223
|
+
"wrap",
|
|
224
|
+
"--server", "filesystem",
|
|
225
|
+
"--workspace", "/Users/you/workspace",
|
|
226
|
+
"--state-dir", "/Users/you/workspace/.mcp-cage",
|
|
227
|
+
"--",
|
|
228
|
+
"npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/you/workspace"
|
|
229
|
+
]
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Research Foundations & Academic Lineage
|
|
238
|
+
|
|
239
|
+
`mcp-cage` translates foundational Operating Systems & Agentic Information-Flow Control (IFC) research into a zero-dependency runtime firewall:
|
|
240
|
+
|
|
241
|
+
| Research System / Paper | Reference | Core Concept Adapted in `mcp-cage` |
|
|
242
|
+
| :--- | :--- | :--- |
|
|
243
|
+
| **CaMeL** *(Debenedetti et al., Google DeepMind, 2025)* | [`arXiv:2503.18813`](https://arxiv.org/abs/2503.18813) | Separating data capabilities & provenance from untrusted control flow in LLM tool invocations. |
|
|
244
|
+
| **FIDES** *(Costa et al., Microsoft Research, 2025)* | [`arXiv:2505.23643`](https://arxiv.org/abs/2505.23643) | Dual-lattice Information-Flow Control (Integrity $\times$ Confidentiality labels) with deterministic sink gates. |
|
|
245
|
+
| **Progent** *(Shi et al., UC Berkeley, 2025)* | [`arXiv:2504.11703`](https://arxiv.org/abs/2504.11703) | Programmable privilege control & deterministic argument guards (`StandardArgGuards`) over tool parameters. |
|
|
246
|
+
| **MELON** *(Zhu et al., 2025)* | [`arXiv:2502.05174`](https://arxiv.org/abs/2502.05174) | Provenance attribution blocking target arguments (URLs, domains, emails) extracted from untrusted tool outputs. |
|
|
247
|
+
| **Spotlighting** *(Hines et al., Microsoft, 2024)* | [`arXiv:2403.14720`](https://arxiv.org/abs/2403.14720) | Cryptographically randomized datamarking boundaries (`<<<UNTRUSTED_DATA_BOUNDARY id=...>>>`) with anti-spoofing. |
|
|
248
|
+
| **MCPTox** *(Wang et al., 2025)* | [`arXiv:2508.14925`](https://arxiv.org/abs/2508.14925) | Structural sanitization of poisoned MCP tool descriptions and cross-server shadowing detection (`SchemaLockVerifier`). |
|
|
249
|
+
| **FLOWSEAL** *(Aerakoni, 2026)* | `arXiv:2609.14003` | Cross-process SQLite WAL ambient taint state machine & bidirectional secret vault across Plane A + Plane B. |
|
|
250
|
+
| **HiStar / Flume / Capsicum** *(Zeldovich et al., Krohn et al., Watson et al.)* | *OSDI '06 / SOSP '07 / USENIX '10* | Decentralized IFC labels, explicit human declassification leases, and OS-level capability confinement. |
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## Repository Structure
|
|
255
|
+
|
|
256
|
+
| File | Description |
|
|
257
|
+
| :--- | :--- |
|
|
258
|
+
| [`mcp_cage_core.py`](mcp_cage_core.py) | Unified core engine: `SessionTaintStateMachine`, `BidirectionalSecretScrubber`, `SchemaLockVerifier`, `ToxicFlowGraphAnalyzer`, `WorkspaceMCPConfigAuditor`, SSRF/DNS Exfil Guard, `MCPWireGateway`, and Dual-Plane CLI (`mcp-cage` / `mcp-sploit`). |
|
|
259
|
+
| [`mcp_cage_proxy.py`](mcp_cage_proxy.py) | Full JSON-RPC 2.0 wire proxy (`MCPJsonRpcProxy` & `StdioSubprocessBridge`) covering `tools/list`, `tools/call`, `resources/read`, `prompts/get`, and `sampling/createMessage`. |
|
|
260
|
+
| [`mcp_cage_cli.py`](mcp_cage_cli.py) | Standalone `stdio` process wrapper (`mcp-cage wrap`) with dynamic `tools/list` classification and config generator. |
|
|
261
|
+
| [`demo_interactive.py`](demo_interactive.py) | 5-Act interactive terminal walkthrough demonstrating every defense end-to-end. |
|
|
262
|
+
| [`test_mcp_cage_v30_empirical_guards.py`](test_mcp_cage_v30_empirical_guards.py) | v0.3.0 empirical guard regression suite covering Jupyter runtime hijack, Cloud Run `app$(...)`, Cloudflare path traversal, GKE/K8s CLI flag injection, Snowflake/MySQL SQLi, and sub-millisecond latency. |
|
|
263
|
+
| [`test_mcp_cage_v21.py`](test_mcp_cage_v21.py) | Comprehensive V2.2 unit & integration test suite (10 test suites including SSRF/DNS exfil & `CurXecute` config auditing). |
|
|
264
|
+
| [`test_e2e_all_8_planes.py`](test_e2e_all_8_planes.py) | 8-Plane End-to-End security test suite (17 tests across cognitive, protocol, trifecta, parameter, memory, and subprocess planes). |
|
|
265
|
+
| [`CHANGELOG.md`](CHANGELOG.md) | Empirical Co-Design release lineage (`v0.1.0` → `v0.2.2` → `v0.3.0`). |
|
|
266
|
+
| [`docs/index.html`](docs/index.html) / [`visualizer.html`](visualizer.html) | Interactive browser-based showcase: 5 Integration Modes, 8-Plane Security Matrix, V1 vs. v0.3.0 Exploit Simulator, Config Generator & 1966–2026 Research Lineage ([live on GitHub Pages](https://nagarajulu.github.io/mcp-cage/)). |
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## License
|
|
271
|
+
|
|
272
|
+
Released under the [MIT License](LICENSE). Copyright (c) 2026 [Nagarajulu Aerakoni](https://github.com/nagarajulu).
|
mcp_cage-0.4.0/README.md
ADDED
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
# `mcp-cage` 🛡️
|
|
2
|
+
|
|
3
|
+
**Zero-Code Wire & Native-Hook Security Firewall for Claude Code, Cursor, Codex, Gemini CLI & MCP**
|
|
4
|
+
*("Gitleaks + Little Snitch for AI Coding Agents" — 100% Python 3.10+ Standard Library, Zero External Dependencies)*
|
|
5
|
+
|
|
6
|
+
[](https://nagarajulu.github.io/mcp-cage/)
|
|
7
|
+
|
|
8
|
+
[](https://github.com/nagarajulu/mcp-cage/actions/workflows/ci.yml)
|
|
9
|
+
[](https://nagarajulu.github.io/mcp-cage/)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](pyproject.toml)
|
|
12
|
+
[-success.svg)](pyproject.toml)
|
|
13
|
+
|
|
14
|
+
> 🚀 **Try the Live Interactive Web Sandbox in Your Browser:** [**`https://nagarajulu.github.io/mcp-cage/`**](https://nagarajulu.github.io/mcp-cage/)
|
|
15
|
+
> Explore the **5 Integration Modes** (`wrap`, `hook`, `shell`, Python SDK, `mcp-sploit`), inspect the **8-Plane Security Feature Matrix**, replay **V1 Failure vs. v0.3.0 Blocked Exploits** on the live $(P \times U \Rightarrow S)$ graph, and generate copy-paste configs for **Claude Code, Cursor, Gemini CLI, Antigravity (`agy`), Codex, Claude Desktop, and LangGraph**.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Why `mcp-cage`?
|
|
20
|
+
|
|
21
|
+
Modern AI coding agents (**Claude Code**, **Cursor**, **OpenAI Codex CLI**, **Google Gemini CLI**, **Google Antigravity `agy`**, and **Claude Desktop**) combine three capabilities in a single context window:
|
|
22
|
+
|
|
23
|
+
1. **Private Data Access (`[P]`)** — reading `.env`, SSH keys, source code, and production databases.
|
|
24
|
+
2. **Untrusted Content Ingestion (`[U]`)** — reading external GitHub issues/PRs, web pages, and third-party documentation.
|
|
25
|
+
3. **External Egress & State Mutation (`[S]` / `[M]`)** — executing shell commands (`curl`, `git push`), posting Slack/GitHub comments, or mutating configuration files.
|
|
26
|
+
|
|
27
|
+
When all three meet in a single session—Simon Willison's **Lethal Trifecta**—a single indirect prompt injection (`XPIA`) or poisoned MCP tool definition (`MCPTox` / `CurXecute` CVE-2025-54135) can silently exfiltrate credentials or execute arbitrary commands.
|
|
28
|
+
|
|
29
|
+
**`mcp-cage` is a deterministic, OS-process-isolated security reference monitor** that sits across **both** planes of an AI coding agent:
|
|
30
|
+
- **Plane A (MCP JSON-RPC 2.0 Wire Gateway):** Wraps any `stdio` MCP server (`mcp-cage wrap`) to scrub secrets on the wire, pin `tools/list` schemas (`mcp-lock.json`), block `sampling/createMessage` hijacks, and spotlight untrusted outputs.
|
|
31
|
+
- **Plane B (Native Agent Lifecycle Hooks):** Plugs directly into `PreToolUse` / `PostToolUse` / `BeforeTool` / `beforeShellExecution` hooks across Claude Code, Cursor, Gemini CLI, Antigravity (`agy`), and Codex CLI—sharing a single cross-process **SQLite WAL** taint & secret vault.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Core Security Capabilities
|
|
36
|
+
|
|
37
|
+
### 1. Zero-Leak Bidirectional Secret Scrubbing (`BidirectionalSecretScrubber`)
|
|
38
|
+
- Intercepts 11+ credential classes (`OPENAI_KEY`, `ANTHROPIC_KEY`, `AWS_ACCESS_KEY`, `GITHUB_PAT`, `STRIPE_KEY`, `SLACK_TOKEN`, `PRIVATE_KEY_PEM`, `JWT_TOKEN`, `DB_CONN_URI`, JSON/YAML secrets, and `.env` assignments) **before** they enter the LLM context window.
|
|
39
|
+
- Replaces raw secrets on the wire with deterministic placeholders (`<MCP_REDACTED_OPENAI_KEY_1>`) backed by an atomic cross-process **SQLite WAL vault**.
|
|
40
|
+
- Even if Process 1 (`filesystem` MCP or native `Read`) mints a token, Process 2 (`slack` MCP or native `Bash`) immediately blocks any attempt to exfiltrate that placeholder to an unauthorized sink.
|
|
41
|
+
|
|
42
|
+
### 2. Destructive Command, SSRF (`169.254.169.254`) & High-Entropy DNS Exfiltration Firewall
|
|
43
|
+
- **Path & Dotfile Confinement (`CVE-2025-53110` / `CVE-2025-53773` / `CVE-2025-54135`):** Resolves canonical paths (`Path.resolve()`) to block symlink escapes and hard-denies agent writes to `.env`, `.git/hooks/`, `.vscode/settings.json`, `.cursor/mcp.json`, `CLAUDE.md`, and `~/.ssh/`.
|
|
44
|
+
- **Cloud Metadata & Private Network SSRF Guard (`validate_outbound_network_target`):** Deterministically blocks requests to AWS/ECS/GCP/Alibaba/IPv6 cloud metadata (`169.254.169.254`, `169.254.170.2`, `fd00:ec2::254`, `metadata.google.internal`, `100.100.100.200`), loopback (`127.0.0.0/8`, `localhost`, `[::1]`), RFC 1918 private networks, and dangerous non-HTTP schemes (`file://`, `gopher://`, `dict://`, `ftp://`, `ldap://`).
|
|
45
|
+
- **High-Entropy DNS Exfiltration Blocker:** Computes per-label Shannon entropy ($H > 3.9$ bits/char for labels $>28$ chars) and regex signatures to block hex/base64 secret exfiltration over DNS (`<hex32>.attacker.com`).
|
|
46
|
+
|
|
47
|
+
### 3. Lethal-Trifecta Circuit Breaker + MELON Provenance Attribution
|
|
48
|
+
- Tracks monotonic session **Integrity** (`TRUSTED` $\rightarrow$ `ENDORSED` $\rightarrow$ `UNTRUSTED`) and **Confidentiality** (`PUBLIC` $\rightarrow$ `INTERNAL` $\rightarrow$ `CONFIDENTIAL` $\rightarrow$ `SECRET`) across concurrent tool calls using `BEGIN IMMEDIATE` SQLite transactions.
|
|
49
|
+
- **MELON Provenance Attribution:** Extracts URLs, domains, and email addresses from untrusted external inputs (`UNTRUSTED_SOURCE`) and hard-denies any subsequent sink or shell call targeting those untrusted entities (`[PROVENANCE HIJACK BLOCKED]`).
|
|
50
|
+
- **Zero-Fatigue UX:** Distinguishes benign reads (`README.md` + teammate issues stay `ENDORSED`/`PUBLIC`), allows safe workspace-local code edits, and supports **5-minute scoped workspace edit leases** (`LEASE_MUTATOR_5M`) while keeping external egress locked.
|
|
51
|
+
|
|
52
|
+
### 4. `CurXecute` Config Linter (`audit-config`) & `MCPTox` Schema Lockfile Verification
|
|
53
|
+
- **On-the-Wire Tool Sanitization & Rug-Pull Detection (`SchemaLockVerifier`):** Strips `<IMPORTANT>`, `<system>`, HTML comments, and cross-server shadowing directives from `tools/list` descriptions prior to SHA-256 pinning in `mcp-lock.json`.
|
|
54
|
+
- **Workspace Config Auditor (`mcp-cage audit-config`):** Scans `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, and `claude_desktop_config.json` for `CurXecute` relative-path RCE (`./`, `../`, `/tmp/`, `bash -c`, command chaining), hardcoded plaintext API keys in `env` blocks, and unwrapped MCP servers.
|
|
55
|
+
|
|
56
|
+
### 5. Zero-Config Empirical Wire-Level Parameter Guards (`v0.3.0`)
|
|
57
|
+
Automatically enforced out of the box by `MCPCageEngine` (`MCPWireGateway`), `DynamicProfileAwareProxy`, and Plane B hooks:
|
|
58
|
+
- **Runtime Endpoint & Session Re-pointing Guard (`endpoint_repoint_guard`):** Blocks runtime connection-mutation tools (`connect_to_*`, `switch_server`, `set_endpoint`, `configure_connection`) unless explicitly opted in, and blocks mid-session `*_url` + `*_token`/`*_key` repointing to `local`, `localhost`, `127.0.0.1`, `169.254.169.254`, RFC1918, or untrusted hosts as well as raw bearer tokens in LLM context (`GHSA-rvjm-7hvp-f868`).
|
|
59
|
+
- **Embedded POSIX Command Substitution Guard (`path_command_substitution_guard` + `make_workspace_path_guard`):** Inspects `folderPath`, `filePath`, `source_dir`, `app_dir`, `working_directory`, `download_directory`, `destination`, and `path` for `$(...)`, `` `...` ``, and `${...}` even when disguised inside a valid relative workspace path segment (`CWE-78`).
|
|
60
|
+
- **REST URL Path-Segment Traversal Guard (`url_path_segment_guard`):** Blocks `..`, `%2e%2e`, `/`, `%2f`, `\`, `?`, and `#` (including URL-decoded/double-encoded forms) across `*_id`, `*Id`, `*Name`, `scriptName`, `job_id`, `session_id`, `rag_id`, `bucket`, and `repo` before REST URL interpolation (`CWE-22`).
|
|
61
|
+
- **CLI Positional-Argument Flag Injection Guard (`cli_flag_injection_guard`):** Blocks leading `-` / `--` flags (`--upload-pack=`, `--template=`, `--kubeconfig=`, `--token=`, `--output=`) injected into positional resource, directory, or target arguments (`CWE-88`).
|
|
62
|
+
- **Multi-Statement & Clause-Level SQL AST Guard (`sql_safety_guard`):** Strips `--` and `/* ... */` comments (both space-joined and compact to defeat token splitting), detects stacked `;` queries, and enforces SQLi checks across `where_clause`, `order_by`, `filter`, `having`, `sort_by`, and `group_by` (`A4.3` / `A8.1`).
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Empirical Co-Design Evolution (`v0.1.0` → `v0.2.2` → `v0.3.0`)
|
|
67
|
+
|
|
68
|
+
Each `mcp-cage` release translates real-world vulnerability classes uncovered across audited public and Big-Tech MCP servers into general-purpose, zero-config architectural capabilities:
|
|
69
|
+
|
|
70
|
+
| Release | Architectural Milestone | Real-World Audited MCP Servers / Incidents Addressed | Generalized Guard Plane |
|
|
71
|
+
| :--- | :--- | :--- | :--- |
|
|
72
|
+
| **`v0.1.0`** | Dual-Lattice IFC & Wire Prototype | Invariant Labs GitHub MCP Exploit, `MCPTox`, Microsoft Spotlighting, `MELON` | `SessionTaintStateMachine`, `SchemaLockVerifier` (`mcp-lock.json`), randomized datamarking boundaries, `ToxicFlowGraphAnalyzer` (`mcp-sploit`). |
|
|
73
|
+
| **`v0.2.2`** | Cross-Process WAL & Dual-Plane Firewall | `CVE-2025-53110`, `CVE-2025-53773` (Copilot YOLO), `CVE-2025-54135` (`CurXecute`), AWS IMDSv1 SSRF, DNS exfiltration | Shared SQLite WAL `BidirectionalSecretScrubber`, `BEGIN IMMEDIATE` atomic taint, `validate_outbound_network_target` (IMDS/RFC1918/Shannon DNS), `WorkspaceMCPConfigAuditor`, Plane A + Plane B hooks. |
|
|
74
|
+
| **`v0.3.0`** | Empirical Zero-Config Wire Guards | `datalayer/jupyter-mcp-server` (`GHSA-rvjm-7hvp-f868`), Cloud Container Deployment MCP Servers (`CWE-78`), Edge & API Gateway MCP Servers (`CWE-22` REST path-segment traversal), Kubernetes & Infrastructure CLI MCP Servers (`CWE-88` positional flag injection), Enterprise Data Warehouse & Relational SQL MCP Servers (`CWE-89` comment-split & clause injection) | `endpoint_repoint_guard`, `path_command_substitution_guard` + hardened `make_workspace_path_guard`, `url_path_segment_guard`, `cli_flag_injection_guard`, comment-stripping & clause-level `sql_safety_guard`. |
|
|
75
|
+
| **`v0.4.0`** | Wire-DIFC, 4-Slot Canonicalizer, Line-Span WAL & Kernel Sandbox Compiler | Day-0 Non-Collision Tool-Provider Misbinding, Cross-Session Stored XPIA (`CLAUDE.md`), `OverServe` Resource Amplification ($93.88\times$), EFF Diceware Covert Identifiers, Missing OS Kernel Containment | `WireDIFCCanonicalizer` (`S_poison >= 0.45` + 4-Slot Canonicalizer), `PersistentLineSpanProvenance` (`persistent_span_taint`), `DestinationBoundFPEVault`, `CausalStateProgressGovernor`, `SchemaToKernelSandboxCompiler` (`mcp-cage compile-sandbox` Seatbelt SBPL / Landlock), `mcp-cage bench`. |
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Quick Start (Zero Dependencies)
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
git clone https://github.com/nagarajulu/mcp-cage.git
|
|
83
|
+
cd mcp-cage
|
|
84
|
+
pip install -e .
|
|
85
|
+
|
|
86
|
+
# 1. Run the Unified 6-Suite Non-Regression & 9-Plane E2E Verification Runner
|
|
87
|
+
python3 run_all_regression_suites.py
|
|
88
|
+
|
|
89
|
+
# 2. Compile an OS Kernel Seatbelt SBPL (macOS) or Landlock/bwrap (Linux) Sandbox Profile
|
|
90
|
+
mcp-cage compile-sandbox --workspace . --os auto
|
|
91
|
+
|
|
92
|
+
# 3. Audit workspace MCP configs for CurXecute RCE & hardcoded secrets
|
|
93
|
+
mcp-cage audit-config
|
|
94
|
+
|
|
95
|
+
# 4. Run static Toxic-Flow Graph Analysis (mcp-sploit)
|
|
96
|
+
mcp-sploit audit
|
|
97
|
+
|
|
98
|
+
# 5. Day-1 Zero-Friction Onboarding: Start in '--mode shadow' (logs alerts to .mcp-cage/audit.jsonl without blocking)
|
|
99
|
+
# then switch to '--mode enforce' once verified in your workflow:
|
|
100
|
+
mcp-cage wrap --server filesystem --workspace . --mode shadow -- npx -y @modelcontextprotocol/server-filesystem .
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Universal Dual-Plane Integration Guide
|
|
106
|
+
|
|
107
|
+
`mcp-cage` unifies **Plane A (`mcp-cage wrap`)** and **Plane B (`mcp-cage hook`)** against a single shared SQLite WAL database (`.mcp-cage/taint.db`).
|
|
108
|
+
|
|
109
|
+
### 1. Claude Code (`.claude/settings.json` + `.mcp.json`)
|
|
110
|
+
|
|
111
|
+
Add Plane B hooks to `.claude/settings.json`:
|
|
112
|
+
```json
|
|
113
|
+
{
|
|
114
|
+
"hooks": {
|
|
115
|
+
"UserPromptSubmit": [
|
|
116
|
+
{
|
|
117
|
+
"hooks": [{ "type": "command", "command": "mcp-cage hook claude UserPromptSubmit --db .mcp-cage/taint.db" }]
|
|
118
|
+
}
|
|
119
|
+
],
|
|
120
|
+
"PreToolUse": [
|
|
121
|
+
{
|
|
122
|
+
"matcher": ".*",
|
|
123
|
+
"hooks": [{ "type": "command", "command": "mcp-cage hook claude PreToolUse --db .mcp-cage/taint.db" }]
|
|
124
|
+
}
|
|
125
|
+
],
|
|
126
|
+
"PostToolUse": [
|
|
127
|
+
{
|
|
128
|
+
"matcher": ".*",
|
|
129
|
+
"hooks": [{ "type": "command", "command": "mcp-cage hook claude PostToolUse --db .mcp-cage/taint.db" }]
|
|
130
|
+
}
|
|
131
|
+
]
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### 2. Cursor (`.cursor/hooks.json` + `.cursor/mcp.json`)
|
|
137
|
+
|
|
138
|
+
Add Plane B hooks to `.cursor/hooks.json`:
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"version": 1,
|
|
142
|
+
"hooks": {
|
|
143
|
+
"beforeReadFile": [{ "command": "mcp-cage hook cursor beforeReadFile --db .mcp-cage/taint.db" }],
|
|
144
|
+
"beforeShellExecution": [{ "command": "mcp-cage hook cursor beforeShellExecution --db .mcp-cage/taint.db" }],
|
|
145
|
+
"beforeMCPExecution": [{ "command": "mcp-cage hook cursor beforeMCPExecution --db .mcp-cage/taint.db" }],
|
|
146
|
+
"afterMCPExecution": [{ "command": "mcp-cage hook cursor afterMCPExecution --db .mcp-cage/taint.db" }]
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### 3. Google Gemini CLI (`.gemini/settings.json`)
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"hooks": {
|
|
156
|
+
"SessionStart": [{ "command": "mcp-cage hook gemini SessionStart --db .mcp-cage/taint.db" }],
|
|
157
|
+
"BeforeTool": [{ "command": "mcp-cage hook gemini BeforeTool --db .mcp-cage/taint.db" }],
|
|
158
|
+
"AfterTool": [{ "command": "mcp-cage hook gemini AfterTool --db .mcp-cage/taint.db" }]
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### 4. Google Antigravity CLI (`agy`)
|
|
164
|
+
|
|
165
|
+
Register a wrapped MCP server with `agy`:
|
|
166
|
+
```bash
|
|
167
|
+
agy mcp add filesystem-caged -- mcp-cage wrap \
|
|
168
|
+
--server filesystem \
|
|
169
|
+
--workspace . \
|
|
170
|
+
--state-dir .mcp-cage \
|
|
171
|
+
-- npx -y @modelcontextprotocol/server-filesystem .
|
|
172
|
+
```
|
|
173
|
+
And configure `PreToolUse` / `PostToolUse` hooks using `mcp-cage hook agy PreToolUse --db .mcp-cage/taint.db`.
|
|
174
|
+
|
|
175
|
+
### 5. OpenAI Codex CLI (`~/.codex/hooks.json`)
|
|
176
|
+
|
|
177
|
+
```json
|
|
178
|
+
{
|
|
179
|
+
"hooks": {
|
|
180
|
+
"UserPromptSubmit": [{ "command": "mcp-cage hook codex UserPromptSubmit --db .mcp-cage/taint.db" }],
|
|
181
|
+
"PreToolUse": [{ "command": "mcp-cage hook codex PreToolUse --db .mcp-cage/taint.db" }],
|
|
182
|
+
"PostToolUse": [{ "command": "mcp-cage hook codex PostToolUse --db .mcp-cage/taint.db" }]
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### 6. Claude Desktop / Any `stdio` MCP Host (`claude_desktop_config.json`)
|
|
188
|
+
|
|
189
|
+
Wrap any upstream MCP server with `mcp-cage wrap`:
|
|
190
|
+
```json
|
|
191
|
+
{
|
|
192
|
+
"mcpServers": {
|
|
193
|
+
"filesystem-caged": {
|
|
194
|
+
"command": "mcp-cage",
|
|
195
|
+
"args": [
|
|
196
|
+
"wrap",
|
|
197
|
+
"--server", "filesystem",
|
|
198
|
+
"--workspace", "/Users/you/workspace",
|
|
199
|
+
"--state-dir", "/Users/you/workspace/.mcp-cage",
|
|
200
|
+
"--",
|
|
201
|
+
"npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/you/workspace"
|
|
202
|
+
]
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Research Foundations & Academic Lineage
|
|
211
|
+
|
|
212
|
+
`mcp-cage` translates foundational Operating Systems & Agentic Information-Flow Control (IFC) research into a zero-dependency runtime firewall:
|
|
213
|
+
|
|
214
|
+
| Research System / Paper | Reference | Core Concept Adapted in `mcp-cage` |
|
|
215
|
+
| :--- | :--- | :--- |
|
|
216
|
+
| **CaMeL** *(Debenedetti et al., Google DeepMind, 2025)* | [`arXiv:2503.18813`](https://arxiv.org/abs/2503.18813) | Separating data capabilities & provenance from untrusted control flow in LLM tool invocations. |
|
|
217
|
+
| **FIDES** *(Costa et al., Microsoft Research, 2025)* | [`arXiv:2505.23643`](https://arxiv.org/abs/2505.23643) | Dual-lattice Information-Flow Control (Integrity $\times$ Confidentiality labels) with deterministic sink gates. |
|
|
218
|
+
| **Progent** *(Shi et al., UC Berkeley, 2025)* | [`arXiv:2504.11703`](https://arxiv.org/abs/2504.11703) | Programmable privilege control & deterministic argument guards (`StandardArgGuards`) over tool parameters. |
|
|
219
|
+
| **MELON** *(Zhu et al., 2025)* | [`arXiv:2502.05174`](https://arxiv.org/abs/2502.05174) | Provenance attribution blocking target arguments (URLs, domains, emails) extracted from untrusted tool outputs. |
|
|
220
|
+
| **Spotlighting** *(Hines et al., Microsoft, 2024)* | [`arXiv:2403.14720`](https://arxiv.org/abs/2403.14720) | Cryptographically randomized datamarking boundaries (`<<<UNTRUSTED_DATA_BOUNDARY id=...>>>`) with anti-spoofing. |
|
|
221
|
+
| **MCPTox** *(Wang et al., 2025)* | [`arXiv:2508.14925`](https://arxiv.org/abs/2508.14925) | Structural sanitization of poisoned MCP tool descriptions and cross-server shadowing detection (`SchemaLockVerifier`). |
|
|
222
|
+
| **FLOWSEAL** *(Aerakoni, 2026)* | `arXiv:2609.14003` | Cross-process SQLite WAL ambient taint state machine & bidirectional secret vault across Plane A + Plane B. |
|
|
223
|
+
| **HiStar / Flume / Capsicum** *(Zeldovich et al., Krohn et al., Watson et al.)* | *OSDI '06 / SOSP '07 / USENIX '10* | Decentralized IFC labels, explicit human declassification leases, and OS-level capability confinement. |
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Repository Structure
|
|
228
|
+
|
|
229
|
+
| File | Description |
|
|
230
|
+
| :--- | :--- |
|
|
231
|
+
| [`mcp_cage_core.py`](mcp_cage_core.py) | Unified core engine: `SessionTaintStateMachine`, `BidirectionalSecretScrubber`, `SchemaLockVerifier`, `ToxicFlowGraphAnalyzer`, `WorkspaceMCPConfigAuditor`, SSRF/DNS Exfil Guard, `MCPWireGateway`, and Dual-Plane CLI (`mcp-cage` / `mcp-sploit`). |
|
|
232
|
+
| [`mcp_cage_proxy.py`](mcp_cage_proxy.py) | Full JSON-RPC 2.0 wire proxy (`MCPJsonRpcProxy` & `StdioSubprocessBridge`) covering `tools/list`, `tools/call`, `resources/read`, `prompts/get`, and `sampling/createMessage`. |
|
|
233
|
+
| [`mcp_cage_cli.py`](mcp_cage_cli.py) | Standalone `stdio` process wrapper (`mcp-cage wrap`) with dynamic `tools/list` classification and config generator. |
|
|
234
|
+
| [`demo_interactive.py`](demo_interactive.py) | 5-Act interactive terminal walkthrough demonstrating every defense end-to-end. |
|
|
235
|
+
| [`test_mcp_cage_v30_empirical_guards.py`](test_mcp_cage_v30_empirical_guards.py) | v0.3.0 empirical guard regression suite covering Jupyter runtime hijack, Cloud Run `app$(...)`, Cloudflare path traversal, GKE/K8s CLI flag injection, Snowflake/MySQL SQLi, and sub-millisecond latency. |
|
|
236
|
+
| [`test_mcp_cage_v21.py`](test_mcp_cage_v21.py) | Comprehensive V2.2 unit & integration test suite (10 test suites including SSRF/DNS exfil & `CurXecute` config auditing). |
|
|
237
|
+
| [`test_e2e_all_8_planes.py`](test_e2e_all_8_planes.py) | 8-Plane End-to-End security test suite (17 tests across cognitive, protocol, trifecta, parameter, memory, and subprocess planes). |
|
|
238
|
+
| [`CHANGELOG.md`](CHANGELOG.md) | Empirical Co-Design release lineage (`v0.1.0` → `v0.2.2` → `v0.3.0`). |
|
|
239
|
+
| [`docs/index.html`](docs/index.html) / [`visualizer.html`](visualizer.html) | Interactive browser-based showcase: 5 Integration Modes, 8-Plane Security Matrix, V1 vs. v0.3.0 Exploit Simulator, Config Generator & 1966–2026 Research Lineage ([live on GitHub Pages](https://nagarajulu.github.io/mcp-cage/)). |
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## License
|
|
244
|
+
|
|
245
|
+
Released under the [MIT License](LICENSE). Copyright (c) 2026 [Nagarajulu Aerakoni](https://github.com/nagarajulu).
|