Aegis/README.md

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

• MITRE ATT&CK Integration: Automatic synchronization with the MITRE ATT&CK framework via TAXII (with GitHub fallback), scheduled every 24h
• Red/Blue Validation Workflow: Structured dual-validation lifecycle for security tests (draft → red_executing → blue_evaluating → in_review → validated/rejected)
• Test Template Catalog: Import tests from Atomic Red Team, create custom templates, and instantiate real tests from them
• Dual Validation: Independent approval/rejection by Red Lead and Blue Lead before a test is finalized
• Coverage Tracking: Track validation status for each technique (validated, partial, not covered, in progress)
• Evidence Storage: Secure evidence file storage with SHA256 integrity verification, separated by team (red/blue)
• In-App Notifications: Real-time notification bell with polling, automatic alerts on state changes
• Reports & Export: Coverage summary, test results, and remediation reports in JSON and CSV formats
• Remediation Tracking: Step-by-step remediation assignments with status tracking per test
• Role-Based Access Control: Granular permissions for red team, blue team, and leadership roles
• Intel Monitoring: Automated scanning for new threat intelligence related to techniques
• Metrics Dashboard: Pipeline funnel, team activity, validation rates, and recent tests

Red Team / Blue Team Validation Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                        TEST LIFECYCLE                                    │
│                                                                          │
│  ┌──────┐    ┌──────────────┐    ┌─────────────────┐    ┌───────────┐  │
│  │ DRAFT│───▶│RED_EXECUTING │───▶│ BLUE_EVALUATING  │───▶│ IN_REVIEW │  │
│  └──────┘    └──────────────┘    └─────────────────┘    └───────────┘  │
│                                                              │          │
│                                         ┌────────────────────┤          │
│                                         ▼                    ▼          │
│                                   ┌──────────┐        ┌──────────┐     │
│                                   │ REJECTED │        │VALIDATED │     │
│                                   └──────────┘        └──────────┘     │
│                                         │                               │
│                                         └──────▶ Back to DRAFT         │
└─────────────────────────────────────────────────────────────────────────┘

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

Test Template Catalog

Tests can be created from predefined templates sourced from:

1. Atomic Red Team (Red Canary) — imported via the System admin panel
2. Custom templates — created by admins with suggested procedures and remediation
3. MITRE procedures — based on MITRE ATT&CK documentation

Templates include attack procedures, expected detections, suggested tools, severity levels, and suggested remediation steps. When instantiated, these fields are pre-populated into the new test.

Tech Stack

• Backend: FastAPI (Python 3.11)
• Database: PostgreSQL 15
• Object Storage: MinIO (S3-compatible)
• ORM: SQLAlchemy with Alembic migrations
• Frontend: React 19 + TypeScript + Vite + Tailwind CSS v4 + TanStack Query
• Scheduler: APScheduler (MITRE sync, Intel scan, Notification cleanup)

Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Installation

1. Clone the repository:

git clone <repository-url>
cd Aegis

2. Start all services:

docker-compose up -d

3. Run database migrations:

docker exec -w /app aegis-backend-1 alembic upgrade head

4. Seed the admin user:

docker exec -w /app aegis-backend-1 python -m app.seed

5. Start the frontend:

cd frontend && npm install && npm run dev

6. Verify the installation:

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

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

Authentication

JWT-based authentication. Default admin credentials after seeding:

curl -X POST http://localhost:8000/api/v1/auth/login \
  -d "username=admin&password=admin123"

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

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

API Documentation

Interactive API documentation available at:

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

API Endpoints

Auth

Method	Route	Auth	Description
POST	/api/v1/auth/login	Public	Obtain JWT token
GET	/api/v1/auth/me	Authenticated	Current user profile

Techniques

Method	Route	Auth	Description
GET	/api/v1/techniques	Authenticated	List all (filters: tactic, status, review_required)
GET	/api/v1/techniques/{mitre_id}	Authenticated	Detail with associated tests
POST	/api/v1/techniques	Admin	Create technique
PATCH	/api/v1/techniques/{mitre_id}	Admin	Update technique fields
PATCH	/api/v1/techniques/{mitre_id}/review	Lead, Admin	Mark as reviewed

Tests — Red/Blue Workflow

