Add wiki page: Home

2026-05-22 12:32:56 +00:00
parent a4588b632a
commit 21dced7605
1 changed files with 123 additions and 0 deletions
--- a/Home.md
+++ b/Home.md
@@ -0,0 +1,123 @@
+# Aegis — Knowledge Base Home
+
+**Aegis** is a MITRE ATT&CK coverage management platform for Purple Team operations.
+It provides a structured workflow for Red and Blue teams to plan, execute, evaluate,
+and track security tests mapped to MITRE ATT&CK techniques, measure detection coverage,
+manage knowledge, and generate executive reporting.
+
+---
+
+## Table of Contents
+
+| Wiki Page | Description |
+|-----------|-------------|
+| [Home](Home) | This page — navigation hub and quick start |
+| [Architecture](Architecture) | Tech stack, Docker services, backend structure, data flow |
+| [Roles-and-Permissions](Roles-and-Permissions) | RBAC roles, permission matrix, admin bypass |
+| [Test-Lifecycle](Test-Lifecycle) | State machine: draft → validated, all transitions |
+| [MITRE-ATT-CK-Coverage](MITRE-ATT-CK-Coverage) | Coverage model, scoring, sync, heatmap |
+| [API-Reference](API-Reference) | All 28 routers with endpoints, methods, required roles |
+| [Authentication-and-Security](Authentication-and-Security) | JWT, cookies, API keys, SAML SSO, rate limiting |
+| [Campaigns](Campaigns) | Campaign types, lifecycle, threat-actor import |
+| [Knowledge-Management](Knowledge-Management) | Playbooks, lessons learned, versioning |
+| [Operational-Alerts](Operational-Alerts) | Alert rules, instances, evaluation, webhooks |
+| [Executive-Dashboard-and-Reports](Executive-Dashboard-and-Reports) | KPIs, snapshots, PDF/DOCX/HTML report generation |
+| [Detection-Lifecycle](Detection-Lifecycle) | Detection assets, validations, infrastructure changes |
+| [Deployment-Guide](Deployment-Guide) | Docker deployment, environment variables, migrations |
+| [QA-Testing-Guide](QA-Testing-Guide) | Automated QA runner, manual checklists per role |
+
+---
+
+## Quick Start
+
+### 1. Log In
+
+```http
+POST /api/v1/auth/login
+Content-Type: application/x-www-form-urlencoded
+
+username=admin&password=<from_env>
+```
+
+The server sets an `aegis_token` HttpOnly cookie. All subsequent requests are
+authenticated automatically by the browser (or pass the token as
+`Authorization: Bearer <token>`).
+
+On **first login**, if the admin account was freshly seeded, you will receive a
+`403 PASSWORD_CHANGE_REQUIRED` on every endpoint except `/api/v1/auth/me` and
+`/api/v1/auth/change-password`. Change your password immediately:
+
+```http
+POST /api/v1/auth/change-password
+Content-Type: application/json
+
+{"current_password": "<old>", "new_password": "<new_12chars+>"}
+```
+
+### 2. Create Your First Test
+
+1. **Create a test** (red_lead / blue_lead / admin):
+   ```http
+   POST /api/v1/tests
+   {"title": "T1059.001 PowerShell execution", "technique_id": "T1059.001"}
+   ```
+2. **Start execution** (red_tech / red_lead / admin):
+   ```http
+   POST /api/v1/tests/{id}/start-execution
+   ```
+3. **Fill in red-side data** (red_tech / red_lead / admin):
+   ```http
+   PATCH /api/v1/tests/{id}/red
+   {"tool_used": "Cobalt Strike", "command_executed": "powershell -nop -enc ..."}
+   ```
+4. **Submit red** → moves to `blue_evaluating`.
+5. **Fill in blue detection data** (blue_tech / blue_lead / admin):
+   ```http
+   PATCH /api/v1/tests/{id}/blue
+   {"detection_result": "detected", "detection_notes": "SIEM alert fired"}
+   ```
+6. **Submit blue** → moves to `in_review`.
+7. **Validate red** (red_lead / admin) and **validate blue** (blue_lead / admin).
+8. Test reaches `validated`. Technique coverage is updated automatically.
+
+### 3. Explore Coverage
+
+Navigate to the heatmap to see your MITRE ATT&CK coverage:
+```http
+GET /api/v1/heatmap
+```
+
+Or check overall scores:
+```http
+GET /api/v1/scores/organization
+```
+
+---
+
+## Key Concepts Glossary
+
+| Term | Definition |
+|------|------------|
+| **Technique** | A MITRE ATT&CK technique (e.g. T1059.001). The atomic unit of coverage. |
+| **Test** | An execution of an attack technique against a target environment. Has a full state machine lifecycle. |
+| **Campaign** | A collection of tests grouped under a common objective (e.g. APT29 simulation). |
+| **Playbook** | Step-by-step procedure for attacking, defending, or detecting a technique. Versioned. |
+| **Lesson** | A "lessons learned" record linked to any entity. Captures what happened, root cause, and improvement actions. |
+| **Coverage** | The status of a technique: `not_covered`, `partial`, or `validated`. Determined by test outcomes. |
+| **Snapshot** | A point-in-time capture of overall coverage metrics. Used for trend analysis. |
+| **Detection Asset** | A defensive capability (SIEM rule, EDR policy, sensor) mapped to one or more techniques. |
+| **Alert Rule** | A condition that triggers an operational alert when met (e.g. coverage drops below threshold). |
+| **Score** | A weighted numeric representation of coverage quality (0–100) for a technique or the entire organization. |
+| **Threat Actor** | A known adversary profile linked to techniques. Campaigns can be auto-generated from threat actor profiles. |
+| **API Key** | A long-lived credential for machine-to-machine access. Scoped to `read`, `write`, or `admin`. |
+
+---
+
+## Where to Go Next
+
+- First-time deployers → [Deployment-Guide](Deployment-Guide)
+- Understand who can do what → [Roles-and-Permissions](Roles-and-Permissions)
+- Deep-dive into test states → [Test-Lifecycle](Test-Lifecycle)
+- All API endpoints → [API-Reference](API-Reference)
+- How coverage scoring works → [MITRE-ATT-CK-Coverage](MITRE-ATT-CK-Coverage)
+- QA and testing → [QA-Testing-Guide](QA-Testing-Guide)