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

# API Reference — Conducting Purple Team Exercises

## Exercise Management

### Scoring Framework

| Score | Label | Criteria |
|---|---|---|
| 3 | Full detection | Alert fired, analyst notified, technique identified |
| 2 | Telemetry only | Events logged but no detection rule triggered |
| 1 | Partial | Related alert fired but not technique-specific |
| 0 | Missed | No telemetry or detection |

### Communication Protocol

| Tag | Sender | Content |
|---|---|---|
| `[RED]` | Red team | Technique ID, target host, execution timestamp |
| `[BLUE]` | Blue team | Detection status, alert time, rule ID |
| `[PURPLE]` | Exercise lead | Phase transitions, gap findings, action items |

### Exercise Metrics

| Metric | Formula |
|---|---|
| Detection rate | `detected / total × 100` |
| MTTD | `avg(alert_time - exec_time)` for detected techniques |
| Coverage delta | `post_coverage - pre_coverage` techniques |
| Gap closure rate | `gaps_closed / total_gaps × 100` |

## Agent Script

```bash
# Plan exercise
node agent.js plan-exercise --threat-actor APT29 \
  --scope initial-access,execution,credential-access --duration 3 --output plan.json

# Execute technique in round
node agent.js execute-round --plan plan.json --round 1 \
  --technique T1003.001 --target-host HOST-01 --exec-time 2026-03-15T14:30:00Z

# Record blue team response
node agent.js record-response --plan plan.json --round 1 \
  --technique T1003.001 --detected true --alert-time 2026-03-15T14:30:42Z \
  --rule-id sigma-cred-001 --score 3

# Generate report
node agent.js generate-report --plan plan.json --output report.json
```
