Add wiki page: MITRE-ATT-CK-Coverage

MITRE-ATT-CK-Coverage.-.md

@@ -0,0 +1,190 @@
+# MITRE ATT&CK Coverage
+
+Aegis is built around the MITRE ATT&CK framework. This page explains how the coverage
+system works, how techniques are scored, and how the data is maintained.
+
+---
+
+## What is MITRE ATT&CK?
+
+MITRE ATT&CK is a globally-accessible knowledge base of adversary tactics and techniques
+based on real-world observations. It provides a common language for describing attacker
+behavior, allowing Red and Blue teams to align their work.
+
+- Official reference: https://attack.mitre.org/
+- Aegis uses the **Enterprise** matrix
+- Techniques are identified by IDs like `T1059` (parent) and `T1059.001` (sub-technique)
+
+---
+
+## Tactics (14)
+
+| # | Tactic ID | Tactic Name | Description |
+|---|-----------|-------------|-------------|
+| 1 | TA0043 | Reconnaissance | Gathering information before attack |
+| 2 | TA0042 | Resource Development | Preparing attack resources |
+| 3 | TA0001 | Initial Access | Getting into the target environment |
+| 4 | TA0002 | Execution | Running adversary-controlled code |
+| 5 | TA0003 | Persistence | Maintaining foothold |
+| 6 | TA0004 | Privilege Escalation | Gaining higher-level permissions |
+| 7 | TA0005 | Defense Evasion | Avoiding detection |
+| 8 | TA0006 | Credential Access | Stealing credentials |
+| 9 | TA0007 | Discovery | Exploring the environment |
+| 10 | TA0008 | Lateral Movement | Moving through the network |
+| 11 | TA0009 | Collection | Gathering data of interest |
+| 12 | TA0011 | Command and Control | Communicating with compromised systems |
+| 13 | TA0010 | Exfiltration | Stealing data out of the environment |
+| 14 | TA0040 | Impact | Manipulating, interrupting, or destroying systems |
+
+---
+
+## Coverage Statuses
+
+Each technique has a `coverage_status` field:
+
+| Status | Meaning |
+|--------|---------|
+| `not_covered` | No validated test exists for this technique |
+| `partial` | At least one test exists but not all are validated, OR detection was partial |
+| `validated` | At least one test is in `validated` state with both leads approved |
+
+Coverage is stored in the `techniques` table and recalculated automatically when:
+- A test reaches `validated` state
+- A test is reopened (back to draft from validated/rejected)
+- MITRE sync runs and adds/removes techniques
+
+---
+
+## Coverage Scoring
+
+Aegis calculates a **weighted coverage score** (0–100) for each technique and for the
+organization overall. The formula combines multiple signals:
+
+### Default weights (configurable)
+
+| Signal | Default weight | Description |
+|--------|---------------|-------------|
+| Tests | 40% | Number and outcome of validated tests |
+| Detection rules | 30% | Detection rules linked to the technique |
+| D3FEND | 10% | Defensive countermeasures mapped via MITRE D3FEND |
+| Recency | 10% | How recently the technique was last tested |
+| Severity | 10% | Technique severity/impact factor |
+
+### Configuring weights
+
+Only admins can change scoring weights:
+```http
+PATCH /api/v1/scores/config
+{
+  "test_weight": 0.40,
+  "detection_rule_weight": 0.30,
+  "d3fend_weight": 0.10,
+  "recency_weight": 0.10,
+  "severity_weight": 0.10
+}
+```
+
+Weights must sum to 1.0.
+
+### Score endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| GET /api/v1/scores/organization | Overall organization coverage score |
+| GET /api/v1/scores/techniques/{id} | Score for a specific technique |
+| GET /api/v1/scores/by-tactic | Scores aggregated by tactic |
+
+---
+
+## MITRE Data Sync
+
+Aegis maintains its own copy of the MITRE ATT&CK technique database.
+
+**Automatic sync**: Runs hourly via APScheduler. Fetches the latest STIX data from
+the official MITRE ATT&CK GitHub repository and upserts all techniques.
+
+**Manual sync** (admin only):
+```http
+POST /api/v1/system/sync-mitre
+```
+
+**What syncs:**
+- Technique ID, name, description
+- Tactic associations
+- Sub-technique relationships
+- Deprecation/revocation status
+- Platform tags (Windows, Linux, macOS, Cloud, etc.)
+
+**New techniques** added by MITRE automatically appear as `not_covered` in Aegis.
+**Deprecated techniques** are marked accordingly but retained for historical test data.
+
+---
+
+## Technique Review
+
+When your infrastructure changes (new tools, new SIEM rules), techniques may need
+re-testing to confirm coverage is still accurate.
+
+**Mark a technique for review** (leads, admin):
+```http
+PATCH /api/v1/techniques/{id}/review
+{"needs_review": true, "review_reason": "SIEM rules rebuilt after migration"}
+```
+
+This triggers the revalidation queue in the detection lifecycle module.
+
+---
+
+## Heatmap
+
+The heatmap visualizes coverage across all tactics and techniques:
+
+```http
+GET /api/v1/heatmap
+```
+
+Returns a matrix organized by tactic, with each technique cell showing:
+- `coverage_status`
+- `score`
+- `test_count`
+- `last_tested` date
+
+---
+
+## D3FEND Mappings
+
+MITRE D3FEND is a knowledge graph of cybersecurity countermeasures.
+Aegis integrates D3FEND mappings to show which defensive techniques apply to each
+ATT&CK technique.
+
+```http
+GET /api/v1/techniques/{mitre_id}/d3fend
+```
+
+Returns a list of D3FEND techniques (countermeasures) mapped to the ATT&CK technique,
+with descriptions and implementation guidance.
+
+---
+
+## Risk Profiles
+
+The risk module assesses how dangerous each uncovered technique is:
+
+| Endpoint | Description |
+|----------|-------------|
+| GET /api/v1/risk/profiles | Risk profile per technique |
+| GET /api/v1/risk/matrix | Risk matrix (severity × coverage) |
+| GET /api/v1/risk/summary | Aggregate risk summary |
+| GET /api/v1/risk/top | Top N highest-risk uncovered techniques |
+| GET /api/v1/risk/recommendations | Prioritized remediation recommendations |
+| POST /api/v1/risk/compute | Trigger manual risk recomputation |
+
+**Top uncovered techniques:**
+```http
+GET /api/v1/risk/top?limit=10
+```
+
+Returns the 10 highest-priority uncovered techniques based on:
+- MITRE technique severity/prevalence
+- Threat actor association (if the technique is used by tracked threat actors)
+- Current coverage gap size