feat: Phase 0 - Infrastructure and scaffolding (T-001 to T-003)

This commit establishes the foundational infrastructure for the Aegis
MITRE ATT&CK Coverage Platform.

T-001: Initialize project and Docker Compose
- Set up Docker Compose with PostgreSQL 15, MinIO, and FastAPI backend
- Create basic FastAPI application with health endpoint
- Configure persistent volumes for data storage

T-002: Configuration and database connection
- Add centralized configuration using pydantic-settings
- Implement SQLAlchemy database connection with session management
- Configure MinIO and JWT settings

T-003: Initialize Alembic for migrations
- Set up Alembic with PostgreSQL connection from settings
- Create initial empty migration
- Configure autogenerate support for future models

Also includes:
- Professional README with setup instructions
- Comprehensive .gitignore for Python/Node/Docker
- Project task plan (AegisTestPlan.md)
This commit is contained in:
2026-02-06 11:28:30 +01:00
commit b479acdea0
16 changed files with 1788 additions and 0 deletions

145
README.md Normal file
View File

@@ -0,0 +1,145 @@
# 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:
```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. Verify the installation:
```bash
# 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
```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.