From 21dced76055743e21a84fff2dbab4a44a58e16af Mon Sep 17 00:00:00 2001 From: kitos Date: Fri, 22 May 2026 12:32:56 +0000 Subject: [PATCH] Add wiki page: Home --- Home.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) diff --git a/Home.md b/Home.md index e69de29..22cd911 100644 --- 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= +``` + +The server sets an `aegis_token` HttpOnly cookie. All subsequent requests are +authenticated automatically by the browser (or pass the token as +`Authorization: Bearer `). + +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": "", "new_password": ""} +``` + +### 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)