# 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
```
