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.

Features

• MITRE ATT&CK Integration: Automatic synchronization with the MITRE ATT&CK framework via TAXII (with GitHub fallback), scheduled every 24h
• Coverage Tracking: Track validation status for each technique (validated, partial, not covered, in progress)
• Test Management: Document and manage security tests with full audit trail
• Evidence Storage: Secure evidence file storage with SHA256 integrity verification
• 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: Real-time coverage metrics and reporting by tactic

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

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 (requires Node.js 20+ or Docker):

# Option A — with Node.js installed locally
cd frontend && npm install && npm run dev

# Option B — via Docker
docker run --rm -v ./frontend:/app -w /app -p 5173:5173 node:20-alpine sh -c "npm run dev"

6. Verify the installation:

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

# Frontend
# Open http://localhost:5173 — should show the Aegis login page

Authentication

The platform uses JWT-based authentication. After seeding, log in with the default admin credentials:

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

# Use the token to access protected endpoints
curl http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer <your-token>"

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 (mapped to 5433 to avoid conflicts)
MinIO API	9000	S3-compatible object storage
MinIO Console	9001	MinIO web interface

API Documentation

Once the backend is running, access the interactive API documentation 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

Method	Route	Auth	Description
POST	/api/v1/tests	Red Tech, Admin	Create test (state=draft)
GET	/api/v1/tests/{id}	Authenticated	Detail with evidences
PATCH	/api/v1/tests/{id}	Creator, Admin	Update (only draft/rejected)
POST	/api/v1/tests/{id}/validate	Lead, Admin	Validate + recalculate technique status
POST	/api/v1/tests/{id}/reject	Lead, Admin	Reject test

Evidence

Method	Route	Auth	Description
POST	/api/v1/tests/{test_id}/evidence	Authenticated	Upload evidence file (SHA-256 verified)
GET	/api/v1/evidence/{id}	Authenticated	Get metadata + presigned download URL

System

Method	Route	Auth	Description
POST	/api/v1/system/sync-mitre	Admin	Manually trigger MITRE ATT&CK sync
POST	/api/v1/system/run-intel-scan	Admin	Manually trigger threat-intel RSS scan
GET	/api/v1/system/scheduler-status	Admin	Background scheduler health & job list

Metrics

Method	Route	Auth	Description
GET	/api/v1/metrics/summary	Authenticated	Global coverage summary (counts + percentage)
GET	/api/v1/metrics/by-tactic	Authenticated	Coverage breakdown per MITRE tactic

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 (role, email, active status)

Audit Logs (Admin)

