Files

Kitos 8032b67fab docs: add disclaimer about Cursor and Claude Opus 4.6 assistance

2026-02-10 10:52:53 +01:00

16 KiB

Raw Blame History

Aegis — MITRE ATT&CK Coverage Platform

Aegis is a comprehensive platform for tracking and managing security coverage against the MITRE ATT&CK framework. It enables security teams to document, validate, and visualize their defensive capabilities against known adversary techniques through a structured Red Team / Blue Team validation workflow.

Features

Core (V1)

MITRE ATT&CK Integration — Automatic synchronization via TAXII 2.0 (with GitHub fallback), scheduled every 24h
Red/Blue Validation Workflow — Structured dual-validation lifecycle: draft → red_executing → blue_evaluating → in_review → validated/rejected
Dual Validation — Independent Red Lead / Blue Lead approval before finalization
Coverage Tracking — Per-technique status (validated, partial, not covered, in progress)
Evidence Storage — Secure evidence with SHA256 integrity, separated by team (red/blue)
Role-Based Access Control — Granular permissions for 6 roles (admin, red_tech, blue_tech, red_lead, blue_lead, viewer)

Enhanced (V2)

Test Template Catalog — Import from Atomic Red Team, create custom templates, instantiate tests
In-App Notifications — Real-time notification bell with polling and automatic state-change alerts
Reports & Export — Coverage summary, test results, and remediation reports in JSON and CSV
Remediation Tracking — Step-by-step remediation assignments with status tracking
Metrics Dashboard — Pipeline funnel, team activity, validation rates

Advanced (V3)

Multi-Source Data Import — Sigma, Elastic, CALDERA, LOLBAS, D3FEND, MITRE CTI threat actors, compliance mappings
Detection Rule Tracking — Import and evaluate Sigma/Elastic detection rules per test
ATT&CK Heatmap — Interactive Navigator-style heatmap with layers, filters, and export
Threat Actor Intelligence — Track intrusion sets and their technique coverage
Campaign Management — Group tests into campaigns with dependencies, scheduling, and recurring execution
Compliance Mapping — Map NIST 800-53 controls to ATT&CK techniques with gap analysis
Granular Scoring — 0–100 scoring for techniques, tactics, actors, and organization with configurable weights
Operational Metrics — MTTD, MTTR, detection efficacy, alert fidelity, coverage velocity
Executive Dashboard — High-level KPIs for leadership (leads + admin)
Temporal Comparison — Coverage snapshots with historical comparison and trend analysis
Auto Re-testing — Automatic retest creation after remediation completion (configurable limit)
Performance Optimizations — Score caching, lazy loading, React.memo, database index optimization

Red Team / Blue Team Validation Flow

┌──────┐    ┌──────────────┐    ┌─────────────────┐    ┌───────────┐
│ DRAFT│───▶│RED_EXECUTING │───▶│ BLUE_EVALUATING  │───▶│ IN_REVIEW │
└──────┘    └──────────────┘    └─────────────────┘    └─────┬─────┘
                                                             │
                                         ┌───────────────────┤
                                         ▼                   ▼
                                   ┌──────────┐       ┌──────────┐
                                   │ REJECTED │       │VALIDATED │
                                   └────┬─────┘       └──────────┘
                                        │                    │
                                        └──▶ Back to DRAFT   ├──▶ Remediation
                                                             └──▶ Auto Re-test

States

State	Description	Who acts
`draft`	Created, pending execution	Red Tech
`red_executing`	Red Team documents attack & uploads evidence	Red Tech
`blue_evaluating`	Blue Team documents detection & uploads evidence	Blue Tech
`in_review`	Both managers review evidence	Red Lead, Blue Lead
`validated`	Approved by both managers	— (terminal)
`rejected`	Rejected — returns to draft for redo	Red/Blue Lead can reopen

Dual Validation

Both Red Lead and Blue Lead must independently vote:

Both approve → test moves to validated
Either rejects → test moves to rejected
One votes, other pending → stays in in_review

User Roles

Role	Description	Capabilities
`admin`	Full system access	Everything
`red_tech`	Red team technician	Create tests, document attacks, upload red evidence
`blue_tech`	Blue team technician	Document detection, upload blue evidence
`red_lead`	Red team lead	Validate/reject the red side of tests
`blue_lead`	Blue team lead	Validate/reject the blue side of tests
`viewer`	Read-only access	View all data

Tech Stack

Backend: FastAPI (Python 3.11)
Database: PostgreSQL 15 with UUID primary keys and JSONB columns
Object Storage: MinIO (S3-compatible)
ORM: SQLAlchemy with Alembic migrations (18 migration files)
Frontend: React 19 + TypeScript + Vite 7 + Tailwind CSS v4 + TanStack Query + TanStack Virtual
Scheduler: APScheduler (MITRE sync, Intel scan, Notification cleanup, Snapshots, Recurring campaigns)
Charts: Recharts

