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

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

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

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
└── frontend/               # React frontend (coming soon)

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