Method	Route	Auth	Description
GET	/api/v1/audit-logs	Admin	List audit logs (filters: ?action=, ?entity_type=, ?start_date=, ?end_date=)
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          # Docker services configuration
├── backend/
│   ├── Dockerfile              # Backend container definition
│   ├── requirements.txt        # Python dependencies
│   ├── alembic.ini             # Alembic configuration
│   ├── alembic/                # Database migrations
│   │   ├── env.py
│   │   ├── versions/           # Migration files
│   │   └── ...
│   └── app/
│       ├── __init__.py
│       ├── main.py             # FastAPI application entry point
│       ├── config.py           # Application settings
│       ├── database.py         # SQLAlchemy configuration
│       ├── auth.py             # Password hashing & JWT utilities
│       ├── seed.py             # Admin seed script (python -m app.seed)
│       ├── models/             # SQLAlchemy models
│       │   ├── user.py         # User authentication model
│       │   ├── technique.py    # MITRE ATT&CK techniques
│       │   ├── test.py         # Security tests
│       │   ├── evidence.py     # Test evidence files
│       │   ├── intel.py        # Threat intelligence items
│       │   ├── audit.py        # Audit logging
│       │   └── enums.py        # Shared enumerations
│       ├── storage.py          # MinIO/S3 client (upload, presigned URLs)
│       ├── schemas/            # Pydantic request/response schemas
│       │   ├── auth.py         # LoginRequest, TokenResponse, UserOut
│       │   ├── technique.py    # TechniqueCreate/Update/Out/Summary
│       │   ├── test.py         # TestCreate/Update/Out/Validate
│       │   └── evidence.py     # EvidenceOut
│       ├── routers/            # API endpoint routers
│       │   ├── auth.py         # POST /auth/login, GET /auth/me
│       │   ├── techniques.py   # CRUD techniques (list, detail, create, update, review)
│       │   ├── tests.py        # CRUD tests (create, detail, update, validate, reject)
│       │   ├── evidence.py     # Upload evidence, presigned download
│       │   ├── system.py       # MITRE sync trigger, scheduler status
│       │   ├── metrics.py      # Coverage summary & per-tactic breakdown
│       │   ├── users.py        # User management (admin only)
│       │   └── audit.py        # Audit log viewer (admin only)
│       ├── dependencies/       # FastAPI dependencies (DI)
│       │   └── auth.py         # get_current_user, require_role, require_any_role
│       ├── jobs/               # Background scheduled jobs
│       │   └── mitre_sync_job.py  # APScheduler: MITRE sync (24h) + Intel scan (7d)
│       └── services/           # Business logic services
│           ├── audit_service.py
│           ├── status_service.py  # Recalculate technique status from tests
│           ├── mitre_sync_service.py  # MITRE ATT&CK sync via TAXII / GitHub
│           └── intel_service.py   # Automated intel scan via RSS feeds
└── frontend/                   # React + TypeScript frontend
    ├── index.html
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    └── src/
        ├── main.tsx              # App entry point
        ├── App.tsx               # Route definitions
        ├── index.css             # Tailwind CSS entry
        ├── api/                  # Axios clients
        │   ├── client.ts         # Base axios instance with JWT interceptor
        │   ├── auth.ts           # login(), getMe()
        │   ├── metrics.ts        # getCoverageSummary(), getCoverageByTactic()
        │   ├── techniques.ts     # getTechniques(), getTechniqueByMitreId()
        │   ├── tests.ts          # createTest(), validateTest(), rejectTest()
        │   ├── evidence.ts       # uploadEvidence(), getEvidence()
        │   ├── system.ts         # triggerMitreSync(), triggerIntelScan()
        │   ├── users.ts          # getUsers(), createUser(), updateUser()
        │   └── audit.ts          # getAuditLogs(), getAuditActions()
        ├── context/
        │   └── AuthContext.tsx    # Auth state: user, login, logout, isLoading
        ├── components/
        │   ├── Layout.tsx              # Sidebar + header + <Outlet/>
        │   ├── Sidebar.tsx             # Nav links (role-aware)
        │   ├── ProtectedRoute.tsx      # Auth route guard with role support
        │   ├── CoverageSummaryCard.tsx # Metric card component
        │   ├── TacticCoverageChart.tsx # Coverage breakdown table
        │   ├── AttackMatrix.tsx        # Interactive technique grid
        │   ├── TechniqueCell.tsx       # Individual technique cell in matrix
        │   ├── TestForm.tsx            # Reusable test creation/edit form
        │   ├── EvidenceUpload.tsx      # Drag & drop file upload
        │   ├── EvidenceList.tsx        # Evidence file listing
        │   ├── ErrorBoundary.tsx       # Global error boundary
        │   ├── ErrorMessage.tsx        # Reusable error display
        │   ├── LoadingSpinner.tsx      # Reusable loading indicator
        │   └── Toast.tsx               # Toast notification system
        ├── pages/
        │   ├── LoginPage.tsx           # User authentication form
        │   ├── DashboardPage.tsx       # Coverage metrics dashboard with summary cards
        │   ├── TechniquesPage.tsx      # Interactive ATT&CK matrix view with filters
        │   ├── TechniqueDetailPage.tsx # Individual technique detail with tests
        │   ├── TestsPage.tsx           # Tests overview and navigation
        │   ├── TestCreatePage.tsx      # Test creation form
        │   ├── TestDetailPage.tsx      # Test details with evidence upload
        │   ├── SystemPage.tsx          # Admin panel for MITRE sync & intel scan
        │   ├── UsersPage.tsx           # User management (admin only)
        │   └── AuditLogPage.tsx        # Audit log viewer (admin only)
        ├── types/
        │   └── models.ts         # TS interfaces matching backend schemas
        ├── hooks/
        └── lib/

Database Schema

The platform uses the following data models:

Table	Description
users	User accounts with role-based access
techniques	MITRE ATT&CK techniques with coverage status
tests	Security tests validating technique coverage
evidences	File evidence attached to tests (stored in MinIO)
intel_items	Threat intelligence items linked to techniques
audit_logs	System-wide audit trail for all actions

Configuration

The application can be configured via environment variables:

Variable	Default	Description
DATABASE_URL	postgresql://postgres:postgres@postgres:5432/attackdb	PostgreSQL connection string
SECRET_KEY	change-me-in-production	JWT signing key
ALGORITHM	HS256	JWT signing algorithm
ACCESS_TOKEN_EXPIRE_MINUTES	60	JWT token lifetime in minutes
MINIO_ENDPOINT	minio:9000	MinIO server endpoint
MINIO_ACCESS_KEY	minioadmin	MinIO access key
MINIO_SECRET_KEY	minioadmin	MinIO secret key
MINIO_BUCKET	evidence	Bucket for evidence files

Development

Running Migrations

# Generate a new migration after model changes
docker exec -w /app aegis-backend-1 alembic revision --autogenerate -m "description"

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

# Rollback one migration
docker exec -w /app aegis-backend-1 alembic downgrade -1

# Check current migration
docker exec -w /app aegis-backend-1 alembic current

Accessing Services

• MinIO Console: http://localhost:9001 (login: minioadmin / minioadmin)
• PostgreSQL: psql -h localhost -p 5433 -U postgres -d attackdb

Running Tests

The backend includes a test suite using pytest:

# Install test dependencies (if running locally)
pip install pytest pytest-asyncio httpx

# Run all tests
docker exec -w /app aegis-backend-1 pytest

# Run tests with verbose output
docker exec -w /app aegis-backend-1 pytest -v

# Run specific test file
docker exec -w /app aegis-backend-1 pytest tests/test_auth.py

# Run locally (requires SQLite)
cd backend && pytest

Test files:

• test_health.py - Health endpoint tests
• test_auth.py - Authentication and authorization tests
• test_techniques.py - Technique CRUD tests
• test_tests.py - Security test CRUD and validation tests

User Roles

Role	Description
admin	Full system access
red_tech	Red team technician - can create and edit tests
blue_tech	Blue team technician - can create and edit tests
red_lead	Red team lead - can validate tests
blue_lead	Blue team lead - can validate tests
viewer	Read-only access

License

This project is proprietary software. All rights reserved.

Contributing

Please read the contribution guidelines before submitting pull requests.