Quick Start

Prerequisites

Docker and Docker Compose
Git

Installation

Clone the repository:

git clone <repository-url>
cd Aegis

Start all services:

docker-compose up -d

Run database migrations:

docker exec aegis-backend alembic upgrade head

Seed the admin user:

docker exec aegis-backend python -m app.seed

Access the application:

# API health check
curl http://localhost:8000/health
# Expected: {"status":"ok"}

# Open http://localhost:5173 — Aegis login page

Authentication

JWT-based authentication. Default admin credentials after seeding:

Username: admin
Password: admin123

Important: Change the default admin123 password and SECRET_KEY in production.

Importing Data Sources

After initial setup, populate the platform with data:

# 1. Sync MITRE ATT&CK techniques
curl -X POST http://localhost:8000/api/v1/system/sync-mitre -H "Authorization: Bearer $TOKEN"

# 2. Import test templates from Atomic Red Team
curl -X POST http://localhost:8000/api/v1/system/import-atomic-red-team -H "Authorization: Bearer $TOKEN"

# 3. Import additional sources via the Data Sources admin page
#    Navigate to System → Data Sources in the UI

See docs/DATA_SOURCES.md for detailed instructions on all data sources.

Configuring Scoring Weights

Default scoring weights can be adjusted via environment variables:

SCORING_WEIGHT_TESTS=40
SCORING_WEIGHT_DETECTION_RULES=20
SCORING_WEIGHT_D3FEND=15
SCORING_WEIGHT_FRESHNESS=15
SCORING_WEIGHT_PLATFORM_DIVERSITY=10

Or at runtime via the admin API — see docs/SCORING.md.

Configuring Campaigns

Navigate to Campaigns in the sidebar
Create a new campaign (custom or from a threat actor)
Add tests with dependencies and phases
Optionally enable recurring scheduling (weekly, monthly, quarterly)

Services

Service	Port	Description
Frontend	5173	React dev server (Vite)
Backend	8000	FastAPI REST API
PostgreSQL	5433	Database
MinIO API	9000	S3-compatible object storage
MinIO Console	9001	MinIO web interface

📊 Dashboard
📊 Executive Dashboard          (leads + admin)
🔲 ATT&CK Matrix                (advanced heatmap)
🧪 Tests
  ├─ All Tests
  ├─ My Pending Tasks
  └─ Test Catalog
📋 Campaigns
👤 Threat Actors
📜 Compliance
📈 Comparison                    (leads + admin)
📄 Reports
⚙️ System                       (admin only)
  ├─ Data Sources
  ├─ MITRE Sync
  ├─ Users
  └─ Audit Log

API Documentation

Interactive API documentation available at:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

API Endpoints

Group	Prefix	Key Operations
Auth	`/api/v1/auth`	Login, get current user
Techniques	`/api/v1/techniques`	CRUD, list with filters, mark reviewed
Tests	`/api/v1/tests`	Full Red/Blue workflow, remediation, retest chain
Test Templates	`/api/v1/test-templates`	CRUD, import, stats, toggle active
Evidence	`/api/v1/tests/{id}/evidence`	Upload evidence, get presigned URLs
Campaigns	`/api/v1/campaigns`	CRUD, scheduling, history
Threat Actors	`/api/v1/threat-actors`	CRUD, technique mappings
Detection Rules	`/api/v1/detection-rules`	List, filter by source/technique
D3FEND	`/api/v1/d3fend`	Defensive techniques and mappings
Compliance	`/api/v1/compliance`	Frameworks, controls, gaps
Scores	`/api/v1/scores`	Technique/tactic/actor/org scores, config
Operational Metrics	`/api/v1/metrics/operational`	MTTD, MTTR, trends, team breakdown
Heatmap	`/api/v1/heatmap`	ATT&CK Navigator-style data
Snapshots	`/api/v1/snapshots`	Create, compare, list snapshots
Reports	`/api/v1/reports`	Coverage, results, remediation exports
Notifications	`/api/v1/notifications`	List, read, mark all read
Metrics	`/api/v1/metrics`	Summary, by-tactic, pipeline, team activity
System	`/api/v1/system`	MITRE sync, import, scheduler status
Users	`/api/v1/users`	User CRUD (admin)
Audit Logs	`/api/v1/audit-logs`	Audit trail (admin)
Data Sources	`/api/v1/data-sources`	Data source management (admin)

See docs/API.md for the full endpoint reference.

Configuration

