Files

Kitos ec65991ac1 feat: Phase 1 - Data models and migrations (T-004 to T-009)

Implements all database models for the Aegis platform with full
Alembic migration support.

Models created:
- User: Authentication with role-based access control
- Technique: MITRE ATT&CK techniques with coverage status tracking
- Test: Security tests with validation workflow (draft/review/validated)
- Evidence: File metadata for test evidence (stored in MinIO)
- IntelItem: Threat intelligence items linked to techniques
- AuditLog: System-wide audit trail with JSONB details

Enumerations:
- TechniqueStatus: not_evaluated, in_progress, validated, partial, etc.
- TestState: draft, in_review, validated, rejected
- TestResult: detected, not_detected, partially_detected

Services:
- audit_service.py: log_action() helper for audit logging

All models include proper foreign key relationships and PostgreSQL
enum types are managed correctly in migrations (create/drop).

2026-02-06 12:26:26 +01:00

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

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

Clone the repository:

git clone <repository-url>
cd Aegis

Start all services:

docker-compose up -d

Run database migrations:

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

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
│       ├── 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
│       └── services/       # Business logic services
│           └── audit_service.py
└── 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
`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

Contributing

Please read the contribution guidelines before submitting pull requests.

5.5 KiB Raw Blame History