Add wiki page: Campaigns

Campaigns.md

@@ -0,0 +1,158 @@
+# Campaigns
+
+Campaigns group related tests under a common objective — for example, simulating a
+specific threat actor, testing a specific tactic, or running a quarterly purple team exercise.
+
+---
+
+## Campaign Types
+
+| Type | Description |
+|------|-------------|
+| `purple_team` | Collaborative red+blue exercise. Tests are executed with blue team full knowledge. |
+| `red_team` | Blind offensive assessment. Blue team may not know which techniques will be tested. |
+| `blue_team` | Detection-focused exercise. Blue team validates detection capabilities against known TTPs. |
+| `tabletop` | Scenario walkthrough. No live execution — tests are planned and reviewed conceptually. |
+
+---
+
+## Campaign Lifecycle
+
+```
+draft ──────────────> active ──────────────> completed
+  │                     │                       │
+  │  POST /activate      │  POST /complete        │
+  │  (leads, admin)      │  (red_lead, admin)     │
+  │                      │                       │
+  └── at least one       └── execution           └── final state
+      test required           in progress             (immutable)
+```
+
+### Draft
+
+- Campaign is being planned
+- Tests can be added and removed
+- Metadata (name, type, objective, schedule) can be edited
+
+**Create a campaign:**
+```http
+POST /api/v1/campaigns
+Content-Type: application/json
+
+{
+  "name": "Q1 2024 Purple Team — APT29 Simulation",
+  "description": "Full simulation of APT29 TTPs against corp environment",
+  "campaign_type": "purple_team",
+  "objective": "Measure detection coverage against Cozy Bear TTPs"
+}
+```
+
+**Add tests:**
+```http
+POST /api/v1/campaigns/{id}/tests
+{"test_id": "test-uuid"}
+```
+
+**Set schedule:**
+```http
+PATCH /api/v1/campaigns/{id}/schedule
+{"start_date": "2024-03-01T09:00:00Z", "end_date": "2024-03-15T18:00:00Z"}
+```
+
+### Active
+
+- Triggered by POST /campaigns/{id}/activate (requires at least one linked test)
+- Tests within the campaign are executed following the normal [Test-Lifecycle](Test-Lifecycle)
+- Campaign-level progress is tracked in real time
+
+**Activate:**
+```http
+POST /api/v1/campaigns/{id}/activate
+```
+
+### Completed
+
+- Only red_lead or admin can complete a campaign
+- All remaining tests are frozen in their current state
+- Report generation becomes available for the full campaign
+
+**Complete:**
+```http
+POST /api/v1/campaigns/{id}/complete
+{"completion_notes": "All priority techniques tested. 72% detection rate."}
+```
+
+---
+
+## Creating a Campaign from a Threat Actor
+
+Aegis maintains a database of known threat actor profiles with associated MITRE techniques.
+You can instantly scaffold a campaign for a threat actor:
+
+```http
+POST /api/v1/campaigns/from-threat-actor/{actor_id}
+Content-Type: application/json
+
+{
+  "campaign_name": "APT29 Full Simulation",
+  "campaign_type": "purple_team",
+  "include_sub_techniques": true
+}
+```
+
+This automatically:
+1. Creates a new campaign
+2. Creates one test draft per technique linked to the threat actor
+3. Returns the campaign with all tests pre-populated
+
+---
+
+## Progress Tracking
+
+```http
+GET /api/v1/campaigns/{id}/progress
+```
+
+Returns:
+```json
+{
+  "campaign_id": "uuid",
+  "total_tests": 24,
+  "validated": 18,
+  "in_progress": 4,
+  "not_started": 2,
+  "detection_rate": 0.72,
+  "progress_percent": 75.0
+}
+```
+
+---
+
+## Campaign History
+
+Every state change in a campaign is logged:
+```http
+GET /api/v1/campaigns/{id}/history
+```
+
+Returns list of:
+```json
+{
+  "timestamp": "2024-03-01T09:15:00Z",
+  "from_state": "draft",
+  "to_state": "active",
+  "actor": "red_lead_user",
+  "notes": null
+}
+```
+
+---
+
+## Reports for Campaigns
+
+Once a campaign is active or completed, a professional report can be generated:
+```http
+GET /api/v1/reports/generate/purple-campaign/{id}?format=pdf
+```
+
+See [Executive-Dashboard-and-Reports](Executive-Dashboard-and-Reports) for all report options.