Method	Route	Auth	Description
GET	/api/v1/tests	Authenticated	List with filters (state, technique, platform, creator, pending_validation_side)
POST	/api/v1/tests	Red Tech, Admin	Create test (state=draft)
POST	/api/v1/tests/from-template	Red Tech, Admin	Create from template (pre-populates fields)
GET	/api/v1/tests/{id}	Authenticated	Detail with split red/blue evidences
PATCH	/api/v1/tests/{id}	Creator, Admin	General update (draft/rejected only)
PATCH	/api/v1/tests/{id}/red	Red Tech, Admin	Red Team fields (draft, red_executing)
PATCH	/api/v1/tests/{id}/blue	Blue Tech, Admin	Blue Team fields (blue_evaluating)
PATCH	/api/v1/tests/{id}/remediation	Authenticated	Update remediation fields
POST	/api/v1/tests/{id}/start-execution	Red Tech, Admin	draft → red_executing
POST	/api/v1/tests/{id}/submit-red	Red Tech, Admin	red_executing → blue_evaluating
POST	/api/v1/tests/{id}/submit-blue	Blue Tech, Admin	blue_evaluating → in_review
POST	/api/v1/tests/{id}/validate-red	Red Lead, Admin	Red Lead approves/rejects
POST	/api/v1/tests/{id}/validate-blue	Blue Lead, Admin	Blue Lead approves/rejects
POST	/api/v1/tests/{id}/reopen	Lead, Admin	rejected → draft (clears validation)
GET	/api/v1/tests/{id}/timeline	Authenticated	Audit-log history for this test

Test Templates

Method	Route	Auth	Description
GET	/api/v1/test-templates	Authenticated	List templates (filters: source, platform, severity, search, mitre_technique_id)
POST	/api/v1/test-templates	Admin	Create custom template
GET	/api/v1/test-templates/stats	Admin	Catalog statistics
GET	/api/v1/test-templates/{id}	Authenticated	Template detail
PATCH	/api/v1/test-templates/{id}	Admin	Update template
DELETE	/api/v1/test-templates/{id}	Admin	Soft-delete (deactivate)
POST	/api/v1/test-templates/{id}/toggle-active	Admin	Toggle active/inactive

Evidence

Method	Route	Auth	Description
POST	/api/v1/tests/{test_id}/evidence	Authenticated	Upload evidence (team=red/blue)
GET	/api/v1/evidence/{id}	Authenticated	Metadata + presigned download URL

Notifications

Method	Route	Auth	Description
GET	/api/v1/notifications	Authenticated	List notifications (paginated, limit=20)
GET	/api/v1/notifications/unread-count	Authenticated	Unread notification count
PATCH	/api/v1/notifications/{id}/read	Authenticated	Mark one as read
POST	/api/v1/notifications/read-all	Authenticated	Mark all as read

Reports

Method	Route	Auth	Description
GET	/api/v1/reports/coverage-summary	Authenticated	Full coverage JSON report (filters: tactic, platform)
GET	/api/v1/reports/coverage-csv	Authenticated	CSV export of coverage
GET	/api/v1/reports/test-results	Authenticated	Test results report (filters: state, date_from, date_to)
GET	/api/v1/reports/remediation-status	Authenticated	Remediation status report (filter: status)

Metrics

Method	Route	Auth	Description
GET	/api/v1/metrics/summary	Authenticated	Global coverage summary
GET	/api/v1/metrics/by-tactic	Authenticated	Coverage by MITRE tactic
GET	/api/v1/metrics/test-pipeline	Authenticated	Test counts by pipeline state
GET	/api/v1/metrics/team-activity	Authenticated	Red/Blue team activity
GET	/api/v1/metrics/validation-rate	Authenticated	Approval/rejection rates by lead
GET	/api/v1/metrics/recent-tests	Authenticated	Last 10 updated tests

System (Admin)

Method	Route	Auth	Description
POST	/api/v1/system/sync-mitre	Admin	Trigger MITRE ATT&CK sync
POST	/api/v1/system/run-intel-scan	Admin	Trigger threat-intel RSS scan
POST	/api/v1/system/import-atomic-red-team	Admin	Import Atomic Red Team templates
GET	/api/v1/system/scheduler-status	Admin	Background scheduler health

Users (Admin)

Method	Route	Auth	Description
GET	/api/v1/users	Admin	List all users
POST	/api/v1/users	Admin	Create new user
GET	/api/v1/users/{id}	Admin	Get user by ID
PATCH	/api/v1/users/{id}	Admin	Update user

Audit Logs (Admin)

