npm package: @modular-intelligence/caldera
Description: MCP server for MITRE CALDERA adversary emulation platform API (read-only)
Latest version: 1.0.2

# 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

```bash
cd /path/to/mi-mcp-servers/packages/caldera
bun install
```

## Configuration

Set the following environment variables:

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

```bash
bun run start
```

### MCP Client Configuration

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

```json
{
  "mcpServers": {
    "caldera": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```bash
bun run build
```

### Testing Connection

```bash
# 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](https://caldera.readthedocs.io/)
- [MITRE ATT&CK Framework](https://attack.mitre.org/)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## License

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

## Support

For CALDERA-specific issues, consult the [CALDERA documentation](https://caldera.readthedocs.io/).
For MCP server issues, check the source code and error messages.