Add wiki page: Detection-Lifecycle

Detection-Lifecycle.-.md

@@ -0,0 +1,213 @@
+# Detection Lifecycle
+
+The Detection Lifecycle module provides a structured system for the Blue Team to manage,
+validate, and track the health of detection capabilities mapped to MITRE ATT&CK techniques.
+
+---
+
+## Overview
+
+The detection lifecycle tracks three main concepts:
+
+1. **Detection Assets** — What you use to detect (SIEM rules, EDR policies, sensors)
+2. **Validations** — Proof that an asset correctly detected a technique
+3. **Infrastructure Changes** — Events that may have broken your detections
+
+These three together provide a **confidence score** per technique: how certain are we
+that our detections for technique T still work today?
+
+---
+
+## Detection Assets
+
+A detection asset represents a defensive capability that can detect one or more techniques.
+
+### Asset Types
+
+| Type | Examples |
+|------|---------|
+| `siem_rule` | Splunk SPL query, KQL rule in Sentinel |
+| `edr_policy` | CrowdStrike prevention policy, Defender ATP rule |
+| `sensor` | Network sensor, honeypot, canary token |
+| `ids_rule` | Snort/Suricata rule |
+| `manual_review` | Human review process |
+| `custom` | Any other detection mechanism |
+
+### Creating an Asset
+
+```http
+POST /api/v1/detection-lifecycle/assets
+Content-Type: application/json
+
+{
+  "name": "Splunk: PowerShell AMSI Bypass Detection",
+  "asset_type": "siem_rule",
+  "description": "SPL search for AMSI bypass patterns in Windows PowerShell logs",
+  "owner_id": "blue-lead-uuid",
+  "team": "blue",
+  "platform": "Windows",
+  "rule_content": "index=wineventlog EventCode=4104 ScriptBlockText=*AmsiUtils*"
+}
+```
+
+### Linking to Techniques
+
+```http
+POST /api/v1/detection-lifecycle/assets/{id}/techniques/{technique_id}
+```
+
+One asset can be linked to multiple techniques. One technique can have multiple assets.
+
+---
+
+## Validations
+
+A validation record proves that an asset successfully detected a technique at a
+specific point in time. This is usually created after a successful test.
+
+### Creating a Validation
+
+```http
+POST /api/v1/detection-lifecycle/validations
+Content-Type: application/json
+
+{
+  "asset_id": "asset-uuid",
+  "technique_id": "T1059.001",
+  "test_id": "test-uuid",
+  "validated_at": "2024-03-15T10:30:00Z",
+  "notes": "SIEM alert fired within 47 seconds of execution",
+  "confidence": "high"
+}
+```
+
+### Invalidating a Validation
+
+When a detection rule changes, is disabled, or the infrastructure shifts, you should
+invalidate the previous validation so the confidence score drops:
+
+```http
+POST /api/v1/detection-lifecycle/validations/{id}/invalidate
+{"reason": "SIEM rule rewritten — new version not yet tested"}
+```
+
+### Confidence Levels
+
+| Level | Meaning |
+|-------|---------|
+| `high` | Tested within 30 days, full detection |
+| `medium` | Tested within 90 days OR partial detection |
+| `low` | Tested more than 90 days ago |
+| `unknown` | No validation exists |
+
+---
+
+## Infrastructure Changes
+
+When infrastructure changes occur (SIEM migration, EDR update, log forwarding reconfigured),
+existing validations may no longer be accurate. Recording an infrastructure change
+automatically flags affected assets and adds techniques to the revalidation queue.
+
+### Recording a Change
+
+```http
+POST /api/v1/detection-lifecycle/infrastructure-changes
+Content-Type: application/json
+
+{
+  "name": "Splunk → Microsoft Sentinel Migration",
+  "description": "All SIEM rules migrated from Splunk to KQL in Sentinel",
+  "change_type": "siem_migration",
+  "affected_asset_ids": ["asset-uuid-1", "asset-uuid-2"],
+  "occurred_at": "2024-03-01T00:00:00Z"
+}
+```
+
+**Effect**: All validations linked to affected assets are automatically marked as
+potentially stale. An alert rule of type `detection_gap` may fire.
+
+### Revalidation Queue
+
+After an infrastructure change, use the ownership module to see which techniques
+need re-testing:
+```http
+GET /api/v1/ownership/revalidation-queue
+```
+
+Generate an updated queue:
+```http
+POST /api/v1/ownership/revalidation-queue/generate
+```
+
+---
+
+## Detection Dashboard
+
+```http
+GET /api/v1/detection-lifecycle/dashboard
+```
+
+Returns per-technique detection confidence:
+```json
+[
+  {
+    "technique_id": "T1059.001",
+    "technique_name": "PowerShell",
+    "asset_count": 2,
+    "latest_validation": "2024-03-15T10:30:00Z",
+    "confidence": "high",
+    "days_since_validation": 5,
+    "pending_revalidation": false
+  },
+  {
+    "technique_id": "T1078",
+    "technique_name": "Valid Accounts",
+    "asset_count": 1,
+    "latest_validation": "2023-11-10T08:00:00Z",
+    "confidence": "low",
+    "days_since_validation": 125,
+    "pending_revalidation": true
+  }
+]
+```
+
+---
+
+## Detection Rules
+
+Detection rules are the concrete SIEM/EDR rule definitions linked to Aegis tests.
+They complement detection assets by providing the exact rule logic.
+
+### Creating a Rule
+
+```http
+POST /api/v1/detection-rules
+Content-Type: application/json
+
+{
+  "name": "PowerShell Encoded Command Execution",
+  "technique_ids": ["T1059.001"],
+  "platform": "Windows",
+  "rule_type": "siem",
+  "rule_content": "EventCode=4104 ScriptBlockText=*-EncodedCommand*",
+  "description": "Detects PowerShell execution with base64 encoded commands",
+  "severity": "high",
+  "is_enabled": true
+}
+```
+
+### Evaluating a Rule Against a Test
+
+After running a test, record whether the rule fired:
+```http
+POST /api/v1/detection-rules/evaluate
+{
+  "rule_id": "rule-uuid",
+  "test_id": "test-uuid",
+  "result": "triggered",
+  "time_to_detect_seconds": 23,
+  "notes": "Rule fired on first PowerShell invocation"
+}
+```
+
+`result` options: `triggered`, `not_triggered`, `false_positive`