Method	Route	Auth	Description
GET	/api/v1/audit-logs	Admin	List audit logs (filters: action, entity_type, dates)
GET	/api/v1/audit-logs/actions	Admin	List distinct action types
GET	/api/v1/audit-logs/entity-types	Admin	List distinct entity types

Project Structure

Aegis/
├── docker-compose.yml
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── alembic.ini
│   ├── alembic/versions/         # b001–b007 migration files
│   └── app/
│       ├── main.py               # FastAPI app with all routers
│       ├── config.py             # Settings from environment
│       ├── database.py           # SQLAlchemy engine + session
│       ├── storage.py            # MinIO/S3 helpers
│       ├── models/
│       │   ├── user.py           # User with roles
│       │   ├── technique.py      # MITRE ATT&CK techniques
│       │   ├── test.py           # Tests with Red/Blue + remediation fields
│       │   ├── test_template.py  # Template catalog
│       │   ├── evidence.py       # Evidence files (team-separated)
│       │   ├── notification.py   # In-app notifications
│       │   ├── intel.py          # Threat intelligence
│       │   ├── audit.py          # Audit logging
│       │   └── enums.py          # Shared enumerations
│       ├── schemas/              # Pydantic schemas
│       │   ├── test.py           # TestCreate/Red/Blue/Validate/Remediation
│       │   ├── test_template.py  # Template CRUD schemas
│       │   ├── notification.py   # NotificationOut, UnreadCountOut
│       │   └── metrics.py        # Pipeline, TeamActivity, ValidationRate
│       ├── routers/              # API endpoints
│       │   ├── tests.py          # Full Red/Blue workflow endpoints
│       │   ├── test_templates.py # Template CRUD + import + stats
│       │   ├── notifications.py  # Notification list/read/mark
│       │   ├── reports.py        # Coverage/results/remediation reports
│       │   ├── metrics.py        # V1 + V2 metrics endpoints
│       │   └── ...               # auth, techniques, evidence, system, users, audit
│       ├── services/
│       │   ├── test_workflow_service.py   # State machine + dual validation
│       │   ├── notification_service.py   # Create/read/cleanup notifications
│       │   ├── status_service.py         # Technique status recalculation
│       │   └── ...                       # audit, mitre_sync, intel
│       └── jobs/
│           └── mitre_sync_job.py  # Scheduler: MITRE sync, Intel scan, Notification cleanup
├── frontend/src/
│   ├── App.tsx                   # Routes including /reports
│   ├── api/                      # API clients
│   │   ├── notifications.ts      # Notification API
│   │   ├── reports.ts            # Report API
│   │   └── ...
│   ├── components/
│   │   ├── Layout.tsx            # Sidebar + header + NotificationBell
│   │   ├── Sidebar.tsx           # Collapsible nav with admin section
│   │   ├── NotificationBell.tsx  # Bell icon with badge (polls every 30s)
│   │   ├── NotificationDropdown.tsx # Notification list dropdown
│   │   ├── ConfirmDialog.tsx     # Reusable confirmation modal
│   │   ├── Toast.tsx             # Toast notification system
│   │   └── test-detail/          # Test detail sub-components
│   └── pages/
│       ├── DashboardPage.tsx     # Pipeline funnel, team activity, validation rates
│       ├── TestsPage.tsx         # Filters, state counters, pending tasks
│       ├── TestDetailPage.tsx    # Red/Blue tabs, validation, evidence
│       ├── TestCatalogPage.tsx   # Browse & use templates
│       ├── ReportsPage.tsx       # Coverage, results, remediation reports
│       └── SystemPage.tsx        # Template admin, import Atomic Red Team
└── backend/tests/                # Test suite
    ├── 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

Database Schema

Table	Description
users	User accounts with role-based access
techniques	MITRE ATT&CK techniques with coverage status
tests	Security tests with Red/Blue fields, dual validation, and remediation
test_templates	Predefined test catalog (Atomic Red Team, custom)
evidences	File evidence separated by team (red/blue)
notifications	In-app notifications with read status
intel_items	Threat intelligence items linked to techniques
audit_logs	System-wide audit trail

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

Development

Running Migrations

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

Running Tests

# Run standalone tests (no database required)
cd backend && python tests/test_workflow.py
cd backend && python tests/test_templates_crud.py
cd backend && python tests/test_metrics_v2.py
cd backend && python tests/test_integration_v2.py

# Run with pytest (requires PostgreSQL)
docker exec -w /app aegis-backend-1 pytest -v

License

This project is proprietary software. All rights reserved.