<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Building Custom Attack Scenarios

## Caldera REST API

### Adversary Management

| Endpoint | Method | Description |
|---|---|---|
| `/api/v2/adversaries` | GET | List all adversary profiles |
| `/api/v2/adversaries` | POST | Create adversary profile |
| `/api/v2/adversaries/{id}` | GET | Get specific adversary |
| `/api/v2/adversaries/{id}` | PATCH | Update adversary |
| `/api/v2/adversaries/{id}` | DELETE | Delete adversary |

### Operation Management

| Endpoint | Method | Description |
|---|---|---|
| `/api/v2/operations` | POST | Start an operation |
| `/api/v2/operations/{id}` | GET | Get operation status |
| `/api/v2/operations/{id}/report` | POST | Generate operation report |

### Request: Create Adversary

```json
{
  "name": "APT29 Credential Theft",
  "description": "Custom scenario emulating APT29",
  "atomic_ordering": ["T1566.001", "T1059.001", "T1053.005"],
  "objective": "credential-harvest"
}
```

### Request: Start Operation

```json
{
  "name": "APT29 Test Run",
  "adversary": {"adversary_id": "custom-apt29-scenario"},
  "planner": {"id": "atomic"},
  "source": {"id": "basic"},
  "auto_close": true,
  "jitter": "2/8"
}
```

## ATT&CK Navigator Layer Schema

| Field | Type | Description |
|---|---|---|
| `name` | string | Layer display name |
| `domain` | string | `enterprise-attack`, `mobile-attack`, `ics-attack` |
| `versions.attack` | string | ATT&CK version |
| `techniques[].techniqueID` | string | Technique ID (e.g. `T1059.001`) |
| `techniques[].color` | string | Hex color for highlighting |
| `techniques[].score` | int | Score 0-100 for gradient coloring |
| `techniques[].comment` | string | Annotation text |

## Agent Script

```bash
# Build scenario from technique list
node agent.js build-scenario --name "APT29 Cred Theft" \
  --techniques T1566.001 T1059.001 T1053.005 T1003.001 \
  --output scenarios/apt29.yaml

# Validate scenario has matching atomics
node agent.js validate-scenario --scenario scenarios/apt29.yaml

# Generate ATT&CK Navigator layer
node agent.js generate-layer --group APT29 \
  --techniques T1566.001 T1059.001 --output layers/apt29.json

# Deploy to Caldera
node agent.js deploy-caldera --scenario scenarios/apt29.yaml \
  --caldera-url http://localhost:8888 --api-key ADMIN123

# Generate detection coverage report
node agent.js coverage-report --scenario scenarios/apt29.yaml \
  --siem-url https://splunk:8089 --timeframe 1h
```
