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.

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 + TypeScript + Vite (coming soon)

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. Verify the installation:

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

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

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
│       ├── 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 frontend (coming soon)

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

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.