MCP 服务器

SecMCP

MCP servers exposing security operations tools (VirusTotal, MITRE Caldera, LimaCharlie) to AI agents with defense-in-depth safety controls.

README

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.

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

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