refactor(detection-rules): extract query/business logic to detection_rule_service, router is thin HTTP adapter
This commit is contained in:
140
docs/C4_CONTEXT_DIAGRAM.md
Normal file
140
docs/C4_CONTEXT_DIAGRAM.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# Aegis — C4 Context Diagram (Level 1)
|
||||
|
||||
> **Author:** Architecture review
|
||||
> **Date:** February 11, 2026
|
||||
> **Notation:** C4 Model — Level 1 (System Context)
|
||||
|
||||
---
|
||||
|
||||
## Diagram
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
title Aegis — System Context Diagram (C4 Level 1)
|
||||
|
||||
%% ─── Actors (People) ────────────────────────────────────────────
|
||||
|
||||
Person(red_tech, "Red Team Technician", "Executes offensive tests, submits evidence, creates tests from templates")
|
||||
Person(blue_tech, "Blue Team Technician", "Evaluates detection results, submits blue evidence, documents findings")
|
||||
Person(red_lead, "Red Team Lead", "Validates red team results, manages campaigns, reviews test outcomes")
|
||||
Person(blue_lead, "Blue Team Lead", "Validates blue team results, manages remediation, reviews detection gaps")
|
||||
Person(admin, "Administrator", "Manages users, triggers data syncs, configures scoring, oversees platform")
|
||||
Person(viewer, "Viewer", "Read-only access to dashboards, reports, heatmaps, and compliance status")
|
||||
|
||||
%% ─── Core System ────────────────────────────────────────────────
|
||||
|
||||
System(aegis, "Aegis Platform", "MITRE ATT&CK coverage management platform. Orchestrates Red/Blue team validation workflows, tracks technique coverage, generates heatmaps, compliance reports, and organizational scoring.")
|
||||
|
||||
%% ─── Internal Infrastructure (Owned / Deployed) ─────────────────
|
||||
|
||||
SystemDb(postgres, "PostgreSQL 15", "Primary data store. Stores techniques, tests, users, campaigns, threat actors, compliance mappings, audit logs, scoring config, and snapshots.")
|
||||
SystemDb(minio, "MinIO (S3-compatible)", "Object storage for Red/Blue team evidence files (screenshots, logs, PCAPs). Serves presigned download URLs.")
|
||||
|
||||
%% ─── External Data Sources (Consumed) ───────────────────────────
|
||||
|
||||
System_Ext(mitre_taxii, "MITRE ATT&CK TAXII Server", "STIX/TAXII 2.0 feed providing Enterprise ATT&CK techniques and tactics. Primary source for technique catalog sync.")
|
||||
System_Ext(mitre_cti, "MITRE CTI GitHub Repository", "STIX 2.0 bundles for ATT&CK techniques (fallback), intrusion-sets (threat actors), and actor-technique relationships.")
|
||||
System_Ext(d3fend, "MITRE D3FEND API", "Public REST API providing defensive techniques and ATT&CK-to-D3FEND mappings for countermeasure coverage.")
|
||||
System_Ext(atomic, "Atomic Red Team (GitHub)", "Repository of atomic tests mapped to ATT&CK techniques. Downloaded as ZIP, parsed from YAML atomics.")
|
||||
System_Ext(sigma, "SigmaHQ (GitHub)", "Repository of Sigma detection rules in YAML format. Parsed for ATT&CK tags and imported as detection rules.")
|
||||
System_Ext(elastic, "Elastic Detection Rules (GitHub)", "Repository of Elastic SIEM rules in TOML format. Parsed for MITRE threat mappings and imported as detection rules.")
|
||||
System_Ext(caldera, "MITRE CALDERA (GitHub)", "Repository of CALDERA abilities. YAML files parsed from data/abilities/ and imported as test templates.")
|
||||
System_Ext(lolbas, "LOLBAS Project (GitHub)", "Living Off The Land Binaries and Scripts. YAML-based catalog imported as test templates mapped to ATT&CK techniques.")
|
||||
System_Ext(gtfobins, "GTFOBins (GitHub)", "Unix binaries exploitation reference. Markdown with YAML front-matter parsed and mapped to ATT&CK techniques.")
|
||||
|
||||
%% ─── Planned Systems (Not Yet Integrated) ──────────────────────
|
||||
|
||||
System_Ext(github_ent, "GitHub Enterprise (Planned)", "Future CI/CD pipeline integration for automated linting, type checking, test execution, and deployment workflows.")
|
||||
System_Ext(artifactory, "Artifactory (Planned)", "Future artifact repository for storing Docker images, build artifacts, and versioned releases.")
|
||||
|
||||
%% ─── Relationships: Users → Aegis ───────────────────────────────
|
||||
|
||||
Rel(red_tech, aegis, "Creates and executes tests, uploads red evidence, uses test catalog", "HTTPS")
|
||||
Rel(blue_tech, aegis, "Evaluates detections, uploads blue evidence, reviews detection rules", "HTTPS")
|
||||
Rel(red_lead, aegis, "Validates red results, manages campaigns, reviews threat actor coverage", "HTTPS")
|
||||
Rel(blue_lead, aegis, "Validates blue results, tracks remediation, reviews compliance", "HTTPS")
|
||||
Rel(admin, aegis, "Manages users, triggers syncs, configures scoring weights, views audit logs", "HTTPS")
|
||||
Rel(viewer, aegis, "Views dashboards, heatmaps, reports, and compliance status", "HTTPS")
|
||||
|
||||
%% ─── Relationships: Aegis → Infrastructure ──────────────────────
|
||||
|
||||
Rel(aegis, postgres, "Reads/writes all domain data", "TCP/5432, SQLAlchemy")
|
||||
Rel(aegis, minio, "Uploads/downloads evidence files, generates presigned URLs", "HTTP/9000, boto3 S3 API")
|
||||
|
||||
%% ─── Relationships: Aegis → External Sources ────────────────────
|
||||
|
||||
Rel(aegis, mitre_taxii, "Syncs ATT&CK techniques every 24h", "TAXII 2.0 / HTTPS")
|
||||
Rel(aegis, mitre_cti, "Fallback technique sync + threat actor import", "HTTPS, ZIP download")
|
||||
Rel(aegis, d3fend, "Imports defensive techniques and ATT&CK mappings", "REST API / HTTPS")
|
||||
Rel(aegis, atomic, "Imports Atomic Red Team test templates", "HTTPS, ZIP download")
|
||||
Rel(aegis, sigma, "Imports Sigma detection rules with ATT&CK tags", "HTTPS, ZIP download")
|
||||
Rel(aegis, elastic, "Imports Elastic SIEM detection rules", "HTTPS, ZIP download")
|
||||
Rel(aegis, caldera, "Imports CALDERA abilities as test templates", "HTTPS, ZIP download")
|
||||
Rel(aegis, lolbas, "Imports LOLBAS binaries as test templates", "HTTPS, ZIP download")
|
||||
Rel(aegis, gtfobins, "Imports GTFOBins as test templates", "HTTPS, ZIP download")
|
||||
|
||||
%% ─── Relationships: Aegis → Planned ─────────────────────────────
|
||||
|
||||
Rel(aegis, github_ent, "CI/CD pipelines (planned)", "HTTPS")
|
||||
Rel(aegis, artifactory, "Artifact storage (planned)", "HTTPS")
|
||||
|
||||
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diagram Notes
|
||||
|
||||
### Actor Roles
|
||||
|
||||
| Role | Access Level | Primary Actions |
|
||||
|------|-------------|-----------------|
|
||||
| **Red Team Technician** | Standard | Create tests, execute attacks, upload red evidence, use test catalog |
|
||||
| **Blue Team Technician** | Standard | Evaluate detections, upload blue evidence, review detection rules |
|
||||
| **Red Team Lead** | Elevated | Validate red results, manage campaigns, review threat actor coverage |
|
||||
| **Blue Team Lead** | Elevated | Validate blue results, track remediation, review compliance |
|
||||
| **Administrator** | Full | User management, trigger data syncs, scoring config, audit logs |
|
||||
| **Viewer** | Read-only | View dashboards, heatmaps, reports, compliance status |
|
||||
|
||||
### External Data Source Details
|
||||
|
||||
| Source | Protocol | Frequency | Data Imported |
|
||||
|--------|----------|-----------|---------------|
|
||||
| MITRE ATT&CK TAXII | STIX/TAXII 2.0 | Every 24 hours (scheduled) | Enterprise techniques and tactics |
|
||||
| MITRE CTI GitHub | HTTPS (ZIP) | Fallback + on-demand | Techniques, threat actors (intrusion-sets), actor-technique relationships |
|
||||
| MITRE D3FEND | REST API | On-demand (admin trigger) | Defensive techniques, ATT&CK-to-D3FEND mappings |
|
||||
| Atomic Red Team | HTTPS (ZIP ~40MB) | On-demand (admin trigger) | Test templates from `atomics/T*/T*.yaml` |
|
||||
| SigmaHQ | HTTPS (ZIP) | On-demand (admin trigger) | Sigma detection rules with ATT&CK tags |
|
||||
| Elastic Detection Rules | HTTPS (ZIP) | On-demand (admin trigger) | Elastic SIEM rules in TOML with MITRE mappings |
|
||||
| MITRE CALDERA | HTTPS (ZIP) | On-demand (admin trigger) | Abilities from `data/abilities/{tactic}/*.yml` |
|
||||
| LOLBAS Project | HTTPS (ZIP) | On-demand (admin trigger) | Living Off The Land binaries/scripts |
|
||||
| GTFOBins | HTTPS (ZIP) | On-demand (admin trigger) | Unix binary exploitation references |
|
||||
|
||||
### Planned Integrations (Not Yet Implemented)
|
||||
|
||||
| System | Purpose | Status |
|
||||
|--------|---------|--------|
|
||||
| **GitHub Enterprise** | CI/CD pipelines for automated lint, type check, tests, and deployment | Planned — no `.github/workflows` exist yet |
|
||||
| **Artifactory** | Docker image and build artifact repository | Planned — no integration code exists yet |
|
||||
|
||||
### Infrastructure Boundary
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Docker Compose Network │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
|
||||
│ │ Frontend │ │ Backend │ │ PostgreSQL│ │
|
||||
│ │ (Nginx) │ │ (Uvicorn)│ │ 15 │ │
|
||||
│ │ :80 │ │ :8000 │ │ :5432 │ │
|
||||
│ └──────────┘ └──────────┘ └───────────┘ │
|
||||
│ ┌───────────┐ │
|
||||
│ │ MinIO │ │
|
||||
│ │ :9000/9001│ │
|
||||
│ └───────────┘ │
|
||||
└─────────────────────────────────────────────┘
|
||||
▲ │
|
||||
│ HTTPS │ HTTPS (outbound)
|
||||
│ ▼
|
||||
Users External Sources
|
||||
```
|
||||
Reference in New Issue
Block a user