Add wiki page: Executive-Dashboard-and-Reports

Executive-Dashboard-and-Reports.-.md

@@ -0,0 +1,215 @@
+# Executive Dashboard and Reports
+
+Aegis provides real-time dashboards, historical snapshots, and professional report
+generation for all stakeholders — from technical leads to C-suite executives.
+
+---
+
+## Dashboard Endpoints
+
+All dashboard endpoints require authentication but are accessible to all roles.
+
+### KPIs
+
+```http
+GET /api/v1/dashboard/kpis
+```
+
+Returns the core metrics at a glance:
+```json
+{
+  "total_techniques": 742,
+  "covered_techniques": 387,
+  "coverage_percent": 52.2,
+  "validated_tests": 312,
+  "active_campaigns": 3,
+  "open_alerts": 7,
+  "last_snapshot": "2024-03-15T08:00:00Z",
+  "organization_score": 64.8
+}
+```
+
+### Executive Summary
+
+```http
+GET /api/v1/dashboard/executive
+```
+
+Returns a narrative summary suitable for non-technical stakeholders:
+- Overall security posture statement
+- Coverage trend (improving/declining/stable)
+- Top 3 uncovered high-risk techniques
+- Recent key achievements (campaigns completed, techniques covered)
+- Open action items
+
+### Coverage by Tactic
+
+```http
+GET /api/v1/dashboard/coverage-by-tactic
+```
+
+Returns per-tactic breakdown:
+```json
+[
+  {
+    "tactic_id": "TA0002",
+    "tactic_name": "Execution",
+    "total_techniques": 13,
+    "validated": 8,
+    "partial": 3,
+    "not_covered": 2,
+    "coverage_percent": 84.6,
+    "score": 76.2
+  },
+  ...
+]
+```
+
+### Posture History
+
+```http
+GET /api/v1/dashboard/posture-history?days=90
+```
+
+Time-series data for trend charts (default: last 90 days):
+```json
+[
+  {"date": "2024-01-01", "score": 48.2, "covered_percent": 45.1},
+  {"date": "2024-02-01", "score": 52.7, "covered_percent": 48.8},
+  {"date": "2024-03-01", "score": 64.8, "covered_percent": 52.2}
+]
+```
+
+### Activity Feed
+
+```http
+GET /api/v1/dashboard/activity?limit=20
+```
+
+Recent actions across the platform:
+- Tests validated
+- Campaigns completed
+- New lessons learned added
+- Alerts fired
+- MITRE sync completed
+
+---
+
+## Snapshots
+
+Snapshots capture a complete point-in-time record of coverage metrics. They enable
+trend analysis and before/after comparison.
+
+### Creating a Snapshot
+
+**Manual** (leads, admin):
+```http
+POST /api/v1/snapshots
+{"notes": "Pre-campaign baseline — March 2024"}
+```
+
+**Automatic**: The system creates snapshots automatically:
+- After every campaign completion
+- After MITRE sync
+- On a scheduled basis (configurable)
+
+### Listing Snapshots
+
+```http
+GET /api/v1/snapshots?limit=10&offset=0
+```
+
+### Coverage Evolution (Trend)
+
+```http
+GET /api/v1/snapshots/evolution?limit=50
+```
+
+Returns time-ordered list of snapshots with key metrics — ideal for plotting a
+trend line of coverage improvement over time.
+
+### Comparing Two Snapshots
+
+```http
+GET /api/v1/snapshots/compare?a=<snapshot_id_1>&b=<snapshot_id_2>
+```
+
+Returns a diff showing:
+- Techniques newly covered since snapshot A
+- Techniques that lost coverage
+- Score delta
+- Test count delta
+
+### Deleting a Snapshot
+
+Only admins can delete snapshots:
+```http
+DELETE /api/v1/snapshots/{id}
+```
+
+---
+
+## Professional Report Generation
+
+Aegis can generate publication-ready reports in PDF, DOCX, or HTML format.
+These are available to: **admin, red_lead, blue_lead, and viewer**.
+
+### Available Reports
+
+| Report | Endpoint | Description |
+|--------|----------|-------------|
+| Purple Team Campaign | GET /reports/generate/purple-campaign/{id} | Full campaign report with all tests |
+| Coverage Summary | GET /reports/generate/coverage-summary | Org-wide coverage status |
+| Executive Summary | GET /reports/generate/executive-summary | C-suite briefing, 2-3 pages |
+| Quarterly Summary | GET /reports/generate/quarterly-summary | Quarterly review with trends |
+| Technique Detail | GET /reports/generate/technique/{id} | Deep-dive on one technique |
+
+### Format Selection
+
+Append `?format=pdf`, `?format=docx`, or `?format=html` (default: html):
+```http
+GET /api/v1/reports/generate/executive-summary?format=pdf
+```
+
+Response headers:
+```
+Content-Type: application/pdf
+Content-Disposition: attachment; filename="executive-summary-2024-03-15.pdf"
+```
+
+### Report Content — Purple Team Campaign
+
+Includes for each test in the campaign:
+- Test title, technique ID and name, objective
+- Execution timeline
+- Red team findings (tool, command, output)
+- Blue team detection result and response
+- Validation status
+- Evidence thumbnails
+- Remediation status
+
+Plus campaign-level summary:
+- Detection rate (detected / total tests)
+- Coverage improvement delta
+- Top findings and recommendations
+- Executive narrative
+
+### Report Content — Executive Summary
+
+- Organization security posture score
+- Coverage percentage vs last quarter
+- Top 5 technique gaps by risk
+- Recent campaign outcomes
+- Key recommendations for next quarter
+- Glossary of terms
+
+---
+
+## Raw Data Exports
+
+| Endpoint | Format | Description |
+|----------|--------|-------------|
+| GET /reports/coverage-summary | JSON | Coverage status per technique |
+| GET /reports/coverage-csv | CSV download | Coverage matrix for Excel/BI tools |
+| GET /reports/test-results | JSON | All test results with outcomes |
+| GET /reports/remediation-status | JSON | Remediation tracking per technique |