CALDERA MCP Server

A Model Context Protocol (MCP) server for integrating with the MITRE CALDERA adversary emulation platform. This server provides STRICTLY READ-ONLY access to CALDERA's API for querying operations, agents, abilities, and collected intelligence.

Overview

CALDERA is an automated adversary emulation platform developed by MITRE that executes post-compromise adversarial techniques mapped to the MITRE ATT&CK framework. This MCP server allows AI assistants to query CALDERA data without the ability to create operations, task agents, or execute abilities.

Security Model

READ-ONLY ONLY: This server is intentionally restricted to prevent any modifications:

• Only HTTP GET requests are allowed
• No operation creation or modification
• No agent tasking or command execution
• No ability execution
• No fact source manipulation
• Requires HTTPS or localhost connections only

Prerequisites

1. CALDERA Instance: A running CALDERA server (v4.0+)
2. API Key: CALDERA API key with read permissions
3. Network Access: Network connectivity to CALDERA API endpoint

Installation

cd /Users/ehenry/Documents/code/mcp-servers/caldera
bun install

Configuration

Set the following environment variables:

export CALDERA_API_URL="https://your-caldera-instance.com"
export CALDERA_API_KEY="your-api-key-here"

Security Requirements

• CALDERA_API_URL must use HTTPS OR be localhost (http://localhost, http://127.0.0.1)
• Both environment variables are required
• The API key should have read-only permissions (recommended)

Usage

Running the Server

bun run start

MCP Client Configuration

Add to your MCP settings file (e.g., Claude Desktop config):

{
  "mcpServers": {
    "caldera": {
      "command": "bun",
      "args": ["run", "/Users/ehenry/Documents/code/mcp-servers/caldera/src/index.ts"],
      "env": {
        "CALDERA_API_URL": "https://your-caldera-instance.com",
        "CALDERA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

1. caldera_abilities_list

List CALDERA abilities (adversary techniques/procedures). Abilities are atomic actions mapped to MITRE ATT&CK techniques.

Parameters:

• tactic (optional): MITRE ATT&CK tactic filter (e.g., "discovery", "execution", "privilege-escalation")
• technique_id (optional): MITRE ATT&CK technique ID (e.g., "T1059", "T1003.001")
• platform (optional): OS platform filter ("windows", "linux", "darwin")
• limit (optional): Max results (1-200, default: 50)

Returns:

{
  "abilities": [
    {
      "ability_id": "uuid",
      "name": "Ability Name",
      "description": "What this ability does",
      "tactic": "discovery",
      "technique_id": "T1082",
      "technique_name": "System Information Discovery",
      "platforms": {"windows": {...}},
      "executors": [...]
    }
  ],
  "total": 150
}

2. caldera_adversary_list

List CALDERA adversary profiles. Adversaries are collections of abilities executed in order to simulate threat actors.

Parameters:

• limit (optional): Max results (1-200, default: 50)

Returns:

{
  "adversaries": [
    {
      "adversary_id": "uuid",
      "name": "Adversary Name",
      "description": "Simulates X threat actor",
      "atomic_ordering": ["ability-id-1", "ability-id-2"],
      "objective": "objective-id"
    }
  ],
  "total": 25
}

3. caldera_operation_list

List CALDERA operations. Operations are instances of adversary emulation campaigns.

Parameters:

• state (optional): Operation state filter ("running", "finished", "paused", "cleanup", "out_of_time")
• limit (optional): Max results (1-200, default: 50)

Returns:

{
  "operations": [
    {
      "id": "uuid",
      "name": "Operation Name",
      "state": "finished",
      "adversary": {...},
      "group": "red-team",
      "start": "2025-01-15T10:00:00Z",
      "finish": "2025-01-15T12:30:00Z",
      "host_group": [...]
    }
  ],
  "total": 42
}

4. caldera_operation_report

Get detailed execution report for a specific operation. Essential for post-operation analysis.

Parameters:

• operation_id (required): Operation UUID

Returns:

{
  "operation_id": "uuid",
  "name": "Operation Name",
  "adversary": {...},
  "start": "2025-01-15T10:00:00Z",
  "finish": "2025-01-15T12:30:00Z",
  "steps": [
    {
      "ability_id": "uuid",
      "ability_name": "Discover Domain Users",
      "status": "success",
      "agent": "agent-paw",
      "command_preview": "net user /domain",
      "output_preview": "List of domain users...",
      "attack_metadata": {
        "technique_id": "T1087.002",
        "tactic": "discovery"
      }
    }
  ],
  "host_group": [...],
  "facts_collected": [...]
}

5. caldera_agent_list

List CALDERA agents (deployed endpoints under test). Agents execute abilities on target systems.

Parameters:

• platform (optional): OS platform filter ("windows", "linux", "darwin")
• group (optional): Agent group name filter
• limit (optional): Max results (1-200, default: 50)

Returns:

{
  "agents": [
    {
      "paw": "agent-unique-id",
      "host": "hostname",
      "platform": "windows",
      "username": "DOMAIN\\user",
      "group": "red-team",
      "privilege": "Elevated",
      "last_seen": "2025-02-09T14:30:00Z",
      "executors": ["cmd", "psh", "pwsh"],
      "contact": "HTTP"
    }
  ],
  "total": 15
}

6. caldera_fact_list

List facts collected during operations. Facts are intelligence gathered by abilities (usernames, IPs, file paths, etc.).

Parameters:

• source_id (optional): Fact source UUID
• trait (optional): Fact trait name filter (e.g., "host.ip.address", "domain.user.name")
• limit (optional): Max results (1-200, default: 50)

Returns:

{
  "facts": [
    {
      "trait": "domain.user.name",
      "value": "DOMAIN\\Administrator",
      "score": 10,
      "technique_id": "T1087.002",
      "collected_by": "operation-id"
    }
  ],
  "total": 87
}

7. caldera_source_list

List CALDERA fact sources. Sources are repositories of facts for seeding operations or storing intelligence.

Parameters:

• limit (optional): Max results (1-200, default: 50)

Returns:

{
  "sources": [
    {
      "id": "uuid",
      "name": "Source Name",
      "facts_count": 45,
      "adjustments": [],
      "rules": []
    }
  ],
  "total": 12
}

Common Use Cases

Analyze Recent Operations

Use caldera_operation_list with state="finished" to see completed operations,
then caldera_operation_report for detailed analysis of specific operations.

Find Abilities by Technique

Use caldera_abilities_list with technique_id="T1003" to find credential dumping abilities,
or tactic="privilege-escalation" for all privilege escalation techniques.

Monitor Agent Status

Use caldera_agent_list to see all deployed agents, filter by platform or group
to check specific environments.

Review Collected Intelligence

Use caldera_fact_list to examine facts collected during operations,
filter by trait to find specific types of intelligence (e.g., credentials, network info).

Architecture

caldera/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── security.ts           # API authentication & read-only enforcement
│   ├── schemas.ts            # Zod validation schemas
│   └── tools/
│       ├── caldera-abilities-list.ts
│       ├── caldera-adversary-list.ts
│       ├── caldera-operation-list.ts
│       ├── caldera-operation-report.ts
│       ├── caldera-agent-list.ts
│       ├── caldera-fact-list.ts
│       └── caldera-source-list.ts
├── package.json
├── tsconfig.json
└── README.md

Security Considerations

1. Read-Only Design: All tools use HTTP GET only, no modifications possible
2. HTTPS Required: Production deployments must use HTTPS (localhost exempt)
3. API Key Protection: Store API key securely, use environment variables
4. Network Security: Ensure CALDERA instance is properly firewalled
5. Audit Logging: CALDERA logs all API access on the server side

Error Handling

The server provides detailed error messages for:

• Missing environment variables
• Invalid HTTPS/localhost configuration
• API authentication failures
• Invalid UUID formats
• Network connectivity issues
• CALDERA API errors

Limitations

• Read-Only: Cannot create, modify, or delete any CALDERA resources
• No Execution: Cannot start operations or task agents
• Result Limits: Maximum 200 results per query (configurable)
• API Version: Requires CALDERA v4.0+ API

Development

Building

bun run build

Testing Connection

# Set environment variables
export CALDERA_API_URL="https://your-caldera-instance.com"
export CALDERA_API_KEY="your-key"

# Run server
bun run start

Resources

• CALDERA Documentation
• MITRE ATT&CK Framework
• Model Context Protocol

License

This MCP server is provided as-is for integration with MITRE CALDERA.

Support

For CALDERA-specific issues, consult the CALDERA documentation. For MCP server issues, check the source code and error messages.