Variable	Default	Description
`DATABASE_URL`	`postgresql://postgres:postgres@postgres:5432/attackdb`	PostgreSQL connection
`SECRET_KEY`	`change-me-in-production`	JWT signing key
`ALGORITHM`	`HS256`	JWT signing algorithm
`ACCESS_TOKEN_EXPIRE_MINUTES`	`60`	Token lifetime
`MINIO_ENDPOINT`	`minio:9000`	MinIO server
`MINIO_ACCESS_KEY`	`minioadmin`	MinIO access key
`MINIO_SECRET_KEY`	`minioadmin`	MinIO secret key
`MINIO_BUCKET`	`evidence`	Evidence bucket
`MAX_RETEST_COUNT`	`3`	Max automatic retests per original test
`SCORING_WEIGHT_TESTS`	`40`	Weight for test validation component
`SCORING_WEIGHT_DETECTION_RULES`	`20`	Weight for detection rules component
`SCORING_WEIGHT_D3FEND`	`15`	Weight for D3FEND coverage component
`SCORING_WEIGHT_FRESHNESS`	`15`	Weight for freshness component
`SCORING_WEIGHT_PLATFORM_DIVERSITY`	`10`	Weight for platform diversity component

Project Structure

Aegis/
├── docker-compose.yml
├── docker-compose.prod.yml
├── docs/
│   ├── API.md                     # Full API endpoint reference
│   ├── ARCHITECTURE.md            # System architecture and DB schema
│   ├── DATA_SOURCES.md            # External data source documentation
│   └── SCORING.md                 # Scoring system and metrics
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── alembic.ini
│   ├── alembic/versions/          # b001–b018 migration files
│   ├── pytest.ini
│   └── app/
│       ├── main.py                # FastAPI app with all routers + lifespan
│       ├── config.py              # Settings from environment
│       ├── database.py            # SQLAlchemy engine + session (lazy init)
│       ├── storage.py             # MinIO/S3 helpers
│       ├── auth.py                # Password hashing + JWT tokens
│       ├── models/                # 18 model files (SQLAlchemy ORM)
│       ├── schemas/               # Pydantic request/response schemas
│       ├── routers/               # 21 API routers
│       ├── services/              # 20 business logic services
│       ├── dependencies/          # Auth dependencies (get_current_user, require_role)
│       └── jobs/
│           └── mitre_sync_job.py  # APScheduler: 5 background jobs
├── frontend/src/
│   ├── App.tsx                    # Routes with lazy loading + role protection
│   ├── api/                       # 22 API client modules (Axios + TanStack Query)
│   ├── components/
│   │   ├── Layout.tsx             # Sidebar + header + NotificationBell
│   │   ├── Sidebar.tsx            # Role-aware collapsible navigation
│   │   ├── heatmap/               # ATT&CK heatmap (6 components)
│   │   ├── compliance/            # Compliance UI (gauge, controls table)
│   │   └── test-detail/           # Test detail sub-components
│   ├── hooks/
│   │   └── useDebounce.ts         # Debounce hook for search inputs
│   ├── context/
│   │   └── AuthContext.tsx         # Auth state management
│   └── pages/                     # 21 page components
└── backend/tests/
    ├── conftest.py                # SQLite test DB with JSONB/UUID compatibility
    ├── fixtures/                  # YAML/TOML/JSON test fixtures
    ├── test_data_sources.py       # Data source parsing tests
    ├── test_scoring_and_compliance.py # Scoring + metrics + compliance tests
    ├── test_campaigns_and_snapshots.py # Campaign, snapshot, and retest tests
    ├── test_workflow.py           # Red/Blue workflow tests
    ├── test_templates_crud.py     # Template CRUD tests
    ├── test_metrics_v2.py         # V2 metrics tests
    └── test_integration_v2.py     # Full integration E2E tests

Development

Running Migrations

docker exec aegis-backend alembic upgrade head
docker exec aegis-backend alembic revision --autogenerate -m "description"
docker exec aegis-backend alembic downgrade -1

Running Tests

# Run all V3 tests inside the container (recommended)
docker exec aegis-backend python -m pytest tests/ -v --tb=short

# Run specific test suites
docker exec aegis-backend python -m pytest tests/test_data_sources.py -v
docker exec aegis-backend python -m pytest tests/test_scoring_and_compliance.py -v
docker exec aegis-backend python -m pytest tests/test_campaigns_and_snapshots.py -v

# Skip integration tests (require network)
docker exec aegis-backend python -m pytest tests/ -v -m "not integration"

Generating Reports

# Coverage summary (JSON)
GET /api/v1/reports/coverage-summary

# Coverage CSV export
GET /api/v1/reports/coverage-csv

# Compliance gap analysis
GET /api/v1/compliance/{framework_id}/gaps

Further Documentation

Architecture — Database schema, service layer, state machine diagrams
Data Sources — All external data sources with import instructions
Scoring — Scoring system explained with examples and configuration
API Reference — Full endpoint documentation

License

Disclaimer

This project has been developed with the assistance of Cursor and Claude Opus 4.6 (Anthropic).

16 KiB Raw Blame History Unescape Escape