feat(phase-20): navigation, error handling, integration tests, and V2 docs (T-132 to T-135)
This commit is contained in:
410
README.md
410
README.md
@@ -1,16 +1,79 @@
|
||||
# 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.
|
||||
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 through a structured Red Team / Blue Team validation workflow.
|
||||
|
||||
## Features
|
||||
|
||||
- **MITRE ATT&CK Integration**: Automatic synchronization with the MITRE ATT&CK framework via TAXII (with GitHub fallback), scheduled every 24h
|
||||
- **Red/Blue Validation Workflow**: Structured dual-validation lifecycle for security tests (draft → red_executing → blue_evaluating → in_review → validated/rejected)
|
||||
- **Test Template Catalog**: Import tests from Atomic Red Team, create custom templates, and instantiate real tests from them
|
||||
- **Dual Validation**: Independent approval/rejection by Red Lead and Blue Lead before a test is finalized
|
||||
- **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
|
||||
- **Evidence Storage**: Secure evidence file storage with SHA256 integrity verification, separated by team (red/blue)
|
||||
- **In-App Notifications**: Real-time notification bell with polling, automatic alerts on state changes
|
||||
- **Reports & Export**: Coverage summary, test results, and remediation reports in JSON and CSV formats
|
||||
- **Remediation Tracking**: Step-by-step remediation assignments with status tracking per test
|
||||
- **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
|
||||
- **Metrics Dashboard**: Pipeline funnel, team activity, validation rates, and recent tests
|
||||
|
||||
## Red Team / Blue Team Validation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ TEST LIFECYCLE │
|
||||
│ │
|
||||
│ ┌──────┐ ┌──────────────┐ ┌─────────────────┐ ┌───────────┐ │
|
||||
│ │ DRAFT│───▶│RED_EXECUTING │───▶│ BLUE_EVALUATING │───▶│ IN_REVIEW │ │
|
||||
│ └──────┘ └──────────────┘ └─────────────────┘ └───────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────┤ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ REJECTED │ │VALIDATED │ │
|
||||
│ └──────────┘ └──────────┘ │
|
||||
│ │ │
|
||||
│ └──────▶ Back to DRAFT │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### States
|
||||
|
||||
| State | Description | Who acts |
|
||||
|-------|-------------|----------|
|
||||
| `draft` | Created, pending execution | Red Tech |
|
||||
| `red_executing` | Red Team documents attack & uploads evidence | Red Tech |
|
||||
| `blue_evaluating` | Blue Team documents detection & uploads evidence | Blue Tech |
|
||||
| `in_review` | Both managers review evidence | Red Lead, Blue Lead |
|
||||
| `validated` | Approved by both managers | — (terminal) |
|
||||
| `rejected` | Rejected — returns to draft for redo | Red/Blue Lead can reopen |
|
||||
|
||||
### Dual Validation
|
||||
|
||||
Both Red Lead and Blue Lead must independently vote:
|
||||
- **Both approve** → test moves to `validated`
|
||||
- **Either rejects** → test moves to `rejected`
|
||||
- **One votes, other pending** → stays in `in_review`
|
||||
|
||||
## User Roles
|
||||
|
||||
| Role | Description | Capabilities |
|
||||
|------|-------------|-------------|
|
||||
| `admin` | Full system access | Everything |
|
||||
| `red_tech` | Red team technician | Create tests, document attacks, upload red evidence |
|
||||
| `blue_tech` | Blue team technician | Document detection, upload blue evidence |
|
||||
| `red_lead` | Red team lead | Validate/reject the red side of tests |
|
||||
| `blue_lead` | Blue team lead | Validate/reject the blue side of tests |
|
||||
| `viewer` | Read-only access | View all data |
|
||||
|
||||
## Test Template Catalog
|
||||
|
||||
Tests can be created from predefined templates sourced from:
|
||||
1. **Atomic Red Team** (Red Canary) — imported via the System admin panel
|
||||
2. **Custom templates** — created by admins with suggested procedures and remediation
|
||||
3. **MITRE procedures** — based on MITRE ATT&CK documentation
|
||||
|
||||
Templates include attack procedures, expected detections, suggested tools, severity levels, and suggested remediation steps. When instantiated, these fields are pre-populated into the new test.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
@@ -19,6 +82,7 @@ Aegis is a comprehensive platform for tracking and managing security coverage ag
|
||||
- **Object Storage**: MinIO (S3-compatible)
|
||||
- **ORM**: SQLAlchemy with Alembic migrations
|
||||
- **Frontend**: React 19 + TypeScript + Vite + Tailwind CSS v4 + TanStack Query
|
||||
- **Scheduler**: APScheduler (MITRE sync, Intel scan, Notification cleanup)
|
||||
|
||||
## Quick Start
|
||||
|
||||
@@ -50,54 +114,43 @@ docker exec -w /app aegis-backend-1 alembic upgrade head
|
||||
docker exec -w /app aegis-backend-1 python -m app.seed
|
||||
```
|
||||
|
||||
5. Start the frontend (requires Node.js 20+ or Docker):
|
||||
5. Start the frontend:
|
||||
```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
|
||||
# Open http://localhost:5173 — Aegis login page
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
The platform uses JWT-based authentication. After seeding, log in with the default admin credentials:
|
||||
JWT-based authentication. Default admin credentials after seeding:
|
||||
|
||||
```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 |
|
||||
|----------|------|-------------|
|
||||
| Service | Port | Description |
|
||||
|---------|------|-------------|
|
||||
| Frontend | 5173 | React dev server (Vite) |
|
||||
| Backend | 8000 | FastAPI REST API |
|
||||
| PostgreSQL | 5433 | Database (mapped to 5433 to avoid conflicts) |
|
||||
| Backend | 8000 | FastAPI REST API |
|
||||
| PostgreSQL | 5433 | Database |
|
||||
| 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:
|
||||
Interactive API documentation available at:
|
||||
|
||||
- **Swagger UI**: http://localhost:8000/docs
|
||||
- **ReDoc**: http://localhost:8000/redoc
|
||||
@@ -113,39 +166,81 @@ Once the backend is running, access the interactive API documentation at:
|
||||
### Techniques
|
||||
| Method | Route | Auth | Description |
|
||||
|--------|-------|------|-------------|
|
||||
| GET | `/api/v1/techniques` | Authenticated | List all (filters: `?tactic=`, `?status=`, `?review_required=`) |
|
||||
| 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
|
||||
### Tests — Red/Blue Workflow
|
||||
| Method | Route | Auth | Description |
|
||||
|--------|-------|------|-------------|
|
||||
| GET | `/api/v1/tests` | Authenticated | List with filters (state, technique, platform, creator, pending_validation_side) |
|
||||
| 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 |
|
||||
| POST | `/api/v1/tests/from-template` | Red Tech, Admin | Create from template (pre-populates fields) |
|
||||
| GET | `/api/v1/tests/{id}` | Authenticated | Detail with split red/blue evidences |
|
||||
| PATCH | `/api/v1/tests/{id}` | Creator, Admin | General update (draft/rejected only) |
|
||||
| PATCH | `/api/v1/tests/{id}/red` | Red Tech, Admin | Red Team fields (draft, red_executing) |
|
||||
| PATCH | `/api/v1/tests/{id}/blue` | Blue Tech, Admin | Blue Team fields (blue_evaluating) |
|
||||
| PATCH | `/api/v1/tests/{id}/remediation` | Authenticated | Update remediation fields |
|
||||
| POST | `/api/v1/tests/{id}/start-execution` | Red Tech, Admin | draft → red_executing |
|
||||
| POST | `/api/v1/tests/{id}/submit-red` | Red Tech, Admin | red_executing → blue_evaluating |
|
||||
| POST | `/api/v1/tests/{id}/submit-blue` | Blue Tech, Admin | blue_evaluating → in_review |
|
||||
| POST | `/api/v1/tests/{id}/validate-red` | Red Lead, Admin | Red Lead approves/rejects |
|
||||
| POST | `/api/v1/tests/{id}/validate-blue` | Blue Lead, Admin | Blue Lead approves/rejects |
|
||||
| POST | `/api/v1/tests/{id}/reopen` | Lead, Admin | rejected → draft (clears validation) |
|
||||
| GET | `/api/v1/tests/{id}/timeline` | Authenticated | Audit-log history for this test |
|
||||
|
||||
### Test Templates
|
||||
| Method | Route | Auth | Description |
|
||||
|--------|-------|------|-------------|
|
||||
| GET | `/api/v1/test-templates` | Authenticated | List templates (filters: source, platform, severity, search, mitre_technique_id) |
|
||||
| POST | `/api/v1/test-templates` | Admin | Create custom template |
|
||||
| GET | `/api/v1/test-templates/stats` | Admin | Catalog statistics |
|
||||
| GET | `/api/v1/test-templates/{id}` | Authenticated | Template detail |
|
||||
| PATCH | `/api/v1/test-templates/{id}` | Admin | Update template |
|
||||
| DELETE | `/api/v1/test-templates/{id}` | Admin | Soft-delete (deactivate) |
|
||||
| POST | `/api/v1/test-templates/{id}/toggle-active` | Admin | Toggle active/inactive |
|
||||
|
||||
### 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 |
|
||||
| POST | `/api/v1/tests/{test_id}/evidence` | Authenticated | Upload evidence (team=red/blue) |
|
||||
| GET | `/api/v1/evidence/{id}` | Authenticated | Metadata + presigned download URL |
|
||||
|
||||
### System
|
||||
### Notifications
|
||||
| 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 |
|
||||
| GET | `/api/v1/notifications` | Authenticated | List notifications (paginated, limit=20) |
|
||||
| GET | `/api/v1/notifications/unread-count` | Authenticated | Unread notification count |
|
||||
| PATCH | `/api/v1/notifications/{id}/read` | Authenticated | Mark one as read |
|
||||
| POST | `/api/v1/notifications/read-all` | Authenticated | Mark all as read |
|
||||
|
||||
### Reports
|
||||
| Method | Route | Auth | Description |
|
||||
|--------|-------|------|-------------|
|
||||
| GET | `/api/v1/reports/coverage-summary` | Authenticated | Full coverage JSON report (filters: tactic, platform) |
|
||||
| GET | `/api/v1/reports/coverage-csv` | Authenticated | CSV export of coverage |
|
||||
| GET | `/api/v1/reports/test-results` | Authenticated | Test results report (filters: state, date_from, date_to) |
|
||||
| GET | `/api/v1/reports/remediation-status` | Authenticated | Remediation status report (filter: status) |
|
||||
|
||||
### 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 |
|
||||
| GET | `/api/v1/metrics/summary` | Authenticated | Global coverage summary |
|
||||
| GET | `/api/v1/metrics/by-tactic` | Authenticated | Coverage by MITRE tactic |
|
||||
| GET | `/api/v1/metrics/test-pipeline` | Authenticated | Test counts by pipeline state |
|
||||
| GET | `/api/v1/metrics/team-activity` | Authenticated | Red/Blue team activity |
|
||||
| GET | `/api/v1/metrics/validation-rate` | Authenticated | Approval/rejection rates by lead |
|
||||
| GET | `/api/v1/metrics/recent-tests` | Authenticated | Last 10 updated tests |
|
||||
|
||||
### System (Admin)
|
||||
| Method | Route | Auth | Description |
|
||||
|--------|-------|------|-------------|
|
||||
| POST | `/api/v1/system/sync-mitre` | Admin | Trigger MITRE ATT&CK sync |
|
||||
| POST | `/api/v1/system/run-intel-scan` | Admin | Trigger threat-intel RSS scan |
|
||||
| POST | `/api/v1/system/import-atomic-red-team` | Admin | Import Atomic Red Team templates |
|
||||
| GET | `/api/v1/system/scheduler-status` | Admin | Background scheduler health |
|
||||
|
||||
### Users (Admin)
|
||||
| Method | Route | Auth | Description |
|
||||
@@ -153,12 +248,12 @@ Once the backend is running, access the interactive API documentation at:
|
||||
| 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) |
|
||||
| PATCH | `/api/v1/users/{id}` | Admin | Update user |
|
||||
|
||||
### 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` | Admin | List audit logs (filters: action, entity_type, dates) |
|
||||
| GET | `/api/v1/audit-logs/actions` | Admin | List distinct action types |
|
||||
| GET | `/api/v1/audit-logs/entity-types` | Admin | List distinct entity types |
|
||||
|
||||
@@ -166,200 +261,123 @@ Once the backend is running, access the interactive API documentation at:
|
||||
|
||||
```
|
||||
Aegis/
|
||||
├── docker-compose.yml # Docker services configuration
|
||||
├── docker-compose.yml
|
||||
├── backend/
|
||||
│ ├── Dockerfile # Backend container definition
|
||||
│ ├── requirements.txt # Python dependencies
|
||||
│ ├── alembic.ini # Alembic configuration
|
||||
│ ├── alembic/ # Database migrations
|
||||
│ │ ├── env.py
|
||||
│ │ ├── versions/ # Migration files
|
||||
│ │ └── ...
|
||||
│ ├── Dockerfile
|
||||
│ ├── requirements.txt
|
||||
│ ├── alembic.ini
|
||||
│ ├── alembic/versions/ # b001–b007 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/
|
||||
│ ├── main.py # FastAPI app with all routers
|
||||
│ ├── config.py # Settings from environment
|
||||
│ ├── database.py # SQLAlchemy engine + session
|
||||
│ ├── storage.py # MinIO/S3 helpers
|
||||
│ ├── models/
|
||||
│ │ ├── user.py # User with roles
|
||||
│ │ ├── technique.py # MITRE ATT&CK techniques
|
||||
│ │ ├── test.py # Tests with Red/Blue + remediation fields
|
||||
│ │ ├── test_template.py # Template catalog
|
||||
│ │ ├── evidence.py # Evidence files (team-separated)
|
||||
│ │ ├── notification.py # In-app notifications
|
||||
│ │ ├── intel.py # Threat intelligence
|
||||
│ │ ├── audit.py # Audit logging
|
||||
│ │ └── enums.py # Shared enumerations
|
||||
│ ├── schemas/ # Pydantic schemas
|
||||
│ │ ├── test.py # TestCreate/Red/Blue/Validate/Remediation
|
||||
│ │ ├── test_template.py # Template CRUD schemas
|
||||
│ │ ├── notification.py # NotificationOut, UnreadCountOut
|
||||
│ │ └── metrics.py # Pipeline, TeamActivity, ValidationRate
|
||||
│ ├── routers/ # API endpoints
|
||||
│ │ ├── tests.py # Full Red/Blue workflow endpoints
|
||||
│ │ ├── test_templates.py # Template CRUD + import + stats
|
||||
│ │ ├── notifications.py # Notification list/read/mark
|
||||
│ │ ├── reports.py # Coverage/results/remediation reports
|
||||
│ │ ├── metrics.py # V1 + V2 metrics endpoints
|
||||
│ │ └── ... # auth, techniques, evidence, system, users, audit
|
||||
│ ├── services/
|
||||
│ │ ├── test_workflow_service.py # State machine + dual validation
|
||||
│ │ ├── notification_service.py # Create/read/cleanup notifications
|
||||
│ │ ├── status_service.py # Technique status recalculation
|
||||
│ │ └── ... # audit, mitre_sync, intel
|
||||
│ └── jobs/
|
||||
│ └── mitre_sync_job.py # Scheduler: MITRE sync, Intel scan, Notification cleanup
|
||||
├── frontend/src/
|
||||
│ ├── App.tsx # Routes including /reports
|
||||
│ ├── api/ # API clients
|
||||
│ │ ├── notifications.ts # Notification API
|
||||
│ │ ├── reports.ts # Report API
|
||||
│ │ └── ...
|
||||
│ ├── components/
|
||||
│ │ ├── Layout.tsx # Sidebar + header + NotificationBell
|
||||
│ │ ├── Sidebar.tsx # Collapsible nav with admin section
|
||||
│ │ ├── NotificationBell.tsx # Bell icon with badge (polls every 30s)
|
||||
│ │ ├── NotificationDropdown.tsx # Notification list dropdown
|
||||
│ │ ├── ConfirmDialog.tsx # Reusable confirmation modal
|
||||
│ │ ├── Toast.tsx # Toast notification system
|
||||
│ │ └── test-detail/ # Test detail sub-components
|
||||
│ └── pages/
|
||||
│ ├── DashboardPage.tsx # Pipeline funnel, team activity, validation rates
|
||||
│ ├── TestsPage.tsx # Filters, state counters, pending tasks
|
||||
│ ├── TestDetailPage.tsx # Red/Blue tabs, validation, evidence
|
||||
│ ├── TestCatalogPage.tsx # Browse & use templates
|
||||
│ ├── ReportsPage.tsx # Coverage, results, remediation reports
|
||||
│ └── SystemPage.tsx # Template admin, import Atomic Red Team
|
||||
└── backend/tests/ # Test suite
|
||||
├── test_workflow.py # Red/Blue workflow tests
|
||||
├── test_templates_crud.py # Template CRUD tests
|
||||
├── test_metrics_v2.py # V2 metrics tests
|
||||
└── test_integration_v2.py # Full integration E2E tests
|
||||
```
|
||||
|
||||
## 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) |
|
||||
| `tests` | Security tests with Red/Blue fields, dual validation, and remediation |
|
||||
| `test_templates` | Predefined test catalog (Atomic Red Team, custom) |
|
||||
| `evidences` | File evidence separated by team (red/blue) |
|
||||
| `notifications` | In-app notifications with read status |
|
||||
| `intel_items` | Threat intelligence items linked to techniques |
|
||||
| `audit_logs` | System-wide audit trail for all actions |
|
||||
| `audit_logs` | System-wide audit trail |
|
||||
|
||||
## Configuration
|
||||
|
||||
The application can be configured via environment variables:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `DATABASE_URL` | `postgresql://postgres:postgres@postgres:5432/attackdb` | PostgreSQL connection string |
|
||||
| `DATABASE_URL` | `postgresql://postgres:postgres@postgres:5432/attackdb` | PostgreSQL connection |
|
||||
| `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 |
|
||||
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `60` | Token lifetime |
|
||||
| `MINIO_ENDPOINT` | `minio:9000` | MinIO server |
|
||||
| `MINIO_ACCESS_KEY` | `minioadmin` | MinIO access key |
|
||||
| `MINIO_SECRET_KEY` | `minioadmin` | MinIO secret key |
|
||||
| `MINIO_BUCKET` | `evidence` | Bucket for evidence files |
|
||||
| `MINIO_BUCKET` | `evidence` | Evidence bucket |
|
||||
|
||||
## 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 revision --autogenerate -m "description"
|
||||
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 standalone tests (no database required)
|
||||
cd backend && python tests/test_workflow.py
|
||||
cd backend && python tests/test_templates_crud.py
|
||||
cd backend && python tests/test_metrics_v2.py
|
||||
cd backend && python tests/test_integration_v2.py
|
||||
|
||||
# Run all tests
|
||||
docker exec -w /app aegis-backend-1 pytest
|
||||
|
||||
# Run tests with verbose output
|
||||
# Run with pytest (requires PostgreSQL)
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user