detonate-mcp

MCP server: run unknown binaries in a maximum-hardening container. The safety profile is enforced server-side and cannot be parameterized away by tool arguments.

What it does

Related MCP server: capsule-agents

Why MCP (and not just bash)

The estate's pentest toolkit runs nmap/sqlmap/etc via shell; those are one-shot CLIs. This server is different because it needs to hold STATE: the allowlisted samples root, the evidence directory chain, the containment profile. An MCP server with typed tools makes that state explicit and testable.

Threat model honesty

The container defends against: network callback, filesystem persistence, privilege escalation, resource exhaustion.

It does NOT defend against: kernel exploits (docker shares the host kernel). For kernel-exploit-grade samples, detonate in a disposable VM.

The tmpfs is the ONE exec-allowed mount; the sample must run, and that is the single deliberate exception to the read-only root.

Architecture

detonate-mcp/
├── src/detonate_mcp/
│   ├── __init__.py
│   ├── core.py         pure: profile constants, RunSpec, argv builder
│   ├── runner.py       DockerRunner: subprocess.run, timeout enforcement
│   ├── server.py       FastMCP tools (thin; delegate to core+runner)
│   ├── jsonc.py        JSONC comment stripping for config parsing
│   ├── config.py       opencode.jsonc declaration probe
│   ├── backend.py      backend resolution probe
│   ├── credential.py   credential entitlement probe
│   ├── handshake.py    MCP initialize handshake probe
│   ├── testing.py      FakeRunner/CtxBuilder test doubles
│   └── util.py         shared helpers (truncate, etc)
├── tests/
└── pyproject.toml

Usage

uv run pytest                    # 18 tests
uv run python -m detonate_mcp.server   # starts the stdio MCP server