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 19 + TypeScript + Vite + Tailwind CSS v4 + TanStack Query

## 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. Start the frontend (requires Node.js 20+ or Docker):
```bash
# 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:
```bash
# 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:

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

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

### Running Tests

The backend includes a test suite using pytest:

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