Add wiki page: Knowledge-Management

Knowledge-Management.-.md

@@ -0,0 +1,180 @@
+# Knowledge Management
+
+Aegis includes a knowledge management module for capturing institutional expertise:
+**Playbooks** (procedural guides) and **Lessons Learned** (post-incident records).
+
+---
+
+## Playbooks
+
+A playbook is a step-by-step procedural guide for a specific MITRE ATT&CK technique.
+Each playbook is scoped to a `playbook_type` and a `technique_id`.
+
+### Playbook Types
+
+| Type | Target audience | Purpose |
+|------|----------------|---------|
+| `attack` | Red team | How to execute this technique |
+| `defense` | Blue team | How to defend against this technique |
+| `detection` | Blue team | How to detect this technique in logs/alerts |
+
+### Playbook Fields
+
+```json
+{
+  "title": "T1059.001 — PowerShell Attack Playbook",
+  "technique_id": "T1059.001",
+  "playbook_type": "attack",
+  "content": "# Overview
+
+This playbook covers...
+
+## Prerequisites
+...",
+  "tools": ["Cobalt Strike", "PowerShell Empire", "Metasploit"],
+  "prerequisites": ["Domain user credentials", "Access to workstation"],
+  "is_active": true
+}
+```
+
+### Versioning
+
+Every time a playbook is updated (PATCH), the system:
+1. Creates a version snapshot with the previous content
+2. Increments the version number
+3. Records the author and timestamp
+
+**List versions:**
+```http
+GET /api/v1/knowledge/playbooks/{id}/versions
+```
+
+**Restore a previous version:**
+```http
+POST /api/v1/knowledge/playbooks/{id}/restore/{version_number}
+```
+
+This creates a new version from the restored content (non-destructive — the history
+is always preserved).
+
+### Creating a Playbook
+
+```http
+POST /api/v1/knowledge/playbooks
+Content-Type: application/json
+
+{
+  "title": "T1078 — Valid Account Detection Playbook",
+  "technique_id": "T1078",
+  "playbook_type": "detection",
+  "content": "## Indicators of Compromise
+
+1. Unusual login times...",
+  "tools": ["Splunk", "Elastic SIEM"],
+  "prerequisites": ["SIEM access", "AD event log forwarding configured"]
+}
+```
+
+### Access Rules
+
+| Action | Required role |
+|--------|--------------|
+| Read any playbook | All roles (including viewer) |
+| Create playbook | red_lead, blue_lead, admin |
+| Update playbook | red_lead, blue_lead, admin |
+| Delete playbook | red_lead, blue_lead, admin |
+| Restore version | red_lead, blue_lead, admin |
+
+---
+
+## Lessons Learned
+
+Lessons Learned records capture what happened during an exercise, the root cause,
+and improvement actions. They can be linked to any entity in the system.
+
+### Lesson Fields
+
+```json
+{
+  "title": "AMSI bypass succeeded due to outdated signatures",
+  "what_happened": "Red team successfully bypassed AMSI on 3 of 5 endpoints...",
+  "root_cause": "AMSI signature database had not been updated in 45 days.",
+  "improvement": "Automate daily AMSI signature updates via WSUS. Set alert for stale updates.",
+  "severity": "high",
+  "tags": ["amsi", "evasion", "detection-gap"],
+  "technique_ids": ["T1562.001"],
+  "entity_type": "test",
+  "entity_id": "test-uuid"
+}
+```
+
+### Severity Levels
+
+| Level | Description |
+|-------|-------------|
+| `low` | Minor finding, low risk |
+| `medium` | Notable gap, moderate risk |
+| `high` | Significant detection failure |
+| `critical` | Systemic failure, immediate action required |
+
+### Entity Linking
+
+Lessons can be linked to any entity:
+
+| `entity_type` | Example `entity_id` |
+|---------------|---------------------|
+| `test` | UUID of the test |
+| `campaign` | UUID of the campaign |
+| `technique` | MITRE technique ID (T1059.001) |
+| `detection_asset` | UUID of the detection asset |
+
+### Access Rules
+
+| Action | Required role |
+|--------|--------------|
+| Read any lesson | All roles (including viewer) |
+| Create lesson | red_lead, blue_lead, admin |
+| Update lesson | red_lead, blue_lead, admin |
+| Delete lesson | red_lead, blue_lead, admin |
+
+---
+
+## Knowledge Stats
+
+```http
+GET /api/v1/knowledge/stats
+```
+
+Returns:
+```json
+{
+  "playbooks": {
+    "total": 87,
+    "by_type": {
+      "attack": 32,
+      "defense": 28,
+      "detection": 27
+    },
+    "techniques_covered": 61
+  },
+  "lessons": {
+    "total": 43,
+    "by_severity": {
+      "critical": 3,
+      "high": 12,
+      "medium": 20,
+      "low": 8
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Always link playbooks to tests**: When creating a test, reference the attack playbook in the test notes.
+2. **Create lessons after every campaign**: Even successful tests yield lessons. Capture `what worked well`.
+3. **Review playbooks quarterly**: Infrastructure changes may invalidate detection steps.
+4. **Tag lessons**: Use consistent tags (`amsi`, `lateral-movement`, `cloud`) to make lessons searchable.
+5. **One playbook per technique per type**: The system enforces uniqueness on `(technique_id, playbook_type)`.