SecMCP

MCP servers exposing security operations tools (VirusTotal, MITRE Caldera, LimaCharlie) to AI agents with defense-in-depth safety controls. Built for SANS SEC598 by Scott Thornton.

3 servers, 20 tools, 7 resources, 153 tests. All write/destructive operations are disabled by default with fail-closed safety controls.

<p align="center"> <img src="docs/images/secmcp-demo.png" alt="SecMCP terminal demo" width="700"> </p>

Background

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. SecMCP fills a gap in the AI security tooling ecosystem: no published MCP servers wrap common security operations platforms with production-grade safety controls.

Each server wraps a security platform's REST API and exposes it as MCP tools with:

• Input validation on all parameters (hashes, IPs, UUIDs, technique IDs)
• Audit logging with automatic sensitive value redaction
• MCP ToolAnnotations declaring each tool's read/write/destructive nature
• Per-tool enable flags and dry-run mode for write/destructive operations

Repository Layout

secmcp/
├── packages/
│   ├── secmcp-shared/              # Thin shared library (config, errors, audit)
│   ├── secmcp-virustotal/          # 6 tools — threat intelligence lookups + file submission
│   ├── secmcp-caldera/             # 7 tools — adversary emulation with 6-layer safety
│   └── secmcp-limacharlie/         # 7 tools — EDR sensors, D&R rules, YARA scanning
├── tests/                          # 153 tests across all packages + MCP protocol compliance
├── docs/
│   ├── architecture.md             # System design and principles
│   ├── security-guide.md           # Threat model and safety controls
│   └── servers/                    # Per-server tool reference
├── .github/workflows/ci.yml       # GitHub Actions: lint, format, test
├── .env.example                    # All config vars with safe defaults
└── pyproject.toml                  # uv workspace root

Servers

Server	Platform	Tools	Safety Controls
secmcp-virustotal	VirusTotal API v3	6 (5 read, 1 write)	Rate limiter (4 req/min free tier)
secmcp-caldera	MITRE Caldera	7 (5 read, 1 write, 1 destructive)	Per-tool flags, group allowlist, dry-run, audit
secmcp-limacharlie	LimaCharlie EDR	7 (4 read, 2 write, 1 destructive)	Per-tool flags, dry-run, JWT auth

Quick Start

1. Clone and install

git clone https://github.com/scthornton/secmcp.git
cd secmcp
uv sync --all-packages

2. Configure

cp .env.example .env
# Edit .env with your API keys

3. Run tests

uv run pytest tests/ -v

4. Add to Claude Code

# VirusTotal server
export SECMCP_VT_VT_API_KEY="your-key"
claude mcp add virustotal -- uv run python -m secmcp_virustotal

# Caldera server (safe defaults: dry-run on, all write tools disabled)
export SECMCP_CALDERA_CALDERA_API_KEY="your-key"
claude mcp add caldera -- uv run python -m secmcp_caldera

# LimaCharlie server (safe defaults: dry-run on, all write tools disabled)
export SECMCP_LC_LC_OID="your-org-id"
export SECMCP_LC_LC_API_KEY="your-key"
claude mcp add limacharlie -- uv run python -m secmcp_limacharlie

5. Add to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "secmcp-virustotal": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/secmcp", "python", "-m", "secmcp_virustotal"],
      "env": {
        "SECMCP_VT_VT_API_KEY": "your-key"
      }
    },
    "secmcp-caldera": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/secmcp", "python", "-m", "secmcp_caldera"],
      "env": {
        "SECMCP_CALDERA_CALDERA_URL": "http://localhost:8888",
        "SECMCP_CALDERA_CALDERA_API_KEY": "your-key",
        "SECMCP_CALDERA_DRY_RUN": "true",
        "SECMCP_CALDERA_ENABLE_CREATE_OPERATION": "false",
        "SECMCP_CALDERA_ENABLE_EXECUTE_ABILITY": "false",
        "SECMCP_CALDERA_ALLOWED_GROUPS_STR": ""
      }
    },
    "secmcp-limacharlie": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/secmcp", "python", "-m", "secmcp_limacharlie"],
      "env": {
        "SECMCP_LC_LC_OID": "your-org-id",
        "SECMCP_LC_LC_API_KEY": "your-key",
        "SECMCP_LC_DRY_RUN": "true",
        "SECMCP_LC_ENABLE_DEPLOY_RULE": "false",
        "SECMCP_LC_ENABLE_DELETE_RULE": "false",
        "SECMCP_LC_ENABLE_YARA_SCAN": "false"
      }
    }
  }
}

Safety Controls

The Caldera and LimaCharlie servers implement independent, composable safety layers:

Layer	Description	Default
Per-tool enable flags	Each write/destructive tool must be explicitly enabled	Disabled
Group allowlist (Caldera)	Operations can only target listed agent groups	Empty = all blocked
Dry-run mode	Write tools describe what they would do without executing	Enabled
Input validation	UUIDs, paw IDs, technique IDs, group names, rule names validated	Always on
Audit logging	JSON lines with redacted parameters, full output for destructive tools	Always on
MCP ToolAnnotations	destructiveHint=True triggers human confirmation in AI clients	Always on

All safety defaults are fail-closed. An unconfigured server blocks all write operations.

Architecture

AI Host (Claude Code / Claude Desktop / Cursor)
    |
    | MCP Protocol (stdio transport)
    |
    +-- secmcp-virustotal  --> VirusTotal API v3 (HTTPS, API key header)
    +-- secmcp-caldera     --> Caldera REST API (HTTP, KEY header)
    +-- secmcp-limacharlie --> LimaCharlie API (HTTPS, JWT exchange)
    |
    +-- secmcp-shared (config, errors, audit)

Tech Stack

• Python 3.12+ with uv workspaces for monorepo management
• MCP SDK (mcp 1.16+) with FastMCP for high-level tool/resource registration
• httpx for async HTTP clients, Pydantic v2 for models and config
• pytest + respx for async testing with mocked HTTP responses
• ruff for linting and formatting

Important Notes

• stdio transport only (v1) — servers run as child processes of the MCP host. HTTP transport with OAuth 2.1 is planned for v2.
• API keys in environment variables — never committed to the repo. Copy .env.example to .env and fill in your values.
• Rate limiting — VirusTotal free tier allows 4 requests/minute. The server enforces this automatically.
• Caldera must be running locally (default: http://localhost:8888) for the Caldera server to connect.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Run tests (uv run pytest tests/ -v) and lint (uv run ruff check packages/ tests/)
4. Submit a pull request

License

MIT — see LICENSE for details.

---

Contact

Scott Thornton — AI Security Researcher

• Website: perfecxion.ai
• Email: scott@perfecxion.ai
• LinkedIn: linkedin.com/in/scthornton
• ORCID: 0009-0008-0491-0032
• GitHub: @scthornton

Security Issues: Please report via SECURITY.md