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:
145
README.md
Normal file
145
README.md
Normal 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.
|
||||
Reference in New Issue
Block a user