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:
```bash
git clone <repository-url>
cd Aegis
```

2. Start all services:
```bash
docker-compose up -d
```

3. Run database migrations:
```bash
docker exec -w /app aegis-backend-1 alembic upgrade head
```

4. Seed the admin user:
```bash
docker exec -w /app aegis-backend-1 python -m app.seed
```

5. Verify the installation:
```bash
# 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:

```bash
# 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 |
| GET | `/api/v1/system/scheduler-status` | Admin | Background scheduler health & job list |

## 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
│       ├── dependencies/       # FastAPI dependencies (DI)
│       │   └── auth.py         # get_current_user, require_role, require_any_role
│       ├── jobs/               # Background scheduled jobs
│       │   └── mitre_sync_job.py  # APScheduler job: sync MITRE every 24h
│       └── 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
└── 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

```bash
# 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.