# 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](https://modelcontextprotocol.io/) (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**

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

**2. Configure**

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

**3. Run tests**

```bash
uv run pytest tests/ -v
```

**4. Add to Claude Code**

```bash
# 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`:

```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](LICENSE) for details.

---

## Contact

**Scott Thornton** — AI Security Researcher

- Website: [perfecxion.ai](https://perfecxion.ai/)
- Email: [scott@perfecxion.ai](mailto:scott@perfecxion.ai)
- LinkedIn: [linkedin.com/in/scthornton](https://www.linkedin.com/in/scthornton)
- ORCID: [0009-0008-0491-0032](https://orcid.org/0009-0008-0491-0032)
- GitHub: [@scthornton](https://github.com/scthornton)

**Security Issues**: Please report via [SECURITY.md](SECURITY.md)