fix(security): replace python-jose with PyJWT to eliminate ecdsa CVEs

Snyk scan found 3 High severity vulns: two in ecdsa (pulled by python-jose)
and one in diskcache (pulled by pySigma, never imported). Remove both
vulnerable dependencies and migrate JWT handling to PyJWT. Fix
test_logout_revokes_token which broke because test stubs sys.modules[jose]
with a MagicMock at collection time; test now uses PyJWT directly.

.cursor/rules/aegis-architecture.md

@@ -0,0 +1,189 @@
+---
+description: Aegis backend Clean Architecture rules. Apply when working on any backend Python file under backend/app/ or backend/tests/.
+globs: backend/**/*.py
+---
+
+# Aegis — Clean Modular Monolith Architecture
+
+## Architecture Overview
+
+Aegis follows a **Clean Architecture** pattern inside a modular monolith. The backend has four layers with strict dependency rules:
+
+```
+Presentation → Application → Domain ← Infrastructure
+```
+
+**The golden rule:** dependencies only point towards the Domain layer. Infrastructure implements the ports (interfaces) defined in Domain.
+
+## Layer Structure and Rules
+
+### Domain Layer (`backend/app/domain/`)
+
+The innermost layer. **ZERO** imports from FastAPI, SQLAlchemy, Pydantic, or any framework.
+
+| Directory | Purpose |
+|-----------|---------|
+| `domain/enums.py` | Canonical domain enums (TechniqueStatus, TestState, TeamSide, TestResult) |
+| `domain/errors.py` | Exception hierarchy (DomainError → EntityNotFoundError, InvalidStateTransition, etc.) |
+| `domain/exceptions.py` | Backward-compatible re-exports from errors.py |
+| `domain/test_entity.py` | TestEntity — pure state machine with domain events |
+| `domain/entities/` | Rich domain entities (TechniqueEntity, etc.) with business behavior |
+| `domain/value_objects/` | Immutable value types (MitreId, ScoringWeights) |
+| `domain/ports/repositories/` | Protocol interfaces defining data access contracts |
+| `domain/ports/services/` | Protocol interfaces for external capabilities (storage, events) |
+| `domain/unit_of_work.py` | UnitOfWork wrapping SQLAlchemy session |
+
+**NEVER** import from `app.models`, `app.routers`, `app.infrastructure`, `fastapi`, or `sqlalchemy` inside `domain/`.
+
+### Application Layer (`backend/app/application/` — future)
+
+Use case orchestrators. Depends only on Domain.
+
+| Directory | Purpose |
+|-----------|---------|
+| `application/use_cases/` | One class per business operation |
+| `application/dto/` | Plain data containers for use case input/output |
+| `application/interfaces/` | Application-level contracts (UnitOfWork protocol) |
+
+### Infrastructure Layer (`backend/app/infrastructure/`)
+
+Implements ports defined in Domain. Depends on Domain and Application.
+
+| Directory | Purpose |
+|-----------|---------|
+| `infrastructure/redis_client.py` | Redis connection singleton |
+| `infrastructure/persistence/repositories/` | SQLAlchemy implementations of repository ports |
+| `infrastructure/persistence/mappers/` | ORM model ↔ domain entity converters |
+
+### Presentation Layer (routers, schemas, dependencies)
+
+HTTP boundary. Depends on Application and Domain (for exceptions).
+
+| Directory | Purpose |
+|-----------|---------|
+| `routers/` | FastAPI routers — HTTP mapping only |
+| `schemas/` | Pydantic request/response models |
+| `dependencies/` | FastAPI `Depends()` wiring (auth, repositories) |
+| `middleware/` | Error handler mapping domain exceptions → HTTP responses |
+
+## Import Rules (Strict)
+
+| From \ To | domain/ | application/ | infrastructure/ | presentation/ |
+|-----------|---------|-------------|----------------|--------------|
+| **domain/** | Self only | FORBIDDEN | FORBIDDEN | FORBIDDEN |
+| **application/** | ALLOWED | Self only | FORBIDDEN | FORBIDDEN |
+| **infrastructure/** | ALLOWED (ports) | ALLOWED (UoW) | Self only | FORBIDDEN |
+| **presentation/** | ALLOWED (exceptions) | ALLOWED (use cases) | ALLOWED (wiring in dependencies/) | Self only |
+
+## How to Add a New Feature
+
+### 1. Start from the Domain
+
+- Define or reuse domain entities in `domain/entities/`
+- Add value objects if needed in `domain/value_objects/`
+- Define repository port if a new aggregate root in `domain/ports/repositories/`
+- Domain exceptions go in `domain/errors.py`
+- Business rules live IN the entity, not in services or routers
+
+### 2. Implement Infrastructure
+
+- Create SQLAlchemy repository implementation in `infrastructure/persistence/repositories/`
+- Create mapper if converting between ORM model and domain entity
+- Repository does NOT call `commit()` — only `flush()`
+- Transaction control belongs to the Unit of Work
+
+### 3. Wire in Presentation
+
+- Add FastAPI `Depends()` provider in `dependencies/repositories.py`
+- Keep routers thin: parse request → call service/use case → return response
+- Map domain exceptions to HTTP via the error handler middleware (automatic)
+
+### 4. Tests (Mandatory)
+
+Every change MUST include tests:
+- **Domain entities/value objects**: pure unit tests, no DB, no mocking frameworks
+- **Repositories**: integration tests using the `db` fixture from conftest
+- **Routers**: API tests using the `client` fixture
+- At least one success test + one failure/edge-case test per behavior
+
+Before committing, run: `scripts/agent_validate_backend.sh`
+
+## Existing Patterns to Follow
+
+### Domain Entity Pattern (see `domain/test_entity.py`)
+
+```python
+@dataclass
+class SomeEntity:
+    id: uuid.UUID
+    # fields...
+    _events: list[DomainEvent] = field(default_factory=list, repr=False)
+
+    @classmethod
+    def from_orm(cls, model: Any) -> "SomeEntity":
+        """Build from SQLAlchemy model."""
+        ...
+
+    def apply_to(self, model: Any) -> None:
+        """Copy mutable fields back onto the ORM model."""
+        ...
+
+    def some_business_method(self) -> None:
+        """Business logic lives HERE, not in services."""
+        ...
+        self._events.append(DomainEvent("something_happened"))
+```
+
+### Repository Port Pattern (Protocol)
+
+```python
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class SomeRepository(Protocol):
+    def find_by_id(self, id: uuid.UUID) -> SomeEntity | None: ...
+    def save(self, entity: SomeEntity) -> SomeEntity: ...
+```
+
+### Repository Implementation Pattern
+
+```python
+class SASomeRepository:
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    def find_by_id(self, id: uuid.UUID) -> SomeEntity | None:
+        model = self._session.query(SomeModel).filter(SomeModel.id == id).first()
+        return SomeMapper.to_entity(model) if model else None
+
+    def save(self, entity: SomeEntity) -> SomeEntity:
+        model = SomeMapper.to_model(entity)
+        merged = self._session.merge(model)
+        self._session.flush()  # NO commit — UoW does that
+        return SomeMapper.to_entity(merged)
+```
+
+### Error Handling (automatic via middleware)
+
+Services raise domain exceptions → middleware maps to HTTP:
+- `EntityNotFoundError` → 404
+- `DuplicateEntityError` → 409
+- `InvalidStateTransition` → 400
+- `BusinessRuleViolation` → 400
+- `PermissionViolation` → 403
+
+### Coexistence Strategy
+
+Old code (direct `db.query()` in routers) and new code (repositories) coexist. Migration is incremental:
+1. New endpoints use repositories
+2. Existing endpoints are migrated one at a time
+3. Both access the same DB, same session, same tables
+
+## Key Conventions
+
+- **Enums**: canonical source is `domain/enums.py`, `models/enums.py` re-exports
+- **Exceptions**: raise from `domain/errors.py`, never raise `HTTPException` from services
+- **Commits**: only via `UnitOfWork.commit()` or at the router level, never inside services/repos
+- **IDs**: UUID everywhere (primary keys, foreign keys)
+- **Tests**: SQLite in-memory for unit/integration, PostgreSQL in CI
+- **Validation**: Pydantic in schemas (presentation), domain rules in entities (domain)

.env.example

@@ -0,0 +1,44 @@
+# =============================================================================
+# Aegis Environment Variables
+# =============================================================================
+# Copy this file to .env and fill in the values BEFORE deploying.
+#
+# Generate secure random values with:
+#   openssl rand -hex 32        (for SECRET_KEY)
+#   openssl rand -base64 18     (for passwords)
+# =============================================================================
+
+# ── Database ─────────────────────────────────────────────────────────────────
+DB_USER=postgres
+DB_PASSWORD=              # REQUIRED — set a strong password
+DB_NAME=attackdb
+
+# ── Security ─────────────────────────────────────────────────────────────────
+# REQUIRED in production — the app will refuse to start without it.
+# Generate with:  openssl rand -hex 32
+SECRET_KEY=
+
+TOKEN_EXPIRE_MINUTES=60
+
+# ── Initial Admin Account ────────────────────────────────────────────────────
+# If ADMIN_PASSWORD is empty, a random password is auto-generated and
+# printed to the backend container logs on first startup.
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=
+
+# ── MinIO Object Storage ─────────────────────────────────────────────────────
+MINIO_ACCESS_KEY=minioadmin
+MINIO_SECRET_KEY=         # REQUIRED — set a strong password
+MINIO_BUCKET=evidence
+MINIO_SECURE=false        # Set to true if MinIO is behind TLS
+
+# ── CORS ──────────────────────────────────────────────────────────────────────
+# Comma-separated list of allowed frontend origins
+CORS_ORIGINS=https://your-domain.com
+
+# ── Frontend ─────────────────────────────────────────────────────────────────
+FRONTEND_PORT=80
+
+# ── Environment flag ─────────────────────────────────────────────────────────
+# Set to "production" for production deployments (enforces SECRET_KEY, etc.)
+AEGIS_ENV=production

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: Aegis CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15-alpine
+        env:
+          POSTGRES_DB: testdb
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    defaults:
+      run:
+        working-directory: backend
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: backend/requirements.txt
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install ruff
+
+      - name: Lint
+        run: ruff check app/ tests/
+
+      - name: Test
+        env:
+          DATABASE_URL: postgresql://test:test@localhost:5432/testdb
+          REDIS_URL: redis://localhost:6379/0
+          SECRET_KEY: ci-test-secret-key-not-for-production
+        run: pytest tests/ -v --tb=short

README.md

@@ -1,24 +1,97 @@
-# Aegis - MITRE ATT&CK Coverage Platform
+# 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.
+Continuous integration (lint + tests against PostgreSQL and Redis) is defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+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
-- **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
+### Core (V1)
+- **MITRE ATT&CK Integration** — Automatic synchronization via TAXII 2.0 (with GitHub fallback), scheduled every 24h
+- **Red/Blue Validation Workflow** — Structured dual-validation lifecycle: draft → red_executing → blue_evaluating → in_review → validated/rejected
+- **Dual Validation** — Independent Red Lead / Blue Lead approval before finalization
+- **Coverage Tracking** — Per-technique status (validated, partial, not covered, in progress)
+- **Evidence Storage** — Secure evidence with SHA256 integrity, separated by team (red/blue)
+- **Role-Based Access Control** — Granular permissions for 6 roles (admin, red_tech, blue_tech, red_lead, blue_lead, viewer)
+
+### Enhanced (V2)
+- **Test Template Catalog** — Import from Atomic Red Team, CALDERA, LOLBAS, GTFOBins; create custom templates; bulk activate/deactivate
+- **In-App Notifications** — Real-time notification bell with polling and automatic state-change alerts
+- **Reports & Export** — Coverage summary, test results, and remediation reports in JSON and CSV
+- **Remediation Tracking** — Step-by-step remediation assignments with status tracking
+- **Metrics Dashboard** — Pipeline funnel, team activity, validation rates
+
+### Advanced (V3)
+- **Multi-Source Data Import** — Sigma, CALDERA, LOLBAS, GTFOBins, D3FEND, MITRE CTI threat actors, compliance mappings (NIST 800-53, CIS Controls v8)
+- **Detection Rule Tracking** — Import and evaluate Sigma/Elastic detection rules per test
+- **ATT&CK Heatmap** — Interactive Navigator-style heatmap with layers, filters, and export
+- **Threat Actor Intelligence** — Track intrusion sets and their technique coverage
+- **Campaign Management** — Group tests into campaigns with dependencies, scheduling, and recurring execution
+- **Compliance Mapping** — Map NIST 800-53 and CIS Controls v8 to ATT&CK techniques with gap analysis
+- **Granular Scoring** — 0–100 scoring for techniques, tactics, actors, and organization with configurable weights
+- **Operational Metrics** — MTTD, MTTR, detection efficacy, alert fidelity, coverage velocity
+- **Executive Dashboard** — High-level KPIs for leadership (leads + admin)
+- **Temporal Comparison** — Coverage snapshots with historical comparison and trend analysis
+- **Auto Re-testing** — Automatic retest creation after remediation completion (configurable limit)
+- **Performance Optimizations** — Score caching, lazy loading, React.memo, database index optimization
+
+## Red Team / Blue Team Validation Flow
+
+```
+┌──────┐    ┌──────────────┐    ┌─────────────────┐    ┌───────────┐
+│ DRAFT│───▶│RED_EXECUTING │───▶│ BLUE_EVALUATING  │───▶│ IN_REVIEW │
+└──────┘    └──────────────┘    └─────────────────┘    └─────┬─────┘
+                                                             │
+                                         ┌───────────────────┤
+                                         ▼                   ▼
+                                   ┌──────────┐       ┌──────────┐
+                                   │ REJECTED │       │VALIDATED │
+                                   └────┬─────┘       └──────────┘
+                                        │                    │
+                                        └──▶ Back to DRAFT   ├──▶ Remediation
+                                                             └──▶ Auto Re-test
+```
+
+### 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 |
 
 ## Tech Stack
 
-- **Backend**: FastAPI (Python 3.11)
-- **Database**: PostgreSQL 15
+- **Backend**: FastAPI (Python 3.11) — Clean Modular Monolith with domain entities, services, and repository pattern
+- **Database**: PostgreSQL 16 with UUID primary keys and JSONB columns
 - **Object Storage**: MinIO (S3-compatible)
-- **ORM**: SQLAlchemy with Alembic migrations
-- **Frontend**: React + TypeScript + Vite (coming soon)
+- **ORM**: SQLAlchemy 2.x with Alembic migrations
+- **Frontend**: React 19 + TypeScript + Vite 7 + Tailwind CSS v4 + TanStack Query + TanStack Virtual
+- **Cache / Token Store**: Redis (token blacklist, score caching)
+- **Scheduler**: APScheduler (MITRE sync, Intel scan, Notification cleanup, Snapshots, Recurring campaigns)
+- **Testing**: Pytest (367+ tests), Ruff (linting), GitHub Actions CI
+- **Charts**: Recharts
 
 ## Quick Start
 
@@ -26,224 +99,341 @@ Aegis is a comprehensive platform for tracking and managing security coverage ag
 
 - Docker and Docker Compose
 - Git
+- Linux / macOS (or WSL on Windows)
 
-### Installation
+### Production Deployment
+
+The recommended way to deploy Aegis in production:
 
-1. Clone the repository:
 ```bash
 git clone <repository-url>
 cd Aegis
+chmod +x scripts/install.sh
+./scripts/install.sh
 ```
 
-2. Start all services:
+The interactive install wizard will guide you through:
+1. **Domain configuration** — your domain or IP, protocol (HTTP/HTTPS), and port
+2. **Admin account** — custom username and password (or auto-generated secure password)
+3. **Database** — name, user, and password (or auto-generated)
+4. **Session duration** — JWT token expiry (default: 15 minutes)
+5. **MITRE ATT&CK sync** — optionally import ~700 techniques on first run
+
+The script automatically generates cryptographically secure random secrets for `SECRET_KEY`, database password, and MinIO credentials. A summary with all credentials is displayed at the end of the installation.
+
+Access the application at the URL shown in the installation summary.
+
+### Development Setup
+
+For local development with hot-reload:
+
 ```bash
+git clone <repository-url>
+cd Aegis
 docker-compose up -d
+./scripts/init.sh
 ```
 
-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"}
-```
+Access at **http://localhost:5173** (frontend dev server) and **http://localhost:8000/docs** (API docs).
 
 ### Authentication
 
-The platform uses JWT-based authentication. After seeding, log in with the default admin credentials:
+JWT-based authentication with HttpOnly cookies. Admin credentials are configured during installation:
+
+- If you set a custom password in the wizard, use that.
+- If you left it blank, a secure random password was auto-generated and displayed in the installation summary and backend logs.
+
+To retrieve auto-generated credentials after installation:
 
 ```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>"
+docker logs aegis-backend 2>&1 | grep -A 5 "Initial Admin User Created"
 ```
 
-> **Important:** Change the default `admin123` password and `SECRET_KEY` in production.
+> **Note:** Passwords must meet complexity requirements: minimum 12 characters with at least one uppercase letter, one lowercase letter, one digit, and one special character.
+
+### Importing Data Sources
+
+On startup, the backend automatically seeds the initial data sources (Atomic Red Team, SigmaHQ, CALDERA, LOLBAS, GTFOBins, D3FEND). You can then sync each source from the UI:
+
+1. Navigate to **Data Sources** in the sidebar
+2. Click **Sync** on each data source to import its content
+3. Trigger a **MITRE ATT&CK Sync** from the **System** page
+
+Alternatively, use the API:
+
+```bash
+# Sync MITRE ATT&CK techniques
+curl -X POST http://your-server/api/v1/system/sync-mitre -H "Authorization: Bearer $TOKEN"
+
+# Sync all data sources at once
+curl -X POST http://your-server/api/v1/data-sources/sync-all -H "Authorization: Bearer $TOKEN"
+```
+
+### Production Considerations
+
+- **HTTPS/TLS:** For internet-facing deployments, place a reverse proxy with TLS in front (e.g., Traefik, Caddy, or Nginx with Let's Encrypt). Uncomment the HSTS header in `frontend/nginx.conf` once HTTPS is configured.
+- **Backups:** Set up regular PostgreSQL backups: `docker exec aegis-postgres pg_dump -U postgres attackdb > backup.sql`
+- **Updates:** To update, pull the latest code and run: `docker compose -f docker-compose.prod.yml up -d --build`
+- **Firewall:** Only expose port 80/443. All other services (DB, MinIO, backend) are internal only.
+- **Reconfigure:** Run `./scripts/install.sh` again to reconfigure the environment (domain, credentials, etc.).
+
+### Configuring Scoring Weights
+
+Default scoring weights can be adjusted via environment variables:
+
+```env
+SCORING_WEIGHT_TESTS=40
+SCORING_WEIGHT_DETECTION_RULES=20
+SCORING_WEIGHT_D3FEND=15
+SCORING_WEIGHT_FRESHNESS=15
+SCORING_WEIGHT_PLATFORM_DIVERSITY=10
+```
+
+Or at runtime via the admin API — see [docs/SCORING.md](docs/SCORING.md).
+
+### Configuring Campaigns
+
+1. Navigate to **Campaigns** in the sidebar
+2. Create a new campaign (custom or from a threat actor)
+3. Add tests with dependencies and phases
+4. Optionally enable **recurring scheduling** (weekly, monthly, quarterly)
 
 ## Services
 
-| Service  | Port | Description |
-|----------|------|-------------|
-| Backend  | 8000 | FastAPI REST API |
-| PostgreSQL | 5433 | Database (mapped to 5433 to avoid conflicts) |
+| Service | Port | Description |
+|---------|------|-------------|
+| Frontend | 5173 | React dev server (Vite) |
+| Backend | 8000 | FastAPI REST API |
+| PostgreSQL | 5433 | Database |
 | MinIO API | 9000 | S3-compatible object storage |
 | MinIO Console | 9001 | MinIO web interface |
 
+## Navigation
+
+```
+📊 Dashboard
+📊 Executive Dashboard          (leads + admin)
+🔲 ATT&CK Matrix                (advanced heatmap)
+🧪 Tests
+  ├─ All Tests
+  ├─ My Pending Tasks
+  └─ Test Catalog
+📋 Campaigns
+👤 Threat Actors
+📜 Compliance
+📈 Comparison                    (leads + admin)
+📄 Reports
+⚙️ System                       (admin only)
+  ├─ Data Sources               (sync Atomic, Sigma, CALDERA, LOLBAS, GTFOBins, D3FEND)
+  ├─ MITRE Sync                 (ATT&CK sync, intel scan, template management)
+  ├─ Users
+  └─ Audit Log
+```
+
 ## API Documentation
 
-Once the backend is running, access the interactive API documentation at:
+Interactive API documentation is available **in development only** (disabled in production for security):
 
 - **Swagger UI**: http://localhost:8000/docs
 - **ReDoc**: http://localhost:8000/redoc
 
-## API Endpoints
+> In production (`AEGIS_ENV=production`), these endpoints are disabled. Use the development environment or refer to [docs/API.md](docs/API.md).
 
-### Auth
-| Method | Route | Auth | Description |
-|--------|-------|------|-------------|
-| POST | `/api/v1/auth/login` | Public | Obtain JWT token |
-| GET | `/api/v1/auth/me` | Authenticated | Current user profile |
+### API Endpoints
 
-### 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 |
+| Group | Prefix | Key Operations |
+|-------|--------|---------------|
+| Auth | `/api/v1/auth` | Login, get current user |
+| Techniques | `/api/v1/techniques` | CRUD, list with filters, mark reviewed |
+| Tests | `/api/v1/tests` | Full Red/Blue workflow, remediation, retest chain |
+| Test Templates | `/api/v1/test-templates` | CRUD, stats, toggle active, bulk activate/deactivate |
+| Evidence | `/api/v1/tests/{id}/evidence` | Upload evidence, get presigned URLs |
+| Campaigns | `/api/v1/campaigns` | CRUD, scheduling, history |
+| Threat Actors | `/api/v1/threat-actors` | CRUD, technique mappings |
+| Detection Rules | `/api/v1/detection-rules` | List, filter by source/technique |
+| D3FEND | `/api/v1/d3fend` | Defensive techniques and mappings |
+| Compliance | `/api/v1/compliance` | Frameworks, controls, gaps |
+| Scores | `/api/v1/scores` | Technique/tactic/actor/org scores, config |
+| Operational Metrics | `/api/v1/metrics/operational` | MTTD, MTTR, trends, team breakdown |
+| Heatmap | `/api/v1/heatmap` | ATT&CK Navigator-style data |
+| Snapshots | `/api/v1/snapshots` | Create, compare, list snapshots |
+| Reports | `/api/v1/reports` | Coverage, results, remediation exports |
+| Notifications | `/api/v1/notifications` | List, read, mark all read |
+| Metrics | `/api/v1/metrics` | Summary, by-tactic, pipeline, team activity |
+| System | `/api/v1/system` | MITRE sync, import, scheduler status |
+| Users | `/api/v1/users` | User CRUD (admin) |
+| Audit Logs | `/api/v1/audit-logs` | Audit trail (admin) |
+| Data Sources | `/api/v1/data-sources` | Data source management (admin) |
 
-### 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 |
+See [docs/API.md](docs/API.md) for the full endpoint reference.
 
-### 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 |
+## Configuration
 
-### 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 |
+All variables are configured automatically by `scripts/install.sh`. For manual setup, copy `.env.example` to `.env` and fill in the values.
+
+### Required (production)
+
+| Variable | Description |
+|----------|-------------|
+| `SECRET_KEY` | JWT signing key — **required** in production (app refuses to start without it). Generate with `openssl rand -hex 32` |
+| `DB_PASSWORD` | PostgreSQL password |
+| `MINIO_SECRET_KEY` | MinIO secret key |
+
+### Security & Auth
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AEGIS_ENV` | — | Set to `production` to enforce security settings |
+| `ADMIN_USERNAME` | `admin` | Initial admin account username |
+| `ADMIN_PASSWORD` | *(auto-generated)* | Initial admin password. If empty, a secure random password is generated and shown in logs |
+| `ACCESS_TOKEN_EXPIRE_MINUTES` | `15` | JWT token lifetime in minutes |
+| `CORS_ORIGINS` | `http://localhost:5173` | Comma-separated list of allowed frontend origins |
+
+### Infrastructure
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DB_USER` | `postgres` | PostgreSQL username |
+| `DB_NAME` | `attackdb` | PostgreSQL database name |
+| `MINIO_ENDPOINT` | `minio:9000` | MinIO server address |
+| `MINIO_ACCESS_KEY` | `minioadmin` | MinIO access key |
+| `MINIO_BUCKET` | `evidence` | MinIO bucket for evidence files |
+| `MINIO_SECURE` | `false` | Set to `true` if MinIO is behind TLS |
+| `FRONTEND_PORT` | `80` | Port exposed by the frontend container |
+
+### Scoring Weights
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SCORING_WEIGHT_TESTS` | `40` | Weight for test validation component |
+| `SCORING_WEIGHT_DETECTION_RULES` | `20` | Weight for detection rules component |
+| `SCORING_WEIGHT_D3FEND` | `15` | Weight for D3FEND coverage component |
+| `SCORING_WEIGHT_FRESHNESS` | `15` | Weight for freshness component |
+| `SCORING_WEIGHT_PLATFORM_DIVERSITY` | `10` | Weight for platform diversity component |
+| `MAX_RETEST_COUNT` | `3` | Max automatic retests per original test |
+
+## Security
+
+Aegis includes several security hardening measures:
+
+- **Authentication:** JWT tokens stored in HttpOnly/Secure/SameSite cookies (immune to XSS theft). Token revocation via Redis-backed blacklist on logout.
+- **Rate limiting:** Login endpoint limited to 5 attempts per minute per IP (via slowapi).
+- **Password policy:** Minimum 12 characters with uppercase, lowercase, digit, and special character.
+- **CORS:** Configurable origins via `CORS_ORIGINS` environment variable. Restrictive method and header lists.
+- **Nginx security headers:** CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy.
+- **Non-root container:** Backend runs as `appuser` (UID 1001), not root.
+- **File uploads:** 50 MB size limit, extension whitelist, filename sanitization.
+- **ZIP imports:** Zip Slip (path traversal) and Zip Bomb (size/entry limit) protection.
+- **API surface:** Swagger UI, ReDoc, and OpenAPI schema disabled in production.
+- **Health endpoint:** Restricted to internal networks via Nginx ACL.
+- **Input sanitization:** LIKE wildcard escaping in all search queries; Pydantic schemas on all endpoints.
+- **XML parsing:** Uses `defusedxml` to prevent Billion Laughs / XXE attacks.
+- **Error handling:** Internal exception details are logged server-side only, never exposed to clients.
 
 ## Project Structure
 
 ```
 Aegis/
-├── docker-compose.yml          # Docker services configuration
+├── docker-compose.yml
+├── docker-compose.prod.yml
+├── .github/workflows/ci.yml      # GitHub Actions: ruff + pytest on PostgreSQL + Redis
+├── docs/
+│   ├── API.md                     # Full API endpoint reference
+│   ├── ARCHITECTURE.md            # System architecture, DB schema, service map
+│   ├── ADR.md                     # Architecture Decision Records
+│   ├── DATA_SOURCES.md            # External data source documentation
+│   ├── SCORING.md                 # Scoring system and metrics
+│   ├── TECHNOLOGY_JUSTIFICATION.md
+│   ├── C4_CONTEXT_DIAGRAM.md      # System context (C4 Level 1)
+│   └── C4_CONTAINER_DIAGRAM.md    # Container architecture (C4 Level 2)
 ├── 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/          # Database migration files
+│   ├── pytest.ini
+│   ├── tests/                     # 367+ pytest tests (domain, service, API)
 │   └── 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)
+│       ├── main.py                # FastAPI app with all routers + lifespan
+│       ├── config.py              # Pydantic Settings from environment
+│       ├── database.py            # SQLAlchemy engine + session (lazy init)
+│       ├── storage.py             # MinIO/S3 helpers
+│       ├── auth.py                # Password hashing + JWT tokens
+│       ├── domain/                # Pure business logic (zero framework imports)
+│       │   ├── entities/          # Rich domain entities (Technique, Campaign, etc.)
+│       │   ├── ports/             # Protocol interfaces (repos, ImportService)
+│       │   ├── value_objects/     # Immutable types (MitreId, ScoringWeights)
+│       │   ├── errors.py          # Domain exception hierarchy
+│       │   └── unit_of_work.py    # Transaction management
+│       ├── infrastructure/        # SQLAlchemy repos, Redis, mappers
+│       ├── models/                # SQLAlchemy ORM models
+│       ├── schemas/               # Pydantic request/response schemas
+│       ├── routers/               # 27 thin HTTP adapter routers
+│       ├── services/              # 46 framework-agnostic business services
+│       ├── middleware/            # Error handler (domain exceptions → HTTP)
+│       ├── dependencies/          # FastAPI dependency injection (auth, repos)
+│       └── jobs/                  # APScheduler background jobs
+└── frontend/src/
+    ├── App.tsx                    # Routes with lazy loading + role protection
+    ├── api/                       # API client modules (Axios + TanStack Query)
+    ├── components/                # Reusable UI components
+    ├── hooks/                     # Custom hooks (useDebounce, etc.)
+    ├── context/                   # Auth state management
+    └── pages/                     # Page components
 ```
 
-## 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
+docker exec aegis-backend alembic upgrade head
+docker exec aegis-backend alembic revision --autogenerate -m "description"
+docker exec aegis-backend alembic downgrade -1
 ```
 
-### Accessing Services
+### Running Tests
 
-- **MinIO Console**: http://localhost:9001 (login: `minioadmin` / `minioadmin`)
-- **PostgreSQL**: `psql -h localhost -p 5433 -U postgres -d attackdb`
+```bash
+# Run all V3 tests inside the container (recommended)
+docker exec aegis-backend python -m pytest tests/ -v --tb=short
 
-## User Roles
+# Run specific test suites
+docker exec aegis-backend python -m pytest tests/test_data_sources.py -v
+docker exec aegis-backend python -m pytest tests/test_scoring_and_compliance.py -v
+docker exec aegis-backend python -m pytest tests/test_campaigns_and_snapshots.py -v
 
-| 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 |
+# Skip integration tests (require network)
+docker exec aegis-backend python -m pytest tests/ -v -m "not integration"
+```
+
+### Generating Reports
+
+```bash
+# Coverage summary (JSON)
+GET /api/v1/reports/coverage-summary
+
+# Coverage CSV export
+GET /api/v1/reports/coverage-csv
+
+# Compliance gap analysis
+GET /api/v1/compliance/{framework_id}/gaps
+```
+
+## Further Documentation
+
+- **[Architecture](docs/ARCHITECTURE.md)** — Database schema, backend layers, domain entities, service map
+- **[API Reference](docs/API.md)** — Full endpoint documentation
+- **[Scoring](docs/SCORING.md)** — Scoring system explained with examples and configuration
+- **[Data Sources](docs/DATA_SOURCES.md)** — All external data sources with import instructions
+- **[ADRs](docs/ADR.md)** — Architecture Decision Records
+- **[Technology Justification](docs/TECHNOLOGY_JUSTIFICATION.md)** — Technology choices and rationale
+- **[C4 Diagrams](docs/C4_CONTEXT_DIAGRAM.md)** — System context and container architecture
 
 ## License
 
 This project is proprietary software. All rights reserved.
 
-## Contributing
+## Disclaimer
 
-Please read the contribution guidelines before submitting pull requests.
+This project has been developed with the assistance of [Cursor](https://cursor.com) and Claude Opus 4.6 (Anthropic).

backend/.dockerignore

@@ -0,0 +1,11 @@
+__pycache__
+*.pyc
+*.pyo
+*.egg-info
+.pytest_cache
+.mypy_cache
+.venv
+venv
+env
+.env
+*.log

backend/Dockerfile

@@ -6,6 +6,7 @@ WORKDIR /app
 RUN apt-get update && apt-get install -y \
     gcc \
     libpq-dev \
+    curl \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy requirements first for better caching
@@ -15,8 +16,17 @@ RUN pip install --no-cache-dir -r requirements.txt
 # Copy application code
 COPY . .
 
+# Make entrypoints executable
+RUN chmod +x /app/entrypoint.sh /app/entrypoint.prod.sh
+
+# Create a non-root user and give it ownership of /app
+RUN adduser --disabled-password --gecos '' --uid 1001 appuser \
+    && chown -R appuser:appuser /app
+
+USER appuser
+
 # Expose port
 EXPOSE 8000
 
-# Default command
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
+# Default command (migrations + seed + uvicorn)
+CMD ["sh", "/app/entrypoint.sh"]

backend/alembic/versions/b001_add_new_test_states.py

@@ -0,0 +1,32 @@
+"""add_new_test_states
+
+Revision ID: b001add0test
+Revises: a1412d1ef337
+Create Date: 2026-02-09 10:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b001add0test'
+down_revision: Union[str, Sequence[str], None] = 'a1412d1ef337'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add red_executing and blue_evaluating values to the teststate enum."""
+    op.execute("ALTER TYPE teststate ADD VALUE IF NOT EXISTS 'red_executing' AFTER 'draft'")
+    op.execute("ALTER TYPE teststate ADD VALUE IF NOT EXISTS 'blue_evaluating' AFTER 'red_executing'")
+
+
+def downgrade() -> None:
+    """Downgrade: removing enum values in PostgreSQL requires recreating the type.
+
+    This is intentionally left as a no-op because dropping enum values is
+    destructive and rarely needed in practice.
+    """
+    pass

backend/alembic/versions/b002_add_evidence_team_notes.py

@@ -0,0 +1,46 @@
+"""add_evidence_team_and_notes
+
+Revision ID: b002evidteam
+Revises: b001add0test
+Create Date: 2026-02-09 10:01:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b002evidteam'
+down_revision: Union[str, Sequence[str], None] = 'b001add0test'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create teamside enum and add team/notes columns to evidences."""
+    # Create the new enum type
+    teamside_enum = postgresql.ENUM('red', 'blue', name='teamside', create_type=False)
+    op.execute("CREATE TYPE teamside AS ENUM ('red', 'blue')")
+
+    # Add columns
+    op.add_column('evidences', sa.Column(
+        'team',
+        teamside_enum,
+        nullable=False,
+        server_default='red',
+    ))
+    op.add_column('evidences', sa.Column(
+        'notes',
+        sa.Text(),
+        nullable=True,
+    ))
+
+
+def downgrade() -> None:
+    """Remove team/notes columns and drop teamside enum."""
+    op.drop_column('evidences', 'notes')
+    op.drop_column('evidences', 'team')
+    op.execute("DROP TYPE IF EXISTS teamside")

backend/alembic/versions/b003_add_dual_validation_fields.py

@@ -0,0 +1,87 @@
+"""add_dual_validation_fields_to_tests
+
+Revision ID: b003dualvalid
+Revises: b002evidteam
+Create Date: 2026-02-09 10:02:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b003dualvalid'
+down_revision: Union[str, Sequence[str], None] = 'b002evidteam'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Drop legacy validated_by/validated_at and add dual validation columns."""
+    # Drop legacy single-validation columns
+    op.drop_constraint('tests_validated_by_fkey', 'tests', type_='foreignkey')
+    op.drop_column('tests', 'validated_by')
+    op.drop_column('tests', 'validated_at')
+
+    # ── Red Team fields ─────────────────────────────────────────
+    op.add_column('tests', sa.Column('red_summary', sa.Text(), nullable=True))
+    op.add_column('tests', sa.Column('attack_success', sa.Boolean(), nullable=True))
+    op.add_column('tests', sa.Column('red_validated_by', sa.UUID(), nullable=True))
+    op.add_column('tests', sa.Column('red_validated_at', sa.DateTime(), nullable=True))
+    op.add_column('tests', sa.Column('red_validation_status', sa.String(), nullable=True))
+    op.add_column('tests', sa.Column('red_validation_notes', sa.Text(), nullable=True))
+
+    # ── Blue Team fields ────────────────────────────────────────
+    op.add_column('tests', sa.Column('blue_summary', sa.Text(), nullable=True))
+    op.add_column('tests', sa.Column(
+        'detection_result',
+        postgresql.ENUM('detected', 'not_detected', 'partially_detected',
+                        name='testresult', create_type=False),
+        nullable=True,
+    ))
+    op.add_column('tests', sa.Column('blue_validated_by', sa.UUID(), nullable=True))
+    op.add_column('tests', sa.Column('blue_validated_at', sa.DateTime(), nullable=True))
+    op.add_column('tests', sa.Column('blue_validation_status', sa.String(), nullable=True))
+    op.add_column('tests', sa.Column('blue_validation_notes', sa.Text(), nullable=True))
+
+    # ── Foreign keys ────────────────────────────────────────────
+    op.create_foreign_key(
+        'fk_tests_red_validated_by', 'tests', 'users',
+        ['red_validated_by'], ['id'],
+    )
+    op.create_foreign_key(
+        'fk_tests_blue_validated_by', 'tests', 'users',
+        ['blue_validated_by'], ['id'],
+    )
+
+
+def downgrade() -> None:
+    """Reverse: drop dual validation columns and restore legacy columns."""
+    # Drop FKs
+    op.drop_constraint('fk_tests_blue_validated_by', 'tests', type_='foreignkey')
+    op.drop_constraint('fk_tests_red_validated_by', 'tests', type_='foreignkey')
+
+    # Drop new columns
+    op.drop_column('tests', 'blue_validation_notes')
+    op.drop_column('tests', 'blue_validation_status')
+    op.drop_column('tests', 'blue_validated_at')
+    op.drop_column('tests', 'blue_validated_by')
+    op.drop_column('tests', 'detection_result')
+    op.drop_column('tests', 'blue_summary')
+    op.drop_column('tests', 'red_validation_notes')
+    op.drop_column('tests', 'red_validation_status')
+    op.drop_column('tests', 'red_validated_at')
+    op.drop_column('tests', 'red_validated_by')
+    op.drop_column('tests', 'attack_success')
+    op.drop_column('tests', 'red_summary')
+
+    # Restore legacy columns
+    op.add_column('tests', sa.Column('validated_by', sa.UUID(), nullable=True))
+    op.add_column('tests', sa.Column('validated_at', sa.DateTime(), nullable=True))
+    op.create_foreign_key(
+        'tests_validated_by_fkey', 'tests', 'users',
+        ['validated_by'], ['id'],
+    )

backend/alembic/versions/b004_add_test_templates_table.py

@@ -0,0 +1,54 @@
+"""add_test_templates_table
+
+Revision ID: b004templates
+Revises: b003dualvalid
+Create Date: 2026-02-09 10:03:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b004templates'
+down_revision: Union[str, Sequence[str], None] = 'b003dualvalid'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create the test_templates table with indexes."""
+    op.create_table(
+        'test_templates',
+        sa.Column('id', sa.UUID(), nullable=False, default=sa.text('gen_random_uuid()')),
+        sa.Column('mitre_technique_id', sa.String(), nullable=False),
+        sa.Column('name', sa.String(), nullable=False),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('source', sa.String(), nullable=False),
+        sa.Column('source_url', sa.String(), nullable=True),
+        sa.Column('attack_procedure', sa.Text(), nullable=True),
+        sa.Column('expected_detection', sa.Text(), nullable=True),
+        sa.Column('platform', sa.String(), nullable=True),
+        sa.Column('tool_suggested', sa.String(), nullable=True),
+        sa.Column('severity', sa.String(), nullable=True),
+        sa.Column('atomic_test_id', sa.String(), nullable=True),
+        sa.Column('is_active', sa.Boolean(), nullable=True, server_default=sa.text('true')),
+        sa.Column('created_at', sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint('id'),
+    )
+
+    op.create_index('ix_test_templates_mitre_technique_id', 'test_templates', ['mitre_technique_id'])
+    op.create_index('ix_test_templates_source', 'test_templates', ['source'])
+    op.create_index('ix_test_templates_platform', 'test_templates', ['platform'])
+    op.create_index('ix_test_templates_severity', 'test_templates', ['severity'])
+
+
+def downgrade() -> None:
+    """Drop the test_templates table and its indexes."""
+    op.drop_index('ix_test_templates_severity', table_name='test_templates')
+    op.drop_index('ix_test_templates_platform', table_name='test_templates')
+    op.drop_index('ix_test_templates_source', table_name='test_templates')
+    op.drop_index('ix_test_templates_mitre_technique_id', table_name='test_templates')
+    op.drop_table('test_templates')

backend/alembic/versions/b005_add_v2_indexes.py

@@ -0,0 +1,55 @@
+"""add_v2_indexes
+
+Revision ID: b005v2indexes
+Revises: b004templates
+Create Date: 2026-02-09 10:04:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b005v2indexes'
+down_revision: Union[str, Sequence[str], None] = 'b004templates'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create performance indexes for V2 queries."""
+    # ── Tests ───────────────────────────────────────────────────
+    op.create_index('ix_tests_state', 'tests', ['state'])
+    op.create_index('ix_tests_technique_id', 'tests', ['technique_id'])
+    op.create_index('ix_tests_created_by', 'tests', ['created_by'])
+    op.create_index('ix_tests_red_validation_status', 'tests', ['red_validation_status'])
+    op.create_index('ix_tests_blue_validation_status', 'tests', ['blue_validation_status'])
+
+    # ── Evidences ───────────────────────────────────────────────
+    op.create_index('ix_evidences_test_id', 'evidences', ['test_id'])
+    op.create_index('ix_evidences_team', 'evidences', ['team'])
+
+    # ── Techniques (if not already present from MVP) ────────────
+    op.create_index('ix_techniques_tactic', 'techniques', ['tactic'])
+    op.create_index('ix_techniques_status_global', 'techniques', ['status_global'])
+    op.create_index('ix_techniques_review_required', 'techniques', ['review_required'])
+
+
+def downgrade() -> None:
+    """Drop all V2 indexes."""
+    # Techniques
+    op.drop_index('ix_techniques_review_required', table_name='techniques')
+    op.drop_index('ix_techniques_status_global', table_name='techniques')
+    op.drop_index('ix_techniques_tactic', table_name='techniques')
+
+    # Evidences
+    op.drop_index('ix_evidences_team', table_name='evidences')
+    op.drop_index('ix_evidences_test_id', table_name='evidences')
+
+    # Tests
+    op.drop_index('ix_tests_blue_validation_status', table_name='tests')
+    op.drop_index('ix_tests_red_validation_status', table_name='tests')
+    op.drop_index('ix_tests_created_by', table_name='tests')
+    op.drop_index('ix_tests_technique_id', table_name='tests')
+    op.drop_index('ix_tests_state', table_name='tests')

backend/alembic/versions/b006_add_notifications_table.py

@@ -0,0 +1,46 @@
+"""add_notifications_table
+
+Revision ID: b006notifications
+Revises: b005v2indexes
+Create Date: 2026-02-09 11:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b006notifications'
+down_revision: Union[str, Sequence[str], None] = 'b005v2indexes'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create notifications table."""
+    op.create_table(
+        'notifications',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('user_id', UUID(as_uuid=True), sa.ForeignKey('users.id'), nullable=False),
+        sa.Column('type', sa.String(), nullable=False),
+        sa.Column('title', sa.String(), nullable=False),
+        sa.Column('message', sa.Text(), nullable=True),
+        sa.Column('entity_type', sa.String(), nullable=True),
+        sa.Column('entity_id', UUID(as_uuid=True), nullable=True),
+        sa.Column('read', sa.Boolean(), server_default='false'),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),
+    )
+    op.create_index('ix_notifications_user_id', 'notifications', ['user_id'])
+    op.create_index('ix_notifications_read', 'notifications', ['read'])
+    op.create_index('ix_notifications_created_at', 'notifications', ['created_at'])
+
+
+def downgrade() -> None:
+    """Drop notifications table."""
+    op.drop_index('ix_notifications_created_at', table_name='notifications')
+    op.drop_index('ix_notifications_read', table_name='notifications')
+    op.drop_index('ix_notifications_user_id', table_name='notifications')
+    op.drop_table('notifications')

backend/alembic/versions/b007_add_remediation_fields.py

@@ -0,0 +1,44 @@
+"""add_remediation_fields
+
+Revision ID: b007remediation
+Revises: b006notifications
+Create Date: 2026-02-09 11:30:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b007remediation'
+down_revision: Union[str, Sequence[str], None] = 'b006notifications'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add remediation fields to tests and test_templates."""
+    # Tests — remediation fields
+    op.add_column('tests', sa.Column('remediation_steps', sa.Text(), nullable=True))
+    op.add_column('tests', sa.Column('remediation_status', sa.String(), nullable=True))
+    op.add_column('tests', sa.Column('remediation_assignee', UUID(as_uuid=True), nullable=True))
+    op.create_foreign_key(
+        'fk_tests_remediation_assignee',
+        'tests', 'users',
+        ['remediation_assignee'], ['id'],
+    )
+
+    # TestTemplates — suggested_remediation
+    op.add_column('test_templates', sa.Column('suggested_remediation', sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    """Remove remediation fields."""
+    op.drop_column('test_templates', 'suggested_remediation')
+    op.drop_constraint('fk_tests_remediation_assignee', 'tests', type_='foreignkey')
+    op.drop_column('tests', 'remediation_assignee')
+    op.drop_column('tests', 'remediation_status')
+    op.drop_column('tests', 'remediation_steps')

backend/alembic/versions/b008_add_data_sources_table.py

@@ -0,0 +1,48 @@
+"""add_data_sources_table
+
+Revision ID: b008datasources
+Revises: b007remediation
+Create Date: 2026-02-09 14:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b008datasources'
+down_revision: Union[str, Sequence[str], None] = 'b007remediation'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create data_sources table."""
+    op.create_table(
+        'data_sources',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('name', sa.String(), unique=True, nullable=False),
+        sa.Column('display_name', sa.String(), nullable=False),
+        sa.Column('type', sa.String(), nullable=False),
+        sa.Column('url', sa.String(), nullable=True),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('is_enabled', sa.Boolean(), server_default='true'),
+        sa.Column('last_sync_at', sa.DateTime(), nullable=True),
+        sa.Column('last_sync_status', sa.String(), nullable=True),
+        sa.Column('last_sync_stats', JSONB(), nullable=True),
+        sa.Column('sync_frequency', sa.String(), nullable=True),
+        sa.Column('config', JSONB(), nullable=True),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),
+    )
+    op.create_index('ix_data_sources_type', 'data_sources', ['type'])
+    op.create_index('ix_data_sources_is_enabled', 'data_sources', ['is_enabled'])
+
+
+def downgrade() -> None:
+    """Drop data_sources table."""
+    op.drop_index('ix_data_sources_is_enabled', table_name='data_sources')
+    op.drop_index('ix_data_sources_type', table_name='data_sources')
+    op.drop_table('data_sources')

backend/alembic/versions/b009_add_detection_rules_table.py

@@ -0,0 +1,52 @@
+"""add_detection_rules_table
+
+Revision ID: b009detectionrules
+Revises: b008datasources
+Create Date: 2026-02-09 14:10:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b009detectionrules'
+down_revision: Union[str, Sequence[str], None] = 'b008datasources'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create detection_rules table."""
+    op.create_table(
+        'detection_rules',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('mitre_technique_id', sa.String(), nullable=False),
+        sa.Column('title', sa.String(), nullable=False),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('source', sa.String(), nullable=False),
+        sa.Column('source_id', sa.String(), nullable=True),
+        sa.Column('source_url', sa.String(), nullable=True),
+        sa.Column('rule_content', sa.Text(), nullable=False),
+        sa.Column('rule_format', sa.String(), nullable=False),
+        sa.Column('severity', sa.String(), nullable=True),
+        sa.Column('platforms', JSONB(), nullable=True),
+        sa.Column('log_sources', JSONB(), nullable=True),
+        sa.Column('false_positive_rate', sa.String(), nullable=True),
+        sa.Column('is_active', sa.Boolean(), server_default='true'),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),
+    )
+    op.create_index('ix_detection_rules_mitre_technique_id', 'detection_rules', ['mitre_technique_id'])
+    op.create_index('ix_detection_rules_source', 'detection_rules', ['source'])
+    op.create_index('ix_detection_rules_severity', 'detection_rules', ['severity'])
+
+
+def downgrade() -> None:
+    """Drop detection_rules table."""
+    op.drop_index('ix_detection_rules_severity', table_name='detection_rules')
+    op.drop_index('ix_detection_rules_source', table_name='detection_rules')
+    op.drop_index('ix_detection_rules_mitre_technique_id', table_name='detection_rules')
+    op.drop_table('detection_rules')

backend/alembic/versions/b010_add_threat_actors_tables.py

@@ -0,0 +1,72 @@
+"""add_threat_actors_tables
+
+Revision ID: b010threatactors
+Revises: b009detectionrules
+Create Date: 2026-02-09 15:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b010threatactors'
+down_revision: Union[str, Sequence[str], None] = 'b009detectionrules'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create threat_actors and threat_actor_techniques tables."""
+    # threat_actors
+    op.create_table(
+        'threat_actors',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('mitre_id', sa.String(), unique=True, nullable=True),
+        sa.Column('name', sa.String(), nullable=False),
+        sa.Column('aliases', JSONB(), nullable=True),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('country', sa.String(), nullable=True),
+        sa.Column('target_sectors', JSONB(), nullable=True),
+        sa.Column('target_regions', JSONB(), nullable=True),
+        sa.Column('motivation', sa.String(), nullable=True),
+        sa.Column('sophistication', sa.String(), nullable=True),
+        sa.Column('first_seen', sa.String(), nullable=True),
+        sa.Column('last_seen', sa.String(), nullable=True),
+        sa.Column('references', JSONB(), nullable=True),
+        sa.Column('mitre_url', sa.String(), nullable=True),
+        sa.Column('is_active', sa.Boolean(), server_default='true'),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),
+    )
+    op.create_index('ix_threat_actors_country', 'threat_actors', ['country'])
+    op.create_index('ix_threat_actors_motivation', 'threat_actors', ['motivation'])
+
+    # threat_actor_techniques (junction table)
+    op.create_table(
+        'threat_actor_techniques',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('threat_actor_id', UUID(as_uuid=True),
+                  sa.ForeignKey('threat_actors.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('technique_id', UUID(as_uuid=True),
+                  sa.ForeignKey('techniques.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('usage_description', sa.Text(), nullable=True),
+        sa.Column('first_seen_using', sa.String(), nullable=True),
+    )
+    op.create_index('ix_threat_actor_techniques_actor', 'threat_actor_techniques', ['threat_actor_id'])
+    op.create_index('ix_threat_actor_techniques_technique', 'threat_actor_techniques', ['technique_id'])
+    op.create_unique_constraint('uq_actor_technique', 'threat_actor_techniques',
+                                ['threat_actor_id', 'technique_id'])
+
+
+def downgrade() -> None:
+    """Drop threat_actor_techniques and threat_actors tables."""
+    op.drop_constraint('uq_actor_technique', 'threat_actor_techniques', type_='unique')
+    op.drop_index('ix_threat_actor_techniques_technique', table_name='threat_actor_techniques')
+    op.drop_index('ix_threat_actor_techniques_actor', table_name='threat_actor_techniques')
+    op.drop_table('threat_actor_techniques')
+    op.drop_index('ix_threat_actors_motivation', table_name='threat_actors')
+    op.drop_index('ix_threat_actors_country', table_name='threat_actors')
+    op.drop_table('threat_actors')

backend/alembic/versions/b011_add_defensive_techniques_tables.py

@@ -0,0 +1,59 @@
+"""add_defensive_techniques_tables
+
+Revision ID: b011defensive
+Revises: b010threatactors
+Create Date: 2026-02-09 16:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b011defensive'
+down_revision: Union[str, Sequence[str], None] = 'b010threatactors'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create defensive_techniques and defensive_technique_mappings tables."""
+    # defensive_techniques
+    op.create_table(
+        'defensive_techniques',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('d3fend_id', sa.String(), unique=True, nullable=False),
+        sa.Column('name', sa.String(), nullable=False),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('tactic', sa.String(), nullable=True),
+        sa.Column('d3fend_url', sa.String(), nullable=True),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),
+    )
+    op.create_index('ix_defensive_techniques_tactic', 'defensive_techniques', ['tactic'])
+
+    # defensive_technique_mappings (ATT&CK → D3FEND)
+    op.create_table(
+        'defensive_technique_mappings',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('attack_technique_id', UUID(as_uuid=True),
+                  sa.ForeignKey('techniques.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('defensive_technique_id', UUID(as_uuid=True),
+                  sa.ForeignKey('defensive_techniques.id', ondelete='CASCADE'), nullable=False),
+    )
+    op.create_index('ix_dtm_attack_technique', 'defensive_technique_mappings', ['attack_technique_id'])
+    op.create_index('ix_dtm_defensive_technique', 'defensive_technique_mappings', ['defensive_technique_id'])
+    op.create_unique_constraint('uq_attack_defensive_technique', 'defensive_technique_mappings',
+                                ['attack_technique_id', 'defensive_technique_id'])
+
+
+def downgrade() -> None:
+    """Drop defensive_technique_mappings and defensive_techniques tables."""
+    op.drop_constraint('uq_attack_defensive_technique', 'defensive_technique_mappings', type_='unique')
+    op.drop_index('ix_dtm_defensive_technique', table_name='defensive_technique_mappings')
+    op.drop_index('ix_dtm_attack_technique', table_name='defensive_technique_mappings')
+    op.drop_table('defensive_technique_mappings')
+    op.drop_index('ix_defensive_techniques_tactic', table_name='defensive_techniques')
+    op.drop_table('defensive_techniques')

backend/alembic/versions/b012_add_detection_rule_associations.py

@@ -0,0 +1,66 @@
+"""add_detection_rule_associations
+
+Revision ID: b012detectionassoc
+Revises: b011defensive
+Create Date: 2026-02-09 17:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b012detectionassoc'
+down_revision: Union[str, Sequence[str], None] = 'b011defensive'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create test_template_detection_rules and test_detection_results tables."""
+
+    # test_template_detection_rules (template ↔ detection rule association)
+    op.create_table(
+        'test_template_detection_rules',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('test_template_id', UUID(as_uuid=True),
+                  sa.ForeignKey('test_templates.id', ondelete='CASCADE'), nullable=True),
+        sa.Column('detection_rule_id', UUID(as_uuid=True),
+                  sa.ForeignKey('detection_rules.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('is_primary', sa.Boolean(), server_default='false'),
+    )
+    op.create_index('ix_ttdr_template', 'test_template_detection_rules', ['test_template_id'])
+    op.create_index('ix_ttdr_rule', 'test_template_detection_rules', ['detection_rule_id'])
+    op.create_unique_constraint('uq_template_detection_rule', 'test_template_detection_rules',
+                                ['test_template_id', 'detection_rule_id'])
+
+    # test_detection_results (per-test, per-rule evaluation results)
+    op.create_table(
+        'test_detection_results',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('test_id', UUID(as_uuid=True),
+                  sa.ForeignKey('tests.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('detection_rule_id', UUID(as_uuid=True),
+                  sa.ForeignKey('detection_rules.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('triggered', sa.Boolean(), nullable=True),
+        sa.Column('notes', sa.Text(), nullable=True),
+        sa.Column('evaluated_by', UUID(as_uuid=True),
+                  sa.ForeignKey('users.id', ondelete='SET NULL'), nullable=True),
+        sa.Column('evaluated_at', sa.DateTime(), nullable=True),
+    )
+    op.create_index('ix_tdr_test', 'test_detection_results', ['test_id'])
+    op.create_index('ix_tdr_rule', 'test_detection_results', ['detection_rule_id'])
+
+
+def downgrade() -> None:
+    """Drop test_detection_results and test_template_detection_rules tables."""
+    op.drop_index('ix_tdr_rule', table_name='test_detection_results')
+    op.drop_index('ix_tdr_test', table_name='test_detection_results')
+    op.drop_table('test_detection_results')
+    op.drop_constraint('uq_template_detection_rule', 'test_template_detection_rules', type_='unique')
+    op.drop_index('ix_ttdr_rule', table_name='test_template_detection_rules')
+    op.drop_index('ix_ttdr_template', table_name='test_template_detection_rules')
+    op.drop_table('test_template_detection_rules')

backend/alembic/versions/b013_add_campaigns_tables.py

@@ -0,0 +1,74 @@
+"""add_campaigns_tables
+
+Revision ID: b013campaigns
+Revises: b012detectionassoc
+Create Date: 2026-02-09 18:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b013campaigns'
+down_revision: Union[str, Sequence[str], None] = 'b012detectionassoc'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create campaigns and campaign_tests tables."""
+
+    # campaigns
+    op.create_table(
+        'campaigns',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('name', sa.String(), nullable=False),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('type', sa.String(), nullable=False, server_default='custom'),
+        sa.Column('threat_actor_id', UUID(as_uuid=True),
+                  sa.ForeignKey('threat_actors.id', ondelete='SET NULL'), nullable=True),
+        sa.Column('status', sa.String(), nullable=False, server_default='draft'),
+        sa.Column('created_by', UUID(as_uuid=True),
+                  sa.ForeignKey('users.id', ondelete='SET NULL'), nullable=True),
+        sa.Column('scheduled_at', sa.DateTime(), nullable=True),
+        sa.Column('completed_at', sa.DateTime(), nullable=True),
+        sa.Column('target_platform', sa.String(), nullable=True),
+        sa.Column('tags', JSONB(), nullable=True),
+        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),
+    )
+    op.create_index('ix_campaigns_status', 'campaigns', ['status'])
+    op.create_index('ix_campaigns_type', 'campaigns', ['type'])
+    op.create_index('ix_campaigns_threat_actor', 'campaigns', ['threat_actor_id'])
+    op.create_index('ix_campaigns_created_by', 'campaigns', ['created_by'])
+
+    # campaign_tests
+    op.create_table(
+        'campaign_tests',
+        sa.Column('id', UUID(as_uuid=True), primary_key=True),
+        sa.Column('campaign_id', UUID(as_uuid=True),
+                  sa.ForeignKey('campaigns.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('test_id', UUID(as_uuid=True),
+                  sa.ForeignKey('tests.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('order_index', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('depends_on', UUID(as_uuid=True),
+                  sa.ForeignKey('campaign_tests.id', ondelete='SET NULL'), nullable=True),
+        sa.Column('phase', sa.String(), nullable=True),
+    )
+    op.create_index('ix_campaign_tests_campaign', 'campaign_tests', ['campaign_id'])
+    op.create_index('ix_campaign_tests_test', 'campaign_tests', ['test_id'])
+
+
+def downgrade() -> None:
+    """Drop campaign_tests and campaigns tables."""
+    op.drop_index('ix_campaign_tests_test', table_name='campaign_tests')
+    op.drop_index('ix_campaign_tests_campaign', table_name='campaign_tests')
+    op.drop_table('campaign_tests')
+    op.drop_index('ix_campaigns_created_by', table_name='campaigns')
+    op.drop_index('ix_campaigns_threat_actor', table_name='campaigns')
+    op.drop_index('ix_campaigns_type', table_name='campaigns')
+    op.drop_index('ix_campaigns_status', table_name='campaigns')
+    op.drop_table('campaigns')

backend/alembic/versions/b014_add_compliance_tables.py

@@ -0,0 +1,92 @@
+"""add_compliance_tables
+
+Revision ID: b014compliance
+Revises: b013campaigns
+Create Date: 2026-02-09 20:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "b014compliance"
+down_revision: Union[str, None] = "b013campaigns"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ── compliance_frameworks ─────────────────────────────────────
+    op.create_table(
+        "compliance_frameworks",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("name", sa.String, unique=True, nullable=False),
+        sa.Column("version", sa.String, nullable=True),
+        sa.Column("description", sa.Text, nullable=True),
+        sa.Column("url", sa.String, nullable=True),
+        sa.Column("is_active", sa.Boolean, server_default="true"),
+        sa.Column("created_at", sa.DateTime, server_default=sa.func.now()),
+    )
+
+    # ── compliance_controls ───────────────────────────────────────
+    op.create_table(
+        "compliance_controls",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "framework_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("compliance_frameworks.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("control_id", sa.String, nullable=False),
+        sa.Column("title", sa.String, nullable=False),
+        sa.Column("description", sa.Text, nullable=True),
+        sa.Column("category", sa.String, nullable=True),
+    )
+    op.create_index(
+        "ix_compliance_controls_framework",
+        "compliance_controls",
+        ["framework_id"],
+    )
+
+    # ── compliance_control_mappings ───────────────────────────────
+    op.create_table(
+        "compliance_control_mappings",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "compliance_control_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("compliance_controls.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "technique_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("techniques.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+    )
+    op.create_index(
+        "ix_compliance_mappings_control",
+        "compliance_control_mappings",
+        ["compliance_control_id"],
+    )
+    op.create_index(
+        "ix_compliance_mappings_technique",
+        "compliance_control_mappings",
+        ["technique_id"],
+    )
+    op.create_unique_constraint(
+        "uq_control_technique",
+        "compliance_control_mappings",
+        ["compliance_control_id", "technique_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("compliance_control_mappings")
+    op.drop_table("compliance_controls")
+    op.drop_table("compliance_frameworks")

backend/alembic/versions/b015_add_coverage_snapshots.py

@@ -0,0 +1,77 @@
+"""add_coverage_snapshots
+
+Revision ID: b015snapshots
+Revises: b014compliance
+Create Date: 2026-02-10 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "b015snapshots"
+down_revision: Union[str, None] = "b014compliance"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ── coverage_snapshots ────────────────────────────────────────
+    op.create_table(
+        "coverage_snapshots",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("name", sa.String, nullable=True),
+        sa.Column("organization_score", sa.Float, nullable=False),
+        sa.Column("total_techniques", sa.Integer, nullable=False),
+        sa.Column("validated_count", sa.Integer, nullable=False),
+        sa.Column("partial_count", sa.Integer, nullable=False),
+        sa.Column("not_covered_count", sa.Integer, nullable=False),
+        sa.Column("in_progress_count", sa.Integer, nullable=False),
+        sa.Column("not_evaluated_count", sa.Integer, nullable=False),
+        sa.Column(
+            "created_by",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("created_at", sa.DateTime, server_default=sa.func.now()),
+    )
+
+    # ── snapshot_technique_states ─────────────────────────────────
+    op.create_table(
+        "snapshot_technique_states",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "snapshot_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("coverage_snapshots.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "technique_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("techniques.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("mitre_id", sa.String, nullable=False),
+        sa.Column("status", sa.String, nullable=False),
+        sa.Column("score", sa.Float, nullable=True),
+    )
+    op.create_index(
+        "ix_snapshot_technique_states_snapshot",
+        "snapshot_technique_states",
+        ["snapshot_id"],
+    )
+    op.create_index(
+        "ix_snapshot_technique_states_technique",
+        "snapshot_technique_states",
+        ["technique_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("snapshot_technique_states")
+    op.drop_table("coverage_snapshots")

backend/alembic/versions/b016_add_retest_fields.py

@@ -0,0 +1,41 @@
+"""add_retest_fields
+
+Revision ID: b016retests
+Revises: b015snapshots
+Create Date: 2026-02-10 01:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "b016retests"
+down_revision: Union[str, None] = "b015snapshots"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tests",
+        sa.Column(
+            "retest_of",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("tests.id"),
+            nullable=True,
+        ),
+    )
+    op.add_column(
+        "tests",
+        sa.Column("retest_count", sa.Integer, server_default="0", nullable=False),
+    )
+    op.create_index("ix_tests_retest_of", "tests", ["retest_of"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_tests_retest_of", table_name="tests")
+    op.drop_column("tests", "retest_count")
+    op.drop_column("tests", "retest_of")

backend/alembic/versions/b017_add_campaign_scheduling.py

@@ -0,0 +1,58 @@
+"""add_campaign_scheduling
+
+Revision ID: b017scheduling
+Revises: b016retests
+Create Date: 2026-02-10 02:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "b017scheduling"
+down_revision: Union[str, None] = "b016retests"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "campaigns",
+        sa.Column("is_recurring", sa.Boolean, server_default="false", nullable=False),
+    )
+    op.add_column(
+        "campaigns",
+        sa.Column("recurrence_pattern", sa.String, nullable=True),
+    )
+    op.add_column(
+        "campaigns",
+        sa.Column("next_run_at", sa.DateTime, nullable=True),
+    )
+    op.add_column(
+        "campaigns",
+        sa.Column("last_run_at", sa.DateTime, nullable=True),
+    )
+    op.add_column(
+        "campaigns",
+        sa.Column(
+            "parent_campaign_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("campaigns.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+    )
+    op.create_index("ix_campaigns_next_run", "campaigns", ["next_run_at"])
+    op.create_index("ix_campaigns_parent", "campaigns", ["parent_campaign_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_campaigns_parent", table_name="campaigns")
+    op.drop_index("ix_campaigns_next_run", table_name="campaigns")
+    op.drop_column("campaigns", "parent_campaign_id")
+    op.drop_column("campaigns", "last_run_at")
+    op.drop_column("campaigns", "next_run_at")
+    op.drop_column("campaigns", "recurrence_pattern")
+    op.drop_column("campaigns", "is_recurring")

backend/alembic/versions/b018_add_performance_indexes.py

@@ -0,0 +1,78 @@
+"""add_performance_indexes
+
+Revision ID: b018perfidx
+Revises: b017scheduling
+Create Date: 2026-02-10 06:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "b018perfidx"
+down_revision: Union[str, None] = "b017scheduling"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Composite index for detection rules filtered by technique + source
+    op.create_index(
+        "ix_detection_rules_technique_source",
+        "detection_rules",
+        ["mitre_technique_id", "source"],
+    )
+
+    # Composite index for snapshot technique states
+    op.create_index(
+        "ix_snapshot_technique_states_snap_tech",
+        "snapshot_technique_states",
+        ["snapshot_id", "technique_id"],
+        unique=True,
+    )
+
+    # Covering index for tests frequently filtered by technique + state
+    op.create_index(
+        "ix_tests_technique_state",
+        "tests",
+        ["technique_id", "state"],
+    )
+
+    # Audit logs — timestamp-based lookups
+    op.create_index(
+        "ix_audit_logs_timestamp",
+        "audit_logs",
+        ["timestamp"],
+    )
+
+    # Audit logs — entity lookups
+    op.create_index(
+        "ix_audit_logs_entity",
+        "audit_logs",
+        ["entity_type", "entity_id"],
+    )
+
+    # Test detection results — triggered flag for maturity queries
+    op.create_index(
+        "ix_test_detection_results_triggered",
+        "test_detection_results",
+        ["triggered"],
+    )
+
+    # Compliance control mappings — composite for joins
+    op.create_index(
+        "ix_compliance_mappings_control_technique",
+        "compliance_control_mappings",
+        ["compliance_control_id", "technique_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_compliance_mappings_control_technique", table_name="compliance_control_mappings")
+    op.drop_index("ix_test_detection_results_triggered", table_name="test_detection_results")
+    op.drop_index("ix_audit_logs_entity", table_name="audit_logs")
+    op.drop_index("ix_audit_logs_timestamp", table_name="audit_logs")
+    op.drop_index("ix_tests_technique_state", table_name="tests")
+    op.drop_index("ix_snapshot_technique_states_snap_tech", table_name="snapshot_technique_states")
+    op.drop_index("ix_detection_rules_technique_source", table_name="detection_rules")

backend/alembic/versions/b019_add_composite_indexes.py

@@ -0,0 +1,67 @@
+"""add_composite_indexes
+
+Additional composite indexes for scoring, heatmap, metrics, reports,
+MTTD/MTTR calculations, and notification queries.
+
+Revision ID: b019composite
+Revises: b018perfidx
+Create Date: 2026-02-17 14:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "b019composite"
+down_revision: Union[str, None] = "b018perfidx"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ── Tests ────────────────────────────────────────────────────────
+    # Used by scoring queries that filter by state + validation date
+    op.create_index(
+        "ix_tests_state_red_validated_at",
+        "tests",
+        ["state", "red_validated_at"],
+    )
+
+    # Used by remediation dashboard and metrics
+    op.create_index(
+        "ix_tests_remediation_status",
+        "tests",
+        ["remediation_status"],
+    )
+
+    # ── Audit logs ───────────────────────────────────────────────────
+    # Three-column index for MTTD/MTTR queries that filter by entity + action
+    op.create_index(
+        "ix_audit_logs_entity_type_entity_id_action",
+        "audit_logs",
+        ["entity_type", "entity_id", "action"],
+    )
+
+    # Used for per-user audit trail queries
+    op.create_index(
+        "ix_audit_logs_user_id",
+        "audit_logs",
+        ["user_id"],
+    )
+
+    # ── Notifications ────────────────────────────────────────────────
+    # Used by "unread notifications" badge and inbox queries
+    op.create_index(
+        "ix_notifications_user_id_read",
+        "notifications",
+        ["user_id", "read"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_notifications_user_id_read", table_name="notifications")
+    op.drop_index("ix_audit_logs_user_id", table_name="audit_logs")
+    op.drop_index("ix_audit_logs_entity_type_entity_id_action", table_name="audit_logs")
+    op.drop_index("ix_tests_remediation_status", table_name="tests")
+    op.drop_index("ix_tests_state_red_validated_at", table_name="tests")

backend/alembic/versions/b020_add_jira_links_and_worklogs.py

@@ -0,0 +1,95 @@
+"""add_jira_links_and_worklogs
+
+Revision ID: b020jiraworklogs
+Revises: b019composite
+Create Date: 2026-02-17 16:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = "b020jiraworklogs"
+down_revision: Union[str, None] = "b019composite"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ── jira_links: 100 % raw SQL to avoid all SQLAlchemy enum hooks ──
+    op.execute("""
+        DO $$ BEGIN
+            IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'jiralinkentitytype') THEN
+                CREATE TYPE jiralinkentitytype AS ENUM ('test', 'technique', 'campaign', 'evidence');
+            END IF;
+        END $$;
+
+        DO $$ BEGIN
+            IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'jirasyncdirection') THEN
+                CREATE TYPE jirasyncdirection AS ENUM ('aegis_to_jira', 'jira_to_aegis', 'bidirectional');
+            END IF;
+        END $$;
+
+        CREATE TABLE IF NOT EXISTS jira_links (
+            id              UUID PRIMARY KEY,
+            entity_type     jiralinkentitytype NOT NULL,
+            entity_id       UUID NOT NULL,
+            jira_issue_key  VARCHAR(50) NOT NULL,
+            jira_issue_id   VARCHAR(50),
+            jira_project_key VARCHAR(20),
+            jira_status     VARCHAR(100),
+            jira_priority   VARCHAR(50),
+            jira_assignee   VARCHAR(255),
+            jira_story_points VARCHAR(10),
+            sync_direction  jirasyncdirection DEFAULT 'bidirectional',
+            last_synced_at  TIMESTAMP,
+            sync_metadata   JSONB DEFAULT '{}',
+            created_by      UUID REFERENCES users(id),
+            created_at      TIMESTAMP DEFAULT now(),
+            updated_at      TIMESTAMP DEFAULT now()
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_jira_links_entity_id
+            ON jira_links (entity_id);
+        CREATE INDEX IF NOT EXISTS ix_jira_links_issue_key
+            ON jira_links (jira_issue_key);
+        CREATE INDEX IF NOT EXISTS ix_jira_links_entity_type_entity_id
+            ON jira_links (entity_type, entity_id);
+    """)
+
+    # ── worklogs table (no enums, straightforward) ───────────────────
+    op.execute("""
+        CREATE TABLE IF NOT EXISTS worklogs (
+            id              UUID PRIMARY KEY,
+            entity_type     VARCHAR(50) NOT NULL,
+            entity_id       UUID NOT NULL,
+            user_id         UUID NOT NULL REFERENCES users(id),
+            activity_type   VARCHAR(100) NOT NULL,
+            started_at      TIMESTAMP NOT NULL,
+            ended_at        TIMESTAMP,
+            duration_seconds INTEGER NOT NULL,
+            description     TEXT,
+            tempo_synced    TIMESTAMP,
+            tempo_worklog_id VARCHAR(100),
+            integrity_hash  VARCHAR(64),
+            created_at      TIMESTAMP DEFAULT now(),
+            metadata        JSONB DEFAULT '{}'
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_worklogs_entity_id
+            ON worklogs (entity_id);
+        CREATE INDEX IF NOT EXISTS ix_worklogs_user_id
+            ON worklogs (user_id);
+        CREATE INDEX IF NOT EXISTS ix_worklogs_entity_type_entity_id
+            ON worklogs (entity_type, entity_id);
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP TABLE IF EXISTS worklogs")
+    op.execute("DROP TABLE IF EXISTS jira_links")
+    op.execute("DROP TYPE IF EXISTS jirasyncdirection")
+    op.execute("DROP TYPE IF EXISTS jiralinkentitytype")

backend/alembic/versions/b021_add_phase_timing_fields.py

@@ -0,0 +1,38 @@
+"""add_phase_timing_fields
+
+Revision ID: b021phasetiming
+Revises: b020jiraworklogs
+Create Date: 2026-02-17 18:00:00.000000
+
+Add red_started_at and blue_started_at columns to the tests table
+so that automatic worklogs can record real elapsed time per phase.
+"""
+
+from alembic import op
+
+revision = "b021phasetiming"
+down_revision = "b020jiraworklogs"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        ALTER TABLE tests
+            ADD COLUMN IF NOT EXISTS red_started_at      TIMESTAMP,
+            ADD COLUMN IF NOT EXISTS blue_started_at     TIMESTAMP,
+            ADD COLUMN IF NOT EXISTS paused_at           TIMESTAMP,
+            ADD COLUMN IF NOT EXISTS red_paused_seconds  INTEGER DEFAULT 0,
+            ADD COLUMN IF NOT EXISTS blue_paused_seconds INTEGER DEFAULT 0;
+    """)
+
+
+def downgrade() -> None:
+    op.execute("""
+        ALTER TABLE tests
+            DROP COLUMN IF EXISTS red_started_at,
+            DROP COLUMN IF EXISTS blue_started_at,
+            DROP COLUMN IF EXISTS paused_at,
+            DROP COLUMN IF EXISTS red_paused_seconds,
+            DROP COLUMN IF EXISTS blue_paused_seconds;
+    """)

backend/alembic/versions/b022_add_osint_items.py

@@ -0,0 +1,47 @@
+"""add_osint_items
+
+Revision ID: b022osintitems
+Revises: b021phasetiming
+Create Date: 2026-02-17 22:00:00.000000
+
+Add osint_items table for OSINT enrichment data linked to techniques.
+"""
+
+from alembic import op
+
+revision = "b022osintitems"
+down_revision = "b021phasetiming"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        CREATE TABLE IF NOT EXISTS osint_items (
+            id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            technique_id UUID NOT NULL REFERENCES techniques(id),
+            source_type  VARCHAR(50)  NOT NULL,
+            source_url   TEXT         NOT NULL,
+            title        VARCHAR(500) NOT NULL,
+            description  TEXT,
+            severity     VARCHAR(20),
+            discovered_at TIMESTAMP   NOT NULL DEFAULT now(),
+            reviewed     BOOLEAN      NOT NULL DEFAULT false,
+            metadata     JSONB        DEFAULT '{}'::jsonb
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_osint_items_technique_id
+            ON osint_items (technique_id);
+
+        CREATE INDEX IF NOT EXISTS ix_osint_items_source_type
+            ON osint_items (source_type);
+
+        CREATE INDEX IF NOT EXISTS ix_osint_items_reviewed
+            ON osint_items (reviewed) WHERE NOT reviewed;
+    """)
+
+
+def downgrade() -> None:
+    op.execute("""
+        DROP TABLE IF EXISTS osint_items CASCADE;
+    """)

backend/alembic/versions/b023_add_must_change_password.py

@@ -0,0 +1,30 @@
+"""add_must_change_password
+
+Revision ID: b023mustchgpwd
+Revises: b022osintitems
+Create Date: 2026-02-17 23:00:00.000000
+
+Add must_change_password column to users table to force password
+change on first login.
+"""
+
+from alembic import op
+
+revision = "b023mustchgpwd"
+down_revision = "b022osintitems"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        ALTER TABLE users
+            ADD COLUMN IF NOT EXISTS must_change_password BOOLEAN DEFAULT true;
+    """)
+
+
+def downgrade() -> None:
+    op.execute("""
+        ALTER TABLE users
+            DROP COLUMN IF EXISTS must_change_password;
+    """)

backend/alembic/versions/b024_add_critical_test_audit_indexes.py

@@ -0,0 +1,37 @@
+"""add_critical_test_audit_indexes
+
+Add missing critical indexes for tests and audit_logs tables to match
+model __table_args__ declarations.  Existing indexes (from b005, b018,
+b019) are left untouched; only the two genuinely new indexes are created.
+
+Revision ID: b024critidx
+Revises: b023mustchgpwd
+Create Date: 2026-02-18 12:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "b024critidx"
+down_revision: Union[str, None] = "b023mustchgpwd"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_index(
+        "ix_tests_created_at",
+        "tests",
+        ["created_at"],
+    )
+    op.create_index(
+        "ix_tests_state_created_at",
+        "tests",
+        ["state", "created_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_tests_state_created_at", table_name="tests")
+    op.drop_index("ix_tests_created_at", table_name="tests")

backend/alembic/versions/b025_add_unique_test_detection_result.py

@@ -0,0 +1,41 @@
+"""add_unique_test_detection_result
+
+Enforce one evaluation per (test, detection_rule) pair.  Before creating
+the constraint, duplicate rows (if any) are collapsed so the migration
+never fails on an existing database.
+
+Revision ID: b025uqtdr
+Revises: b024critidx
+Create Date: 2026-02-18 14:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "b025uqtdr"
+down_revision: Union[str, None] = "b024critidx"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Remove duplicates keeping the most recently evaluated row
+    op.execute("""
+        DELETE FROM test_detection_results
+        WHERE id NOT IN (
+            SELECT DISTINCT ON (test_id, detection_rule_id) id
+            FROM test_detection_results
+            ORDER BY test_id, detection_rule_id, evaluated_at DESC NULLS LAST
+        )
+    """)
+
+    op.create_unique_constraint(
+        "uq_tdr_test_rule",
+        "test_detection_results",
+        ["test_id", "detection_rule_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("uq_tdr_test_rule", "test_detection_results", type_="unique")

backend/alembic/versions/b026_add_technique_query_indexes.py

@@ -0,0 +1,38 @@
+"""add_technique_query_indexes
+
+Add indexes on techniques table for common query patterns
+(filter by tactic, filter by status_global) used in heatmap, scoring,
+and list-all-techniques operations.
+
+These may already exist if the ORM model auto-created them; the
+``if_not_exists`` flag makes this migration safe to run regardless.
+
+Revision ID: b026techidx
+Revises: b025uqtdr
+Create Date: 2026-02-18 18:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "b026techidx"
+down_revision: Union[str, None] = "b025uqtdr"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_techniques_tactic "
+        "ON techniques (tactic)"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_techniques_status_global "
+        "ON techniques (status_global)"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_techniques_status_global", table_name="techniques")
+    op.drop_index("ix_techniques_tactic", table_name="techniques")

backend/alembic/versions/b027_add_scoring_config.py

@@ -0,0 +1,37 @@
+"""add_scoring_config
+
+Single-row table to persist scoring weights in the database,
+replacing the mutable in-process Settings approach.
+
+Revision ID: b027scorecfg
+Revises: b026techidx
+Create Date: 2026-02-19 10:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+revision: str = "b027scorecfg"
+down_revision: Union[str, None] = "b026techidx"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "scoring_config",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("weight_tests", sa.Float(), nullable=False, server_default="40.0"),
+        sa.Column("weight_detection_rules", sa.Float(), nullable=False, server_default="20.0"),
+        sa.Column("weight_d3fend", sa.Float(), nullable=False, server_default="15.0"),
+        sa.Column("weight_freshness", sa.Float(), nullable=False, server_default="15.0"),
+        sa.Column("weight_platform_diversity", sa.Float(), nullable=False, server_default="10.0"),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("scoring_config")

backend/alembic/versions/b028_phase0_campaign_tests_composite_index.py

@@ -0,0 +1,35 @@
+"""phase0 SR-006 — campaign_tests composite index
+
+Most SR-006 indexes already ship in b005, b009, b018, b019, and b026.
+``tests`` has no ``campaign_id`` column (membership is ``campaign_tests``),
+so this revision adds a composite index to speed “tests in campaign” joins.
+
+Revision ID: b028phase0
+Revises: b027scorecfg
+Create Date: 2026-05-18 12:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+revision: str = "b028phase0"
+down_revision: Union[str, None] = "b027scorecfg"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_index(
+        "ix_campaign_tests_campaign_id_test_id",
+        "campaign_tests",
+        ["campaign_id", "test_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_campaign_tests_campaign_id_test_id",
+        table_name="campaign_tests",
+    )

backend/alembic/versions/b029_phase3_audit_and_classification.py

@@ -0,0 +1,58 @@
+"""Phase 3: audit trail columns and data classification fields.
+
+Revision ID: b029phase3
+Revises: b028phase0
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "b029phase3"
+down_revision: Union[str, None] = "b028phase0"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _column_names(table: str) -> set[str]:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    return {c["name"] for c in insp.get_columns(table)}
+
+
+def upgrade() -> None:
+    audit_cols = _column_names("audit_logs")
+    if "ip_address" not in audit_cols:
+        op.add_column("audit_logs", sa.Column("ip_address", sa.String(45), nullable=True))
+    if "user_agent" not in audit_cols:
+        op.add_column("audit_logs", sa.Column("user_agent", sa.String(500), nullable=True))
+    if "integrity_hash" not in audit_cols:
+        op.add_column("audit_logs", sa.Column("integrity_hash", sa.String(64), nullable=True))
+    if "session_id" not in audit_cols:
+        op.add_column("audit_logs", sa.Column("session_id", sa.String(100), nullable=True))
+
+    for table in ("tests", "evidences", "campaigns"):
+        cols = _column_names(table)
+        if "data_classification" not in cols:
+            op.add_column(
+                table,
+                sa.Column(
+                    "data_classification",
+                    sa.String(20),
+                    nullable=False,
+                    server_default="internal",
+                ),
+            )
+
+
+def downgrade() -> None:
+    for table in ("campaigns", "evidences", "tests"):
+        cols = _column_names(table)
+        if "data_classification" in cols:
+            op.drop_column(table, "data_classification")
+
+    audit_cols = _column_names("audit_logs")
+    for col in ("session_id", "integrity_hash", "user_agent", "ip_address"):
+        if col in audit_cols:
+            op.drop_column("audit_logs", col)

backend/alembic/versions/b030_phase5_scoring_and_snapshots.py

@@ -0,0 +1,117 @@
+"""Phase 5: scoring recency/severity columns and snapshot breakdown fields.
+
+Revision ID: b030phase5
+Revises: b029phase3
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "b030phase5"
+down_revision: Union[str, None] = "b029phase3"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _column_names(table: str) -> set[str]:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    return {c["name"] for c in insp.get_columns(table)}
+
+
+def upgrade() -> None:
+    snap_cols = _column_names("coverage_snapshots")
+    if "by_tactic" not in snap_cols:
+        op.add_column(
+            "coverage_snapshots",
+            sa.Column("by_tactic", postgresql.JSONB(), nullable=False, server_default="{}"),
+        )
+    if "by_status" not in snap_cols:
+        op.add_column(
+            "coverage_snapshots",
+            sa.Column("by_status", postgresql.JSONB(), nullable=False, server_default="{}"),
+        )
+    if "stale_count" not in snap_cols:
+        op.add_column(
+            "coverage_snapshots",
+            sa.Column("stale_count", sa.Integer(), nullable=False, server_default="0"),
+        )
+    if "never_tested_count" not in snap_cols:
+        op.add_column(
+            "coverage_snapshots",
+            sa.Column("never_tested_count", sa.Integer(), nullable=False, server_default="0"),
+        )
+    if "coverage_percentage" not in snap_cols:
+        op.add_column(
+            "coverage_snapshots",
+            sa.Column("coverage_percentage", sa.Float(), nullable=False, server_default="0"),
+        )
+
+    cfg_cols = _column_names("scoring_config")
+    if "weight_recency" not in cfg_cols and "weight_freshness" in cfg_cols:
+        op.alter_column(
+            "scoring_config",
+            "weight_freshness",
+            new_column_name="weight_recency",
+        )
+        cfg_cols.remove("weight_freshness")
+        cfg_cols.add("weight_recency")
+    elif "weight_recency" not in cfg_cols:
+        op.add_column(
+            "scoring_config",
+            sa.Column("weight_recency", sa.Float(), nullable=False, server_default="10.0"),
+        )
+
+    if "weight_severity" not in cfg_cols and "weight_platform_diversity" in cfg_cols:
+        op.alter_column(
+            "scoring_config",
+            "weight_platform_diversity",
+            new_column_name="weight_severity",
+        )
+    elif "weight_severity" not in cfg_cols:
+        op.add_column(
+            "scoring_config",
+            sa.Column("weight_severity", sa.Float(), nullable=False, server_default="10.0"),
+        )
+
+    if "updated_by" not in cfg_cols:
+        op.add_column(
+            "scoring_config",
+            sa.Column(
+                "updated_by",
+                postgresql.UUID(as_uuid=True),
+                sa.ForeignKey("users.id", ondelete="SET NULL"),
+                nullable=True,
+            ),
+        )
+
+
+def downgrade() -> None:
+    cfg_cols = _column_names("scoring_config")
+    if "updated_by" in cfg_cols:
+        op.drop_column("scoring_config", "updated_by")
+    if "weight_severity" in cfg_cols:
+        op.alter_column(
+            "scoring_config",
+            "weight_severity",
+            new_column_name="weight_platform_diversity",
+        )
+    if "weight_recency" in cfg_cols:
+        op.alter_column(
+            "scoring_config",
+            "weight_recency",
+            new_column_name="weight_freshness",
+        )
+
+    for col in (
+        "coverage_percentage",
+        "never_tested_count",
+        "stale_count",
+        "by_status",
+        "by_tactic",
+    ):
+        if col in _column_names("coverage_snapshots"):
+            op.drop_column("coverage_snapshots", col)

backend/app/__init__.py

@@ -0,0 +1 @@
+"""Aegis — MITRE ATT&CK Coverage Platform application package."""

backend/app/auth.py

@@ -1,20 +1,34 @@
-"""
-Security utilities: password hashing and JWT token management.
+"""Security utilities: password hashing and JWT token management.
 
 This module provides pure functions for:
 - Hashing and verifying passwords using bcrypt via passlib.
-- Creating JWT access tokens using python-jose.
+- Creating JWT access tokens using PyJWT.
+- Managing a Redis-backed token blacklist for revocation.
 
 No endpoints are defined here.
 """
 
+# Import logging
+import logging
+
+# Import uuid
+import uuid as _uuid
+
+# Import datetime, timedelta, timezone from datetime
 from datetime import datetime, timedelta, timezone
 
-from jose import jwt
+# Import jwt (PyJWT)
+import jwt
+
+# Import CryptContext from passlib.context
 from passlib.context import CryptContext
 
+# Import settings from app.config
 from app.config import settings
 
+# Assign logger = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
+
 # ---------------------------------------------------------------------------
 # Password hashing
 # ---------------------------------------------------------------------------
@@ -22,13 +36,17 @@ from app.config import settings
 pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
 
 
+# Define function hash_password
 def hash_password(password: str) -> str:
     """Return a bcrypt hash of *password*."""
+    # Return pwd_context.hash(password)
     return pwd_context.hash(password)
 
 
+# Define function verify_password
 def verify_password(plain: str, hashed: str) -> bool:
     """Return ``True`` if *plain* matches the bcrypt *hashed* value."""
+    # Return pwd_context.verify(plain, hashed)
     return pwd_context.verify(plain, hashed)
 
 
@@ -38,13 +56,83 @@ def verify_password(plain: str, hashed: str) -> bool:
 
 
 def create_access_token(data: dict) -> str:
-    """Create a signed JWT containing *data* plus an ``exp`` claim.
+    """Create a signed JWT containing *data* plus ``exp`` and ``jti`` claims.
 
-    The token expires after ``ACCESS_TOKEN_EXPIRE_MINUTES`` (from settings).
+    - ``jti`` (JWT ID): unique identifier that enables token revocation.
+    - ``exp``: expiration timestamp based on ``ACCESS_TOKEN_EXPIRE_MINUTES``.
     """
+    # Assign to_encode = data.copy()
     to_encode = data.copy()
+    # Assign expire = datetime.now(timezone.utc) + timedelta(
     expire = datetime.now(timezone.utc) + timedelta(
+        # Keyword argument: minutes
         minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
     )
-    to_encode.update({"exp": expire})
+    # Call to_encode.update()
+    to_encode.update({
+        # Literal argument value
+        "exp": expire,
+        # Literal argument value
+        "jti": str(_uuid.uuid4()),
+    })
+    # Return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGOR...
     return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+
+
+# ---------------------------------------------------------------------------
+# Token blacklist (Redis-backed)
+# ---------------------------------------------------------------------------
+# Each revoked token's ``jti`` is stored in Redis with a TTL equal to the
+# token's remaining lifetime.  This means entries auto-expire exactly when
+# the token would have become invalid anyway — no manual cleanup needed.
+#
+# Redis survives backend restarts, so blacklisted tokens stay revoked
+# across deploys and multi-worker setups.
+# ---------------------------------------------------------------------------
+
+_BLACKLIST_PREFIX = "blacklist:"
+
+
+# Define function blacklist_token
+def blacklist_token(jti: str, exp: float) -> None:
+    """Add *jti* to the Redis blacklist with a TTL derived from *exp*.
+
+    *exp* is the token's ``exp`` claim (epoch timestamp).  The TTL is set
+    to ``exp - now`` so the key vanishes when the token would have expired
+    naturally.
+    """
+    # Import get_redis_blacklist from app.infrastructure.redis_client
+    from app.infrastructure.redis_client import get_redis_blacklist
+
+    # Assign ttl = max(int(exp - datetime.now(timezone.utc).timestamp()), 1)
+    ttl = max(int(exp - datetime.now(timezone.utc).timestamp()), 1)
+    # Attempt the following; catch errors below
+    try:
+        # Assign r = get_redis_blacklist()
+        r = get_redis_blacklist()
+        # Call r.setex()
+        r.setex(f"{_BLACKLIST_PREFIX}{jti}", ttl, "1")
+    # Handle Exception
+    except Exception:
+        # Log warning: "Failed to blacklist token %s in Redis", jti, exc_
+        logger.warning("Failed to blacklist token %s in Redis", jti, exc_info=True)
+
+
+# Define function is_token_blacklisted
+def is_token_blacklisted(jti: str) -> bool:
+    """Return ``True`` if *jti* has been revoked (exists in Redis)."""
+    # Import get_redis_blacklist from app.infrastructure.redis_client
+    from app.infrastructure.redis_client import get_redis_blacklist
+
+    # Attempt the following; catch errors below
+    try:
+        # Assign r = get_redis_blacklist()
+        r = get_redis_blacklist()
+        # Return r.exists(f"{_BLACKLIST_PREFIX}{jti}") > 0
+        return r.exists(f"{_BLACKLIST_PREFIX}{jti}") > 0
+    # Handle Exception
+    except Exception:
+        # Log warning: "Failed to check blacklist for %s in Redis", jti,
+        logger.warning("Failed to check blacklist for %s in Redis", jti, exc_info=True)
+        # Return False
+        return False

backend/app/config.py

@@ -1,18 +1,197 @@
+"""Application configuration for the Aegis MITRE ATT&CK Coverage Platform.
+
+Loads settings from environment variables and ``.env`` files via
+``pydantic-settings``.  Validates critical secrets at import time and raises
+``RuntimeError`` (production) or issues a ``UserWarning`` (development) when
+unsafe defaults are detected.
+"""
+
+# Import os
+import os
+
+# Import secrets
+import secrets
+
+# Import warnings
+import warnings
+
+# Import BaseSettings from pydantic_settings
 from pydantic_settings import BaseSettings
 
+# ---------------------------------------------------------------------------
+# Detect environment: "production" when AEGIS_ENV or common indicators are set
+# ---------------------------------------------------------------------------
+_is_production = os.environ.get("AEGIS_ENV", "").lower() == "production"
 
+
+# Define class Settings
 class Settings(BaseSettings):
-    DATABASE_URL: str = "postgresql://postgres:postgres@postgres:5432/attackdb"
-    SECRET_KEY: str = "change-me-in-production"
-    ALGORITHM: str = "HS256"
-    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
-    MINIO_ENDPOINT: str = "minio:9000"
-    MINIO_ACCESS_KEY: str = "minioadmin"
-    MINIO_SECRET_KEY: str = "minioadmin"
-    MINIO_BUCKET: str = "evidence"
+    """Application settings loaded from environment variables and .env file."""
 
+    # Assign DATABASE_URL = "postgresql://postgres:postgres@postgres:5432/attackdb"
+    DATABASE_URL: str = "postgresql://postgres:postgres@postgres:5432/attackdb"
+
+    # ── Security ──────────────────────────────────────────────────────
+    # SECRET_KEY has NO safe default.  In development a random key is
+    # generated at startup (tokens invalidate on restart — acceptable
+    # for local dev).  In production it MUST be supplied via env/.env
+    # so tokens survive restarts.
+    SECRET_KEY: str = ""
+    # Assign ALGORITHM = "HS256"
+    ALGORITHM: str = "HS256"
+    # Assign ACCESS_TOKEN_EXPIRE_MINUTES = 15  # short-lived for security; configurable via env
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 15  # short-lived for security; configurable via env
+
+    # ── Redis ─────────────────────────────────────────────────────────
+    REDIS_URL: str = "redis://redis:6379/0"
+    # Logical DB indices on the same Redis instance (PATH in URL is overridden).
+    REDIS_TOKEN_BLACKLIST_DB: int = 1
+    # Assign REDIS_CACHE_DB = 2
+    REDIS_CACHE_DB: int = 2
+
+    # ── CORS ─────────────────────────────────────────────────────────
+    # Comma-separated list of allowed origins, or a JSON array.
+    # In dev this defaults to common local ports; in production set it
+    # to the actual frontend domain(s).
+    CORS_ORIGINS: str = "http://localhost:3000,http://localhost:5173"
+
+    # ── MinIO / S3 ───────────────────────────────────────────────────
+    MINIO_ENDPOINT: str = "minio:9000"
+    # Assign MINIO_ACCESS_KEY = "minioadmin"
+    MINIO_ACCESS_KEY: str = "minioadmin"
+    # Assign MINIO_SECRET_KEY = "minioadmin"
+    MINIO_SECRET_KEY: str = "minioadmin"
+    # Assign MINIO_BUCKET = "evidence"
+    MINIO_BUCKET: str = "evidence"
+    # Assign MINIO_SECURE = False  # True → use HTTPS to connect to MinIO
+    MINIO_SECURE: bool = False  # True → use HTTPS to connect to MinIO
+
+    # ── Re-testing ───────────────────────────────────────────────────
+    MAX_RETEST_COUNT: int = 3  # maximum automatic retests per original test
+
+    # ── Jira Integration ────────────────────────────────────────────
+    JIRA_ENABLED: bool = False
+    # Assign JIRA_URL = ""
+    JIRA_URL: str = ""
+    # Assign JIRA_USERNAME = ""
+    JIRA_USERNAME: str = ""
+    # Assign JIRA_API_TOKEN = ""
+    JIRA_API_TOKEN: str = ""
+    # Assign JIRA_IS_CLOUD = True
+    JIRA_IS_CLOUD: bool = True
+    # Assign JIRA_DEFAULT_PROJECT = ""
+    JIRA_DEFAULT_PROJECT: str = ""
+    # Assign JIRA_ISSUE_TYPE_TEST = "Task"
+    JIRA_ISSUE_TYPE_TEST: str = "Task"
+    # Assign JIRA_ISSUE_TYPE_CAMPAIGN = "Epic"
+    JIRA_ISSUE_TYPE_CAMPAIGN: str = "Epic"
+
+    # ── Tempo Integration ─────────────────────────────────────────────
+    TEMPO_ENABLED: bool = False
+    # Assign TEMPO_API_TOKEN = ""
+    TEMPO_API_TOKEN: str = ""
+    # Assign TEMPO_API_VERSION = 4
+    TEMPO_API_VERSION: int = 4
+    # Assign TEMPO_DEFAULT_WORK_TYPE = "Red Team"
+    TEMPO_DEFAULT_WORK_TYPE: str = "Red Team"
+
+    # ── OSINT / Intelligence ────────────────────────────────────────
+    NVD_API_KEY: str = ""  # optional; increases NVD rate limit from 5/30s to 50/30s
+    # Assign STALE_THRESHOLD_DAYS = 365  # days before coverage is considered stale
+    STALE_THRESHOLD_DAYS: int = 365  # days before coverage is considered stale
+
+    # ── Reporting ─────────────────────────────────────────────────────
+    REPORT_TEMPLATES_DIR: str = "app/templates/reports"
+    # Assign REPORT_OUTPUT_DIR = "/tmp/aegis_reports"
+    REPORT_OUTPUT_DIR: str = "/tmp/aegis_reports"
+    # Assign COMPANY_NAME = "Organization"
+    COMPANY_NAME: str = "Organization"
+    # Assign COMPANY_LOGO_PATH = "app/templates/reports/assets/logo.png"
+    COMPANY_LOGO_PATH: str = "app/templates/reports/assets/logo.png"
+
+    # ── Scoring weights (must sum to 100) ────────────────────────────
+    SCORING_WEIGHT_TESTS: int = 40
+    # Assign SCORING_WEIGHT_DETECTION_RULES = 25
+    SCORING_WEIGHT_DETECTION_RULES: int = 25
+    # Assign SCORING_WEIGHT_D3FEND = 15
+    SCORING_WEIGHT_D3FEND: int = 15
+    # Assign SCORING_WEIGHT_RECENCY = 10
+    SCORING_WEIGHT_RECENCY: int = 10
+    # Assign SCORING_WEIGHT_SEVERITY = 10
+    SCORING_WEIGHT_SEVERITY: int = 10
+    # Legacy env names (mapped in scoring_config_service)
+    SCORING_WEIGHT_FRESHNESS: int = 10
+    # Assign SCORING_WEIGHT_PLATFORM_DIVERSITY = 10
+    SCORING_WEIGHT_PLATFORM_DIVERSITY: int = 10
+
+    # Define class Config
     class Config:
+        """Pydantic BaseSettings configuration — load from .env file."""
+
+        # Assign env_file = ".env"
         env_file = ".env"
 
 
+# Assign settings = Settings()
 settings = Settings()
+
+# ---------------------------------------------------------------------------
+# Post-init validation for SECRET_KEY
+# ---------------------------------------------------------------------------
+_UNSAFE_SECRETS = {
+    # Literal argument value
+    "",
+    # Literal argument value
+    "change-me-in-production",
+    # Literal argument value
+    "change-me-in-production-use-a-long-random-string",
+}
+
+# Check: settings.SECRET_KEY in _UNSAFE_SECRETS
+if settings.SECRET_KEY in _UNSAFE_SECRETS:
+    # Check: _is_production
+    if _is_production:
+        # Raise RuntimeError
+        raise RuntimeError(
+            # Literal argument value
+            "CRITICAL: SECRET_KEY is not configured.  "
+            # Literal argument value
+            "Set a strong random value (>= 32 chars) via the SECRET_KEY "
+            # Literal argument value
+            "environment variable or in your .env file before running in "
+            # Literal argument value
+            "production.  Example:  openssl rand -hex 32"
+        )
+    # Development: auto-generate an ephemeral key and warn
+    settings.SECRET_KEY = secrets.token_hex(32)
+    # Call warnings.warn()
+    warnings.warn(
+        # Literal argument value
+        "SECRET_KEY was not set — using an auto-generated ephemeral key. "
+        # Literal argument value
+        "JWT tokens will be invalidated on every restart.  "
+        # Literal argument value
+        "Set SECRET_KEY in your environment for persistent sessions.",
+        # Keyword argument: stacklevel
+        stacklevel=2,
+    )
+
+# ---------------------------------------------------------------------------
+# SEC-002: Reject default credentials in production
+# ---------------------------------------------------------------------------
+if _is_production:
+    # Assign _DEFAULT_CREDS = {
+    _DEFAULT_CREDS = {
+        ("MINIO_ACCESS_KEY", settings.MINIO_ACCESS_KEY, "minioadmin"),
+        ("MINIO_SECRET_KEY", settings.MINIO_SECRET_KEY, "minioadmin"),
+    }
+    # Iterate over _DEFAULT_CREDS
+    for name, current, default in _DEFAULT_CREDS:
+        # Check: current == default
+        if current == default:
+            # Raise RuntimeError
+            raise RuntimeError(
+                f"CRITICAL: {name} is using the default value '{default}'. "
+                f"Set a strong value via the {name} environment variable "
+                f"before running in production."
+            )

backend/app/database.py

@@ -1,16 +1,164 @@
+"""Database engine and session management for the Aegis platform.
+
+The engine and session factory are created lazily so that tests can override
+``DATABASE_URL`` via environment variables before any import triggers real
+PostgreSQL engine creation (which requires psycopg2).
+"""
+
+# Import Generator from collections.abc
+from collections.abc import Generator
+
+# Import create_engine from sqlalchemy
 from sqlalchemy import create_engine
-from sqlalchemy.orm import sessionmaker, declarative_base
 
-from app.config import settings
+# Import Engine from sqlalchemy.engine
+from sqlalchemy.engine import Engine
 
-engine = create_engine(settings.DATABASE_URL)
-SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+# Import Session, declarative_base, sessionmaker from sqlalchemy.orm
+from sqlalchemy.orm import Session, declarative_base, sessionmaker
+
+# Assign Base = declarative_base()
 Base = declarative_base()
 
+# Engine and session factory are created lazily so that tests can
+# override DATABASE_URL via environment *before* any import triggers
+# the real PostgreSQL engine creation (which requires psycopg2).
+_engine = None
+# Assign _SessionLocal = None
+_SessionLocal = None
 
-def get_db():
+
+# Define function _get_engine
+def _get_engine() -> Engine:
+    """Return the shared SQLAlchemy engine, creating it on first call.
+
+    Returns:
+        Engine: Configured SQLAlchemy engine for the application database.
+    """
+    # Declare global variable
+    global _engine
+    # Check: _engine is None
+    if _engine is None:
+        # Import settings from app.config
+        from app.config import settings
+
+        # Assign url = settings.DATABASE_URL
+        url = settings.DATABASE_URL
+        # Assign kwargs = {}
+        kwargs: dict = {}
+        # Check: url.startswith("postgresql")
+        if url.startswith("postgresql"):
+            # Call kwargs.update()
+            kwargs.update(
+                # Keyword argument: pool_size
+                pool_size=20,
+                # Keyword argument: max_overflow
+                max_overflow=10,
+                # Keyword argument: pool_recycle
+                pool_recycle=3600,
+                # Keyword argument: pool_pre_ping
+                pool_pre_ping=True,
+            )
+        # Assign _engine = create_engine(url, **kwargs)
+        _engine = create_engine(url, **kwargs)
+    # Return _engine
+    return _engine
+
+
+# Define function _get_session_factory
+def _get_session_factory() -> sessionmaker:
+    """Return the shared sessionmaker, creating it on first call.
+
+    Returns:
+        sessionmaker: Configured sessionmaker bound to the application engine.
+    """
+    # Declare global variable
+    global _SessionLocal
+    # Check: _SessionLocal is None
+    if _SessionLocal is None:
+        # Assign _SessionLocal = sessionmaker(
+        _SessionLocal = sessionmaker(
+            # Keyword argument: autocommit
+            autocommit=False, autoflush=False, bind=_get_engine()
+        )
+    # Return _SessionLocal
+    return _SessionLocal
+
+
+# Define class _LazySessionLocal
+class _LazySessionLocal:
+    """Proxy so ``SessionLocal()`` keeps working as before but the real sessionmaker is only created on first call."""
+
+    # Define function __call__
+    def __call__(self, *args: object, **kwargs: object) -> Session:
+        """Create and return a new database session.
+
+        Args:
+            *args (object): Positional arguments forwarded to the sessionmaker.
+            **kwargs (object): Keyword arguments forwarded to the sessionmaker.
+
+        Returns:
+            Session: A new SQLAlchemy database session.
+        """
+        # Return _get_session_factory()(*args, **kwargs)
+        return _get_session_factory()(*args, **kwargs)
+
+    # Define function __getattr__
+    def __getattr__(self, name: str) -> object:
+        """Delegate attribute access to the underlying sessionmaker.
+
+        Args:
+            name (str): Attribute name to look up on the sessionmaker.
+
+        Returns:
+            object: The attribute value from the underlying sessionmaker.
+        """
+        # Return getattr(_get_session_factory(), name)
+        return getattr(_get_session_factory(), name)
+
+
+# Assign SessionLocal = _LazySessionLocal()
+SessionLocal = _LazySessionLocal()
+
+
+# Define class _EngineProxy
+class _EngineProxy:
+    """Thin proxy so ``from app.database import engine`` still works."""
+
+    # Define function __getattr__
+    def __getattr__(self, name: str) -> object:
+        """Delegate attribute access to the lazily-created engine.
+
+        Args:
+            name (str): Attribute name to look up on the real engine.
+
+        Returns:
+            object: The attribute value from the underlying SQLAlchemy engine.
+        """
+        # Return getattr(_get_engine(), name)
+        return getattr(_get_engine(), name)
+
+
+# Assign engine = _EngineProxy()  # type: ignore[assignment]
+engine = _EngineProxy()  # type: ignore[assignment]
+
+
+# Define function get_db
+def get_db() -> Generator[Session, None, None]:
+    """Yield a database session and close it when the request is done.
+
+    Intended for use as a FastAPI dependency.
+
+    Yields:
+        Session: An active SQLAlchemy session for the current request.
+    """
+    # Assign db = SessionLocal()
     db = SessionLocal()
+    # Attempt the following; catch errors below
     try:
+        # Yield db
         yield db
+    # Always execute this cleanup block
     finally:
+        # Close the database session
         db.close()

backend/app/dependencies/__init__.py

@@ -0,0 +1 @@
+"""FastAPI dependency injection helpers for auth, DB, and shared state."""

backend/app/dependencies/auth.py

@@ -1,26 +1,50 @@
-"""
-Authentication and RBAC dependencies for FastAPI.
+"""Authentication and RBAC dependencies for FastAPI.
 
 Provides:
-- ``get_current_user``: decodes JWT, fetches user from DB, raises 401 on failure.
+- ``get_current_user``: decodes JWT from HttpOnly cookie (preferred) or
+  Authorization header (fallback), fetches user from DB, raises 401 on failure.
 - ``require_role``: factory that returns a dependency enforcing a specific role
   (admins always pass).
 """
 
-from fastapi import Depends, HTTPException, status
+# Import Callable from collections.abc
+from collections.abc import Callable
+
+# Import Optional from typing
+from typing import Optional
+
+# Import Cookie, Depends, HTTPException, status from fastapi
+from fastapi import Cookie, Depends, HTTPException, status
+
+# Import OAuth2PasswordBearer from fastapi.security
 from fastapi.security import OAuth2PasswordBearer
-from jose import JWTError, jwt
+
+# Import jwt (PyJWT)
+import jwt
+
+# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
+# Import auth as auth_lib from app
+from app import auth as auth_lib
+
+# Import settings from app.config
 from app.config import settings
+
+# Import get_db from app.database
 from app.database import get_db
+
+# Import User from app.models.user
 from app.models.user import User
 
 # ---------------------------------------------------------------------------
-# OAuth2 scheme
+# OAuth2 scheme (reads Authorization header — used as fallback / Swagger UI)
 # ---------------------------------------------------------------------------
 
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login", auto_error=False)
+
+# Cookie name — must match the one set in the auth router
+_COOKIE_NAME = "aegis_token"
 
 # ---------------------------------------------------------------------------
 # Current-user dependency
@@ -28,38 +52,86 @@ oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
 
 
 async def get_current_user(
-    token: str = Depends(oauth2_scheme),
+    # Entry: aegis_token
+    aegis_token: Optional[str] = Cookie(None),
+    # Entry: bearer_token
+    bearer_token: Optional[str] = Depends(oauth2_scheme),
+    # Entry: db
     db: Session = Depends(get_db),
 ) -> User:
-    """Decode the JWT *token*, look up the user in *db*, and return it.
+    """Decode the JWT, look up the user in *db*, and return it.
+
+    Token resolution order:
+    1. ``aegis_token`` **HttpOnly cookie** (preferred — immune to XSS).
+    2. ``Authorization: Bearer <token>`` header (fallback for API clients
+       and Swagger UI).
 
     Raises :class:`~fastapi.HTTPException` **401** when:
+    - no token is found in either location,
     - the token cannot be decoded,
     - the ``sub`` claim is missing, or
     - no matching active user exists in the database.
     """
+    # Assign credentials_exception = HTTPException(
     credentials_exception = HTTPException(
+        # Keyword argument: status_code
         status_code=status.HTTP_401_UNAUTHORIZED,
+        # Keyword argument: detail
         detail="Could not validate credentials",
+        # Keyword argument: headers
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    # Assign revoked_exception = HTTPException(
+    revoked_exception = HTTPException(
+        # Keyword argument: status_code
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        # Keyword argument: detail
+        detail="Token has been revoked",
+        # Keyword argument: headers
         headers={"WWW-Authenticate": "Bearer"},
     )
 
+    # Prefer cookie, fall back to header
+    token = aegis_token or bearer_token
+    # Check: token is None
+    if token is None:
+        # Raise credentials_exception
+        raise credentials_exception
+
+    # Attempt the following; catch errors below
     try:
+        # Assign payload = jwt.decode(
         payload = jwt.decode(
             token,
             settings.SECRET_KEY,
+            # Keyword argument: algorithms
             algorithms=[settings.ALGORITHM],
         )
+        # Assign username = payload.get("sub")
         username: str | None = payload.get("sub")
+        # Check: username is None
         if username is None:
+            # Raise credentials_exception
             raise credentials_exception
-    except JWTError:
+        # Check token blacklist (revoked tokens)
+        jti: str | None = payload.get("jti")
+        # Check: jti and auth_lib.is_token_blacklisted(jti)
+        if jti and auth_lib.is_token_blacklisted(jti):
+            # Raise revoked_exception
+            raise revoked_exception
+    # Handle any JWT validation error (expired, invalid signature, malformed)
+    except jwt.exceptions.InvalidTokenError:
+        # Raise credentials_exception
         raise credentials_exception
 
+    # Assign user = db.query(User).filter(User.username == username).first()
     user = db.query(User).filter(User.username == username).first()
-    if user is None:
+    # Check: user is None or not user.is_active
+    if user is None or not user.is_active:
+        # Raise credentials_exception
         raise credentials_exception
 
+    # Return user
     return user
 
 
@@ -68,7 +140,30 @@ async def get_current_user(
 # ---------------------------------------------------------------------------
 
 
-def require_role(required_role: str):
+async def require_password_changed(
+    # Entry: current_user
+    current_user: User = Depends(get_current_user),
+) -> User:
+    """Block all requests when the user still needs to change their password.
+
+    Only ``/auth/change-password`` and ``/auth/me`` are exempt — those
+    endpoints do **not** depend on this function.
+    """
+    # Check: getattr(current_user, "must_change_password", False)
+    if getattr(current_user, "must_change_password", False):
+        # Raise HTTPException
+        raise HTTPException(
+            # Keyword argument: status_code
+            status_code=status.HTTP_403_FORBIDDEN,
+            # Keyword argument: detail
+            detail="PASSWORD_CHANGE_REQUIRED",
+        )
+    # Return current_user
+    return current_user
+
+
+# Define function require_role
+def require_role(required_role: str) -> Callable[..., object]:
     """Return a FastAPI dependency that enforces *required_role*.
 
     The dependency allows the request to proceed when
@@ -76,20 +171,29 @@ def require_role(required_role: str):
     Otherwise it raises :class:`~fastapi.HTTPException` **403**.
     """
 
+    # Define async function role_checker
     async def role_checker(
+        # Entry: current_user
         current_user: User = Depends(get_current_user),
     ) -> User:
+        # Check: current_user.role != required_role and current_user.role != "admin"
         if current_user.role != required_role and current_user.role != "admin":
+            # Raise HTTPException
             raise HTTPException(
+                # Keyword argument: status_code
                 status_code=status.HTTP_403_FORBIDDEN,
+                # Keyword argument: detail
                 detail="Not enough permissions",
             )
+        # Return current_user
         return current_user
 
+    # Return role_checker
     return role_checker
 
 
-def require_any_role(*roles: str):
+# Define function require_any_role
+def require_any_role(*roles: str) -> Callable[..., object]:
     """Return a FastAPI dependency that enforces **any** of the given *roles*.
 
     Admins always pass.  Usage example::
@@ -97,14 +201,22 @@ def require_any_role(*roles: str):
         @router.patch("/resource", dependencies=[Depends(require_any_role("red_lead", "blue_lead"))])
     """
 
+    # Define async function role_checker
     async def role_checker(
+        # Entry: current_user
         current_user: User = Depends(get_current_user),
     ) -> User:
+        # Check: current_user.role != "admin" and current_user.role not in roles
         if current_user.role != "admin" and current_user.role not in roles:
+            # Raise HTTPException
             raise HTTPException(
+                # Keyword argument: status_code
                 status_code=status.HTTP_403_FORBIDDEN,
+                # Keyword argument: detail
                 detail="Not enough permissions",
             )
+        # Return current_user
         return current_user
 
+    # Return role_checker
     return role_checker

backend/app/dependencies/repositories.py

@@ -0,0 +1,44 @@
+"""FastAPI dependency providers for repositories.
+
+Wiring lives ONLY in the presentation layer — use cases and services
+never know which concrete repository implementation they receive.
+"""
+
+# Import Depends from fastapi
+from fastapi import Depends
+
+# Import Session from sqlalchemy.orm
+from sqlalchemy.orm import Session
+
+# Import get_db from app.database
+from app.database import get_db
+
+# Import  from app.infrastructure.persistence.repositories.sa_technique_repository
+from app.infrastructure.persistence.repositories.sa_technique_repository import (
+    SATechniqueRepository,
+)
+
+# Import  from app.infrastructure.persistence.repositories.sa_test_repository
+from app.infrastructure.persistence.repositories.sa_test_repository import (
+    SATestRepository,
+)
+
+
+# Define function get_technique_repository
+def get_technique_repository(
+    # Entry: db
+    db: Session = Depends(get_db),
+) -> SATechniqueRepository:
+    """Provide a TechniqueRepository backed by the current DB session."""
+    # Return SATechniqueRepository(db)
+    return SATechniqueRepository(db)
+
+
+# Define function get_test_repository
+def get_test_repository(
+    # Entry: db
+    db: Session = Depends(get_db),
+) -> SATestRepository:
+    """Provide a TestRepository backed by the current DB session."""
+    # Return SATestRepository(db)
+    return SATestRepository(db)

backend/app/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain layer — entities, value objects, errors, and repository ports."""

backend/app/domain/entities/__init__.py

@@ -0,0 +1,34 @@
+"""Domain entity classes representing core business objects."""
+# Import CampaignEntity from app.domain.entities.campaign
+from app.domain.entities.campaign import CampaignEntity
+
+# Import  from app.domain.entities.compliance
+from app.domain.entities.compliance import (
+    ComplianceControlEntity,
+    ComplianceFrameworkEntity,
+    ControlCoverageStatus,
+)
+
+# Import TechniqueEntity from app.domain.entities.technique
+from app.domain.entities.technique import TechniqueEntity
+
+# Import ThreatActorEntity, ThreatActorTechniqueRef from app.domain.entities.threat_actor
+from app.domain.entities.threat_actor import ThreatActorEntity, ThreatActorTechniqueRef
+
+# Assign __all__ = [
+__all__ = [
+    # Literal argument value
+    "CampaignEntity",
+    # Literal argument value
+    "ComplianceControlEntity",
+    # Literal argument value
+    "ComplianceFrameworkEntity",
+    # Literal argument value
+    "ControlCoverageStatus",
+    # Literal argument value
+    "TechniqueEntity",
+    # Literal argument value
+    "ThreatActorEntity",
+    # Literal argument value
+    "ThreatActorTechniqueRef",
+]

backend/app/domain/entities/campaign.py

@@ -0,0 +1,219 @@
+"""Campaign domain entity with lifecycle validation.
+
+Pure domain logic — no framework imports.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import enum
+import enum
+
+# Import uuid
+import uuid
+
+# Import dataclass, field from dataclasses
+from dataclasses import dataclass, field
+
+# Import TYPE_CHECKING from typing
+from typing import TYPE_CHECKING
+
+# Import BusinessRuleViolation, InvalidStateTransition from app.domain.errors
+from app.domain.errors import BusinessRuleViolation, InvalidStateTransition
+
+# Check: TYPE_CHECKING
+if TYPE_CHECKING:
+    # Import Campaign as CampaignORM from app.models.campaign
+    from app.models.campaign import Campaign as CampaignORM
+
+
+# Define class CampaignStatus
+class CampaignStatus(str, enum.Enum):
+    """Lifecycle states for a campaign."""
+
+    # Assign draft = "draft"
+    draft = "draft"
+    # Assign active = "active"
+    active = "active"
+    # Assign completed = "completed"
+    completed = "completed"
+    # Assign archived = "archived"
+    archived = "archived"
+
+
+# Define class CampaignType
+class CampaignType(str, enum.Enum):
+    """Classification of the campaign's testing methodology."""
+
+    # Assign custom = "custom"
+    custom = "custom"
+    # Assign apt_emulation = "apt_emulation"
+    apt_emulation = "apt_emulation"
+    # Assign kill_chain = "kill_chain"
+    kill_chain = "kill_chain"
+    # Assign compliance = "compliance"
+    compliance = "compliance"
+
+
+# Assign VALID_TRANSITIONS = {
+VALID_TRANSITIONS: dict[CampaignStatus, list[CampaignStatus]] = {
+    CampaignStatus.draft: [CampaignStatus.active],
+    CampaignStatus.active: [CampaignStatus.completed],
+    CampaignStatus.completed: [CampaignStatus.archived],
+    CampaignStatus.archived: [],
+}
+
+
+# Apply the @dataclass decorator
+@dataclass
+# Define class CampaignEntity
+class CampaignEntity:
+    """Pure domain representation of a security testing campaign.
+
+    Owns all lifecycle state-machine logic for campaign activation,
+    completion, and archival.
+    """
+
+    # name: str
+    name: str
+    # Assign type = CampaignType.custom
+    type: CampaignType = CampaignType.custom
+    # Assign status = CampaignStatus.draft
+    status: CampaignStatus = CampaignStatus.draft
+    # Assign id = None
+    id: uuid.UUID | None = None
+    # Assign description = None
+    description: str | None = None
+    # Assign threat_actor_id = None
+    threat_actor_id: uuid.UUID | None = None
+    # Assign created_by = None
+    created_by: uuid.UUID | None = None
+    # Assign target_platform = None
+    target_platform: str | None = None
+    # Assign tags = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    # Assign test_count = 0
+    test_count: int = 0
+
+    # Define function can_transition_to
+    def can_transition_to(self, target: CampaignStatus) -> bool:
+        """Check whether transitioning from the current status to *target* is valid.
+
+        Args:
+            target (CampaignStatus): The desired next status.
+
+        Returns:
+            bool: True if the transition is allowed, False otherwise.
+        """
+        # Return target in VALID_TRANSITIONS.get(self.status, [])
+        return target in VALID_TRANSITIONS.get(self.status, [])
+
+    # Define function activate
+    def activate(self) -> None:
+        """Transition the campaign from ``draft`` to ``active``.
+
+        Returns:
+            None
+        """
+        # Check: not self.can_transition_to(CampaignStatus.active)
+        if not self.can_transition_to(CampaignStatus.active):
+            # Raise InvalidStateTransition
+            raise InvalidStateTransition(
+                self.status.value, CampaignStatus.active.value,
+                [s.value for s in VALID_TRANSITIONS[self.status]],
+            )
+        # Check: self.test_count == 0
+        if self.test_count == 0:
+            # Raise BusinessRuleViolation
+            raise BusinessRuleViolation(
+                # Literal argument value
+                "Campaign must have at least one test to activate"
+            )
+        # Assign self.status = CampaignStatus.active
+        self.status = CampaignStatus.active
+
+    # Define function complete
+    def complete(self) -> None:
+        """Transition the campaign from ``active`` to ``completed``.
+
+        Returns:
+            None
+        """
+        # Check: not self.can_transition_to(CampaignStatus.completed)
+        if not self.can_transition_to(CampaignStatus.completed):
+            # Raise InvalidStateTransition
+            raise InvalidStateTransition(
+                self.status.value, CampaignStatus.completed.value,
+                [s.value for s in VALID_TRANSITIONS[self.status]],
+            )
+        # Assign self.status = CampaignStatus.completed
+        self.status = CampaignStatus.completed
+
+    # Define function archive
+    def archive(self) -> None:
+        """Transition the campaign from ``completed`` to ``archived``.
+
+        Returns:
+            None
+        """
+        # Check: not self.can_transition_to(CampaignStatus.archived)
+        if not self.can_transition_to(CampaignStatus.archived):
+            # Raise InvalidStateTransition
+            raise InvalidStateTransition(
+                self.status.value, CampaignStatus.archived.value,
+                [s.value for s in VALID_TRANSITIONS[self.status]],
+            )
+        # Assign self.status = CampaignStatus.archived
+        self.status = CampaignStatus.archived
+
+    # Define function ensure_modifiable
+    def ensure_modifiable(self) -> None:
+        """Raise BusinessRuleViolation if the campaign is not in a modifiable state.
+
+        Returns:
+            None
+        """
+        # Check: self.status not in (CampaignStatus.draft, CampaignStatus.active)
+        if self.status not in (CampaignStatus.draft, CampaignStatus.active):
+            # Raise BusinessRuleViolation
+            raise BusinessRuleViolation(
+                f"Cannot modify campaign in '{self.status.value}' state"
+            )
+
+    # Apply the @classmethod decorator
+    @classmethod
+    # Define function from_orm
+    def from_orm(cls, orm: CampaignORM) -> CampaignEntity:
+        """Build a CampaignEntity from a SQLAlchemy Campaign model.
+
+        Args:
+            orm (CampaignORM): The SQLAlchemy Campaign ORM model instance.
+
+        Returns:
+            CampaignEntity: A fully populated domain entity reflecting the ORM state.
+        """
+        # Assign test_count = len(getattr(orm, "campaign_tests", None) or [])
+        test_count = len(getattr(orm, "campaign_tests", None) or [])
+        # Return cls(
+        return cls(
+            # Keyword argument: id
+            id=orm.id,
+            # Keyword argument: name
+            name=orm.name,
+            # Keyword argument: type
+            type=CampaignType(orm.type) if orm.type else CampaignType.custom,
+            # Keyword argument: status
+            status=CampaignStatus(orm.status) if orm.status else CampaignStatus.draft,
+            # Keyword argument: description
+            description=orm.description,
+            # Keyword argument: threat_actor_id
+            threat_actor_id=orm.threat_actor_id,
+            # Keyword argument: created_by
+            created_by=orm.created_by,
+            # Keyword argument: target_platform
+            target_platform=orm.target_platform,
+            # Keyword argument: tags
+            tags=orm.tags or [],
+            # Keyword argument: test_count
+            test_count=test_count,
+        )

backend/app/domain/entities/compliance.py

@@ -0,0 +1,164 @@
+"""Compliance domain entities with coverage calculation logic.
+
+Pure domain logic — no framework imports.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import enum
+import enum
+
+# Import uuid
+import uuid
+
+# Import dataclass, field from dataclasses
+from dataclasses import dataclass, field
+
+
+# Define class ControlCoverageStatus
+class ControlCoverageStatus(str, enum.Enum):
+    """Computed coverage level for a single compliance control."""
+
+    # Assign covered = "covered"
+    covered = "covered"
+    # Assign partially_covered = "partially_covered"
+    partially_covered = "partially_covered"
+    # Assign not_covered = "not_covered"
+    not_covered = "not_covered"
+
+
+# Apply the @dataclass decorator
+@dataclass
+# Define class ComplianceControlEntity
+class ComplianceControlEntity:
+    """Pure domain representation of a single compliance framework control.
+
+    Derives its coverage status from the technique statuses associated
+    with it via the ``technique_statuses`` list.
+    """
+
+    # control_id: str
+    control_id: str
+    # title: str
+    title: str
+    # Assign id = None
+    id: uuid.UUID | None = None
+    # Assign description = None
+    description: str | None = None
+    # Assign category = None
+    category: str | None = None
+    # Assign technique_statuses = field(default_factory=list)
+    technique_statuses: list[str] = field(default_factory=list)
+
+    # Apply the @property decorator
+    @property
+    # Define function coverage_status
+    def coverage_status(self) -> ControlCoverageStatus:
+        """Compute the coverage status for this control based on linked technique statuses.
+
+        Returns:
+            ControlCoverageStatus: ``covered`` when all techniques are covered,
+                ``partially_covered`` when at least one is covered, and
+                ``not_covered`` when none are covered or the control has no techniques.
+        """
+        # Check: not self.technique_statuses
+        if not self.technique_statuses:
+            # Return ControlCoverageStatus.not_covered
+            return ControlCoverageStatus.not_covered
+        # Assign covered_statuses = {"validated", "partial"}
+        covered_statuses = {"validated", "partial"}
+        # Assign covered = [s for s in self.technique_statuses if s in covered_statuses]
+        covered = [s for s in self.technique_statuses if s in covered_statuses]
+        # Check: len(covered) == len(self.technique_statuses)
+        if len(covered) == len(self.technique_statuses):
+            # Return ControlCoverageStatus.covered
+            return ControlCoverageStatus.covered
+        # Alternative: len(covered) > 0
+        elif len(covered) > 0:
+            # Return ControlCoverageStatus.partially_covered
+            return ControlCoverageStatus.partially_covered
+        # Return ControlCoverageStatus.not_covered
+        return ControlCoverageStatus.not_covered
+
+
+# Apply the @dataclass decorator
+@dataclass
+# Define class ComplianceFrameworkEntity
+class ComplianceFrameworkEntity:
+    """Pure domain representation of a compliance framework (e.g. NIST 800-53, PCI-DSS).
+
+    Aggregates a collection of controls and provides aggregate coverage statistics.
+    """
+
+    # name: str
+    name: str
+    # Assign id = None
+    id: uuid.UUID | None = None
+    # Assign version = None
+    version: str | None = None
+    # Assign description = None
+    description: str | None = None
+    # Assign is_active = True
+    is_active: bool = True
+    # Assign controls = field(default_factory=list)
+    controls: list[ComplianceControlEntity] = field(default_factory=list)
+
+    # Apply the @property decorator
+    @property
+    # Define function total_controls
+    def total_controls(self) -> int:
+        """Return the total number of controls in this framework.
+
+        Returns:
+            int: Count of all controls regardless of coverage status.
+        """
+        # Return len(self.controls)
+        return len(self.controls)
+
+    # Apply the @property decorator
+    @property
+    # Define function covered_controls
+    def covered_controls(self) -> int:
+        """Return the number of fully covered controls in this framework.
+
+        Returns:
+            int: Count of controls with ``ControlCoverageStatus.covered`` status.
+        """
+        # Return sum(
+        return sum(
+            # Literal argument value
+            1 for c in self.controls
+            if c.coverage_status == ControlCoverageStatus.covered
+        )
+
+    # Apply the @property decorator
+    @property
+    # Define function coverage_pct
+    def coverage_pct(self) -> float:
+        """Return the percentage of controls that are fully covered.
+
+        Returns:
+            float: A value from 0.0 to 100.0, rounded to one decimal place.
+                Returns 0.0 when the framework has no controls.
+        """
+        # Check: self.total_controls == 0
+        if self.total_controls == 0:
+            # Return 0.0
+            return 0.0
+        # Return round(self.covered_controls / self.total_controls * 100, 1)
+        return round(self.covered_controls / self.total_controls * 100, 1)
+
+    # Define function get_gap_controls
+    def get_gap_controls(self) -> list[ComplianceControlEntity]:
+        """Return controls that are not fully covered.
+
+        Returns:
+            list[ComplianceControlEntity]: Controls with ``partially_covered`` or
+                ``not_covered`` status.
+        """
+        # Return [
+        return [
+            c for c in self.controls
+            if c.coverage_status != ControlCoverageStatus.covered
+        ]

backend/app/domain/entities/technique.py

@@ -0,0 +1,310 @@
+"""TechniqueEntity — pure domain object for a MITRE ATT&CK technique.
+
+Owns the status recalculation logic that was previously in
+``status_service.py``.  Has **no** dependency on FastAPI, SQLAlchemy,
+or any infrastructure concern.
+
+Usage::
+
+    entity = TechniqueEntity.from_orm(technique_orm_model)
+    entity.recalculate_status(test_states_and_results)
+    entity.mark_reviewed()
+    entity.apply_to(technique_orm_model)
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import uuid
+import uuid
+
+# Import dataclass, field from dataclasses
+from dataclasses import dataclass, field
+
+# Import datetime from datetime
+from datetime import datetime
+
+# Import TYPE_CHECKING from typing
+from typing import TYPE_CHECKING
+
+# Import TechniqueStatus, TestResult, TestState from app.domain.enums
+from app.domain.enums import TechniqueStatus, TestResult, TestState
+
+# Import MitreId from app.domain.value_objects.mitre_id
+from app.domain.value_objects.mitre_id import MitreId
+
+# Check: TYPE_CHECKING
+if TYPE_CHECKING:
+    # Import Technique as TechniqueORM from app.models.technique
+    from app.models.technique import Technique as TechniqueORM
+
+
+# Apply the @dataclass decorator
+@dataclass(frozen=True)
+# Define class _TestSnapshot
+class _TestSnapshot:
+    """Minimal read-only view of a test for status calculation."""
+
+    # state: TestState
+    state: TestState
+    # detection_result: str | None
+    detection_result: str | None
+
+
+# Apply the @dataclass decorator
+@dataclass
+# Define class TechniqueEntity
+class TechniqueEntity:
+    """Pure domain representation of a MITRE ATT&CK technique."""
+
+    # id: uuid.UUID
+    id: uuid.UUID
+    # mitre_id: str
+    mitre_id: str
+    # name: str
+    name: str
+    # Assign tactic = None
+    tactic: str | None = None
+    # Assign description = None
+    description: str | None = None
+    # Assign platforms = field(default_factory=list)
+    platforms: list[str] = field(default_factory=list)
+    # Assign is_subtechnique = False
+    is_subtechnique: bool = False
+    # Assign parent_mitre_id = None
+    parent_mitre_id: str | None = None
+    # Assign status_global = TechniqueStatus.not_evaluated
+    status_global: TechniqueStatus = TechniqueStatus.not_evaluated
+    # Assign review_required = False
+    review_required: bool = False
+    # Assign last_review_date = None
+    last_review_date: datetime | None = None
+    # Assign mitre_version = None
+    mitre_version: str | None = None
+    # Assign mitre_last_modified = None
+    mitre_last_modified: datetime | None = None
+
+    # -- Factory -----------------------------------------------------------
+
+    @classmethod
+    # Define function create
+    def create(
+        cls,
+        *,
+        # Entry: mitre_id
+        mitre_id: str,
+        # Entry: name
+        name: str,
+        # Entry: tactic
+        tactic: str | None = None,
+        # Entry: description
+        description: str | None = None,
+        # Entry: platforms
+        platforms: list[str] | None = None,
+    ) -> TechniqueEntity:
+        """Create a new technique, validating the MITRE ID format.
+
+        Args:
+            mitre_id (str): MITRE ATT&CK identifier (e.g. ``"T1059"`` or ``"T1059.001"``).
+            name (str): Human-readable name of the technique.
+            tactic (str | None): MITRE tactic category the technique belongs to.
+            description (str | None): Optional free-text description.
+            platforms (list[str] | None): List of platform strings the technique applies to.
+
+        Returns:
+            TechniqueEntity: A new entity with a freshly generated UUID and
+                ``status_global`` set to ``not_evaluated``.
+        """
+        # Assign validated_id = MitreId(mitre_id)
+        validated_id = MitreId(mitre_id)
+        # Return cls(
+        return cls(
+            # Keyword argument: id
+            id=uuid.uuid4(),
+            # Keyword argument: mitre_id
+            mitre_id=validated_id.value,
+            # Keyword argument: name
+            name=name,
+            # Keyword argument: tactic
+            tactic=tactic,
+            # Keyword argument: description
+            description=description,
+            # Keyword argument: platforms
+            platforms=platforms or [],
+            # Keyword argument: is_subtechnique
+            is_subtechnique=validated_id.is_subtechnique,
+            # Keyword argument: parent_mitre_id
+            parent_mitre_id=validated_id.parent_id,
+            # Keyword argument: status_global
+            status_global=TechniqueStatus.not_evaluated,
+        )
+
+    # Apply the @classmethod decorator
+    @classmethod
+    # Define function from_orm
+    def from_orm(cls, model: TechniqueORM) -> TechniqueEntity:
+        """Build a TechniqueEntity from a SQLAlchemy Technique model.
+
+        Args:
+            model (TechniqueORM): The ORM model instance to convert.
+
+        Returns:
+            TechniqueEntity: A fully populated domain entity reflecting the ORM state.
+        """
+        # Assign raw_status = model.status_global
+        raw_status = model.status_global
+        # Check: raw_status is None
+        if raw_status is None:
+            # Assign status = TechniqueStatus.not_evaluated
+            status = TechniqueStatus.not_evaluated
+        # Alternative: isinstance(raw_status, TechniqueStatus)
+        elif isinstance(raw_status, TechniqueStatus):
+            # Assign status = raw_status
+            status = raw_status
+        # Fallback: handle remaining cases
+        else:
+            # Assign status = TechniqueStatus(raw_status)
+            status = TechniqueStatus(raw_status)
+        # Return cls(
+        return cls(
+            # Keyword argument: id
+            id=model.id,
+            # Keyword argument: mitre_id
+            mitre_id=model.mitre_id,
+            # Keyword argument: name
+            name=model.name,
+            # Keyword argument: tactic
+            tactic=model.tactic,
+            # Keyword argument: description
+            description=model.description,
+            # Keyword argument: platforms
+            platforms=model.platforms or [],
+            # Keyword argument: is_subtechnique
+            is_subtechnique=model.is_subtechnique or False,
+            # Keyword argument: parent_mitre_id
+            parent_mitre_id=model.parent_mitre_id,
+            # Keyword argument: status_global
+            status_global=status,
+            # Keyword argument: review_required
+            review_required=model.review_required or False,
+            # Keyword argument: last_review_date
+            last_review_date=model.last_review_date,
+            # Keyword argument: mitre_version
+            mitre_version=getattr(model, "mitre_version", None),
+            # Keyword argument: mitre_last_modified
+            mitre_last_modified=getattr(model, "mitre_last_modified", None),
+        )
+
+    # Define function apply_to
+    def apply_to(self, model: TechniqueORM) -> None:
+        """Copy mutable fields back onto the ORM model.
+
+        Args:
+            model (TechniqueORM): The ORM model to update in-place.
+
+        Returns:
+            None
+        """
+        # Assign model.status_global = self.status_global
+        model.status_global = self.status_global
+        # Assign model.review_required = self.review_required
+        model.review_required = self.review_required
+        # Assign model.last_review_date = self.last_review_date
+        model.last_review_date = self.last_review_date
+
+    # -- Business logic ----------------------------------------------------
+
+    def recalculate_status(
+        self,
+        # Entry: test_snapshots
+        test_snapshots: list[tuple[str, str | None]],
+    ) -> TechniqueStatus:
+        """Recompute ``status_global`` from a list of (state, detection_result) pairs.
+
+        Rules (v2):
+          1. No tests -> not_evaluated
+          2. All validated -> inspect detection results:
+             - All detected -> validated
+             - Any partially_detected -> partial
+             - Otherwise -> not_covered
+          3. Some validated, others in progress -> partial
+          4. All in intermediate states -> in_progress
+
+        Args:
+            test_snapshots (list[tuple[str, str | None]]): Each element is a
+                ``(state, detection_result)`` pair where *state* is a
+                :class:`TestState` value string and *detection_result* is a
+                :class:`TestResult` value string or ``None``.
+
+        Returns:
+            TechniqueStatus: The newly computed status, which is also stored on
+                the entity's ``status_global`` field.
+        """
+        # Assign tests = [
+        tests = [
+            _TestSnapshot(
+                # Keyword argument: state
+                state=s if isinstance(s, TestState) else TestState(s),
+                # Keyword argument: detection_result
+                detection_result=dr,
+            )
+            for s, dr in test_snapshots
+        ]
+
+        # Check: not tests
+        if not tests:
+            # Assign self.status_global = TechniqueStatus.not_evaluated
+            self.status_global = TechniqueStatus.not_evaluated
+        # Alternative: all(t.state == TestState.validated for t in tests)
+        elif all(t.state == TestState.validated for t in tests):
+            # Assign results = [t.detection_result for t in tests if t.detection_result]
+            results = [t.detection_result for t in tests if t.detection_result]
+            # Check: results and all(r == TestResult.detected or r == "detected" for r i...
+            if results and all(r == TestResult.detected or r == "detected" for r in results):
+                # Assign self.status_global = TechniqueStatus.validated
+                self.status_global = TechniqueStatus.validated
+            # elif any(
+            elif any(
+                # Keyword argument: r
+                r == TestResult.partially_detected or r == "partially_detected"
+                for r in results
+            ):
+                # Assign self.status_global = TechniqueStatus.partial
+                self.status_global = TechniqueStatus.partial
+            # Fallback: handle remaining cases
+            else:
+                # Assign self.status_global = TechniqueStatus.not_covered
+                self.status_global = TechniqueStatus.not_covered
+        # Alternative: any(t.state == TestState.validated for t in tests)
+        elif any(t.state == TestState.validated for t in tests):
+            # Assign self.status_global = TechniqueStatus.partial
+            self.status_global = TechniqueStatus.partial
+        # Fallback: handle remaining cases
+        else:
+            # Assign self.status_global = TechniqueStatus.in_progress
+            self.status_global = TechniqueStatus.in_progress
+
+        # Return self.status_global
+        return self.status_global
+
+    # Define function mark_reviewed
+    def mark_reviewed(self) -> None:
+        """Mark the technique as reviewed, clearing the review flag.
+
+        Returns:
+            None
+        """
+        # Assign self.review_required = False
+        self.review_required = False
+        # Assign self.last_review_date = datetime.utcnow()
+        self.last_review_date = datetime.utcnow()
+
+    # Define function flag_for_review
+    def flag_for_review(self) -> None:
+        """Flag the technique as needing review.
+
+        Returns:
+            None
+        """
+        # Assign self.review_required = True
+        self.review_required = True

backend/app/domain/entities/threat_actor.py

@@ -0,0 +1,206 @@
+"""Threat actor domain entity with coverage analysis logic.
+
+Pure domain logic — no framework imports.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import uuid
+import uuid
+
+# Import dataclass, field from dataclasses
+from dataclasses import dataclass, field
+
+# Import TYPE_CHECKING from typing
+from typing import TYPE_CHECKING
+
+# Check: TYPE_CHECKING
+if TYPE_CHECKING:
+    # Import ThreatActor as ThreatActorORM from app.models.threat_actor
+    from app.models.threat_actor import ThreatActor as ThreatActorORM
+
+
+# Apply the @dataclass decorator
+@dataclass
+# Define class ThreatActorTechniqueRef
+class ThreatActorTechniqueRef:
+    """Lightweight reference to a technique used by an actor."""
+
+    # technique_id: uuid.UUID
+    technique_id: uuid.UUID
+    # Assign mitre_id = None
+    mitre_id: str | None = None
+    # Assign name = None
+    name: str | None = None
+    # Assign status = None
+    status: str | None = None
+    # Assign usage_description = None
+    usage_description: str | None = None
+
+
+# Apply the @dataclass decorator
+@dataclass
+# Define class ThreatActorEntity
+class ThreatActorEntity:
+    """Pure domain representation of a MITRE ATT&CK threat actor (group).
+
+    Aggregates references to the techniques the actor is known to use and
+    provides coverage analysis properties.
+    """
+
+    # name: str
+    name: str
+    # Assign id = None
+    id: uuid.UUID | None = None
+    # Assign mitre_id = None
+    mitre_id: str | None = None
+    # Assign aliases = field(default_factory=list)
+    aliases: list[str] = field(default_factory=list)
+    # Assign description = None
+    description: str | None = None
+    # Assign country = None
+    country: str | None = None
+    # Assign target_sectors = field(default_factory=list)
+    target_sectors: list[str] = field(default_factory=list)
+    # Assign target_regions = field(default_factory=list)
+    target_regions: list[str] = field(default_factory=list)
+    # Assign motivation = None
+    motivation: str | None = None
+    # Assign sophistication = None
+    sophistication: str | None = None
+    # Assign first_seen = None
+    first_seen: str | None = None
+    # Assign last_seen = None
+    last_seen: str | None = None
+    # Assign is_active = True
+    is_active: bool = True
+    # Assign techniques = field(default_factory=list)
+    techniques: list[ThreatActorTechniqueRef] = field(default_factory=list)
+
+    # Apply the @property decorator
+    @property
+    # Define function technique_count
+    def technique_count(self) -> int:
+        """Return the total number of techniques associated with this actor.
+
+        Returns:
+            int: Count of technique references.
+        """
+        # Return len(self.techniques)
+        return len(self.techniques)
+
+    # Apply the @property decorator
+    @property
+    # Define function covered_techniques
+    def covered_techniques(self) -> list[ThreatActorTechniqueRef]:
+        """Return technique references whose coverage status is ``validated`` or ``partial``.
+
+        Returns:
+            list[ThreatActorTechniqueRef]: Subset of techniques considered covered.
+        """
+        # Return [
+        return [
+            t for t in self.techniques
+            if t.status in ("validated", "partial")
+        ]
+
+    # Apply the @property decorator
+    @property
+    # Define function uncovered_techniques
+    def uncovered_techniques(self) -> list[ThreatActorTechniqueRef]:
+        """Return technique references whose coverage status is neither ``validated`` nor ``partial``.
+
+        Returns:
+            list[ThreatActorTechniqueRef]: Subset of techniques not yet covered.
+        """
+        # Return [
+        return [
+            t for t in self.techniques
+            if t.status not in ("validated", "partial")
+        ]
+
+    # Apply the @property decorator
+    @property
+    # Define function coverage_pct
+    def coverage_pct(self) -> float:
+        """Return the percentage of the actor's techniques that are covered.
+
+        Returns:
+            float: A value from 0.0 to 100.0, rounded to one decimal place.
+                Returns 0.0 when the actor has no associated techniques.
+        """
+        # Check: not self.techniques
+        if not self.techniques:
+            # Return 0.0
+            return 0.0
+        # Return round(len(self.covered_techniques) / len(self.techniques) * 100, 1)
+        return round(len(self.covered_techniques) / len(self.techniques) * 100, 1)
+
+    # Apply the @classmethod decorator
+    @classmethod
+    # Define function from_orm
+    def from_orm(cls, orm: ThreatActorORM) -> ThreatActorEntity:
+        """Build a ThreatActorEntity from a SQLAlchemy ThreatActor model.
+
+        Args:
+            orm (ThreatActorORM): The ORM model instance to convert.
+
+        Returns:
+            ThreatActorEntity: A fully populated domain entity including
+                technique references resolved from the ORM relationship.
+        """
+        # Assign techs = []
+        techs: list[ThreatActorTechniqueRef] = []
+        # Iterate over getattr(orm, "techniques", None) or []
+        for tat in getattr(orm, "techniques", None) or []:
+            # Assign technique = getattr(tat, "technique", None)
+            technique = getattr(tat, "technique", None)
+            # Call techs.append()
+            techs.append(ThreatActorTechniqueRef(
+                # Keyword argument: technique_id
+                technique_id=tat.technique_id,
+                # Keyword argument: mitre_id
+                mitre_id=getattr(technique, "mitre_id", None) if technique else None,
+                # Keyword argument: name
+                name=getattr(technique, "name", None) if technique else None,
+                # Keyword argument: status
+                status=(
+                    technique.status_global.value
+                    if technique and hasattr(technique.status_global, "value")
+                    else getattr(technique, "status_global", None) if technique else None
+                ),
+                # Keyword argument: usage_description
+                usage_description=tat.usage_description,
+            ))
+        # Return cls(
+        return cls(
+            # Keyword argument: id
+            id=orm.id,
+            # Keyword argument: name
+            name=orm.name,
+            # Keyword argument: mitre_id
+            mitre_id=orm.mitre_id,
+            # Keyword argument: aliases
+            aliases=orm.aliases or [],
+            # Keyword argument: description
+            description=orm.description,
+            # Keyword argument: country
+            country=orm.country,
+            # Keyword argument: target_sectors
+            target_sectors=orm.target_sectors or [],
+            # Keyword argument: target_regions
+            target_regions=orm.target_regions or [],
+            # Keyword argument: motivation
+            motivation=orm.motivation,
+            # Keyword argument: sophistication
+            sophistication=orm.sophistication,
+            # Keyword argument: first_seen
+            first_seen=orm.first_seen,
+            # Keyword argument: last_seen
+            last_seen=orm.last_seen,
+            # Keyword argument: is_active
+            is_active=orm.is_active if orm.is_active is not None else True,
+            # Keyword argument: techniques
+            techniques=techs,
+        )

backend/app/domain/enums.py

@@ -0,0 +1,81 @@
+"""Canonical domain enums for Aegis.
+
+These enums represent core domain concepts and are the single source of
+truth.  ``models/enums.py`` re-exports them so that existing ORM code
+continues to work without changes.
+"""
+
+# Import enum
+import enum
+
+
+# Define class TechniqueStatus
+class TechniqueStatus(str, enum.Enum):
+    """Coverage and evaluation status for a MITRE ATT&CK technique."""
+
+    # Assign not_evaluated = "not_evaluated"
+    not_evaluated = "not_evaluated"
+    # Assign in_progress = "in_progress"
+    in_progress = "in_progress"
+    # Assign validated = "validated"
+    validated = "validated"
+    # Assign partial = "partial"
+    partial = "partial"
+    # Assign not_covered = "not_covered"
+    not_covered = "not_covered"
+    # Assign review_required = "review_required"
+    review_required = "review_required"
+
+
+# Define class TestState
+class TestState(str, enum.Enum):
+    """Lifecycle states in the security test state machine."""
+
+    # Assign draft = "draft"
+    draft = "draft"
+    # Assign red_executing = "red_executing"
+    red_executing = "red_executing"
+    # Assign blue_evaluating = "blue_evaluating"
+    blue_evaluating = "blue_evaluating"
+    # Assign in_review = "in_review"
+    in_review = "in_review"
+    # Assign validated = "validated"
+    validated = "validated"
+    # Assign rejected = "rejected"
+    rejected = "rejected"
+
+
+# Define class TeamSide
+class TeamSide(str, enum.Enum):
+    """Identifies which team (red or blue) an action belongs to."""
+
+    # Assign red = "red"
+    red = "red"
+    # Assign blue = "blue"
+    blue = "blue"
+
+
+# Define class TestResult
+class TestResult(str, enum.Enum):
+    """Outcome of a red-team test from a detection perspective."""
+
+    # Assign detected = "detected"
+    detected = "detected"
+    # Assign not_detected = "not_detected"
+    not_detected = "not_detected"
+    # Assign partially_detected = "partially_detected"
+    partially_detected = "partially_detected"
+
+
+# Define class DataClassification
+class DataClassification(str, enum.Enum):
+    """Data sensitivity classification levels for compliance and retention policies."""
+
+    # Assign public = "public"
+    public = "public"
+    # Assign internal = "internal"
+    internal = "internal"
+    # Assign sensitive = "sensitive"
+    sensitive = "sensitive"
+    # Assign restricted = "restricted"
+    restricted = "restricted"

backend/app/domain/errors.py

@@ -0,0 +1,192 @@
+"""Canonical domain error hierarchy for Aegis.
+
+Every service-layer error should be a subclass of :class:`DomainError`.
+The global exception handler in ``app.middleware.error_handler`` maps
+each concrete subclass to an appropriate HTTP status code so that
+services never depend on FastAPI.
+
+Existing code that imports from ``app.domain.exceptions`` continues to
+work — that module re-exports everything defined here.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+
+# Define class DomainError
+class DomainError(Exception):
+    """Base for all domain errors."""
+
+    # Define function __init__
+    def __init__(self, message: str, *, code: str = "DOMAIN_ERROR") -> None:
+        """Initialise the domain error with a human-readable message and error code.
+
+        Args:
+            message (str): Human-readable description of the error.
+            code (str): Machine-readable error code used by the HTTP error handler.
+
+        Returns:
+            None
+        """
+        # Assign self.message = message
+        self.message = message
+        # Assign self.code = code
+        self.code = code
+        # Call super()
+        super().__init__(message)
+
+
+# ── Entity lifecycle ──────────────────────────────────────────────────
+
+
+class EntityNotFoundError(DomainError):
+    """A requested entity does not exist."""
+
+    # Define function __init__
+    def __init__(self, entity: str, identifier: str) -> None:
+        """Initialise an entity-not-found error.
+
+        Args:
+            entity (str): Name of the entity type that was not found (e.g. "Technique").
+            identifier (str): The ID or key used in the failed lookup.
+
+        Returns:
+            None
+        """
+        # Call super()
+        super().__init__(f"{entity} not found: {identifier}", code="NOT_FOUND")
+        # Assign self.entity = entity
+        self.entity = entity
+        # Assign self.identifier = identifier
+        self.identifier = identifier
+
+
+# Define class DuplicateEntityError
+class DuplicateEntityError(DomainError):
+    """Creating an entity that already exists."""
+
+    # Define function __init__
+    def __init__(self, entity: str, field: str, value: str) -> None:
+        """Initialise a duplicate-entity error.
+
+        Args:
+            entity (str): Name of the entity type that already exists (e.g. "Campaign").
+            field (str): Name of the field whose value conflicts (e.g. "name").
+            value (str): The conflicting value that is already in use.
+
+        Returns:
+            None
+        """
+        # Call super()
+        super().__init__(
+            f"{entity} with {field}='{value}' already exists",
+            # Keyword argument: code
+            code="DUPLICATE",
+        )
+
+
+# ── State machine ────────────────────────────────────────────────────
+
+
+class InvalidStateTransition(DomainError):  # noqa: N818 — DDD term, renaming would break 96 call sites
+    """A state-machine transition is not allowed."""
+
+    # Define function __init__
+    def __init__(
+        self,
+        # Entry: current_state
+        current_state: str,
+        # Entry: target_state
+        target_state: str,
+        # Entry: valid_transitions
+        valid_transitions: list[str] | None = None,
+    ) -> None:
+        """Initialise an invalid state-transition error.
+
+        Args:
+            current_state (str): The entity's present state (e.g. "draft").
+            target_state (str): The state that was illegally requested.
+            valid_transitions (list[str] | None): Allowed target states from the
+                current state; included in the error message when provided.
+
+        Returns:
+            None
+        """
+        # Assign msg = f"Cannot transition from '{current_state}' to '{target_state}'"
+        msg = f"Cannot transition from '{current_state}' to '{target_state}'"
+        # Check: valid_transitions
+        if valid_transitions:
+            # Assign msg = f". Valid transitions: {valid_transitions}"
+            msg += f". Valid transitions: {valid_transitions}"
+        # Call super()
+        super().__init__(msg, code="INVALID_TRANSITION")
+        # Assign self.current_state = current_state
+        self.current_state = current_state
+        # Assign self.target_state = target_state
+        self.target_state = target_state
+        # Assign self.valid_transitions = valid_transitions or []
+        self.valid_transitions = valid_transitions or []
+
+
+# ── Business rules ────────────────────────────────────────────────────
+
+
+class BusinessRuleViolation(DomainError):  # noqa: N818 — DDD term, renaming would break 96 call sites
+    """An operation violates a business invariant."""
+
+    # Define function __init__
+    def __init__(self, message: str) -> None:
+        """Initialise a business-rule violation error.
+
+        Args:
+            message (str): Human-readable description of the violated rule.
+
+        Returns:
+            None
+        """
+        # Call super()
+        super().__init__(message, code="BUSINESS_RULE_VIOLATION")
+
+
+# Define class InvalidOperationError
+class InvalidOperationError(BusinessRuleViolation):
+    """An operation is invalid in the current context.
+
+    Kept for backward compatibility; new code should prefer
+    :class:`BusinessRuleViolation` directly.
+    """
+
+    # Define function __init__
+    def __init__(self, message: str) -> None:
+        """Initialise an invalid-operation error.
+
+        Args:
+            message (str): Human-readable description of why the operation is invalid.
+
+        Returns:
+            None
+        """
+        # Call super()
+        super().__init__(message)
+        # Assign self.code = "INVALID_OPERATION"
+        self.code = "INVALID_OPERATION"
+
+
+# ── Authorization ────────────────────────────────────────────────────
+
+
+class PermissionViolation(DomainError):  # noqa: N818 — DDD term, renaming would break 96 call sites
+    """The user lacks permissions for an action."""
+
+    # Define function __init__
+    def __init__(self, message: str = "Insufficient permissions") -> None:
+        """Initialise a permission-violation error.
+
+        Args:
+            message (str): Human-readable description of the access denial.
+
+        Returns:
+            None
+        """
+        # Call super()
+        super().__init__(message, code="FORBIDDEN")

backend/app/domain/exceptions.py

@@ -0,0 +1,25 @@
+"""Backward-compatible re-exports from :mod:`app.domain.errors`.
+
+All domain errors now live in ``errors.py``.  This module preserves the
+old import paths so that existing code keeps working without changes::
+
+    from app.domain.exceptions import InvalidTransitionError  # still works
+"""
+
+# Import # noqa: F401 from app.domain.errors
+from app.domain.errors import (  # noqa: F401
+    BusinessRuleViolation,
+    DomainError,
+    DuplicateEntityError,
+    EntityNotFoundError,
+    InvalidOperationError,
+    InvalidStateTransition,
+    PermissionViolation,
+)
+
+# Legacy aliases — old name → new name
+DomainException = DomainError
+# Assign InvalidTransitionError = InvalidStateTransition
+InvalidTransitionError = InvalidStateTransition
+# Assign AuthorizationError = PermissionViolation
+AuthorizationError = PermissionViolation

backend/app/domain/ports/__init__.py

@@ -0,0 +1 @@
+"""Abstract port interfaces that infrastructure adapters must implement."""

backend/app/domain/ports/import_service.py

@@ -0,0 +1,165 @@
+"""Port defining the common interface for data import services.
+
+All import services (Atomic Red Team, Sigma, CALDERA, etc.) follow the
+same contract: they receive a database session and return a summary dict
+with import statistics.
+
+New import sources can be added by:
+1. Implementing the ``ImportService`` protocol in a new module
+2. Registering the handler in the ``IMPORT_REGISTRY``
+
+This satisfies the Open/Closed Principle — the system is open for new
+import sources without modifying existing code.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import Any, Protocol, runtime_checkable from typing
+from typing import Any, Protocol, runtime_checkable
+
+# Import Session from sqlalchemy.orm
+from sqlalchemy.orm import Session
+
+
+# Apply the @runtime_checkable decorator
+@runtime_checkable
+# Define class ImportService
+class ImportService(Protocol):
+    """Contract for any data-import operation.
+
+    Each implementation is a callable ``(Session) -> dict`` that
+    downloads, parses, and upserts records from an external source.
+    """
+
+    # Define function __call__
+    def __call__(self, db: Session) -> dict[str, Any]:
+        """Execute the import operation against the given database session.
+
+        Args:
+            db (Session): Active SQLAlchemy session to use for all DB operations.
+
+        Returns:
+            dict[str, Any]: Summary statistics for the import run (e.g. created,
+                updated, skipped counts).
+        """
+        # ...
+        ...
+
+
+# Define class ImportServiceEntry
+class ImportServiceEntry:
+    """Lazy-loading wrapper that resolves a module-level function on first call."""
+
+    # Assign __slots__ = ("_module_path", "_func_name", "_resolved")
+    __slots__ = ("_module_path", "_func_name", "_resolved")
+
+    # Define function __init__
+    def __init__(self, module_path: str, func_name: str) -> None:
+        """Initialise the lazy entry with the module path and function name to resolve later.
+
+        Args:
+            module_path (str): Dotted Python module path, e.g.
+                ``"app.services.atomic_import_service"``.
+            func_name (str): Name of the callable to import from *module_path*.
+
+        Returns:
+            None
+        """
+        # Assign self._module_path = module_path
+        self._module_path = module_path
+        # Assign self._func_name = func_name
+        self._func_name = func_name
+        # Assign self._resolved = None
+        self._resolved: ImportService | None = None
+
+    # Define function __call__
+    def __call__(self, db: Session) -> dict[str, Any]:
+        """Resolve the import function on first call and invoke it with *db*.
+
+        Args:
+            db (Session): SQLAlchemy session passed through to the underlying
+                import function.
+
+        Returns:
+            dict[str, Any]: Import statistics returned by the underlying function
+                (e.g. counts of created/updated/skipped records).
+        """
+        # Check: self._resolved is None
+        if self._resolved is None:
+            # Import importlib
+            import importlib
+            # Assign mod = importlib.import_module(self._module_path)
+            mod = importlib.import_module(self._module_path)
+            # Assign self._resolved = getattr(mod, self._func_name)
+            self._resolved = getattr(mod, self._func_name)
+        # Return self._resolved(db)
+        return self._resolved(db)
+
+    # Apply the @property decorator
+    @property
+    # Define function source_info
+    def source_info(self) -> str:
+        """Return a human-readable identifier for this import entry.
+
+        Returns:
+            str: The fully qualified function reference as
+                ``"<module_path>.<func_name>"``.
+        """
+        # Return f"{self._module_path}.{self._func_name}"
+        return f"{self._module_path}.{self._func_name}"
+
+
+# Assign IMPORT_REGISTRY = {
+IMPORT_REGISTRY: dict[str, ImportServiceEntry] = {
+    # Literal argument value
+    "atomic_red_team": ImportServiceEntry(
+        # Literal argument value
+        "app.services.atomic_import_service", "import_atomic_red_team",
+    ),
+    # Literal argument value
+    "sigma": ImportServiceEntry(
+        # Literal argument value
+        "app.services.sigma_import_service", "sync",
+    ),
+    # Literal argument value
+    "lolbas": ImportServiceEntry(
+        # Literal argument value
+        "app.services.lolbas_import_service", "sync",
+    ),
+    # Literal argument value
+    "gtfobins": ImportServiceEntry(
+        # Literal argument value
+        "app.services.lolbas_import_service", "sync_gtfobins",
+    ),
+    # Literal argument value
+    "caldera": ImportServiceEntry(
+        # Literal argument value
+        "app.services.caldera_import_service", "sync",
+    ),
+    # Literal argument value
+    "elastic_rules": ImportServiceEntry(
+        # Literal argument value
+        "app.services.elastic_import_service", "sync",
+    ),
+    # Literal argument value
+    "mitre_cti": ImportServiceEntry(
+        # Literal argument value
+        "app.services.threat_actor_import_service", "sync",
+    ),
+    # Literal argument value
+    "d3fend": ImportServiceEntry(
+        # Literal argument value
+        "app.services.d3fend_import_service", "sync",
+    ),
+}
+
+
+# Define function get_import_handler
+def get_import_handler(source_name: str) -> ImportServiceEntry | None:
+    """Look up the import handler for *source_name*.
+
+    Returns ``None`` when no handler is registered.
+    """
+    # Return IMPORT_REGISTRY.get(source_name)
+    return IMPORT_REGISTRY.get(source_name)

backend/app/domain/ports/repositories/__init__.py

@@ -0,0 +1,9 @@
+"""Abstract repository port interfaces for domain entity persistence."""
+# Import TechniqueRepository from app.domain.ports.repositories.technique_repository
+from app.domain.ports.repositories.technique_repository import TechniqueRepository
+
+# Import TestRepository from app.domain.ports.repositories.test_repository
+from app.domain.ports.repositories.test_repository import TestRepository
+
+# Assign __all__ = ["TechniqueRepository", "TestRepository"]
+__all__ = ["TechniqueRepository", "TestRepository"]

backend/app/domain/ports/repositories/technique_repository.py

@@ -0,0 +1,160 @@
+"""Port defining how the application accesses technique data.
+
+This is a domain contract — implementations live in infrastructure/.
+The domain layer NEVER imports the implementation.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import uuid
+import uuid
+
+# Import NamedTuple, Protocol, runtime_checkable from typing
+from typing import NamedTuple, Protocol, runtime_checkable
+
+# Import TechniqueEntity from app.domain.entities.technique
+from app.domain.entities.technique import TechniqueEntity
+
+# Import TechniqueStatus from app.domain.enums
+from app.domain.enums import TechniqueStatus
+
+
+# Define class TechniqueWithCounts
+class TechniqueWithCounts(NamedTuple):
+    """Pre-aggregated technique data for heatmap/scoring."""
+
+    # entity: TechniqueEntity
+    entity: TechniqueEntity
+    # test_count: int
+    test_count: int
+    # validated_test_count: int
+    validated_test_count: int
+    # detection_rule_count: int
+    detection_rule_count: int
+
+
+# Apply the @runtime_checkable decorator
+@runtime_checkable
+# Define class TechniqueRepository
+class TechniqueRepository(Protocol):
+    """Data access contract for techniques (one per aggregate root)."""
+
+    # -- Single-entity access ----------------------------------------------
+
+    def find_by_id(self, technique_id: uuid.UUID) -> TechniqueEntity | None:
+        """Return the technique with the given primary key, or None if absent.
+
+        Args:
+            technique_id (uuid.UUID): Primary key of the technique to look up.
+
+        Returns:
+            TechniqueEntity | None: The matching entity, or None if not found.
+        """
+        # ...
+        ...
+
+    # Define function find_by_mitre_id
+    def find_by_mitre_id(self, mitre_id: str) -> TechniqueEntity | None:
+        """Return the technique matching the given MITRE ATT&CK identifier, or None.
+
+        Args:
+            mitre_id (str): MITRE ATT&CK ID (e.g. ``"T1059"`` or ``"T1059.001"``).
+
+        Returns:
+            TechniqueEntity | None: The matching entity, or None if not found.
+        """
+        # ...
+        ...
+
+    # -- List access -------------------------------------------------------
+
+    def list_all(
+        self,
+        *,
+        # Entry: tactic
+        tactic: str | None = None,
+        # Entry: status
+        status: TechniqueStatus | None = None,
+        # Entry: review_required
+        review_required: bool | None = None,
+    ) -> list[TechniqueEntity]:
+        """Return all techniques, optionally filtered by tactic, status, or review flag.
+
+        Args:
+            tactic (str | None): When provided, restrict results to this tactic category.
+            status (TechniqueStatus | None): When provided, restrict results to this status.
+            review_required (bool | None): When provided, restrict results to techniques
+                whose ``review_required`` flag matches this value.
+
+        Returns:
+            list[TechniqueEntity]: Matching technique entities; may be empty.
+        """
+        # ...
+        ...
+
+    # Define function list_by_ids
+    def list_by_ids(self, ids: list[uuid.UUID]) -> list[TechniqueEntity]:
+        """Return all techniques whose primary keys are in *ids*.
+
+        Args:
+            ids (list[uuid.UUID]): List of technique UUIDs to retrieve.
+
+        Returns:
+            list[TechniqueEntity]: Entities found for the supplied IDs; order
+                is not guaranteed and missing IDs are silently omitted.
+        """
+        # ...
+        ...
+
+    # -- Batch queries (scoring/heatmap performance) -----------------------
+
+    def count_by_status(self) -> dict[TechniqueStatus, int]:
+        """Return a count of techniques grouped by their global status.
+
+        Returns:
+            dict[TechniqueStatus, int]: Mapping from each status value to the
+                number of techniques in that state.
+        """
+        # ...
+        ...
+
+    # Define function find_all_with_test_counts
+    def find_all_with_test_counts(self) -> list[TechniqueWithCounts]:
+        """Return all techniques together with pre-aggregated test and rule counts.
+
+        Returns:
+            list[TechniqueWithCounts]: Each element bundles a TechniqueEntity
+                with its total, validated, and detection-rule counts for use
+                in heatmap and scoring calculations.
+        """
+        # ...
+        ...
+
+    # -- Mutations ---------------------------------------------------------
+
+    def save(self, technique: TechniqueEntity) -> TechniqueEntity:
+        """Persist a technique entity and return the saved state.
+
+        Args:
+            technique (TechniqueEntity): The entity to create or update.
+
+        Returns:
+            TechniqueEntity: The persisted entity, potentially with updated
+                fields (e.g. server-side timestamps).
+        """
+        # ...
+        ...
+
+    # Define function exists_by_mitre_id
+    def exists_by_mitre_id(self, mitre_id: str) -> bool:
+        """Return True if a technique with the given MITRE ID exists in the repository.
+
+        Args:
+            mitre_id (str): MITRE ATT&CK ID to check (e.g. ``"T1059"``).
+
+        Returns:
+            bool: True if a matching technique is found, False otherwise.
+        """
+        # ...
+        ...

backend/app/domain/ports/repositories/test_repository.py

@@ -0,0 +1,108 @@
+"""Port defining how the application accesses test data.
+
+This is a domain contract — implementations live in infrastructure/.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import uuid
+import uuid
+
+# Import Protocol from typing
+from typing import Protocol
+
+# Import TestState from app.domain.enums
+from app.domain.enums import TestState
+
+
+# Define class TestRepository
+class TestRepository(Protocol):
+    """Data access contract for tests."""
+
+    # -- Single-entity access ----------------------------------------------
+
+    def find_by_id(self, test_id: uuid.UUID) -> object | None:
+        """Return a Test ORM model by primary key, or None.
+
+        Returns the ORM model directly (not a domain entity) because
+        the TestEntity is constructed at the service layer via
+        ``TestEntity.from_orm()``.
+
+        Args:
+            test_id (uuid.UUID): Primary key of the test to look up.
+
+        Returns:
+            object | None: The ORM model instance, or None if not found.
+        """
+        # ...
+        ...
+
+    # -- List access -------------------------------------------------------
+
+    def list_by_technique(self, technique_id: uuid.UUID) -> list[object]:
+        """Return all test ORM models associated with the given technique.
+
+        Args:
+            technique_id (uuid.UUID): Primary key of the technique whose tests to retrieve.
+
+        Returns:
+            list[object]: ORM model instances for all tests linked to this technique.
+        """
+        # ...
+        ...
+
+    # Define function list_by_state
+    def list_by_state(self, state: TestState) -> list[object]:
+        """Return all test ORM models in the given state.
+
+        Args:
+            state (TestState): The state to filter tests by.
+
+        Returns:
+            list[object]: ORM model instances for all tests currently in *state*.
+        """
+        # ...
+        ...
+
+    # Define function count_by_technique_and_state
+    def count_by_technique_and_state(
+        self,
+        # Entry: technique_id
+        technique_id: uuid.UUID,
+    ) -> dict[TestState, int]:
+        """Return test counts grouped by state for a single technique.
+
+        Args:
+            technique_id (uuid.UUID): Primary key of the technique whose test
+                counts to aggregate.
+
+        Returns:
+            dict[TestState, int]: Mapping from each test state to the number of
+                tests in that state for the given technique.
+        """
+        # ...
+        ...
+
+    # -- Batch queries -----------------------------------------------------
+
+    def get_states_and_results_for_technique(
+        self,
+        # Entry: technique_id
+        technique_id: uuid.UUID,
+    ) -> list[tuple[str, str | None]]:
+        """Return (state, detection_result) pairs for all tests of a technique.
+
+        Used by TechniqueEntity.recalculate_status() without loading full
+        test models.
+
+        Args:
+            technique_id (uuid.UUID): Primary key of the technique whose test
+                data to retrieve.
+
+        Returns:
+            list[tuple[str, str | None]]: Each tuple contains the test state
+                string and the detection result string (or None if not yet set).
+        """
+        # ...
+        ...

backend/app/domain/test_entity.py

@@ -0,0 +1,667 @@
+"""TestEntity — pure domain object for the test lifecycle state machine.
+
+This entity owns ALL state-transition logic and business rules for a
+security test.  It has **no** dependency on FastAPI, SQLAlchemy, or any
+infrastructure concern.
+
+Usage::
+
+    entity = TestEntity.from_orm(test_orm_model)
+    entity.start_execution()          # draft → red_executing
+    entity.submit_red_evidence()      # red_executing → blue_evaluating
+    entity.pause_timer()
+    entity.resume_timer()
+    entity.submit_blue_evidence()     # blue_evaluating → in_review
+    entity.validate_red("approved")
+    entity.validate_blue("approved")  # triggers dual-validation → validated
+    entity.reopen()                   # rejected → draft
+
+After mutations, the service layer copies ``entity.changes`` back onto
+the ORM model and persists via Unit of Work.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import enum
+import enum
+
+# Import uuid
+import uuid
+
+# Import dataclass, field from dataclasses
+from dataclasses import dataclass, field
+
+# Import datetime from datetime
+from datetime import datetime
+
+# Import TYPE_CHECKING, Any from typing
+from typing import TYPE_CHECKING, Any
+
+# Import  from app.domain.errors
+from app.domain.errors import (
+    BusinessRuleViolation,
+    InvalidOperationError,
+    InvalidStateTransition,
+)
+
+# Check: TYPE_CHECKING
+if TYPE_CHECKING:
+    # Import Test as TestORM from app.models.test
+    from app.models.test import Test as TestORM
+
+# ── Value objects ────────────────────────────────────────────────────
+
+
+class TestState(str, enum.Enum):
+    """Ordered lifecycle states for a security test."""
+
+    # Assign draft = "draft"
+    draft = "draft"
+    # Assign red_executing = "red_executing"
+    red_executing = "red_executing"
+    # Assign blue_evaluating = "blue_evaluating"
+    blue_evaluating = "blue_evaluating"
+    # Assign in_review = "in_review"
+    in_review = "in_review"
+    # Assign validated = "validated"
+    validated = "validated"
+    # Assign rejected = "rejected"
+    rejected = "rejected"
+
+
+# Assign VALID_TRANSITIONS = {
+VALID_TRANSITIONS: dict[TestState, list[TestState]] = {
+    TestState.draft:           [TestState.red_executing],
+    TestState.red_executing:   [TestState.blue_evaluating],
+    TestState.blue_evaluating: [TestState.in_review],
+    TestState.in_review:       [TestState.validated, TestState.rejected],
+    TestState.rejected:        [TestState.draft],
+    TestState.validated:       [],
+}
+
+# Assign _PAUSABLE_STATES = frozenset({TestState.red_executing, TestState.blue_evaluating})
+_PAUSABLE_STATES = frozenset({TestState.red_executing, TestState.blue_evaluating})
+
+
+# ── Domain events (lightweight records of what happened) ─────────────
+
+
+@dataclass(frozen=True)
+# Define class DomainEvent
+class DomainEvent:
+    """Immutable record of a domain-level event emitted by the test entity."""
+
+    # name: str
+    name: str
+    # Assign payload = field(default_factory=dict)
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+# ── Entity ───────────────────────────────────────────────────────────
+
+
+@dataclass
+# Define class TestEntity
+class TestEntity:
+    """Pure domain representation of a security test."""
+
+    # id: uuid.UUID
+    id: uuid.UUID
+    # state: TestState
+    state: TestState
+
+    # Red validation
+    red_validation_status: str | None = None
+    # Assign red_validated_by = None
+    red_validated_by: uuid.UUID | None = None
+    # Assign red_validated_at = None
+    red_validated_at: datetime | None = None
+    # Assign red_validation_notes = None
+    red_validation_notes: str | None = None
+
+    # Blue validation
+    blue_validation_status: str | None = None
+    # Assign blue_validated_by = None
+    blue_validated_by: uuid.UUID | None = None
+    # Assign blue_validated_at = None
+    blue_validated_at: datetime | None = None
+    # Assign blue_validation_notes = None
+    blue_validation_notes: str | None = None
+
+    # Phase timing
+    execution_date: datetime | None = None
+    # Assign red_started_at = None
+    red_started_at: datetime | None = None
+    # Assign blue_started_at = None
+    blue_started_at: datetime | None = None
+    # Assign paused_at = None
+    paused_at: datetime | None = None
+    # Assign red_paused_seconds = 0
+    red_paused_seconds: int = 0
+    # Assign blue_paused_seconds = 0
+    blue_paused_seconds: int = 0
+
+    # Internal bookkeeping (not persisted as-is)
+    _events: list[DomainEvent] = field(default_factory=list, repr=False)
+
+    # -- Factory --------------------------------------------------------
+
+    @classmethod
+    # Define function from_orm
+    def from_orm(cls, model: TestORM) -> TestEntity:
+        """Build a TestEntity from a SQLAlchemy ``Test`` model instance.
+
+        Args:
+            model (TestORM): The ORM model whose fields will be copied into the entity.
+
+        Returns:
+            TestEntity: A fully populated domain entity reflecting the ORM state.
+        """
+        # Assign raw_state = model.state
+        raw_state = model.state
+        # Assign state = raw_state if isinstance(raw_state, TestState) else TestState(raw_st...
+        state = raw_state if isinstance(raw_state, TestState) else TestState(raw_state)
+        # Return cls(
+        return cls(
+            # Keyword argument: id
+            id=model.id,
+            # Keyword argument: state
+            state=state,
+            # Keyword argument: red_validation_status
+            red_validation_status=model.red_validation_status,
+            # Keyword argument: red_validated_by
+            red_validated_by=model.red_validated_by,
+            # Keyword argument: red_validated_at
+            red_validated_at=model.red_validated_at,
+            # Keyword argument: red_validation_notes
+            red_validation_notes=model.red_validation_notes,
+            # Keyword argument: blue_validation_status
+            blue_validation_status=model.blue_validation_status,
+            # Keyword argument: blue_validated_by
+            blue_validated_by=model.blue_validated_by,
+            # Keyword argument: blue_validated_at
+            blue_validated_at=model.blue_validated_at,
+            # Keyword argument: blue_validation_notes
+            blue_validation_notes=model.blue_validation_notes,
+            # Keyword argument: execution_date
+            execution_date=model.execution_date,
+            # Keyword argument: red_started_at
+            red_started_at=model.red_started_at,
+            # Keyword argument: blue_started_at
+            blue_started_at=model.blue_started_at,
+            # Keyword argument: paused_at
+            paused_at=model.paused_at,
+            # Keyword argument: red_paused_seconds
+            red_paused_seconds=model.red_paused_seconds or 0,
+            # Keyword argument: blue_paused_seconds
+            blue_paused_seconds=model.blue_paused_seconds or 0,
+        )
+
+    # Define function apply_to
+    def apply_to(self, model: TestORM) -> None:
+        """Copy the entity's mutable fields back onto the ORM model.
+
+        Args:
+            model (TestORM): The ORM model to update in-place.
+
+        Returns:
+            None
+        """
+        # Assign model.state = self.state
+        model.state = self.state
+        # Assign model.red_validation_status = self.red_validation_status
+        model.red_validation_status = self.red_validation_status
+        # Assign model.red_validated_by = self.red_validated_by
+        model.red_validated_by = self.red_validated_by
+        # Assign model.red_validated_at = self.red_validated_at
+        model.red_validated_at = self.red_validated_at
+        # Assign model.red_validation_notes = self.red_validation_notes
+        model.red_validation_notes = self.red_validation_notes
+        # Assign model.blue_validation_status = self.blue_validation_status
+        model.blue_validation_status = self.blue_validation_status
+        # Assign model.blue_validated_by = self.blue_validated_by
+        model.blue_validated_by = self.blue_validated_by
+        # Assign model.blue_validated_at = self.blue_validated_at
+        model.blue_validated_at = self.blue_validated_at
+        # Assign model.blue_validation_notes = self.blue_validation_notes
+        model.blue_validation_notes = self.blue_validation_notes
+        # Assign model.execution_date = self.execution_date
+        model.execution_date = self.execution_date
+        # Assign model.red_started_at = self.red_started_at
+        model.red_started_at = self.red_started_at
+        # Assign model.blue_started_at = self.blue_started_at
+        model.blue_started_at = self.blue_started_at
+        # Assign model.paused_at = self.paused_at
+        model.paused_at = self.paused_at
+        # Assign model.red_paused_seconds = self.red_paused_seconds
+        model.red_paused_seconds = self.red_paused_seconds
+        # Assign model.blue_paused_seconds = self.blue_paused_seconds
+        model.blue_paused_seconds = self.blue_paused_seconds
+
+    # -- Query helpers --------------------------------------------------
+
+    @property
+    # Define function events
+    def events(self) -> list[DomainEvent]:
+        """Return a snapshot of all domain events raised on this entity.
+
+        Returns:
+            list[DomainEvent]: Ordered list of events emitted since the entity
+                was constructed or last cleared.
+        """
+        # Return list(self._events)
+        return list(self._events)
+
+    # Define function can_transition
+    def can_transition(self, target: TestState) -> bool:
+        """Check whether a transition from the current state to *target* is valid.
+
+        Args:
+            target (TestState): The desired next state.
+
+        Returns:
+            bool: True if the transition is allowed, False otherwise.
+        """
+        # Return target in VALID_TRANSITIONS.get(self.state, [])
+        return target in VALID_TRANSITIONS.get(self.state, [])
+
+    # Apply the @property decorator
+    @property
+    # Define function is_terminal
+    def is_terminal(self) -> bool:
+        """Return True if the test has reached its final (validated) state.
+
+        Returns:
+            bool: True when state is ``validated``, False for all other states.
+        """
+        # Return self.state == TestState.validated
+        return self.state == TestState.validated
+
+    # -- Core transition ------------------------------------------------
+
+    def transition_to(self, target: TestState | str) -> str:
+        """Validate and apply a state transition.
+
+        Accepts either a :class:`TestState` member or its string value
+        (so callers using ``models.enums.TestState`` work transparently).
+
+        Returns the *previous* state value as a plain string.
+
+        Raises :class:`InvalidStateTransition` when the move is illegal.
+
+        Args:
+            target (TestState | str): The desired next state, as an enum member
+                or its string equivalent.
+
+        Returns:
+            str: The previous state value before the transition.
+        """
+        # Assign value = target.value if hasattr(target, "value") else str(target)
+        value = target.value if hasattr(target, "value") else str(target)
+        # Assign resolved = target if isinstance(target, TestState) else TestState(value)
+        resolved = target if isinstance(target, TestState) else TestState(value)
+        # Return self._transition(resolved)
+        return self._transition(resolved)
+
+    # Define function _transition
+    def _transition(self, target: TestState) -> str:
+        """Validate and apply a state transition, returning the previous state value.
+
+        Args:
+            target (TestState): The desired next state enum member.
+
+        Returns:
+            str: The previous state value before the transition was applied.
+        """
+        # Check: not self.can_transition(target)
+        if not self.can_transition(target):
+            # Assign valid = [s.value for s in VALID_TRANSITIONS.get(self.state, [])]
+            valid = [s.value for s in VALID_TRANSITIONS.get(self.state, [])]
+            # Raise InvalidStateTransition
+            raise InvalidStateTransition(
+                # Keyword argument: current_state
+                current_state=self.state.value,
+                # Keyword argument: target_state
+                target_state=target.value,
+                # Keyword argument: valid_transitions
+                valid_transitions=valid,
+            )
+        # Assign previous = self.state.value
+        previous = self.state.value
+        # Assign self.state = target
+        self.state = target
+        # Call self._events.append()
+        self._events.append(DomainEvent(
+            # Literal argument value
+            "state_changed",
+            {"previous": previous, "new": target.value},
+        ))
+        # Return previous
+        return previous
+
+    # -- Lifecycle commands --------------------------------------------
+
+    def start_execution(self) -> None:
+        """Transition the test from ``draft`` to ``red_executing``.
+
+        Returns:
+            None
+        """
+        # Call self._transition()
+        self._transition(TestState.red_executing)
+        # Assign now = datetime.utcnow()
+        now = datetime.utcnow()
+        # Assign self.execution_date = now
+        self.execution_date = now
+        # Assign self.red_started_at = now
+        self.red_started_at = now
+        # Call self._events.append()
+        self._events.append(DomainEvent("execution_started"))
+
+    # Define function submit_red_evidence
+    def submit_red_evidence(self) -> int:
+        """Transition the test from ``red_executing`` to ``blue_evaluating``.
+
+        Auto-resumes if paused.  Returns paused seconds accumulated
+        during this phase (for worklog calculation).
+
+        Returns:
+            int: Total seconds the red phase was paused.
+        """
+        # Assign paused_extra = self._auto_resume()
+        paused_extra = self._auto_resume()
+        # Call self._transition()
+        self._transition(TestState.blue_evaluating)
+        # Assign total_paused = self.red_paused_seconds + paused_extra
+        total_paused = self.red_paused_seconds + paused_extra
+        # Assign self.blue_started_at = datetime.utcnow()
+        self.blue_started_at = datetime.utcnow()
+        # Assign self.blue_paused_seconds = 0
+        self.blue_paused_seconds = 0
+        # Call self._events.append()
+        self._events.append(DomainEvent(
+            # Literal argument value
+            "red_evidence_submitted",
+            {"red_paused_seconds": total_paused},
+        ))
+        # Return total_paused
+        return total_paused
+
+    # Define function submit_blue_evidence
+    def submit_blue_evidence(self) -> int:
+        """Transition the test from ``blue_evaluating`` to ``in_review``.
+
+        Auto-resumes if paused.  Returns paused seconds accumulated
+        during this phase (for worklog calculation).
+
+        Returns:
+            int: Total seconds the blue phase was paused.
+        """
+        # Assign paused_extra = self._auto_resume()
+        paused_extra = self._auto_resume()
+        # Call self._transition()
+        self._transition(TestState.in_review)
+        # Assign total_paused = self.blue_paused_seconds + paused_extra
+        total_paused = self.blue_paused_seconds + paused_extra
+        # Call self._events.append()
+        self._events.append(DomainEvent(
+            # Literal argument value
+            "blue_evidence_submitted",
+            {"blue_paused_seconds": total_paused},
+        ))
+        # Return total_paused
+        return total_paused
+
+    # Define function pause_timer
+    def pause_timer(self) -> None:
+        """Pause the active phase timer.
+
+        Returns:
+            None
+        """
+        # Check: self.state not in _PAUSABLE_STATES
+        if self.state not in _PAUSABLE_STATES:
+            # Raise BusinessRuleViolation
+            raise BusinessRuleViolation(
+                f"Cannot pause timer in '{self.state.value}' state"
+            )
+        # Check: self.paused_at is not None
+        if self.paused_at is not None:
+            # Raise BusinessRuleViolation
+            raise BusinessRuleViolation("Timer is already paused")
+        # Assign self.paused_at = datetime.utcnow()
+        self.paused_at = datetime.utcnow()
+        # Call self._events.append()
+        self._events.append(DomainEvent("timer_paused"))
+
+    # Define function resume_timer
+    def resume_timer(self) -> int:
+        """Resume a paused timer.
+
+        Returns:
+            int: Number of seconds the timer was paused for.
+        """
+        # Check: self.paused_at is None
+        if self.paused_at is None:
+            # Raise BusinessRuleViolation
+            raise BusinessRuleViolation("Timer is not paused")
+        # Assign now = datetime.utcnow()
+        now = datetime.utcnow()
+        # Assign paused_seconds = max(int((now - self.paused_at).total_seconds()), 0)
+        paused_seconds = max(int((now - self.paused_at).total_seconds()), 0)
+        # Check: self.state == TestState.red_executing
+        if self.state == TestState.red_executing:
+            # Assign self.red_paused_seconds = paused_seconds
+            self.red_paused_seconds += paused_seconds
+        # Alternative: self.state == TestState.blue_evaluating
+        elif self.state == TestState.blue_evaluating:
+            # Assign self.blue_paused_seconds = paused_seconds
+            self.blue_paused_seconds += paused_seconds
+        # Assign self.paused_at = None
+        self.paused_at = None
+        # Call self._events.append()
+        self._events.append(DomainEvent("timer_resumed", {"paused_seconds": paused_seconds}))
+        # Return paused_seconds
+        return paused_seconds
+
+    # Define function validate_red
+    def validate_red(self, status: str, *, by: uuid.UUID, notes: str | None = None) -> None:
+        """Record Red Lead's validation decision.
+
+        Args:
+            status (str): Validation outcome; must be ``"approved"`` or ``"rejected"``.
+            by (uuid.UUID): UUID of the Red Lead recording the decision.
+            notes (str | None): Optional free-text notes about the decision.
+
+        Returns:
+            None
+        """
+        # Call self._assert_in_review()
+        self._assert_in_review("red")
+        # Call self._assert_valid_vote()
+        self._assert_valid_vote(status)
+        # Assign now = datetime.utcnow()
+        now = datetime.utcnow()
+        # Assign self.red_validation_status = status
+        self.red_validation_status = status
+        # Assign self.red_validated_by = by
+        self.red_validated_by = by
+        # Assign self.red_validated_at = now
+        self.red_validated_at = now
+        # Assign self.red_validation_notes = notes
+        self.red_validation_notes = notes
+        # Call self._events.append()
+        self._events.append(DomainEvent("red_validated", {"status": status}))
+        # Call self._check_dual_validation()
+        self._check_dual_validation()
+
+    # Define function validate_blue
+    def validate_blue(self, status: str, *, by: uuid.UUID, notes: str | None = None) -> None:
+        """Record Blue Lead's validation decision.
+
+        Args:
+            status (str): Validation outcome; must be ``"approved"`` or ``"rejected"``.
+            by (uuid.UUID): UUID of the Blue Lead recording the decision.
+            notes (str | None): Optional free-text notes about the decision.
+
+        Returns:
+            None
+        """
+        # Call self._assert_in_review()
+        self._assert_in_review("blue")
+        # Call self._assert_valid_vote()
+        self._assert_valid_vote(status)
+        # Assign now = datetime.utcnow()
+        now = datetime.utcnow()
+        # Assign self.blue_validation_status = status
+        self.blue_validation_status = status
+        # Assign self.blue_validated_by = by
+        self.blue_validated_by = by
+        # Assign self.blue_validated_at = now
+        self.blue_validated_at = now
+        # Assign self.blue_validation_notes = notes
+        self.blue_validation_notes = notes
+        # Call self._events.append()
+        self._events.append(DomainEvent("blue_validated", {"status": status}))
+        # Call self._check_dual_validation()
+        self._check_dual_validation()
+
+    # Define function reopen
+    def reopen(self) -> None:
+        """Transition the test from ``rejected`` back to ``draft``, clearing all validation and timing fields.
+
+        Returns:
+            None
+        """
+        # Call self._transition()
+        self._transition(TestState.draft)
+        # Assign self.red_validation_status = None
+        self.red_validation_status = None
+        # Assign self.red_validated_by = None
+        self.red_validated_by = None
+        # Assign self.red_validated_at = None
+        self.red_validated_at = None
+        # Assign self.red_validation_notes = None
+        self.red_validation_notes = None
+        # Assign self.blue_validation_status = None
+        self.blue_validation_status = None
+        # Assign self.blue_validated_by = None
+        self.blue_validated_by = None
+        # Assign self.blue_validated_at = None
+        self.blue_validated_at = None
+        # Assign self.blue_validation_notes = None
+        self.blue_validation_notes = None
+        # Assign self.red_started_at = None
+        self.red_started_at = None
+        # Assign self.blue_started_at = None
+        self.blue_started_at = None
+        # Assign self.paused_at = None
+        self.paused_at = None
+        # Assign self.red_paused_seconds = 0
+        self.red_paused_seconds = 0
+        # Assign self.blue_paused_seconds = 0
+        self.blue_paused_seconds = 0
+        # Call self._events.append()
+        self._events.append(DomainEvent("test_reopened"))
+
+    # -- Private -------------------------------------------------------
+
+    def _auto_resume(self) -> int:
+        """Accumulate pause time and clear the paused timestamp if currently paused.
+
+        Returns:
+            int: Extra seconds that were accumulated from the current pause, or 0
+                if the timer was not paused.
+        """
+        # Check: self.paused_at is None
+        if self.paused_at is None:
+            # Return 0
+            return 0
+        # Assign now = datetime.utcnow()
+        now = datetime.utcnow()
+        # Assign extra = max(int((now - self.paused_at).total_seconds()), 0)
+        extra = max(int((now - self.paused_at).total_seconds()), 0)
+        # Assign self.paused_at = None
+        self.paused_at = None
+        # Return extra
+        return extra
+
+    # Define function check_dual_validation
+    def check_dual_validation(self) -> None:
+        """Evaluate both leads' votes and advance state if appropriate.
+
+        - Both **approved** -> ``validated``
+        - Either **rejected** -> ``rejected``
+        - Otherwise no change (waiting for the other lead).
+
+        Called automatically by :meth:`validate_red` and :meth:`validate_blue`.
+        Also available as a standalone entry point for backward compatibility
+        when validation fields are set externally.
+
+        Returns:
+            None
+        """
+        # Call self._check_dual_validation()
+        self._check_dual_validation()
+
+    # Define function _assert_in_review
+    def _assert_in_review(self, side: str) -> None:
+        """Raise InvalidOperationError unless the test is in ``in_review`` state.
+
+        Args:
+            side (str): The team side being validated (``"red"`` or ``"blue"``),
+                used in the error message.
+
+        Returns:
+            None
+        """
+        # Check: self.state != TestState.in_review
+        if self.state != TestState.in_review:
+            # Raise InvalidOperationError
+            raise InvalidOperationError(
+                f"Cannot validate {side} side while test is in "
+                f"'{self.state.value}' state (must be in_review)"
+            )
+
+    # Apply the @staticmethod decorator
+    @staticmethod
+    # Define function _assert_valid_vote
+    def _assert_valid_vote(status: str) -> None:
+        """Raise InvalidOperationError if *status* is not a valid vote value.
+
+        Args:
+            status (str): The vote value to validate; must be ``"approved"`` or ``"rejected"``.
+
+        Returns:
+            None
+        """
+        # Check: status not in ("approved", "rejected")
+        if status not in ("approved", "rejected"):
+            # Raise InvalidOperationError
+            raise InvalidOperationError(
+                # Literal argument value
+                "validation_status must be 'approved' or 'rejected'"
+            )
+
+    # Define function _check_dual_validation
+    def _check_dual_validation(self) -> None:
+        """Advance to ``validated`` or ``rejected`` once both leads have voted.
+
+        Returns:
+            None
+        """
+        # r, b = self.red_validation_status, self.blue_validation_status
+        r, b = self.red_validation_status, self.blue_validation_status
+        # Check: r == "rejected" or b == "rejected"
+        if r == "rejected" or b == "rejected":
+            # Assign self.state = TestState.rejected
+            self.state = TestState.rejected
+            # Call self._events.append()
+            self._events.append(DomainEvent("dual_validation_rejected"))
+        # Alternative: r == "approved" and b == "approved"
+        elif r == "approved" and b == "approved":
+            # Assign self.state = TestState.validated
+            self.state = TestState.validated
+            # Call self._events.append()
+            self._events.append(DomainEvent("dual_validation_approved"))

backend/app/domain/unit_of_work.py

@@ -0,0 +1,103 @@
+"""Unit of Work — wraps a SQLAlchemy session for explicit transaction control.
+
+Usage in routers::
+
+    with UnitOfWork(db) as uow:
+        service_a(db, ...)
+        service_b(db, ...)
+        uow.commit()          # single commit for the entire operation
+
+If an exception propagates, ``__exit__`` issues a rollback automatically.
+Services should **never** call ``db.commit()``; they use ``db.add()`` /
+``db.flush()`` to stage work and let the caller decide when to commit.
+
+**Documented exceptions** (services that may commit internally):
+- Import services (atomic_import, sigma_import, etc.) — self-contained sync ops.
+- Background jobs (campaign_scheduler, intel_service, stale_detection,
+  mitre_sync) — self-contained operations.
+- Self-contained batch ops (e.g. detection_rule_service.auto_associate_rules,
+  snapshot_service.create_snapshot, campaign_service.generate_campaign_from_*,
+  osint_enrichment_service.enrich_technique_with_cves).
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import TracebackType from types
+from types import TracebackType
+
+# Import Session from sqlalchemy.orm
+from sqlalchemy.orm import Session
+
+
+# Define class UnitOfWork
+class UnitOfWork:
+    """Lightweight transaction wrapper around an existing SQLAlchemy session."""
+
+    # Define function __init__
+    def __init__(self, session: Session) -> None:
+        """Wrap an existing SQLAlchemy session in a Unit of Work.
+
+        Args:
+            session (Session): The active SQLAlchemy session to manage.
+
+        Returns:
+            None
+        """
+        # Assign self._session = session
+        self._session = session
+
+    # -- context manager -----------------------------------------------------
+
+    def __enter__(self) -> "UnitOfWork":
+        """Enter the runtime context, returning this UnitOfWork instance.
+
+        Returns:
+            UnitOfWork: The UnitOfWork itself, for use in ``with`` statements.
+        """
+        # Return self
+        return self
+
+    # Define function __exit__
+    def __exit__(
+        self,
+        # Entry: exc_type
+        exc_type: type[BaseException] | None,
+        # Entry: exc_val
+        exc_val: BaseException | None,
+        # Entry: exc_tb
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the runtime context, rolling back if an exception propagated.
+
+        Args:
+            exc_type (type[BaseException] | None): Exception class, if raised.
+            exc_val (BaseException | None): Exception instance, if raised.
+            exc_tb (TracebackType | None): Traceback object, if an exception was raised.
+
+        Returns:
+            None
+        """
+        # Check: exc_type is not None
+        if exc_type is not None:
+            # Call self.rollback()
+            self.rollback()
+
+    # -- public API ----------------------------------------------------------
+
+    def commit(self) -> None:
+        """Flush pending changes and commit the transaction."""
+        # Call self._session.commit()
+        self._session.commit()
+
+    # Define function rollback
+    def rollback(self) -> None:
+        """Roll back the current transaction."""
+        # Call self._session.rollback()
+        self._session.rollback()
+
+    # Define function flush
+    def flush(self) -> None:
+        """Flush pending changes without committing (useful for getting IDs)."""
+        # Call self._session.flush()
+        self._session.flush()

backend/app/domain/value_objects/__init__.py

@@ -0,0 +1,9 @@
+"""Immutable domain value objects."""
+# Import MitreId from app.domain.value_objects.mitre_id
+from app.domain.value_objects.mitre_id import MitreId
+
+# Import ScoringWeights from app.domain.value_objects.scoring_weights
+from app.domain.value_objects.scoring_weights import ScoringWeights
+
+# Assign __all__ = ["MitreId", "ScoringWeights"]
+__all__ = ["MitreId", "ScoringWeights"]

backend/app/domain/value_objects/mitre_id.py

@@ -0,0 +1,115 @@
+"""MitreId — validated MITRE ATT&CK technique identifier.
+
+Immutable value object that ensures the identifier follows the ATT&CK
+format: ``T`` followed by 4 digits, optionally a dot and 3 more digits
+for sub-techniques (e.g. ``T1059``, ``T1059.001``).
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import re
+import re
+
+# Import dataclass from dataclasses
+from dataclasses import dataclass
+
+# Assign _MITRE_ID_RE = re.compile(r"^T\d{4}(\.\d{3})?$")
+_MITRE_ID_RE = re.compile(r"^T\d{4}(\.\d{3})?$")
+
+
+# Apply the @dataclass decorator
+@dataclass(frozen=True, slots=True)
+# Define class MitreId
+class MitreId:
+    """Validated MITRE ATT&CK technique identifier."""
+
+    # value: str
+    value: str
+
+    # Define function __post_init__
+    def __post_init__(self) -> None:
+        """Validate that *value* matches the expected MITRE ATT&CK ID format.
+
+        Returns:
+            None
+        """
+        # Check: not _MITRE_ID_RE.match(self.value)
+        if not _MITRE_ID_RE.match(self.value):
+            # Raise ValueError
+            raise ValueError(
+                f"Invalid MITRE ATT&CK ID '{self.value}'. "
+                # Literal argument value
+                "Expected format: T1234 or T1234.001"
+            )
+
+    # Apply the @property decorator
+    @property
+    # Define function is_subtechnique
+    def is_subtechnique(self) -> bool:
+        """Return True if this identifier represents a sub-technique.
+
+        Returns:
+            bool: True when the ID contains a dot (e.g. ``T1059.001``).
+        """
+        # Return "." in self.value
+        return "." in self.value
+
+    # Apply the @property decorator
+    @property
+    # Define function parent_id
+    def parent_id(self) -> str | None:
+        """Return the parent technique ID (e.g. ``T1059`` for ``T1059.001``).
+
+        Returns:
+            str | None: The parent ID string, or None if this is not a sub-technique.
+        """
+        # Check: not self.is_subtechnique
+        if not self.is_subtechnique:
+            # Return None
+            return None
+        # Return self.value.split(".")[0]
+        return self.value.split(".")[0]
+
+    # Define function __str__
+    def __str__(self) -> str:
+        """Return the string representation of the MITRE ID.
+
+        Returns:
+            str: The raw identifier string (e.g. ``"T1059.001"``).
+        """
+        # Return self.value
+        return self.value
+
+    # Define function __eq__
+    def __eq__(self, other: object) -> bool:
+        """Compare this MitreId to another MitreId or a plain string.
+
+        Args:
+            other (object): The value to compare against; may be a
+                :class:`MitreId` instance or a plain ``str``.
+
+        Returns:
+            bool: True if the identifiers are equal, NotImplemented for
+                unsupported types.
+        """
+        # Check: isinstance(other, MitreId)
+        if isinstance(other, MitreId):
+            # Return self.value == other.value
+            return self.value == other.value
+        # Check: isinstance(other, str)
+        if isinstance(other, str):
+            # Return self.value == other
+            return self.value == other
+        # Return NotImplemented
+        return NotImplemented
+
+    # Define function __hash__
+    def __hash__(self) -> int:
+        """Return the hash of the identifier string.
+
+        Returns:
+            int: Hash value derived from the raw identifier string.
+        """
+        # Return hash(self.value)
+        return hash(self.value)

backend/app/domain/value_objects/scoring_weights.py

@@ -0,0 +1,107 @@
+"""ScoringWeights — validated immutable weight set for the scoring engine.
+
+Enforces that all five weights are non-negative and sum to exactly 100.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import dataclass from dataclasses
+from dataclasses import dataclass
+
+
+# Apply the @dataclass decorator
+@dataclass(frozen=True, slots=True)
+# Define class ScoringWeights
+class ScoringWeights:
+    """Five scoring dimension weights that must sum to 100."""
+
+    # tests: float
+    tests: float
+    # detection_rules: float
+    detection_rules: float
+    # d3fend: float
+    d3fend: float
+    # recency: float
+    recency: float
+    # severity: float
+    severity: float
+
+    # Define function __post_init__
+    def __post_init__(self) -> None:
+        """Validate that all weights are non-negative and sum to exactly 100.
+
+        Returns:
+            None
+        """
+        # Assign fields = [
+        fields = [
+            self.tests,
+            self.detection_rules,
+            self.d3fend,
+            self.recency,
+            self.severity,
+        ]
+        # Iterate over fields
+        for f in fields:
+            # Check: f < 0
+            if f < 0:
+                # Raise ValueError
+                raise ValueError("Scoring weights must be non-negative")
+
+        # Assign total = sum(fields)
+        total = sum(fields)
+        # Check: abs(total - 100) > 0.01
+        if abs(total - 100) > 0.01:
+            # Raise ValueError
+            raise ValueError(
+                f"Scoring weights must sum to 100, got {total}"
+            )
+
+    # Apply the @classmethod decorator
+    @classmethod
+    # Define function default
+    def default(cls) -> ScoringWeights:
+        """Return the default weight distribution.
+
+        Returns:
+            ScoringWeights: A weight set with tests=40, detection_rules=25,
+                d3fend=15, recency=10, severity=10.
+        """
+        # Return cls(
+        return cls(
+            # Keyword argument: tests
+            tests=40.0,
+            # Keyword argument: detection_rules
+            detection_rules=25.0,
+            # Keyword argument: d3fend
+            d3fend=15.0,
+            # Keyword argument: recency
+            recency=10.0,
+            # Keyword argument: severity
+            severity=10.0,
+        )
+
+    # Backward-compatible aliases for older API payloads
+    @property
+    # Define function freshness
+    def freshness(self) -> float:
+        """Return the recency weight (backward-compatible alias).
+
+        Returns:
+            float: The value of the ``recency`` weight.
+        """
+        # Return self.recency
+        return self.recency
+
+    # Apply the @property decorator
+    @property
+    # Define function platform_diversity
+    def platform_diversity(self) -> float:
+        """Return the severity weight (backward-compatible alias).
+
+        Returns:
+            float: The value of the ``severity`` weight.
+        """
+        # Return self.severity
+        return self.severity

backend/app/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure adapters — persistence, caching, and external services."""

backend/app/infrastructure/persistence/__init__.py

@@ -0,0 +1 @@
+"""SQLAlchemy-based persistence adapters for the domain repository ports."""

backend/app/infrastructure/persistence/mappers/__init__.py

@@ -0,0 +1 @@
+"""ORM-to-domain entity mapper functions."""

backend/app/infrastructure/persistence/mappers/technique_mapper.py

@@ -0,0 +1,28 @@
+"""Technique ORM model <-> domain entity mapper."""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import TechniqueEntity from app.domain.entities.technique
+from app.domain.entities.technique import TechniqueEntity
+
+
+# Define class TechniqueMapper
+class TechniqueMapper:
+    """Converts between SQLAlchemy Technique model and TechniqueEntity."""
+
+    # Apply the @staticmethod decorator
+    @staticmethod
+    # Define function to_entity
+    def to_entity(model: object) -> TechniqueEntity:
+        """Convert an ORM Technique model to a domain TechniqueEntity."""
+        # Return TechniqueEntity.from_orm(model)
+        return TechniqueEntity.from_orm(model)
+
+    # Apply the @staticmethod decorator
+    @staticmethod
+    # Define function to_model_updates
+    def to_model_updates(entity: TechniqueEntity, model: object) -> None:
+        """Apply entity changes back onto an existing ORM model."""
+        # Call entity.apply_to()
+        entity.apply_to(model)

backend/app/infrastructure/persistence/repositories/__init__.py

@@ -0,0 +1,13 @@
+"""Concrete SQLAlchemy repository implementations."""
+# Import  from app.infrastructure.persistence.repositories.sa_technique_repository
+from app.infrastructure.persistence.repositories.sa_technique_repository import (
+    SATechniqueRepository,
+)
+
+# Import  from app.infrastructure.persistence.repositories.sa_test_repository
+from app.infrastructure.persistence.repositories.sa_test_repository import (
+    SATestRepository,
+)
+
+# Assign __all__ = ["SATechniqueRepository", "SATestRepository"]
+__all__ = ["SATechniqueRepository", "SATestRepository"]

backend/app/infrastructure/persistence/repositories/sa_technique_repository.py

@@ -0,0 +1,380 @@
+"""SQLAlchemy implementation of TechniqueRepository.
+
+Receives a Session from the caller — does NOT create its own.
+Does NOT call commit() — the Unit of Work owns that.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import uuid
+import uuid
+
+# Import func from sqlalchemy
+from sqlalchemy import func
+
+# Import Session from sqlalchemy.orm
+from sqlalchemy.orm import Session
+
+# Import TechniqueEntity from app.domain.entities.technique
+from app.domain.entities.technique import TechniqueEntity
+
+# Import TechniqueStatus, TestState from app.domain.enums
+from app.domain.enums import TechniqueStatus, TestState
+
+# Import TechniqueWithCounts from app.domain.ports.repositories.technique_repository
+from app.domain.ports.repositories.technique_repository import TechniqueWithCounts
+
+# Import TechniqueMapper from app.infrastructure.persistence.mappers.technique_mapper
+from app.infrastructure.persistence.mappers.technique_mapper import TechniqueMapper
+
+# Import DetectionRule from app.models.detection_rule
+from app.models.detection_rule import DetectionRule
+
+# Import Technique from app.models.technique
+from app.models.technique import Technique
+
+# Import Test from app.models.test
+from app.models.test import Test
+
+
+# Define class SATechniqueRepository
+class SATechniqueRepository:
+    """Concrete repository backed by SQLAlchemy."""
+
+    # Define function __init__
+    def __init__(self, session: Session) -> None:
+        """Initialise the repository with a caller-provided session.
+
+        Args:
+            session (Session): The SQLAlchemy session to use for all queries.
+        """
+        # Assign self._session = session
+        self._session = session
+
+    # -- Single-entity access ----------------------------------------------
+
+    def find_by_id(self, technique_id: uuid.UUID) -> TechniqueEntity | None:
+        """Return a single technique by its primary key.
+
+        Args:
+            technique_id (uuid.UUID): The UUID primary key of the technique.
+
+        Returns:
+            TechniqueEntity | None: The matching entity, or ``None`` if not found.
+        """
+        # Assign model = (
+        model = (
+            self._session.query(Technique)
+            # Chain .filter() call
+            .filter(Technique.id == technique_id)
+            # Chain .first() call
+            .first()
+        )
+        # Return TechniqueMapper.to_entity(model) if model else None
+        return TechniqueMapper.to_entity(model) if model else None
+
+    # Define function find_by_mitre_id
+    def find_by_mitre_id(self, mitre_id: str) -> TechniqueEntity | None:
+        """Return a single technique by its MITRE ATT&CK ID (e.g. ``T1059.001``).
+
+        Args:
+            mitre_id (str): The MITRE ATT&CK identifier string.
+
+        Returns:
+            TechniqueEntity | None: The matching entity, or ``None`` if not found.
+        """
+        # Assign model = (
+        model = (
+            self._session.query(Technique)
+            # Chain .filter() call
+            .filter(Technique.mitre_id == mitre_id)
+            # Chain .first() call
+            .first()
+        )
+        # Return TechniqueMapper.to_entity(model) if model else None
+        return TechniqueMapper.to_entity(model) if model else None
+
+    # -- List access -------------------------------------------------------
+
+    def list_all(
+        self,
+        *,
+        # Entry: tactic
+        tactic: str | None = None,
+        # Entry: status
+        status: TechniqueStatus | None = None,
+        # Entry: review_required
+        review_required: bool | None = None,
+    ) -> list[TechniqueEntity]:
+        """Return all techniques, optionally filtered by tactic, status, or review flag.
+
+        Args:
+            tactic (str | None): Filter to techniques belonging to this tactic name.
+            status (TechniqueStatus | None): Filter to techniques with this coverage status.
+            review_required (bool | None): Filter to techniques where ``review_required`` matches.
+
+        Returns:
+            list[TechniqueEntity]: Ordered list of matching technique entities.
+        """
+        # Assign query = self._session.query(Technique)
+        query = self._session.query(Technique)
+        # Check: tactic is not None
+        if tactic is not None:
+            # Assign query = query.filter(Technique.tactic == tactic)
+            query = query.filter(Technique.tactic == tactic)
+        # Check: status is not None
+        if status is not None:
+            # Assign query = query.filter(Technique.status_global == status)
+            query = query.filter(Technique.status_global == status)
+        # Check: review_required is not None
+        if review_required is not None:
+            # Assign query = query.filter(Technique.review_required == review_required)
+            query = query.filter(Technique.review_required == review_required)
+        # Assign models = query.order_by(Technique.mitre_id).all()
+        models = query.order_by(Technique.mitre_id).all()
+        # Return [TechniqueMapper.to_entity(m) for m in models]
+        return [TechniqueMapper.to_entity(m) for m in models]
+
+    # Define function list_by_ids
+    def list_by_ids(self, ids: list[uuid.UUID]) -> list[TechniqueEntity]:
+        """Return techniques matching the provided list of UUIDs.
+
+        Args:
+            ids (list[uuid.UUID]): UUIDs of the techniques to retrieve.
+
+        Returns:
+            list[TechniqueEntity]: Technique entities corresponding to the given IDs.
+        """
+        # Check: not ids
+        if not ids:
+            # Return []
+            return []
+        # Assign models = (
+        models = (
+            self._session.query(Technique)
+            # Chain .filter() call
+            .filter(Technique.id.in_(ids))
+            # Chain .all() call
+            .all()
+        )
+        # Return [TechniqueMapper.to_entity(m) for m in models]
+        return [TechniqueMapper.to_entity(m) for m in models]
+
+    # -- Batch queries (for scoring/heatmap) -------------------------------
+
+    def count_by_status(self) -> dict[TechniqueStatus, int]:
+        """Return a count of techniques grouped by their coverage status.
+
+        Returns:
+            dict[TechniqueStatus, int]: Mapping of each status value to its technique count.
+        """
+        # Assign rows = (
+        rows = (
+            self._session.query(
+                Technique.status_global,
+                func.count(Technique.id),
+            )
+            # Chain .group_by() call
+            .group_by(Technique.status_global)
+            # Chain .all() call
+            .all()
+        )
+        # Assign result = {s: 0 for s in TechniqueStatus}
+        result = {s: 0 for s in TechniqueStatus}
+        # Iterate over rows
+        for status_val, count in rows:
+            # Assign key = (
+            key = (
+                status_val
+                if isinstance(status_val, TechniqueStatus)
+                else TechniqueStatus(status_val)
+            )
+            # Assign result[key] = count
+            result[key] = count
+        # Return result
+        return result
+
+    # Define function find_all_with_test_counts
+    def find_all_with_test_counts(self) -> list[TechniqueWithCounts]:
+        """Return all techniques with pre-aggregated test and detection rule counts.
+
+        Uses a single query with subqueries to avoid the N+1 pattern.
+
+        Returns:
+            list[TechniqueWithCounts]: All techniques with their associated counts.
+        """
+        # Assign test_count_sq = (
+        test_count_sq = (
+            self._session.query(
+                Test.technique_id,
+                func.count(Test.id).label("test_count"),
+                func.sum(
+                    func.cast(Test.state == TestState.validated, self._int_type())
+                ).label("validated_count"),
+            )
+            # Chain .group_by() call
+            .group_by(Test.technique_id)
+            # Chain .subquery() call
+            .subquery()
+        )
+        # Assign rule_count_sq = (
+        rule_count_sq = (
+            self._session.query(
+                DetectionRule.mitre_technique_id,
+                func.count(DetectionRule.id).label("rule_count"),
+            )
+            # Chain .group_by() call
+            .group_by(DetectionRule.mitre_technique_id)
+            # Chain .subquery() call
+            .subquery()
+        )
+
+        # Assign rows = (
+        rows = (
+            self._session.query(
+                Technique,
+                func.coalesce(test_count_sq.c.test_count, 0),
+                func.coalesce(test_count_sq.c.validated_count, 0),
+                func.coalesce(rule_count_sq.c.rule_count, 0),
+            )
+            # Chain .outerjoin() call
+            .outerjoin(test_count_sq, Technique.id == test_count_sq.c.technique_id)
+            # Chain .outerjoin() call
+            .outerjoin(
+                rule_count_sq,
+                Technique.mitre_id == rule_count_sq.c.mitre_technique_id,
+            )
+            # Chain .order_by() call
+            .order_by(Technique.mitre_id)
+            # Chain .all() call
+            .all()
+        )
+
+        # Return [
+        return [
+            TechniqueWithCounts(
+                # Keyword argument: entity
+                entity=TechniqueMapper.to_entity(tech),
+                # Keyword argument: test_count
+                test_count=int(tc),
+                # Keyword argument: validated_test_count
+                validated_test_count=int(vtc),
+                # Keyword argument: detection_rule_count
+                detection_rule_count=int(rc),
+            )
+            for tech, tc, vtc, rc in rows
+        ]
+
+    # -- Mutations ---------------------------------------------------------
+
+    def save(self, technique: TechniqueEntity) -> TechniqueEntity:
+        """Persist a technique entity, inserting or updating as needed.
+
+        Args:
+            technique (TechniqueEntity): The domain entity to persist.
+
+        Returns:
+            TechniqueEntity: The persisted entity reflecting the current DB state.
+        """
+        # Assign existing = (
+        existing = (
+            self._session.query(Technique)
+            # Chain .filter() call
+            .filter(Technique.id == technique.id)
+            # Chain .first() call
+            .first()
+        )
+        # Check: existing
+        if existing:
+            # Call technique.apply_to()
+            technique.apply_to(existing)
+            # Assign existing.mitre_id = technique.mitre_id
+            existing.mitre_id = technique.mitre_id
+            # Assign existing.name = technique.name
+            existing.name = technique.name
+            # Assign existing.tactic = technique.tactic
+            existing.tactic = technique.tactic
+            # Assign existing.description = technique.description
+            existing.description = technique.description
+            # Assign existing.platforms = technique.platforms
+            existing.platforms = technique.platforms
+            # Assign existing.is_subtechnique = technique.is_subtechnique
+            existing.is_subtechnique = technique.is_subtechnique
+            # Assign existing.parent_mitre_id = technique.parent_mitre_id
+            existing.parent_mitre_id = technique.parent_mitre_id
+            # Assign existing.mitre_version = technique.mitre_version
+            existing.mitre_version = technique.mitre_version
+            # Assign existing.mitre_last_modified = technique.mitre_last_modified
+            existing.mitre_last_modified = technique.mitre_last_modified
+            # Call self._session.flush()
+            self._session.flush()
+            # Return TechniqueMapper.to_entity(existing)
+            return TechniqueMapper.to_entity(existing)
+        # Fallback: handle remaining cases
+        else:
+            # Assign model = Technique(
+            model = Technique(
+                # Keyword argument: id
+                id=technique.id,
+                # Keyword argument: mitre_id
+                mitre_id=technique.mitre_id,
+                # Keyword argument: name
+                name=technique.name,
+                # Keyword argument: tactic
+                tactic=technique.tactic,
+                # Keyword argument: description
+                description=technique.description,
+                # Keyword argument: platforms
+                platforms=technique.platforms,
+                # Keyword argument: is_subtechnique
+                is_subtechnique=technique.is_subtechnique,
+                # Keyword argument: parent_mitre_id
+                parent_mitre_id=technique.parent_mitre_id,
+                # Keyword argument: status_global
+                status_global=technique.status_global,
+                # Keyword argument: review_required
+                review_required=technique.review_required,
+                # Keyword argument: last_review_date
+                last_review_date=technique.last_review_date,
+                # Keyword argument: mitre_version
+                mitre_version=technique.mitre_version,
+                # Keyword argument: mitre_last_modified
+                mitre_last_modified=technique.mitre_last_modified,
+            )
+            # Call self._session.add()
+            self._session.add(model)
+            # Call self._session.flush()
+            self._session.flush()
+            # Return TechniqueMapper.to_entity(model)
+            return TechniqueMapper.to_entity(model)
+
+    # Define function exists_by_mitre_id
+    def exists_by_mitre_id(self, mitre_id: str) -> bool:
+        """Check whether a technique with the given MITRE ID already exists.
+
+        Args:
+            mitre_id (str): The MITRE ATT&CK identifier to look up.
+
+        Returns:
+            bool: ``True`` if the technique exists, ``False`` otherwise.
+        """
+        # Return (
+        return (
+            self._session.query(Technique.id)
+            # Chain .filter() call
+            .filter(Technique.mitre_id == mitre_id)
+            # Chain .first() call
+            .first()
+        ) is not None
+
+    # -- Internal ----------------------------------------------------------
+
+    @staticmethod
+    # Define function _int_type
+    def _int_type() -> type:
+        """Return an Integer type for CAST expressions (SQLite-compatible)."""
+        # Import Integer from sqlalchemy
+        from sqlalchemy import Integer
+        # Return Integer
+        return Integer

backend/app/infrastructure/persistence/repositories/sa_test_repository.py

@@ -0,0 +1,171 @@
+"""SQLAlchemy implementation of TestRepository."""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import uuid
+import uuid
+
+# Import func from sqlalchemy
+from sqlalchemy import func
+
+# Import Session from sqlalchemy.orm
+from sqlalchemy.orm import Session
+
+# Import TestState from app.domain.enums
+from app.domain.enums import TestState
+
+# Import Test from app.models.test
+from app.models.test import Test
+
+
+# Define class SATestRepository
+class SATestRepository:
+    """Concrete test repository backed by SQLAlchemy."""
+
+    # Define function __init__
+    def __init__(self, session: Session) -> None:
+        """Initialise the repository with a caller-provided session.
+
+        Args:
+            session (Session): The SQLAlchemy session to use for all queries.
+        """
+        # Assign self._session = session
+        self._session = session
+
+    # Define function find_by_id
+    def find_by_id(self, test_id: uuid.UUID) -> Test | None:
+        """Return a single test by its primary key.
+
+        Args:
+            test_id (uuid.UUID): The UUID primary key of the test.
+
+        Returns:
+            Test | None: The ORM model instance, or ``None`` if not found.
+        """
+        # Return (
+        return (
+            self._session.query(Test)
+            # Chain .filter() call
+            .filter(Test.id == test_id)
+            # Chain .first() call
+            .first()
+        )
+
+    # Define function list_by_technique
+    def list_by_technique(self, technique_id: uuid.UUID) -> list[Test]:
+        """Return all tests for a given technique, ordered by creation date.
+
+        Args:
+            technique_id (uuid.UUID): The UUID of the parent technique.
+
+        Returns:
+            list[Test]: ORM model instances ordered by ``created_at`` ascending.
+        """
+        # Return (
+        return (
+            self._session.query(Test)
+            # Chain .filter() call
+            .filter(Test.technique_id == technique_id)
+            # Chain .order_by() call
+            .order_by(Test.created_at)
+            # Chain .all() call
+            .all()
+        )
+
+    # Define function list_by_state
+    def list_by_state(self, state: TestState) -> list[Test]:
+        """Return all tests that are currently in the given workflow state.
+
+        Args:
+            state (TestState): The workflow state to filter on.
+
+        Returns:
+            list[Test]: All ORM model instances with the specified state.
+        """
+        # Return (
+        return (
+            self._session.query(Test)
+            # Chain .filter() call
+            .filter(Test.state == state)
+            # Chain .all() call
+            .all()
+        )
+
+    # Define function count_by_technique_and_state
+    def count_by_technique_and_state(
+        self,
+        # Entry: technique_id
+        technique_id: uuid.UUID,
+    ) -> dict[TestState, int]:
+        """Return per-state test counts for a specific technique.
+
+        Args:
+            technique_id (uuid.UUID): The UUID of the technique to aggregate for.
+
+        Returns:
+            dict[TestState, int]: Mapping of each state to the number of tests in that state.
+        """
+        # Assign rows = (
+        rows = (
+            self._session.query(Test.state, func.count(Test.id))
+            # Chain .filter() call
+            .filter(Test.technique_id == technique_id)
+            # Chain .group_by() call
+            .group_by(Test.state)
+            # Chain .all() call
+            .all()
+        )
+        # Assign result = {}
+        result: dict[TestState, int] = {}
+        # Iterate over rows
+        for state_val, count in rows:
+            # Assign key = (
+            key = (
+                state_val
+                if isinstance(state_val, TestState)
+                else TestState(state_val)
+            )
+            # Assign result[key] = count
+            result[key] = count
+        # Return result
+        return result
+
+    # Define function get_states_and_results_for_technique
+    def get_states_and_results_for_technique(
+        self,
+        # Entry: technique_id
+        technique_id: uuid.UUID,
+    ) -> list[tuple[str, str | None]]:
+        """Return lightweight ``(state, detection_result)`` pairs for a technique.
+
+        Used by ``TechniqueEntity.recalculate_status()`` to avoid loading full
+        ``Test`` models.
+
+        Args:
+            technique_id (uuid.UUID): The UUID of the technique to query.
+
+        Returns:
+            list[tuple[str, str | None]]: Each tuple contains the state string
+                and the detection result string (or ``None``).
+        """
+        # Assign rows = (
+        rows = (
+            self._session.query(Test.state, Test.detection_result)
+            # Chain .filter() call
+            .filter(Test.technique_id == technique_id)
+            # Chain .all() call
+            .all()
+        )
+        # Return [
+        return [
+            (
+                r.state.value if hasattr(r.state, "value") else str(r.state),
+                (
+                    r.detection_result.value
+                    if hasattr(r.detection_result, "value")
+                    else r.detection_result
+                ),
+            )
+            for r in rows
+        ]

backend/app/infrastructure/redis_client.py

@@ -0,0 +1,91 @@
+"""Redis client factories.
+
+``settings.REDIS_URL`` selects the default logical database (usually ``0``).
+Token blacklist and application cache use separate logical DBs on the same
+Redis instance (``REDIS_TOKEN_BLACKLIST_DB``, ``REDIS_CACHE_DB``) so keys never
+collide and TTL policies can differ per workload.
+
+Usage::
+
+    from app.infrastructure.redis_client import get_redis, get_redis_blacklist
+
+    get_redis().set("key", "value", ex=300)
+    get_redis_blacklist().setex("blacklist:…", ttl, "1")
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import logging
+import logging
+
+# Import urlparse, urlunparse from urllib.parse
+from urllib.parse import urlparse, urlunparse
+
+# Import redis
+import redis
+
+# Import settings from app.config
+from app.config import settings
+
+# Assign logger = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
+
+# Assign _clients = {}
+_clients: dict[str, redis.Redis] = {}
+
+
+# Define function _redis_url_with_db
+def _redis_url_with_db(base_url: str, db_index: int) -> str:
+    """Return *base_url* with its path replaced by ``/{db_index}``."""
+    # Assign parsed = urlparse(base_url)
+    parsed = urlparse(base_url)
+    # Assign path = f"/{db_index}"
+    path = f"/{db_index}"
+    # Return urlunparse(
+    return urlunparse(
+        (parsed.scheme, parsed.netloc, path, "", "", ""),
+    )
+
+
+# Define function _get_client
+def _get_client(url: str) -> redis.Redis:
+    # Check: url not in _clients
+    if url not in _clients:
+        # Assign _clients[url] = redis.from_url(url, decode_responses=True)
+        _clients[url] = redis.from_url(url, decode_responses=True)
+        # Log info: "Redis client connected to %s", url
+        logger.info("Redis client connected to %s", url)
+    # Return _clients[url]
+    return _clients[url]
+
+
+# Define function get_redis
+def get_redis() -> redis.Redis:
+    """Default Redis connection (URL from ``settings.REDIS_URL``)."""
+    # Return _get_client(settings.REDIS_URL)
+    return _get_client(settings.REDIS_URL)
+
+
+# Define function get_redis_blacklist
+def get_redis_blacklist() -> redis.Redis:
+    """Redis DB used for JWT revocation (``jti`` keys with TTL)."""
+    # Assign url = _redis_url_with_db(
+    url = _redis_url_with_db(
+        settings.REDIS_URL,
+        settings.REDIS_TOKEN_BLACKLIST_DB,
+    )
+    # Return _get_client(url)
+    return _get_client(url)
+
+
+# Define function get_redis_cache
+def get_redis_cache() -> redis.Redis:
+    """Redis DB reserved for shared cache (scores, queues, etc.)."""
+    # Assign url = _redis_url_with_db(
+    url = _redis_url_with_db(
+        settings.REDIS_URL,
+        settings.REDIS_CACHE_DB,
+    )
+    # Return _get_client(url)
+    return _get_client(url)

backend/app/jobs/__init__.py

@@ -0,0 +1 @@
+"""Background scheduler jobs (MITRE sync, Jira sync, data retention)."""

backend/app/jobs/jira_sync_job.py

@@ -0,0 +1,65 @@
+"""Scheduled job — syncs all Jira links hourly."""
+
+# Import logging
+import logging
+
+# Import settings from app.config
+from app.config import settings
+
+# Import SessionLocal from app.database
+from app.database import SessionLocal
+
+# Import JiraLink from app.models.jira_link
+from app.models.jira_link import JiraLink
+
+# Import jira_service from app.services
+from app.services import jira_service
+
+# Assign logger = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
+
+
+# Define function sync_all_jira_links
+def sync_all_jira_links() -> None:
+    """Pull latest status from Jira for every stored link.
+
+    Silently skips if ``JIRA_ENABLED`` is ``False``.  Individual link
+    failures are logged but do not abort the rest of the batch.
+    """
+    # Check: not settings.JIRA_ENABLED
+    if not settings.JIRA_ENABLED:
+        # Return control to caller
+        return
+
+    # Assign db = SessionLocal()
+    db = SessionLocal()
+    # Attempt the following; catch errors below
+    try:
+        # Assign links = db.query(JiraLink).all()
+        links = db.query(JiraLink).all()
+        # Assign synced = 0
+        synced = 0
+        # Iterate over links
+        for link in links:
+            # Attempt the following; catch errors below
+            try:
+                # Call jira_service.sync_jira_to_aegis()
+                jira_service.sync_jira_to_aegis(db, link)
+                # Assign synced = 1
+                synced += 1
+            # Handle Exception
+            except Exception as e:
+                # Log warning: "Jira sync failed for link %s: %s", link.id, e
+                logger.warning("Jira sync failed for link %s: %s", link.id, e)
+        # Commit all pending changes to the database
+        db.commit()
+        # Log info: "Jira sync completed: %d/%d links updated", synced
+        logger.info("Jira sync completed: %d/%d links updated", synced, len(links))
+    # Handle Exception
+    except Exception:
+        # Log exception: "Jira sync batch job failed"
+        logger.exception("Jira sync batch job failed")
+    # Always execute this cleanup block
+    finally:
+        # Close the database session
+        db.close()

backend/app/jobs/mitre_sync_job.py

@@ -1,18 +1,52 @@
-"""Scheduled job for periodic MITRE ATT&CK synchronisation.
+"""Scheduled background jobs.
 
-Uses APScheduler's ``BackgroundScheduler`` to run :func:`sync_mitre` every
-24 hours.  The job manages its own database session (created on entry,
-closed in ``finally``) so it is fully independent from FastAPI's
-request-scoped sessions.
+Registers periodic tasks on an APScheduler ``BackgroundScheduler``:
+
+* **MITRE sync** — every 24 hours (see :func:`sync_mitre`)
+* **Intel scan** — every 7 days (see :func:`scan_intel`)
+
+Each job manages its own database session (created on entry, closed in
+``finally``) so it is fully independent from FastAPI's request-scoped
+sessions.
 """
 
+# Import logging
 import logging
 
+# Import BackgroundScheduler from apscheduler.schedulers.background
 from apscheduler.schedulers.background import BackgroundScheduler
 
+# Import SessionLocal from app.database
 from app.database import SessionLocal
+
+# Import sync_all_jira_links from app.jobs.jira_sync_job
+from app.jobs.jira_sync_job import sync_all_jira_links
+
+# Import run_retention_job from app.jobs.retention_job
+from app.jobs.retention_job import run_retention_job
+
+# Import check_and_run_recurring_campaigns from app.services.campaign_scheduler_service
+from app.services.campaign_scheduler_service import check_and_run_recurring_campaigns
+
+# Import scan_intel from app.services.intel_service
+from app.services.intel_service import scan_intel
+
+# Import sync_mitre from app.services.mitre_sync_service
 from app.services.mitre_sync_service import sync_mitre
 
+# Import cleanup_old_notifications from app.services.notification_service
+from app.services.notification_service import cleanup_old_notifications
+
+# Import enrich_all_techniques from app.services.osint_enrichment_service
+from app.services.osint_enrichment_service import enrich_all_techniques
+
+# Import cleanup_old_snapshots, create_snapshot from app.services.snapshot_service
+from app.services.snapshot_service import cleanup_old_snapshots, create_snapshot
+
+# Import detect_stale_coverage from app.services.stale_detection_service
+from app.services.stale_detection_service import detect_stale_coverage
+
+# Assign logger = logging.getLogger(__name__)
 logger = logging.getLogger(__name__)
 
 # ---------------------------------------------------------------------------
@@ -22,32 +56,339 @@ logger = logging.getLogger(__name__)
 scheduler = BackgroundScheduler()
 
 
+# ---------------------------------------------------------------------------
+# Job functions
+# ---------------------------------------------------------------------------
+
+
 def _run_mitre_sync() -> None:
     """Execute a MITRE sync inside its own DB session."""
+    # Log info: "Scheduled MITRE sync job starting..."
     logger.info("Scheduled MITRE sync job starting...")
+    # Assign db = SessionLocal()
     db = SessionLocal()
+    # Attempt the following; catch errors below
     try:
+        # Assign summary = sync_mitre(db)
         summary = sync_mitre(db)
+        # Log info: "Scheduled MITRE sync job finished — %s", summary
         logger.info("Scheduled MITRE sync job finished — %s", summary)
+    # Handle Exception
     except Exception:
+        # Log exception: "Scheduled MITRE sync job failed"
         logger.exception("Scheduled MITRE sync job failed")
+    # Always execute this cleanup block
     finally:
+        # Close the database session
         db.close()
 
 
-def start_scheduler() -> None:
-    """Register the MITRE sync job and start the background scheduler.
+# Define function _run_notification_cleanup
+def _run_notification_cleanup() -> None:
+    """Clean up old read notifications."""
+    # Log info: "Scheduled notification cleanup job starting..."
+    logger.info("Scheduled notification cleanup job starting...")
+    # Assign db = SessionLocal()
+    db = SessionLocal()
+    # Attempt the following; catch errors below
+    try:
+        # Assign deleted = cleanup_old_notifications(db, days=90)
+        deleted = cleanup_old_notifications(db, days=90)
+        # Log info: "Notification cleanup finished — deleted %d old no
+        logger.info("Notification cleanup finished — deleted %d old notifications", deleted)
+    # Handle Exception
+    except Exception:
+        # Log exception: "Notification cleanup job failed"
+        logger.exception("Notification cleanup job failed")
+    # Always execute this cleanup block
+    finally:
+        # Close the database session
+        db.close()
 
-    The job runs every **24 hours**.  It does **not** fire immediately on
-    startup — the first execution happens 24 h after the application boots.
+
+# Define function _run_weekly_snapshot
+def _run_weekly_snapshot() -> None:
+    """Create a weekly coverage snapshot and clean up old ones."""
+    # Log info: "Scheduled weekly snapshot job starting..."
+    logger.info("Scheduled weekly snapshot job starting...")
+    # Assign db = SessionLocal()
+    db = SessionLocal()
+    # Attempt the following; catch errors below
+    try:
+        # Assign snapshot = create_snapshot(db, name="Auto-weekly")
+        snapshot = create_snapshot(db, name="Auto-weekly")
+        # Log info:
+        logger.info(
+            # Literal argument value
+            "Weekly snapshot created — score %.1f, %d techniques",
+            snapshot.organization_score,
+            snapshot.total_techniques,
+        )
+        # Assign deleted = cleanup_old_snapshots(db, keep_last=52)
+        deleted = cleanup_old_snapshots(db, keep_last=52)
+        # Check: deleted
+        if deleted:
+            # Log info: "Cleaned up %d old snapshots", deleted
+            logger.info("Cleaned up %d old snapshots", deleted)
+    # Handle Exception
+    except Exception:
+        # Log exception: "Weekly snapshot job failed"
+        logger.exception("Weekly snapshot job failed")
+    # Always execute this cleanup block
+    finally:
+        # Close the database session
+        db.close()
+
+
+# Define function _run_recurring_campaigns
+def _run_recurring_campaigns() -> None:
+    """Check and run any due recurring campaigns."""
+    # Log info: "Scheduled recurring campaigns check starting..."
+    logger.info("Scheduled recurring campaigns check starting...")
+    # Assign db = SessionLocal()
+    db = SessionLocal()
+    # Attempt the following; catch errors below
+    try:
+        # Assign spawned = check_and_run_recurring_campaigns(db)
+        spawned = check_and_run_recurring_campaigns(db)
+        # Log info: "Recurring campaigns check finished — spawned %d c
+        logger.info("Recurring campaigns check finished — spawned %d campaigns", spawned)
+    # Handle Exception
+    except Exception:
+        # Log exception: "Recurring campaigns check failed"
+        logger.exception("Recurring campaigns check failed")
+    # Always execute this cleanup block
+    finally:
+        # Close the database session
+        db.close()
+
+
+# Define function _run_intel_scan
+def _run_intel_scan() -> None:
+    """Execute an intel scan inside its own DB session."""
+    # Log info: "Scheduled intel scan job starting..."
+    logger.info("Scheduled intel scan job starting...")
+    # Assign db = SessionLocal()
+    db = SessionLocal()
+    # Attempt the following; catch errors below
+    try:
+        # Assign summary = scan_intel(db)
+        summary = scan_intel(db)
+        # Log info: "Scheduled intel scan job finished — %s", summary
+        logger.info("Scheduled intel scan job finished — %s", summary)
+    # Handle Exception
+    except Exception:
+        # Log exception: "Scheduled intel scan job failed"
+        logger.exception("Scheduled intel scan job failed")
+    # Always execute this cleanup block
+    finally:
+        # Close the database session
+        db.close()
+
+
+# Define function _run_osint_enrichment
+def _run_osint_enrichment() -> None:
+    """Execute weekly OSINT enrichment inside its own DB session."""
+    # Log info: "Scheduled OSINT enrichment job starting..."
+    logger.info("Scheduled OSINT enrichment job starting...")
+    # Assign db = SessionLocal()
+    db = SessionLocal()
+    # Attempt the following; catch errors below
+    try:
+        # Assign total = enrich_all_techniques(db)
+        total = enrich_all_techniques(db)
+        # Log info: "OSINT enrichment finished — %d new items", total
+        logger.info("OSINT enrichment finished — %d new items", total)
+    # Handle Exception
+    except Exception:
+        # Log exception: "OSINT enrichment job failed"
+        logger.exception("OSINT enrichment job failed")
+    # Always execute this cleanup block
+    finally:
+        # Close the database session
+        db.close()
+
+
+# Define function _run_stale_detection
+def _run_stale_detection() -> None:
+    """Execute daily stale coverage detection inside its own DB session."""
+    # Log info: "Scheduled stale coverage detection starting..."
+    logger.info("Scheduled stale coverage detection starting...")
+    # Assign db = SessionLocal()
+    db = SessionLocal()
+    # Attempt the following; catch errors below
+    try:
+        # Assign count = detect_stale_coverage(db)
+        count = detect_stale_coverage(db)
+        # Log info: "Stale detection finished — %d techniques flagged"
+        logger.info("Stale detection finished — %d techniques flagged", count)
+    # Handle Exception
+    except Exception:
+        # Log exception: "Stale coverage detection job failed"
+        logger.exception("Stale coverage detection job failed")
+    # Always execute this cleanup block
+    finally:
+        # Close the database session
+        db.close()
+
+
+# ---------------------------------------------------------------------------
+# Scheduler bootstrap
+# ---------------------------------------------------------------------------
+
+
+def start_scheduler() -> None:
+    """Register all periodic jobs and start the background scheduler.
+
+    Jobs registered:
+
+    * ``mitre_sync`` — every **24 hours**
+    * ``intel_scan`` — every **7 days**
+
+    Neither job fires immediately on startup.
     """
+    # Call scheduler.add_job()
     scheduler.add_job(
         _run_mitre_sync,
+        # Keyword argument: trigger
         trigger="interval",
+        # Keyword argument: hours
         hours=24,
+        # Keyword argument: id
         id="mitre_sync",
+        # Keyword argument: name
         name="MITRE ATT&CK sync (every 24h)",
+        # Keyword argument: replace_existing
         replace_existing=True,
     )
+    # Call scheduler.add_job()
+    scheduler.add_job(
+        _run_intel_scan,
+        # Keyword argument: trigger
+        trigger="interval",
+        # Keyword argument: weeks
+        weeks=1,
+        # Keyword argument: id
+        id="intel_scan",
+        # Keyword argument: name
+        name="Intel scan (every 7d)",
+        # Keyword argument: replace_existing
+        replace_existing=True,
+    )
+    # Call scheduler.add_job()
+    scheduler.add_job(
+        _run_notification_cleanup,
+        # Keyword argument: trigger
+        trigger="interval",
+        # Keyword argument: hours
+        hours=24,
+        # Keyword argument: id
+        id="notification_cleanup",
+        # Keyword argument: name
+        name="Notification cleanup (daily)",
+        # Keyword argument: replace_existing
+        replace_existing=True,
+    )
+    # Call scheduler.add_job()
+    scheduler.add_job(
+        _run_weekly_snapshot,
+        # Keyword argument: trigger
+        trigger="cron",
+        # Keyword argument: day_of_week
+        day_of_week="sun",
+        # Keyword argument: hour
+        hour=0,
+        # Keyword argument: minute
+        minute=0,
+        # Keyword argument: id
+        id="weekly_snapshot",
+        # Keyword argument: name
+        name="Weekly coverage snapshot (Sundays 00:00)",
+        # Keyword argument: replace_existing
+        replace_existing=True,
+    )
+    # Call scheduler.add_job()
+    scheduler.add_job(
+        _run_recurring_campaigns,
+        # Keyword argument: trigger
+        trigger="interval",
+        # Keyword argument: hours
+        hours=24,
+        # Keyword argument: id
+        id="recurring_campaigns",
+        # Keyword argument: name
+        name="Recurring campaigns check (daily)",
+        # Keyword argument: replace_existing
+        replace_existing=True,
+    )
+    # Call scheduler.add_job()
+    scheduler.add_job(
+        sync_all_jira_links,
+        # Keyword argument: trigger
+        trigger="interval",
+        # Keyword argument: hours
+        hours=1,
+        # Keyword argument: id
+        id="jira_sync",
+        # Keyword argument: name
+        name="Jira link sync (hourly)",
+        # Keyword argument: replace_existing
+        replace_existing=True,
+    )
+    # Call scheduler.add_job()
+    scheduler.add_job(
+        _run_osint_enrichment,
+        # Keyword argument: trigger
+        trigger="interval",
+        # Keyword argument: weeks
+        weeks=1,
+        # Keyword argument: id
+        id="osint_enrichment",
+        # Keyword argument: name
+        name="OSINT enrichment (weekly)",
+        # Keyword argument: replace_existing
+        replace_existing=True,
+    )
+    # Call scheduler.add_job()
+    scheduler.add_job(
+        _run_stale_detection,
+        # Keyword argument: trigger
+        trigger="interval",
+        # Keyword argument: hours
+        hours=24,
+        # Keyword argument: id
+        id="stale_detection",
+        # Keyword argument: name
+        name="Stale coverage detection (daily)",
+        # Keyword argument: replace_existing
+        replace_existing=True,
+    )
+    # Call scheduler.add_job()
+    scheduler.add_job(
+        run_retention_job,
+        # Keyword argument: trigger
+        trigger="interval",
+        # Keyword argument: hours
+        hours=24,
+        # Keyword argument: id
+        id="retention_policies",
+        # Keyword argument: name
+        name="Data retention policies (daily)",
+        # Keyword argument: replace_existing
+        replace_existing=True,
+    )
+    # Call scheduler.start()
     scheduler.start()
-    logger.info("MITRE sync scheduler started (interval=24h)")
+    # Log info:
+    logger.info(
+        # Literal argument value
+        "Background scheduler started — mitre_sync (24h), intel_scan (7d), "
+        # Literal argument value
+        "notification_cleanup (24h), weekly_snapshot (Sundays 00:00), "
+        # Literal argument value
+        "recurring_campaigns (daily), jira_sync (1h), "
+        # Literal argument value
+        "osint_enrichment (weekly), stale_detection (daily), "
+        # Literal argument value
+        "retention_policies (daily)"
+    )

backend/app/jobs/retention_job.py

@@ -0,0 +1,89 @@
+"""Data retention policies — scheduled cleanup of aged records."""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import logging
+import logging
+
+# Import datetime, timedelta, timezone from datetime
+from datetime import datetime, timedelta, timezone
+
+# Import Session from sqlalchemy.orm
+from sqlalchemy.orm import Session
+
+# Import SessionLocal from app.database
+from app.database import SessionLocal
+
+# Import AuditLog from app.models.audit
+from app.models.audit import AuditLog
+
+# Import cleanup_old_notifications from app.services.notification_service
+from app.services.notification_service import cleanup_old_notifications
+
+# Assign logger = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
+
+# Assign AUDIT_LOG_RETENTION_DAYS = 730
+AUDIT_LOG_RETENTION_DAYS = 730
+
+
+# Define function apply_retention_policies
+def apply_retention_policies(db: Session) -> dict[str, int]:
+    """Apply retention rules. Commits the session before returning."""
+    # Assign cutoff = datetime.now(timezone.utc) - timedelta(days=AUDIT_LOG_RETENTION_DAYS)
+    cutoff = datetime.now(timezone.utc) - timedelta(days=AUDIT_LOG_RETENTION_DAYS)
+    # Assign deleted_audit = (
+    deleted_audit = (
+        db.query(AuditLog)
+        # Chain .filter() call
+        .filter(AuditLog.timestamp < cutoff)
+        # Chain .delete() call
+        .delete(synchronize_session=False)
+    )
+    # Check: deleted_audit
+    if deleted_audit:
+        # Log info:
+        logger.info(
+            # Literal argument value
+            "Retention: deleted %d audit logs older than %d days",
+            deleted_audit,
+            AUDIT_LOG_RETENTION_DAYS,
+        )
+
+    # Assign deleted_notifications = cleanup_old_notifications(db, days=90)
+    deleted_notifications = cleanup_old_notifications(db, days=90)
+    # Commit all pending changes to the database
+    db.commit()
+    # Return {
+    return {
+        # Literal argument value
+        "audit_logs_deleted": deleted_audit,
+        # Literal argument value
+        "notifications_deleted": deleted_notifications,
+    }
+
+
+# Define function run_retention_job
+def run_retention_job() -> None:
+    """Entry point for the daily retention scheduler job."""
+    # Log info: "Scheduled retention job starting..."
+    logger.info("Scheduled retention job starting...")
+    # Assign db = SessionLocal()
+    db = SessionLocal()
+    # Attempt the following; catch errors below
+    try:
+        # Assign summary = apply_retention_policies(db)
+        summary = apply_retention_policies(db)
+        # Log info: "Retention job finished — %s", summary
+        logger.info("Retention job finished — %s", summary)
+    # Handle Exception
+    except Exception:
+        # Log exception: "Retention job failed"
+        logger.exception("Retention job failed")
+        # Roll back all uncommitted changes
+        db.rollback()
+    # Always execute this cleanup block
+    finally:
+        # Close the database session
+        db.close()

backend/app/limiter.py

@@ -0,0 +1,10 @@
+"""Shared SlowAPI rate limiter for all routers."""
+
+# Import Limiter from slowapi
+from slowapi import Limiter
+
+# Import get_remote_address from slowapi.util
+from slowapi.util import get_remote_address
+
+# Assign limiter = Limiter(key_func=get_remote_address)
+limiter = Limiter(key_func=get_remote_address)

backend/app/logging_config.py

@@ -0,0 +1,108 @@
+"""Structured JSON logging configuration.
+
+In **production** (``AEGIS_ENV=production``), emits one JSON object per
+line so that log aggregators (ELK, CloudWatch, Datadog) can ingest them
+without custom parsing.
+
+In **development** (default), uses a human-readable text format for
+comfortable local work.
+"""
+
+# Enable future language features for compatibility
+from __future__ import annotations
+
+# Import json
+import json
+
+# Import logging
+import logging
+
+# Import os
+import os
+
+# Import sys
+import sys
+
+# Import datetime, timezone from datetime
+from datetime import datetime, timezone
+
+
+# Define class _JSONFormatter
+class _JSONFormatter(logging.Formatter):
+    """Emit each log record as a single-line JSON object."""
+
+    # Define function format
+    def format(self, record: logging.LogRecord) -> str:
+        # Assign payload = {
+        payload: dict = {
+            # Literal argument value
+            "timestamp": datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat(),
+            # Literal argument value
+            "level": record.levelname,
+            # Literal argument value
+            "logger": record.name,
+            # Literal argument value
+            "message": record.getMessage(),
+        }
+
+        # Check: record.exc_info and record.exc_info[1] is not None
+        if record.exc_info and record.exc_info[1] is not None:
+            # Assign payload["exception"] = self.formatException(record.exc_info)
+            payload["exception"] = self.formatException(record.exc_info)
+
+        # Assign extra = getattr(record, "_extra", None)
+        extra = getattr(record, "_extra", None)
+        # Check: extra
+        if extra:
+            # Call payload.update()
+            payload.update(extra)
+
+        # Return json.dumps(payload, default=str)
+        return json.dumps(payload, default=str)
+
+
+# Assign _DEV_FORMAT = "%(asctime)s  %(levelname)-8s  %(name)s — %(message)s"
+_DEV_FORMAT = "%(asctime)s  %(levelname)-8s  %(name)s — %(message)s"
+
+
+# Define function setup_logging
+def setup_logging() -> None:
+    """Configure the root logger based on the environment."""
+    # Assign is_production = os.environ.get("AEGIS_ENV", "").lower() == "production"
+    is_production = os.environ.get("AEGIS_ENV", "").lower() == "production"
+    # Assign level_name = os.environ.get("LOG_LEVEL", "INFO").upper()
+    level_name = os.environ.get("LOG_LEVEL", "INFO").upper()
+    # Assign level = getattr(logging, level_name, logging.INFO)
+    level = getattr(logging, level_name, logging.INFO)
+
+    # Assign root = logging.getLogger()
+    root = logging.getLogger()
+    # Call root.setLevel()
+    root.setLevel(level)
+
+    # Check: root.handlers
+    if root.handlers:
+        # Call root.handlers.clear()
+        root.handlers.clear()
+
+    # Assign handler = logging.StreamHandler(sys.stdout)
+    handler = logging.StreamHandler(sys.stdout)
+    # Call handler.setLevel()
+    handler.setLevel(level)
+
+    # Check: is_production
+    if is_production:
+        # Call handler.setFormatter()
+        handler.setFormatter(_JSONFormatter())
+    # Fallback: handle remaining cases
+    else:
+        # Call handler.setFormatter()
+        handler.setFormatter(logging.Formatter(_DEV_FORMAT))
+
+    # Call root.addHandler()
+    root.addHandler(handler)
+
+    # Call logging.getLogger()
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    # Call logging.getLogger()
+    logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)

backend/app/main.py

@@ -1,52 +1,406 @@
+"""FastAPI application factory and global middleware/exception configuration.
+
+Builds the ``app`` instance, wires up CORS, rate limiting, domain-error
+mapping, all API routers, and async lifespan hooks (MinIO bucket creation,
+APScheduler startup/shutdown).
+"""
+
+# Import logging
 import logging
+
+# Import os
+import os
+
+# Import AsyncGenerator from collections.abc
+from collections.abc import AsyncGenerator
+
+# Import asynccontextmanager from contextlib
 from contextlib import asynccontextmanager
 
-from fastapi import FastAPI
+# Import FastAPI, Request, status from fastapi
+from fastapi import FastAPI, Request, status
+
+# Import RequestValidationError from fastapi.exceptions
+from fastapi.exceptions import RequestValidationError
+
+# Import CORSMiddleware from fastapi.middleware.cors
 from fastapi.middleware.cors import CORSMiddleware
 
+# Import JSONResponse from fastapi.responses
+from fastapi.responses import JSONResponse
+
+# Import _rate_limit_exceeded_handler from slowapi
+from slowapi import _rate_limit_exceeded_handler
+
+# Import RateLimitExceeded from slowapi.errors
+from slowapi.errors import RateLimitExceeded
+
+# Import SQLAlchemyError from sqlalchemy.exc
+from sqlalchemy.exc import SQLAlchemyError
+
+# Import settings as _settings from app.config
+from app.config import settings as _settings
+
+# Import DomainError from app.domain.errors
+from app.domain.errors import DomainError
+
+# Import scheduler, start_scheduler from app.jobs.mitre_sync_job
+from app.jobs.mitre_sync_job import scheduler, start_scheduler
+
+# Import limiter from app.limiter
+from app.limiter import limiter
+
+# Import setup_logging from app.logging_config
+from app.logging_config import setup_logging
+
+# Import domain_exception_handler from app.middleware.error_handler
+from app.middleware.error_handler import domain_exception_handler
+
+# Import RequestContextMiddleware from app.middleware.request_context
+from app.middleware.request_context import RequestContextMiddleware
+
+# Import advanced_metrics as advanced_metrics_router from app.routers
+from app.routers import advanced_metrics as advanced_metrics_router
+
+# Import analytics as analytics_router from app.routers
+from app.routers import analytics as analytics_router
+
+# Import audit as audit_router from app.routers
+from app.routers import audit as audit_router
+
+# Import auth as auth_router from app.routers
 from app.routers import auth as auth_router
-from app.routers import techniques as techniques_router
-from app.routers import tests as tests_router
+
+# Import campaigns as campaigns_router from app.routers
+from app.routers import campaigns as campaigns_router
+
+# Import compliance as compliance_router from app.routers
+from app.routers import compliance as compliance_router
+
+# Import d3fend as d3fend_router from app.routers
+from app.routers import d3fend as d3fend_router
+
+# Import data_sources as data_sources_router from app.routers
+from app.routers import data_sources as data_sources_router
+
+# Import detection_rules as detection_rules_router from app.routers
+from app.routers import detection_rules as detection_rules_router
+
+# Import evidence as evidence_router from app.routers
 from app.routers import evidence as evidence_router
+
+# Import heatmap as heatmap_router from app.routers
+from app.routers import heatmap as heatmap_router
+
+# Import jira as jira_router from app.routers
+from app.routers import jira as jira_router
+
+# Import metrics as metrics_router from app.routers
+from app.routers import metrics as metrics_router
+
+# Import notifications as notifications_router from app.routers
+from app.routers import notifications as notifications_router
+
+# Import operational_metrics as operational_metrics_router from app.routers
+from app.routers import operational_metrics as operational_metrics_router
+
+# Import osint as osint_router from app.routers
+from app.routers import osint as osint_router
+
+# Import professional_reports as professional_reports_ro... from app.routers
+from app.routers import professional_reports as professional_reports_router
+
+# Import reports as reports_router from app.routers
+from app.routers import reports as reports_router
+
+# Import scores as scores_router from app.routers
+from app.routers import scores as scores_router
+
+# Import snapshots as snapshots_router from app.routers
+from app.routers import snapshots as snapshots_router
+
+# Import system as system_router from app.routers
 from app.routers import system as system_router
+
+# Import techniques as techniques_router from app.routers
+from app.routers import techniques as techniques_router
+
+# Import test_templates as test_templates_router from app.routers
+from app.routers import test_templates as test_templates_router
+
+# Import tests as tests_router from app.routers
+from app.routers import tests as tests_router
+
+# Import threat_actors as threat_actors_router from app.routers
+from app.routers import threat_actors as threat_actors_router
+
+# Import users as users_router from app.routers
+from app.routers import users as users_router
+
+# Import worklogs as worklogs_router from app.routers
+from app.routers import worklogs as worklogs_router
+
+# Import ensure_bucket_exists from app.storage
 from app.storage import ensure_bucket_exists
-from app.jobs.mitre_sync_job import start_scheduler, scheduler
 
-# ── Logging ───────────────────────────────────────────────────────────────
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s  %(levelname)-8s  %(name)s — %(message)s",
-)
+# Configure structured logging before any module initialises its own logger
+setup_logging()
 
+# ── Environment detection ─────────────────────────────────────────────────
+_IS_PRODUCTION = os.environ.get("AEGIS_ENV", "").lower() == "production"
+
+# Apply the @asynccontextmanager decorator
 @asynccontextmanager
-async def lifespan(app: FastAPI):
-    """Startup / shutdown logic."""
+# Define async function lifespan
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Manage application startup and shutdown lifecycle.
+
+    Args:
+        app (FastAPI): The FastAPI application instance.
+
+    Yields:
+        None: Control is yielded to the running application.
+    """
+    # Call ensure_bucket_exists()
     ensure_bucket_exists()
+    # Call start_scheduler()
     start_scheduler()
+    # Yield value
     yield
     # Graceful shutdown of the background scheduler
     scheduler.shutdown(wait=False)
 
 
-app = FastAPI(title="Attack Coverage Platform", lifespan=lifespan)
+# ── In production, disable Swagger UI and ReDoc to hide API surface ──────
+app = FastAPI(
+    # Keyword argument: title
+    title="Attack Coverage Platform",
+    # Keyword argument: lifespan
+    lifespan=lifespan,
+    # Keyword argument: docs_url
+    docs_url=None if _IS_PRODUCTION else "/docs",
+    # Keyword argument: redoc_url
+    redoc_url=None if _IS_PRODUCTION else "/redoc",
+    # Keyword argument: openapi_url
+    openapi_url=None if _IS_PRODUCTION else "/openapi.json",
+)
+
+# ── Rate Limiter ──────────────────────────────────────────────────────────
+app.state.limiter = limiter
+# Call app.add_exception_handler()
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+# Call app.add_middleware()
+app.add_middleware(RequestContextMiddleware)
+
+# ── Domain exception → HTTP mapping ──────────────────────────────────────
+app.add_exception_handler(DomainError, domain_exception_handler)
 
 # ── CORS ──────────────────────────────────────────────────────────────────
+_cors_origins: list[str] = [
+    o.strip() for o in _settings.CORS_ORIGINS.split(",") if o.strip()
+]
+
+# Call app.add_middleware()
 app.add_middleware(
     CORSMiddleware,
-    allow_origins=["http://localhost:3000", "http://localhost:5173"],
+    # Keyword argument: allow_origins
+    allow_origins=_cors_origins,
+    # Keyword argument: allow_credentials
     allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
+    # Keyword argument: allow_methods
+    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    # Keyword argument: allow_headers
+    allow_headers=["Authorization", "Content-Type"],
 )
 
 # ── Routers ──────────────────────────────────────────────────────────────
 app.include_router(auth_router.router, prefix="/api/v1")
+# Call app.include_router()
 app.include_router(techniques_router.router, prefix="/api/v1")
+# Call app.include_router()
 app.include_router(tests_router.router, prefix="/api/v1")
+# Call app.include_router()
 app.include_router(evidence_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(test_templates_router.router, prefix="/api/v1")
+# Call app.include_router()
 app.include_router(system_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(metrics_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(users_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(audit_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(notifications_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(reports_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(data_sources_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(threat_actors_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(d3fend_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(detection_rules_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(campaigns_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(heatmap_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(scores_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(operational_metrics_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(compliance_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(snapshots_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(jira_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(worklogs_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(professional_reports_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(analytics_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(advanced_metrics_router.router, prefix="/api/v1")
+# Call app.include_router()
+app.include_router(osint_router.router, prefix="/api/v1")
 
 
-@app.get("/health")
-def health():
+# Apply the @app.get decorator
+@app.get("/health", include_in_schema=False)
+# Define function health
+def health() -> dict[str, str]:
+    """Return a minimal liveness probe response.
+
+    Access is restricted to internal networks at the Nginx level
+    (see ``frontend/nginx.conf``).
+
+    Returns:
+        dict[str, str]: A dict with ``{"status": "ok"}``.
+    """
+    # Return {"status": "ok"}
     return {"status": "ok"}
+
+
+# ── Exception Handlers ────────────────────────────────────────────────────
+
+
+def _serialize_validation_errors(exc: RequestValidationError) -> list[dict]:
+    """Return validation errors safe for JSON serialization.
+
+    Converts non-serializable values inside ``ctx`` dictionaries to strings
+    so the response body can be safely encoded.
+
+    Args:
+        exc (RequestValidationError): The Pydantic validation exception.
+
+    Returns:
+        list[dict]: A list of sanitised error detail dictionaries.
+    """
+    # Assign serialized = []
+    serialized: list[dict] = []
+    # Iterate over exc.errors()
+    for err in exc.errors():
+        # Assign item = dict(err)
+        item = dict(err)
+        # Assign ctx = item.get("ctx")
+        ctx = item.get("ctx")
+        # Check: isinstance(ctx, dict)
+        if isinstance(ctx, dict):
+            # Assign item["ctx"] = {key: str(value) for key, value in ctx.items()}
+            item["ctx"] = {key: str(value) for key, value in ctx.items()}
+        # Call serialized.append()
+        serialized.append(item)
+    # Return serialized
+    return serialized
+
+
+# Apply the @app.exception_handler decorator
+@app.exception_handler(RequestValidationError)
+# Define async function validation_exception_handler
+async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    """Handle Pydantic validation errors and return a structured 422 response.
+
+    Args:
+        request (Request): The incoming HTTP request.
+        exc (RequestValidationError): The caught validation exception.
+
+    Returns:
+        JSONResponse: A 422 response with a ``VALIDATION_ERROR`` code and error details.
+    """
+    # Return JSONResponse(
+    return JSONResponse(
+        # Keyword argument: status_code
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        # Keyword argument: content
+        content={
+            # Literal argument value
+            "detail": "Validation error",
+            # Literal argument value
+            "code": "VALIDATION_ERROR",
+            # Literal argument value
+            "errors": _serialize_validation_errors(exc),
+        },
+    )
+
+
+# Apply the @app.exception_handler decorator
+@app.exception_handler(SQLAlchemyError)
+# Define async function sqlalchemy_exception_handler
+async def sqlalchemy_exception_handler(request: Request, exc: SQLAlchemyError) -> JSONResponse:
+    """Handle SQLAlchemy database errors and return a structured 500 response.
+
+    Args:
+        request (Request): The incoming HTTP request.
+        exc (SQLAlchemyError): The caught SQLAlchemy exception.
+
+    Returns:
+        JSONResponse: A 500 response with a ``DATABASE_ERROR`` code.
+    """
+    # Log error: f"Database error: {exc}"
+    logging.error(f"Database error: {exc}")
+    # Return JSONResponse(
+    return JSONResponse(
+        # Keyword argument: status_code
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        # Keyword argument: content
+        content={
+            # Literal argument value
+            "detail": "Database error occurred",
+            # Literal argument value
+            "code": "DATABASE_ERROR",
+        },
+    )
+
+
+# Apply the @app.exception_handler decorator
+@app.exception_handler(Exception)
+# Define async function general_exception_handler
+async def general_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """Handle all otherwise-unhandled exceptions and return a structured 500 response.
+
+    Args:
+        request (Request): The incoming HTTP request.
+        exc (Exception): The unhandled exception.
+
+    Returns:
+        JSONResponse: A 500 response with an ``INTERNAL_ERROR`` code.
+    """
+    # Log error: f"Unhandled exception: {exc}"
+    logging.error(f"Unhandled exception: {exc}")
+    # Return JSONResponse(
+    return JSONResponse(
+        # Keyword argument: status_code
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        # Keyword argument: content
+        content={
+            # Literal argument value
+            "detail": "An internal server error occurred",
+            # Literal argument value
+            "code": "INTERNAL_ERROR",
+        },
+    )

backend/app/middleware/__init__.py

@@ -0,0 +1 @@
+"""ASGI middleware components for request context, error handling, and rate limiting."""

backend/app/middleware/error_handler.py

@@ -0,0 +1,66 @@
+"""Domain error → HTTP response mapping.
+
+This module provides a single exception handler that converts
+domain-layer errors into structured JSON responses, keeping
+the service layer free from FastAPI's ``HTTPException``.
+"""
+
+# Import Request from fastapi
+from fastapi import Request
+
+# Import JSONResponse from fastapi.responses
+from fastapi.responses import JSONResponse
+
+# Import  from app.domain.errors
+from app.domain.errors import (
+    BusinessRuleViolation,
+    DomainError,
+    DuplicateEntityError,
+    EntityNotFoundError,
+    InvalidOperationError,
+    InvalidStateTransition,
+    PermissionViolation,
+)
+
+# Assign EXCEPTION_STATUS_MAP = {
+EXCEPTION_STATUS_MAP: dict[type[DomainError], int] = {
+    # Entry: EntityNotFoundError
+    EntityNotFoundError: 404,
+    # Entry: DuplicateEntityError
+    DuplicateEntityError: 409,
+    # Entry: InvalidStateTransition
+    InvalidStateTransition: 400,
+    # Entry: InvalidOperationError
+    InvalidOperationError: 400,
+    # Entry: BusinessRuleViolation
+    BusinessRuleViolation: 400,
+    # Entry: PermissionViolation
+    PermissionViolation: 403,
+}
+
+
+# Define async function domain_exception_handler
+async def domain_exception_handler(
+    # Entry: request
+    request: Request,
+    # Entry: exc
+    exc: DomainError,
+) -> JSONResponse:
+    """Convert a :class:`DomainError` into a JSON error response."""
+    # Assign status_code = EXCEPTION_STATUS_MAP.get(type(exc), 400)
+    status_code = EXCEPTION_STATUS_MAP.get(type(exc), 400)
+
+    # Assign content = {"detail": exc.message, "code": exc.code}
+    content: dict = {"detail": exc.message, "code": exc.code}
+
+    # Check: isinstance(exc, InvalidStateTransition)
+    if isinstance(exc, InvalidStateTransition):
+        # Assign content["current_state"] = exc.current_state
+        content["current_state"] = exc.current_state
+        # Assign content["target_state"] = exc.target_state
+        content["target_state"] = exc.target_state
+        # Assign content["valid_transitions"] = exc.valid_transitions
+        content["valid_transitions"] = exc.valid_transitions
+
+    # Return JSONResponse(status_code=status_code, content=content)
+    return JSONResponse(status_code=status_code, content=content)

backend/app/middleware/request_context.py

@@ -0,0 +1,74 @@
+"""Request context middleware — captures client IP and User-Agent per request."""
+
+# Import Awaitable, Callable from collections.abc
+from collections.abc import Awaitable, Callable
+
+# Import ContextVar from contextvars
+from contextvars import ContextVar
+
+# Import Request from fastapi
+from fastapi import Request
+
+# Import BaseHTTPMiddleware from starlette.middleware.base
+from starlette.middleware.base import BaseHTTPMiddleware
+
+# Import Response from starlette.responses
+from starlette.responses import Response
+
+# Assign request_ip = ContextVar("request_ip", default="")
+request_ip: ContextVar[str] = ContextVar("request_ip", default="")
+# Assign request_user_agent = ContextVar("request_user_agent", default="")
+request_user_agent: ContextVar[str] = ContextVar("request_user_agent", default="")
+
+
+# Define function resolve_client_ip
+def resolve_client_ip(request: Request) -> str:
+    """Extract the real client IP, honouring ``X-Forwarded-For`` when present.
+
+    Args:
+        request (Request): The incoming Starlette/FastAPI request.
+
+    Returns:
+        str: The resolved client IP address, or ``"unknown"`` when unavailable.
+    """
+    # Assign forwarded = request.headers.get("X-Forwarded-For")
+    forwarded = request.headers.get("X-Forwarded-For")
+    # Check: forwarded
+    if forwarded:
+        # Return forwarded.split(",")[0].strip()
+        return forwarded.split(",")[0].strip()
+    # Check: request.client
+    if request.client:
+        # Return request.client.host
+        return request.client.host
+    # Return "unknown"
+    return "unknown"
+
+
+# Define class RequestContextMiddleware
+class RequestContextMiddleware(BaseHTTPMiddleware):
+    """Middleware that captures client IP and User-Agent into context variables."""
+
+    # Define async function dispatch
+    async def dispatch(
+        self,
+        # Entry: request
+        request: Request,
+        # Entry: call_next
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        """Store client IP and User-Agent in context vars for the current request.
+
+        Args:
+            request (Request): The incoming HTTP request.
+            call_next (Callable[[Request], Awaitable[Response]]): The next middleware or route handler.
+
+        Returns:
+            Response: The HTTP response produced by the downstream handler.
+        """
+        # Call request_ip.set()
+        request_ip.set(resolve_client_ip(request))
+        # Call request_user_agent.set()
+        request_user_agent.set(request.headers.get("User-Agent", ""))
+        # Return await call_next(request)
+        return await call_next(request)

backend/app/models/__init__.py

@@ -1,13 +1,96 @@
+"""SQLAlchemy ORM model definitions for all database tables."""
 # Import all models here so Alembic can detect them
-from app.models.user import User
-from app.models.technique import Technique
-from app.models.test import Test
-from app.models.evidence import Evidence
-from app.models.intel import IntelItem
 from app.models.audit import AuditLog
-from app.models.enums import TechniqueStatus, TestState, TestResult
 
+# Import Campaign, CampaignTest from app.models.campaign
+from app.models.campaign import Campaign, CampaignTest
+
+# Import  from app.models.compliance
+from app.models.compliance import (
+    ComplianceControl,
+    ComplianceControlMapping,
+    ComplianceFramework,
+)
+
+# Import CoverageSnapshot, SnapshotTechniqueState from app.models.coverage_snapshot
+from app.models.coverage_snapshot import CoverageSnapshot, SnapshotTechniqueState
+
+# Import DataSource from app.models.data_source
+from app.models.data_source import DataSource
+
+# Import DefensiveTechnique, DefensiveTechniqueMapping from app.models.defensive_technique
+from app.models.defensive_technique import DefensiveTechnique, DefensiveTechniqueMapping
+
+# Import DetectionRule from app.models.detection_rule
+from app.models.detection_rule import DetectionRule
+
+# Import TeamSide, TechniqueStatus, TestResult, TestState from app.models.enums
+from app.models.enums import TeamSide, TechniqueStatus, TestResult, TestState
+
+# Import Evidence from app.models.evidence
+from app.models.evidence import Evidence
+
+# Import IntelItem from app.models.intel
+from app.models.intel import IntelItem
+
+# Import JiraLink, JiraLinkEntityType, JiraSyncDirection from app.models.jira_link
+from app.models.jira_link import JiraLink, JiraLinkEntityType, JiraSyncDirection
+
+# Import Notification from app.models.notification
+from app.models.notification import Notification
+
+# Import OsintItem from app.models.osint_item
+from app.models.osint_item import OsintItem
+
+# Import ScoringConfig from app.models.scoring_config
+from app.models.scoring_config import ScoringConfig
+
+# Import Technique from app.models.technique
+from app.models.technique import Technique
+
+# Import Test from app.models.test
+from app.models.test import Test
+
+# Import TestDetectionResult from app.models.test_detection_result
+from app.models.test_detection_result import TestDetectionResult
+
+# Import TestTemplate from app.models.test_template
+from app.models.test_template import TestTemplate
+
+# Import TestTemplateDetectionRule from app.models.test_template_detection_rule
+from app.models.test_template_detection_rule import TestTemplateDetectionRule
+
+# Import ThreatActor, ThreatActorTechnique from app.models.threat_actor
+from app.models.threat_actor import ThreatActor, ThreatActorTechnique
+
+# Import User from app.models.user
+from app.models.user import User
+
+# Import Worklog from app.models.worklog
+from app.models.worklog import Worklog
+
+# Assign __all__ = [
 __all__ = [
-    "User", "Technique", "Test", "Evidence", "IntelItem", "AuditLog",
-    "TechniqueStatus", "TestState", "TestResult"
+    # Literal argument value
+    "User", "Technique", "Test", "TestTemplate", "Evidence",
+    # Literal argument value
+    "IntelItem", "AuditLog", "Notification", "DataSource",
+    # Literal argument value
+    "DetectionRule", "ThreatActor", "ThreatActorTechnique",
+    # Literal argument value
+    "DefensiveTechnique", "DefensiveTechniqueMapping",
+    # Literal argument value
+    "TestTemplateDetectionRule", "TestDetectionResult",
+    # Literal argument value
+    "Campaign", "CampaignTest",
+    # Literal argument value
+    "ComplianceFramework", "ComplianceControl", "ComplianceControlMapping",
+    # Literal argument value
+    "CoverageSnapshot", "SnapshotTechniqueState",
+    # Literal argument value
+    "JiraLink", "JiraLinkEntityType", "JiraSyncDirection",
+    # Literal argument value
+    "Worklog", "OsintItem", "ScoringConfig",
+    # Literal argument value
+    "TechniqueStatus", "TestState", "TestResult", "TeamSide",
 ]

backend/app/models/audit.py

@@ -1,29 +1,60 @@
-import uuid
-from datetime import datetime
+"""SQLAlchemy model for the audit log table."""
 
-from sqlalchemy import Column, String, DateTime, ForeignKey
-from sqlalchemy.dialects.postgresql import UUID, JSONB
+# Import uuid
+import uuid
+
+# Import Column, DateTime, ForeignKey, Index, String, func from sqlalchemy
+from sqlalchemy import Column, DateTime, ForeignKey, Index, String, func
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import relationship from sqlalchemy.orm
 from sqlalchemy.orm import relationship
 
+# Import Base from app.database
 from app.database import Base
 
 
+# Define class AuditLog
 class AuditLog(Base):
-    """
-    Audit log model for tracking all system actions.
-    
+    """Audit log model for tracking all system actions.
+
     Records user actions, entity changes, and system events
     for security auditing and compliance purposes.
     """
+    # Assign __tablename__ = "audit_logs"
     __tablename__ = "audit_logs"
 
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign user_id = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
     user_id = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+    # Assign action = Column(String, nullable=False)
     action = Column(String, nullable=False)
+    # Assign entity_type = Column(String, nullable=True)
     entity_type = Column(String, nullable=True)
+    # Assign entity_id = Column(String, nullable=True)
     entity_id = Column(String, nullable=True)
-    timestamp = Column(DateTime, default=datetime.utcnow)
+    # Assign timestamp = Column(DateTime(timezone=True), server_default=func.now())
+    timestamp = Column(DateTime(timezone=True), server_default=func.now())
+    # Assign details = Column(JSONB, nullable=True)
     details = Column(JSONB, nullable=True)
+    # Assign ip_address = Column(String(45), nullable=True)
+    ip_address = Column(String(45), nullable=True)
+    # Assign user_agent = Column(String(500), nullable=True)
+    user_agent = Column(String(500), nullable=True)
+    # Assign integrity_hash = Column(String(64), nullable=True)
+    integrity_hash = Column(String(64), nullable=True)
+    # Assign session_id = Column(String(100), nullable=True)
+    session_id = Column(String(100), nullable=True)
 
     # Relationships
     user = relationship("User")
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index("ix_audit_logs_entity", "entity_type", "entity_id"),
+        Index("ix_audit_logs_timestamp", "timestamp"),
+        Index("ix_audit_logs_entity_type_entity_id_action", "entity_type", "entity_id", "action"),
+    )

backend/app/models/campaign.py

@@ -0,0 +1,231 @@
+"""Campaign and CampaignTest models.
+
+Campaigns group multiple tests into a kill chain sequence,
+enabling simulation of complete attack chains and APT emulations.
+"""
+
+# Import uuid
+import uuid
+
+# Import  from sqlalchemy
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    func,
+)
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import relationship from sqlalchemy.orm
+from sqlalchemy.orm import relationship
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class Campaign
+class Campaign(Base):
+    """A campaign groups multiple tests into a sequenced attack chain.
+
+    Types:
+    - custom: manually created campaign
+    - apt_emulation: generated from a threat actor profile
+    - kill_chain: structured around kill chain phases
+    - compliance: targeting specific compliance requirements
+
+    Status:
+    - draft: being configured
+    - active: tests are being executed
+    - completed: all tests done
+    - archived: historical record
+    """
+    # Assign __tablename__ = "campaigns"
+    __tablename__ = "campaigns"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign name = Column(String, nullable=False)
+    name = Column(String, nullable=False)
+    # Assign description = Column(Text, nullable=True)
+    description = Column(Text, nullable=True)
+    # Assign type = Column(String, nullable=False, default="custom")       # custom, ap...
+    type = Column(String, nullable=False, default="custom")       # custom, apt_emulation, kill_chain, compliance
+    # Assign threat_actor_id = Column(
+    threat_actor_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("threat_actors.id", ondelete="SET NULL"),
+        # Keyword argument: nullable
+        nullable=True,
+    )
+    # Assign status = Column(String, nullable=False, default="draft")      # draft, activ...
+    status = Column(String, nullable=False, default="draft")      # draft, active, completed, archived
+    # Assign created_by = Column(
+    created_by = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        # Keyword argument: nullable
+        nullable=True,
+    )
+    # Assign scheduled_at = Column(DateTime, nullable=True)
+    scheduled_at = Column(DateTime, nullable=True)
+    # Assign completed_at = Column(DateTime, nullable=True)
+    completed_at = Column(DateTime, nullable=True)
+    # Assign target_platform = Column(String, nullable=True)
+    target_platform = Column(String, nullable=True)
+    # Assign tags = Column(JSONB, nullable=True, default=[])
+    tags = Column(JSONB, nullable=True, default=[])
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    # Assign data_classification = Column(String(20), nullable=False, server_default="internal")
+    data_classification = Column(String(20), nullable=False, server_default="internal")
+
+    # Recurring scheduling fields
+    is_recurring = Column(Boolean, default=False)
+    # Assign recurrence_pattern = Column(String, nullable=True)   # weekly, monthly, quarterly
+    recurrence_pattern = Column(String, nullable=True)   # weekly, monthly, quarterly
+    # Assign next_run_at = Column(DateTime, nullable=True)
+    next_run_at = Column(DateTime, nullable=True)
+    # Assign last_run_at = Column(DateTime, nullable=True)
+    last_run_at = Column(DateTime, nullable=True)
+    # Assign parent_campaign_id = Column(
+    parent_campaign_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("campaigns.id", ondelete="SET NULL"),
+        # Keyword argument: nullable
+        nullable=True,
+    )
+
+    # Relationships
+    threat_actor = relationship("ThreatActor")
+    # Assign creator = relationship("User", foreign_keys=[created_by])
+    creator = relationship("User", foreign_keys=[created_by])
+    # Assign campaign_tests = relationship(
+    campaign_tests = relationship(
+        # Literal argument value
+        "CampaignTest",
+        # Keyword argument: back_populates
+        back_populates="campaign",
+        # Keyword argument: cascade
+        cascade="all, delete-orphan",
+        # Keyword argument: order_by
+        order_by="CampaignTest.order_index",
+    )
+    # Assign parent_campaign = relationship(
+    parent_campaign = relationship(
+        # Literal argument value
+        "Campaign",
+        # Keyword argument: remote_side
+        remote_side="Campaign.id",
+        # Keyword argument: foreign_keys
+        foreign_keys=[parent_campaign_id],
+    )
+    # Assign child_campaigns = relationship(
+    child_campaigns = relationship(
+        # Literal argument value
+        "Campaign",
+        # Keyword argument: foreign_keys
+        foreign_keys=[parent_campaign_id],
+        # Keyword argument: back_populates
+        back_populates="parent_campaign",
+    )
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_campaigns_status', 'status'),
+        Index('ix_campaigns_type', 'type'),
+        Index('ix_campaigns_threat_actor', 'threat_actor_id'),
+        Index('ix_campaigns_created_by', 'created_by'),
+        Index('ix_campaigns_next_run', 'next_run_at'),
+    )
+
+
+# Kill chain phases in order (for sorting and validation)
+KILL_CHAIN_PHASES = [
+    # Literal argument value
+    "reconnaissance",
+    # Literal argument value
+    "resource_development",
+    # Literal argument value
+    "initial_access",
+    # Literal argument value
+    "execution",
+    # Literal argument value
+    "persistence",
+    # Literal argument value
+    "privilege_escalation",
+    # Literal argument value
+    "defense_evasion",
+    # Literal argument value
+    "credential_access",
+    # Literal argument value
+    "discovery",
+    # Literal argument value
+    "lateral_movement",
+    # Literal argument value
+    "collection",
+    # Literal argument value
+    "command_and_control",
+    # Literal argument value
+    "exfiltration",
+    # Literal argument value
+    "impact",
+]
+
+
+# Define class CampaignTest
+class CampaignTest(Base):
+    """A test within a campaign, with ordering and dependency information.
+
+    ``depends_on`` creates a self-referential chain (A -> B -> C).
+    Circular dependencies are validated at the service layer.
+    """
+    # Assign __tablename__ = "campaign_tests"
+    __tablename__ = "campaign_tests"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign campaign_id = Column(
+    campaign_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("campaigns.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign test_id = Column(
+    test_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("tests.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign order_index = Column(Integer, nullable=False, default=0)
+    order_index = Column(Integer, nullable=False, default=0)
+    # Assign depends_on = Column(
+    depends_on = Column(
+        UUID(as_uuid=True),
+        ForeignKey("campaign_tests.id", ondelete="SET NULL"),
+        # Keyword argument: nullable
+        nullable=True,
+    )
+    # Assign phase = Column(String, nullable=True)   # kill chain phase
+    phase = Column(String, nullable=True)   # kill chain phase
+
+    # Relationships
+    campaign = relationship("Campaign", back_populates="campaign_tests")
+    # Assign test = relationship("Test")
+    test = relationship("Test")
+    # Assign dependency = relationship("CampaignTest", remote_side="CampaignTest.id")
+    dependency = relationship("CampaignTest", remote_side="CampaignTest.id")
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_campaign_tests_campaign', 'campaign_id'),
+        Index('ix_campaign_tests_test', 'test_id'),
+    )

backend/app/models/compliance.py

@@ -0,0 +1,148 @@
+"""Compliance models — frameworks, controls, and technique mappings.
+
+Maps compliance frameworks (NIST 800-53, DORA, NIS2, ISO 27001) to
+MITRE ATT&CK techniques, enabling compliance gap analysis.
+"""
+
+# Import uuid
+import uuid
+
+# Import  from sqlalchemy
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+
+# Import UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import UUID
+
+# Import relationship from sqlalchemy.orm
+from sqlalchemy.orm import relationship
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class ComplianceFramework
+class ComplianceFramework(Base):
+    """A compliance framework (e.g. NIST 800-53, ISO 27001)."""
+    # Assign __tablename__ = "compliance_frameworks"
+    __tablename__ = "compliance_frameworks"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign name = Column(String, unique=True, nullable=False)
+    name = Column(String, unique=True, nullable=False)
+    # Assign version = Column(String, nullable=True)
+    version = Column(String, nullable=True)
+    # Assign description = Column(Text, nullable=True)
+    description = Column(Text, nullable=True)
+    # Assign url = Column(String, nullable=True)
+    url = Column(String, nullable=True)
+    # Assign is_active = Column(Boolean, default=True)
+    is_active = Column(Boolean, default=True)
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Relationships
+    controls = relationship(
+        # Literal argument value
+        "ComplianceControl",
+        # Keyword argument: back_populates
+        back_populates="framework",
+        # Keyword argument: cascade
+        cascade="all, delete-orphan",
+    )
+
+
+# Define class ComplianceControl
+class ComplianceControl(Base):
+    """A control within a compliance framework (e.g. AC-2, PR.AC-1)."""
+    # Assign __tablename__ = "compliance_controls"
+    __tablename__ = "compliance_controls"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign framework_id = Column(
+    framework_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("compliance_frameworks.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign control_id = Column(String, nullable=False)  # e.g. "AC-2"
+    control_id = Column(String, nullable=False)  # e.g. "AC-2"
+    # Assign title = Column(String, nullable=False)
+    title = Column(String, nullable=False)
+    # Assign description = Column(Text, nullable=True)
+    description = Column(Text, nullable=True)
+    # Assign category = Column(String, nullable=True)
+    category = Column(String, nullable=True)
+
+    # Relationships
+    framework = relationship("ComplianceFramework", back_populates="controls")
+    # Assign technique_mappings = relationship(
+    technique_mappings = relationship(
+        # Literal argument value
+        "ComplianceControlMapping",
+        # Keyword argument: back_populates
+        back_populates="compliance_control",
+        # Keyword argument: cascade
+        cascade="all, delete-orphan",
+    )
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_compliance_controls_framework', 'framework_id'),
+    )
+
+
+# Define class ComplianceControlMapping
+class ComplianceControlMapping(Base):
+    """Maps a compliance control to a MITRE ATT&CK technique."""
+    # Assign __tablename__ = "compliance_control_mappings"
+    __tablename__ = "compliance_control_mappings"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign compliance_control_id = Column(
+    compliance_control_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("compliance_controls.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign technique_id = Column(
+    technique_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("techniques.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+
+    # Relationships
+    compliance_control = relationship(
+        # Literal argument value
+        "ComplianceControl", back_populates="technique_mappings"
+    )
+    # Assign technique = relationship("Technique")
+    technique = relationship("Technique")
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_compliance_mappings_control', 'compliance_control_id'),
+        Index('ix_compliance_mappings_technique', 'technique_id'),
+        UniqueConstraint(
+            # Literal argument value
+            'compliance_control_id', 'technique_id',
+            # Keyword argument: name
+            name='uq_control_technique',
+        ),
+    )

backend/app/models/coverage_snapshot.py

@@ -0,0 +1,130 @@
+"""Coverage snapshot models — periodic snapshots of coverage state.
+
+CoverageSnapshot stores aggregate metrics at a point in time.
+SnapshotTechniqueState stores per-technique state (normalized, one row
+per technique per snapshot) to avoid bloated JSONB fields.
+"""
+
+# Import uuid
+import uuid
+
+# Import  from sqlalchemy
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    func,
+)
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import relationship from sqlalchemy.orm
+from sqlalchemy.orm import relationship
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class CoverageSnapshot
+class CoverageSnapshot(Base):
+    """A point-in-time snapshot of the organisation's overall coverage."""
+
+    # Assign __tablename__ = "coverage_snapshots"
+    __tablename__ = "coverage_snapshots"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign name = Column(String, nullable=True)  # e.g. "Pre-remediación Q1"
+    name = Column(String, nullable=True)  # e.g. "Pre-remediación Q1"
+    # Assign organization_score = Column(Float, nullable=False)
+    organization_score = Column(Float, nullable=False)
+    # Assign total_techniques = Column(Integer, nullable=False)
+    total_techniques = Column(Integer, nullable=False)
+    # Assign validated_count = Column(Integer, nullable=False)
+    validated_count = Column(Integer, nullable=False)
+    # Assign partial_count = Column(Integer, nullable=False)
+    partial_count = Column(Integer, nullable=False)
+    # Assign not_covered_count = Column(Integer, nullable=False)
+    not_covered_count = Column(Integer, nullable=False)
+    # Assign in_progress_count = Column(Integer, nullable=False)
+    in_progress_count = Column(Integer, nullable=False)
+    # Assign not_evaluated_count = Column(Integer, nullable=False)
+    not_evaluated_count = Column(Integer, nullable=False)
+    # Assign coverage_percentage = Column(Float, nullable=False, default=0.0)
+    coverage_percentage = Column(Float, nullable=False, default=0.0)
+    # Assign by_tactic = Column(JSONB, nullable=False, default=dict)
+    by_tactic = Column(JSONB, nullable=False, default=dict)
+    # Assign by_status = Column(JSONB, nullable=False, default=dict)
+    by_status = Column(JSONB, nullable=False, default=dict)
+    # Assign stale_count = Column(Integer, nullable=False, default=0)
+    stale_count = Column(Integer, nullable=False, default=0)
+    # Assign never_tested_count = Column(Integer, nullable=False, default=0)
+    never_tested_count = Column(Integer, nullable=False, default=0)
+    # Assign created_by = Column(
+    created_by = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        # Keyword argument: nullable
+        nullable=True,
+    )
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Relationships
+    creator = relationship("User", foreign_keys=[created_by])
+    # Assign technique_states = relationship(
+    technique_states = relationship(
+        # Literal argument value
+        "SnapshotTechniqueState",
+        # Keyword argument: back_populates
+        back_populates="snapshot",
+        # Keyword argument: cascade
+        cascade="all, delete-orphan",
+    )
+
+
+# Define class SnapshotTechniqueState
+class SnapshotTechniqueState(Base):
+    """Per-technique state within a snapshot (normalised storage)."""
+
+    # Assign __tablename__ = "snapshot_technique_states"
+    __tablename__ = "snapshot_technique_states"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign snapshot_id = Column(
+    snapshot_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("coverage_snapshots.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign technique_id = Column(
+    technique_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("techniques.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign mitre_id = Column(String, nullable=False)  # denormalised for fast queries
+    mitre_id = Column(String, nullable=False)  # denormalised for fast queries
+    # Assign status = Column(String, nullable=False)
+    status = Column(String, nullable=False)
+    # Assign score = Column(Float, nullable=True)
+    score = Column(Float, nullable=True)
+
+    # Relationships
+    snapshot = relationship("CoverageSnapshot", back_populates="technique_states")
+    # Assign technique = relationship("Technique")
+    technique = relationship("Technique")
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index("ix_snapshot_technique_states_snapshot", "snapshot_id"),
+        Index("ix_snapshot_technique_states_technique", "technique_id"),
+    )

backend/app/models/data_source.py

@@ -0,0 +1,57 @@
+"""DataSource model — registry of external data sources for import."""
+
+# Import uuid
+import uuid
+
+# Import Boolean, Column, DateTime, Index, String, Text,... from sqlalchemy
+from sqlalchemy import Boolean, Column, DateTime, Index, String, Text, func
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class DataSource
+class DataSource(Base):
+    """Unified registry of all external data sources.
+
+    Covers attack procedures, detection rules, threat intel, and defensive techniques.
+    Each source can be independently enabled/disabled and tracks its own synchronisation state.
+    """
+    # Assign __tablename__ = "data_sources"
+    __tablename__ = "data_sources"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign name = Column(String, unique=True, nullable=False)            # e.g. "atom...
+    name = Column(String, unique=True, nullable=False)            # e.g. "atomic_red_team"
+    # Assign display_name = Column(String, nullable=False)                  # e.g. "Atomic Red ...
+    display_name = Column(String, nullable=False)                  # e.g. "Atomic Red Team"
+    # Values: attack_procedure / detection_rule / threat_intel / defensive_technique
+    type = Column(String, nullable=False)
+    # Assign url = Column(String, nullable=True)                            # URL base...
+    url = Column(String, nullable=True)                            # URL base of repo/API
+    # Assign description = Column(Text, nullable=True)
+    description = Column(Text, nullable=True)
+    # Assign is_enabled = Column(Boolean, default=True)
+    is_enabled = Column(Boolean, default=True)
+    # Assign last_sync_at = Column(DateTime, nullable=True)
+    last_sync_at = Column(DateTime, nullable=True)
+    # Assign last_sync_status = Column(String, nullable=True)               # success / error / in_...
+    last_sync_status = Column(String, nullable=True)               # success / error / in_progress
+    # Assign last_sync_stats = Column(JSONB, nullable=True)                 # {"imported": X, "upd...
+    last_sync_stats = Column(JSONB, nullable=True)                 # {"imported": X, "updated": Y, ...}
+    # Assign sync_frequency = Column(String, nullable=True)                 # daily / weekly / mo...
+    sync_frequency = Column(String, nullable=True)                 # daily / weekly / monthly / manual
+    # Assign config = Column(JSONB, nullable=True)                          # source-spec...
+    config = Column(JSONB, nullable=True)                          # source-specific configuration
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_data_sources_type', 'type'),
+        Index('ix_data_sources_is_enabled', 'is_enabled'),
+    )

backend/app/models/defensive_technique.py

@@ -0,0 +1,111 @@
+"""DefensiveTechnique and DefensiveTechniqueMapping models.
+
+Stores MITRE D3FEND defensive techniques and their mappings to
+ATT&CK techniques, enabling recommended countermeasure lookups.
+"""
+
+# Import uuid
+import uuid
+
+# Import  from sqlalchemy
+from sqlalchemy import (
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+
+# Import UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import UUID
+
+# Import relationship from sqlalchemy.orm
+from sqlalchemy.orm import relationship
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class DefensiveTechnique
+class DefensiveTechnique(Base):
+    """MITRE D3FEND defensive technique.
+
+    Represents a countermeasure from the D3FEND framework that can be
+    mapped to one or more ATT&CK techniques via DefensiveTechniqueMapping.
+    """
+    # Assign __tablename__ = "defensive_techniques"
+    __tablename__ = "defensive_techniques"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign d3fend_id = Column(String, unique=True, nullable=False)          # e.g. "D3-AL"
+    d3fend_id = Column(String, unique=True, nullable=False)          # e.g. "D3-AL"
+    # Assign name = Column(String, nullable=False)
+    name = Column(String, nullable=False)
+    # Assign description = Column(Text, nullable=True)
+    description = Column(Text, nullable=True)
+    # Assign tactic = Column(String, nullable=True)                            # Detect, ...
+    tactic = Column(String, nullable=True)                            # Detect, Isolate, Deceive, Evict, etc.
+    # Assign d3fend_url = Column(String, nullable=True)
+    d3fend_url = Column(String, nullable=True)
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Relationships
+    attack_mappings = relationship(
+        # Literal argument value
+        "DefensiveTechniqueMapping",
+        # Keyword argument: back_populates
+        back_populates="defensive_technique",
+        # Keyword argument: cascade
+        cascade="all, delete-orphan",
+    )
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_defensive_techniques_tactic', 'tactic'),
+    )
+
+
+# Define class DefensiveTechniqueMapping
+class DefensiveTechniqueMapping(Base):
+    """Association between a MITRE ATT&CK technique and a D3FEND defensive technique."""
+    # Assign __tablename__ = "defensive_technique_mappings"
+    __tablename__ = "defensive_technique_mappings"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign attack_technique_id = Column(
+    attack_technique_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("techniques.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign defensive_technique_id = Column(
+    defensive_technique_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("defensive_techniques.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+
+    # Relationships
+    attack_technique = relationship("Technique")
+    # Assign defensive_technique = relationship("DefensiveTechnique", back_populates="attack_mappings")
+    defensive_technique = relationship("DefensiveTechnique", back_populates="attack_mappings")
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_dtm_attack_technique', 'attack_technique_id'),
+        Index('ix_dtm_defensive_technique', 'defensive_technique_id'),
+        UniqueConstraint(
+            # Literal argument value
+            'attack_technique_id', 'defensive_technique_id',
+            # Keyword argument: name
+            name='uq_attack_defensive_technique',
+        ),
+    )

backend/app/models/detection_rule.py

@@ -0,0 +1,63 @@
+"""DetectionRule model — detection rules from multiple sources."""
+
+# Import uuid
+import uuid
+
+# Import Boolean, Column, DateTime, Index, String, Text,... from sqlalchemy
+from sqlalchemy import Boolean, Column, DateTime, Index, String, Text, func
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class DetectionRule
+class DetectionRule(Base):
+    """Detection rule from an external source (Sigma, Elastic, Splunk, custom).
+
+    Each rule is mapped to one MITRE ATT&CK technique via
+    ``mitre_technique_id`` and stores the complete rule content in
+    ``rule_content``.
+    """
+    # Assign __tablename__ = "detection_rules"
+    __tablename__ = "detection_rules"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign mitre_technique_id = Column(String, nullable=False)            # e.g. "T1059.001"
+    mitre_technique_id = Column(String, nullable=False)            # e.g. "T1059.001"
+    # Assign title = Column(String, nullable=False)
+    title = Column(String, nullable=False)
+    # Assign description = Column(Text, nullable=True)
+    description = Column(Text, nullable=True)
+    # Assign source = Column(String, nullable=False)                        # sigma / ela...
+    source = Column(String, nullable=False)                        # sigma / elastic / splunk / custom
+    # Assign source_id = Column(String, nullable=True)                      # ID in the sour...
+    source_id = Column(String, nullable=True)                      # ID in the source repo (for dedup)
+    # Assign source_url = Column(String, nullable=True)
+    source_url = Column(String, nullable=True)
+    # Assign rule_content = Column(Text, nullable=False)                    # YAML / KQL / SPL ...
+    rule_content = Column(Text, nullable=False)                    # YAML / KQL / SPL content
+    # Assign rule_format = Column(String, nullable=False)                   # sigma_yaml / kql...
+    rule_format = Column(String, nullable=False)                   # sigma_yaml / kql / spl / custom
+    # Assign severity = Column(String, nullable=True)                       # informational...
+    severity = Column(String, nullable=True)                       # informational / low / medium / high / critical
+    # Assign platforms = Column(JSONB, nullable=True, default=[])
+    platforms = Column(JSONB, nullable=True, default=[])
+    # Assign log_sources = Column(JSONB, nullable=True)                     # e.g. {"product":...
+    log_sources = Column(JSONB, nullable=True)                     # e.g. {"product": "windows", "service": "sysmon"}
+    # Assign false_positive_rate = Column(String, nullable=True)            # low / medium / high
+    false_positive_rate = Column(String, nullable=True)            # low / medium / high
+    # Assign is_active = Column(Boolean, default=True)
+    is_active = Column(Boolean, default=True)
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_detection_rules_mitre_technique_id', 'mitre_technique_id'),
+        Index('ix_detection_rules_source', 'source'),
+        Index('ix_detection_rules_severity', 'severity'),
+    )

backend/app/models/enums.py

@@ -1,23 +1,15 @@
-import enum
+"""ORM-level re-exports of the canonical domain enums.
 
+The single source of truth lives in ``app.domain.enums``.  This module
+re-exports every enum so that existing model and router code keeps
+working with ``from app.models.enums import ...``.
+"""
 
-class TechniqueStatus(str, enum.Enum):
-    not_evaluated = "not_evaluated"
-    in_progress = "in_progress"
-    validated = "validated"
-    partial = "partial"
-    not_covered = "not_covered"
-    review_required = "review_required"
-
-
-class TestState(str, enum.Enum):
-    draft = "draft"
-    in_review = "in_review"
-    validated = "validated"
-    rejected = "rejected"
-
-
-class TestResult(str, enum.Enum):
-    detected = "detected"
-    not_detected = "not_detected"
-    partially_detected = "partially_detected"
+# Import # noqa: F401 from app.domain.enums
+from app.domain.enums import (  # noqa: F401
+    DataClassification,
+    TeamSide,
+    TechniqueStatus,
+    TestResult,
+    TestState,
+)

backend/app/models/evidence.py

@@ -1,30 +1,59 @@
-import uuid
-from datetime import datetime
+"""SQLAlchemy model for the evidence table."""
 
-from sqlalchemy import Column, String, DateTime, ForeignKey
+# Import uuid
+import uuid
+
+# Import Column, DateTime, Enum, ForeignKey, String, Tex... from sqlalchemy
+from sqlalchemy import Column, DateTime, Enum, ForeignKey, String, Text, func
+
+# Import UUID from sqlalchemy.dialects.postgresql
 from sqlalchemy.dialects.postgresql import UUID
+
+# Import relationship from sqlalchemy.orm
 from sqlalchemy.orm import relationship
 
+# Import Base from app.database
 from app.database import Base
 
+# Import TeamSide from app.models.enums
+from app.models.enums import TeamSide
 
+
+# Define class Evidence
 class Evidence(Base):
-    """
-    Evidence model for storing file metadata associated with tests.
-    
+    """Evidence model for storing file metadata associated with tests.
+
     Files are stored in MinIO, and this model tracks the file location,
     integrity hash, and upload metadata.
+
+    The ``team`` field distinguishes whether this evidence was uploaded by
+    Red Team (attack evidence) or Blue Team (detection evidence).
     """
+    # Assign __tablename__ = "evidences"
     __tablename__ = "evidences"
 
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign test_id = Column(UUID(as_uuid=True), ForeignKey("tests.id"), nullable=False)
     test_id = Column(UUID(as_uuid=True), ForeignKey("tests.id"), nullable=False)
+    # Assign file_name = Column(String, nullable=False)
     file_name = Column(String, nullable=False)
+    # Assign file_path = Column(String, nullable=False)  # Path in MinIO
     file_path = Column(String, nullable=False)  # Path in MinIO
+    # Assign sha256_hash = Column(String, nullable=False)
     sha256_hash = Column(String, nullable=False)
+    # Assign uploaded_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
     uploaded_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
-    uploaded_at = Column(DateTime, default=datetime.utcnow)
+    # Assign uploaded_at = Column(DateTime(timezone=True), server_default=func.now())
+    uploaded_at = Column(DateTime(timezone=True), server_default=func.now())
+    # Assign team = Column(Enum(TeamSide, name="teamside"), nullable=False, default=Tea...
+    team = Column(Enum(TeamSide, name="teamside"), nullable=False, default=TeamSide.red)
+    # Assign notes = Column(Text, nullable=True)
+    notes = Column(Text, nullable=True)
+    # Assign data_classification = Column(String(20), nullable=False, server_default="internal")
+    data_classification = Column(String(20), nullable=False, server_default="internal")
 
     # Relationships
     test = relationship("Test", back_populates="evidences")
+    # Assign uploader = relationship("User", foreign_keys=[uploaded_by])
     uploader = relationship("User", foreign_keys=[uploaded_by])

backend/app/models/intel.py

@@ -1,28 +1,44 @@
-import uuid
-from datetime import datetime
+"""SQLAlchemy model for the intel_items table."""
 
-from sqlalchemy import Column, String, Boolean, DateTime, ForeignKey
+# Import uuid
+import uuid
+
+# Import Boolean, Column, DateTime, ForeignKey, String, ... from sqlalchemy
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, String, func
+
+# Import UUID from sqlalchemy.dialects.postgresql
 from sqlalchemy.dialects.postgresql import UUID
+
+# Import relationship from sqlalchemy.orm
 from sqlalchemy.orm import relationship
 
+# Import Base from app.database
 from app.database import Base
 
 
+# Define class IntelItem
 class IntelItem(Base):
-    """
-    Intelligence item model for tracking threat intelligence related to techniques.
-    
+    """Intelligence item model for tracking threat intelligence related to techniques.
+
     Stores URLs and metadata from automated intel scans that may indicate
     new attack variations or detection bypasses for specific techniques.
     """
+    # Assign __tablename__ = "intel_items"
     __tablename__ = "intel_items"
 
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign technique_id = Column(UUID(as_uuid=True), ForeignKey("techniques.id"), nullable=True)
     technique_id = Column(UUID(as_uuid=True), ForeignKey("techniques.id"), nullable=True)
+    # Assign url = Column(String, nullable=False)
     url = Column(String, nullable=False)
+    # Assign title = Column(String, nullable=True)
     title = Column(String, nullable=True)
+    # Assign source = Column(String, nullable=True)
     source = Column(String, nullable=True)
-    detected_at = Column(DateTime, default=datetime.utcnow)
+    # Assign detected_at = Column(DateTime(timezone=True), server_default=func.now())
+    detected_at = Column(DateTime(timezone=True), server_default=func.now())
+    # Assign reviewed = Column(Boolean, default=False)
     reviewed = Column(Boolean, default=False)
 
     # Relationships

backend/app/models/jira_link.py

@@ -0,0 +1,101 @@
+"""Jira integration models — link Aegis entities to Jira issues."""
+
+# Import enum
+import enum
+
+# Import uuid
+import uuid
+
+# Import Column, DateTime, ForeignKey, Index, String, func from sqlalchemy
+from sqlalchemy import Column, DateTime, ForeignKey, Index, String, func
+
+# Import Enum as SQLEnum from sqlalchemy
+from sqlalchemy import Enum as SQLEnum
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import relationship from sqlalchemy.orm
+from sqlalchemy.orm import relationship
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class JiraLinkEntityType
+class JiraLinkEntityType(str, enum.Enum):
+    """Aegis entity types that can be linked to a Jira issue."""
+
+    # Assign test = "test"
+    test = "test"
+    # Assign technique = "technique"
+    technique = "technique"
+    # Assign campaign = "campaign"
+    campaign = "campaign"
+    # Assign evidence = "evidence"
+    evidence = "evidence"
+
+
+# Define class JiraSyncDirection
+class JiraSyncDirection(str, enum.Enum):
+    """Direction of synchronisation between Aegis and Jira."""
+
+    # Assign aegis_to_jira = "aegis_to_jira"
+    aegis_to_jira = "aegis_to_jira"
+    # Assign jira_to_aegis = "jira_to_aegis"
+    jira_to_aegis = "jira_to_aegis"
+    # Assign bidirectional = "bidirectional"
+    bidirectional = "bidirectional"
+
+
+# Define class JiraLink
+class JiraLink(Base):
+    """Associates an Aegis entity with a Jira issue for bidirectional sync."""
+
+    # Assign __tablename__ = "jira_links"
+    __tablename__ = "jira_links"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign entity_type = Column(SQLEnum(JiraLinkEntityType), nullable=False)
+    entity_type = Column(SQLEnum(JiraLinkEntityType), nullable=False)
+    # Assign entity_id = Column(UUID(as_uuid=True), nullable=False)
+    entity_id = Column(UUID(as_uuid=True), nullable=False)
+    # Assign jira_issue_key = Column(String(50), nullable=False)
+    jira_issue_key = Column(String(50), nullable=False)
+    # Assign jira_issue_id = Column(String(50))
+    jira_issue_id = Column(String(50))
+    # Assign jira_project_key = Column(String(20))
+    jira_project_key = Column(String(20))
+    # Assign jira_status = Column(String(100))
+    jira_status = Column(String(100))
+    # Assign jira_priority = Column(String(50))
+    jira_priority = Column(String(50))
+    # Assign jira_assignee = Column(String(255))
+    jira_assignee = Column(String(255))
+    # Assign jira_story_points = Column(String(10))
+    jira_story_points = Column(String(10))
+    # Assign sync_direction = Column(
+    sync_direction = Column(
+        SQLEnum(JiraSyncDirection), default=JiraSyncDirection.bidirectional
+    )
+    # Assign last_synced_at = Column(DateTime)
+    last_synced_at = Column(DateTime)
+    # Assign sync_metadata = Column(JSONB, default={})
+    sync_metadata = Column(JSONB, default={})
+    # Assign created_by = Column(UUID(as_uuid=True), ForeignKey("users.id"))
+    created_by = Column(UUID(as_uuid=True), ForeignKey("users.id"))
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    # Assign updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate...
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    # Assign creator = relationship("User", foreign_keys=[created_by])
+    creator = relationship("User", foreign_keys=[created_by])
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index("ix_jira_links_entity_id", "entity_id"),
+        Index("ix_jira_links_issue_key", "jira_issue_key"),
+        Index("ix_jira_links_entity_type_entity_id", "entity_type", "entity_id"),
+    )

backend/app/models/notification.py

@@ -0,0 +1,56 @@
+"""Notification model — in-app notifications for user actions."""
+
+# Import uuid
+import uuid
+
+# Import Boolean, Column, DateTime, ForeignKey, Index, S... from sqlalchemy
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Index, String, Text, func
+
+# Import UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import UUID
+
+# Import relationship from sqlalchemy.orm
+from sqlalchemy.orm import relationship
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class Notification
+class Notification(Base):
+    """In-app notification for alerting users when they need to act.
+
+    Types include: test_assigned, validation_needed, test_rejected,
+    test_validated, test_state_changed, etc.
+    """
+    # Assign __tablename__ = "notifications"
+    __tablename__ = "notifications"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign user_id = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
+    user_id = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
+    # Assign type = Column(String, nullable=False)
+    type = Column(String, nullable=False)
+    # Assign title = Column(String, nullable=False)
+    title = Column(String, nullable=False)
+    # Assign message = Column(Text, nullable=True)
+    message = Column(Text, nullable=True)
+    # Assign entity_type = Column(String, nullable=True)
+    entity_type = Column(String, nullable=True)
+    # Assign entity_id = Column(UUID(as_uuid=True), nullable=True)
+    entity_id = Column(UUID(as_uuid=True), nullable=True)
+    # Assign read = Column(Boolean, default=False)
+    read = Column(Boolean, default=False)
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Relationships
+    user = relationship("User")
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index("ix_notifications_user_id", "user_id"),
+        Index("ix_notifications_read", "read"),
+        Index("ix_notifications_created_at", "created_at"),
+    )

backend/app/models/osint_item.py

@@ -0,0 +1,59 @@
+"""OSINT enrichment items — CVEs, blogs, PoCs, and advisories linked to techniques."""
+
+# Import uuid
+import uuid
+
+# Import Boolean, Column, DateTime, ForeignKey, String, ... from sqlalchemy
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, String, Text, func
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import relationship from sqlalchemy.orm
+from sqlalchemy.orm import relationship
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class OsintItem
+class OsintItem(Base):
+    """Represents an OSINT data point (CVE, blog, PoC, advisory) associated with a MITRE ATT&CK technique.
+
+    Used by the enrichment pipeline to surface relevant threat intelligence
+    for each technique, flagging those that need review.
+    """
+
+    # Assign __tablename__ = "osint_items"
+    __tablename__ = "osint_items"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign technique_id = Column(
+    technique_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("techniques.id"),
+        # Keyword argument: nullable
+        nullable=False,
+        # Keyword argument: index
+        index=True,
+    )
+    # Assign source_type = Column(String(50), nullable=False)  # "cve", "blog", "poc", "advisory"
+    source_type = Column(String(50), nullable=False)  # "cve", "blog", "poc", "advisory"
+    # Assign source_url = Column(Text, nullable=False)
+    source_url = Column(Text, nullable=False)
+    # Assign title = Column(String(500), nullable=False)
+    title = Column(String(500), nullable=False)
+    # Assign description = Column(Text, nullable=True)
+    description = Column(Text, nullable=True)
+    # Assign severity = Column(String(20), nullable=True)  # CRITICAL, HIGH, MEDIUM, LOW, U...
+    severity = Column(String(20), nullable=True)  # CRITICAL, HIGH, MEDIUM, LOW, UNKNOWN
+    # Assign discovered_at = Column(DateTime(timezone=True), server_default=func.now(), nullable...
+    discovered_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    # Assign reviewed = Column(Boolean, default=False)
+    reviewed = Column(Boolean, default=False)
+    # Assign metadata_ = Column("metadata", JSONB, default={})
+    metadata_ = Column("metadata", JSONB, default={})
+
+    # ── Relationships ─────────────────────────────────────────────────
+    technique = relationship("Technique", backref="osint_items")

backend/app/models/scoring_config.py

@@ -0,0 +1,43 @@
+"""ScoringConfig — single-row table for persisted scoring weights."""
+
+# Import uuid
+import uuid
+
+# Import Column, DateTime, Float, ForeignKey, func from sqlalchemy
+from sqlalchemy import Column, DateTime, Float, ForeignKey, func
+
+# Import UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import UUID
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class ScoringConfig
+class ScoringConfig(Base):
+    """Single-row table persisting the active scoring weight configuration."""
+
+    # Assign __tablename__ = "scoring_config"
+    __tablename__ = "scoring_config"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign weight_tests = Column(Float, nullable=False, default=40.0)
+    weight_tests = Column(Float, nullable=False, default=40.0)
+    # Assign weight_detection_rules = Column(Float, nullable=False, default=25.0)
+    weight_detection_rules = Column(Float, nullable=False, default=25.0)
+    # Assign weight_d3fend = Column(Float, nullable=False, default=15.0)
+    weight_d3fend = Column(Float, nullable=False, default=15.0)
+    # Assign weight_recency = Column(Float, nullable=False, default=10.0)
+    weight_recency = Column(Float, nullable=False, default=10.0)
+    # Assign weight_severity = Column(Float, nullable=False, default=10.0)
+    weight_severity = Column(Float, nullable=False, default=10.0)
+    # Assign updated_by = Column(
+    updated_by = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        # Keyword argument: nullable
+        nullable=True,
+    )
+    # Assign updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate...
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())

backend/app/models/technique.py

@@ -1,38 +1,63 @@
-import uuid
-from datetime import datetime
+"""SQLAlchemy model for the techniques table."""
 
-from sqlalchemy import Column, String, Text, Boolean, DateTime, Enum
-from sqlalchemy.dialects.postgresql import UUID, JSONB
+# Import uuid
+import uuid
+
+# Import Boolean, Column, DateTime, Enum, String, Text from sqlalchemy
+from sqlalchemy import Boolean, Column, DateTime, Enum, String, Text
+
+# Import JSONB, UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+# Import relationship from sqlalchemy.orm
 from sqlalchemy.orm import relationship
 
+# Import Base from app.database
 from app.database import Base
+
+# Import TechniqueStatus from app.models.enums
 from app.models.enums import TechniqueStatus
 
 
+# Define class Technique
 class Technique(Base):
-    """
-    MITRE ATT&CK Technique model.
-    
+    """MITRE ATT&CK Technique model.
+
     Represents an attack technique from the MITRE ATT&CK framework,
     including its coverage status and associated tests.
     """
+    # Assign __tablename__ = "techniques"
     __tablename__ = "techniques"
 
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign mitre_id = Column(String, unique=True, nullable=False)  # e.g., "T1059.001"
     mitre_id = Column(String, unique=True, nullable=False)  # e.g., "T1059.001"
+    # Assign name = Column(String, nullable=False)
     name = Column(String, nullable=False)
+    # Assign description = Column(Text, nullable=True)
     description = Column(Text, nullable=True)
+    # Assign tactic = Column(String, nullable=True)
     tactic = Column(String, nullable=True)
+    # Assign platforms = Column(JSONB, nullable=True, default=[])
     platforms = Column(JSONB, nullable=True, default=[])
+    # Assign mitre_version = Column(String, nullable=True)
     mitre_version = Column(String, nullable=True)
+    # Assign mitre_last_modified = Column(DateTime, nullable=True)
     mitre_last_modified = Column(DateTime, nullable=True)
+    # Assign is_subtechnique = Column(Boolean, default=False)
     is_subtechnique = Column(Boolean, default=False)
+    # Assign parent_mitre_id = Column(String, nullable=True)
     parent_mitre_id = Column(String, nullable=True)
+    # Assign status_global = Column(
     status_global = Column(
         Enum(TechniqueStatus, name="techniquestatus"),
+        # Keyword argument: default
         default=TechniqueStatus.not_evaluated
     )
+    # Assign review_required = Column(Boolean, default=False)
     review_required = Column(Boolean, default=False)
+    # Assign last_review_date = Column(DateTime, nullable=True)
     last_review_date = Column(DateTime, nullable=True)
 
     # Relationships

backend/app/models/test.py

@@ -1,40 +1,144 @@
-import uuid
-from datetime import datetime
+"""SQLAlchemy model for the tests table."""
 
-from sqlalchemy import Column, String, Text, DateTime, ForeignKey, Enum
+# Import uuid
+import uuid
+
+# Import  from sqlalchemy
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    func,
+)
+
+# Import UUID from sqlalchemy.dialects.postgresql
 from sqlalchemy.dialects.postgresql import UUID
+
+# Import relationship from sqlalchemy.orm
 from sqlalchemy.orm import relationship
 
+# Import Base from app.database
 from app.database import Base
-from app.models.enums import TestState, TestResult
+
+# Import TestResult, TestState from app.models.enums
+from app.models.enums import TestResult, TestState
 
 
+# Define class Test
 class Test(Base):
-    """
-    Test model representing a security test for a MITRE ATT&CK technique.
-    
+    """Test model representing a security test for a MITRE ATT&CK technique.
+
     Each test documents an attempt to validate coverage of a specific technique,
-    including the procedure, tools used, and outcome.
+    including the procedure, tools used, and outcome.  V2 introduces dual
+    validation: Red Lead and Blue Lead must each approve independently.
     """
+    # Assign __tablename__ = "tests"
     __tablename__ = "tests"
 
+    # ── Core fields ─────────────────────────────────────────────────
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign technique_id = Column(UUID(as_uuid=True), ForeignKey("techniques.id"), nullable=Fa...
     technique_id = Column(UUID(as_uuid=True), ForeignKey("techniques.id"), nullable=False)
+    # Assign name = Column(String, nullable=False)
     name = Column(String, nullable=False)
+    # Assign description = Column(Text, nullable=True)
     description = Column(Text, nullable=True)
+    # Assign platform = Column(String, nullable=True)
     platform = Column(String, nullable=True)
+    # Assign procedure_text = Column(Text, nullable=True)
     procedure_text = Column(Text, nullable=True)
+    # Assign tool_used = Column(String, nullable=True)
     tool_used = Column(String, nullable=True)
+    # Assign execution_date = Column(DateTime, nullable=True)
     execution_date = Column(DateTime, nullable=True)
+    # Assign created_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
     created_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+    # Assign result = Column(Enum(TestResult, name="testresult"), nullable=True)
     result = Column(Enum(TestResult, name="testresult"), nullable=True)
+    # Assign state = Column(Enum(TestState, name="teststate"), default=TestState.draft)
     state = Column(Enum(TestState, name="teststate"), default=TestState.draft)
-    validated_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
-    validated_at = Column(DateTime, nullable=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
 
-    # Relationships
+    # ── Red Team fields ─────────────────────────────────────────────
+    red_summary = Column(Text, nullable=True)
+    # Assign attack_success = Column(Boolean, nullable=True)
+    attack_success = Column(Boolean, nullable=True)
+    # Assign red_validated_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+    red_validated_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+    # Assign red_validated_at = Column(DateTime, nullable=True)
+    red_validated_at = Column(DateTime, nullable=True)
+    # Assign red_validation_status = Column(String, nullable=True)   # pending / approved / rejected
+    red_validation_status = Column(String, nullable=True)   # pending / approved / rejected
+    # Assign red_validation_notes = Column(Text, nullable=True)
+    red_validation_notes = Column(Text, nullable=True)
+
+    # ── Blue Team fields ────────────────────────────────────────────
+    blue_summary = Column(Text, nullable=True)
+    # Assign detection_result = Column(Enum(TestResult, name="testresult"), nullable=True)
+    detection_result = Column(Enum(TestResult, name="testresult"), nullable=True)
+    # Assign blue_validated_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+    blue_validated_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+    # Assign blue_validated_at = Column(DateTime, nullable=True)
+    blue_validated_at = Column(DateTime, nullable=True)
+    # Assign blue_validation_status = Column(String, nullable=True)  # pending / approved / rejected
+    blue_validation_status = Column(String, nullable=True)  # pending / approved / rejected
+    # Assign blue_validation_notes = Column(Text, nullable=True)
+    blue_validation_notes = Column(Text, nullable=True)
+
+    # ── Phase timing fields (for automatic Tempo worklogs) ──────────
+    red_started_at = Column(DateTime, nullable=True)
+    # Assign blue_started_at = Column(DateTime, nullable=True)
+    blue_started_at = Column(DateTime, nullable=True)
+    # Assign paused_at = Column(DateTime, nullable=True)
+    paused_at = Column(DateTime, nullable=True)
+    # Assign red_paused_seconds = Column(Integer, default=0)
+    red_paused_seconds = Column(Integer, default=0)
+    # Assign blue_paused_seconds = Column(Integer, default=0)
+    blue_paused_seconds = Column(Integer, default=0)
+
+    # ── Remediation fields ───────────────────────────────────────────
+    remediation_steps = Column(Text, nullable=True)
+    # Assign remediation_status = Column(String, nullable=True)  # pending / in_progress / completed ...
+    remediation_status = Column(String, nullable=True)  # pending / in_progress / completed / not_applicable
+    # Assign remediation_assignee = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+    remediation_assignee = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
+
+    # ── Re-test fields ────────────────────────────────────────────
+    retest_of = Column(UUID(as_uuid=True), ForeignKey("tests.id"), nullable=True)
+    # Assign retest_count = Column(Integer, default=0)
+    retest_count = Column(Integer, default=0)
+    # Assign data_classification = Column(String(20), nullable=False, server_default="internal")
+    data_classification = Column(String(20), nullable=False, server_default="internal")
+
+    # ── Relationships ───────────────────────────────────────────────
     technique = relationship("Technique", back_populates="tests")
+    # Assign evidences = relationship("Evidence", back_populates="test")
     evidences = relationship("Evidence", back_populates="test")
+    # Assign creator = relationship("User", foreign_keys=[created_by])
     creator = relationship("User", foreign_keys=[created_by])
-    validator = relationship("User", foreign_keys=[validated_by])
+    # Assign red_validator = relationship("User", foreign_keys=[red_validated_by])
+    red_validator = relationship("User", foreign_keys=[red_validated_by])
+    # Assign blue_validator = relationship("User", foreign_keys=[blue_validated_by])
+    blue_validator = relationship("User", foreign_keys=[blue_validated_by])
+    # Assign remediation_user = relationship("User", foreign_keys=[remediation_assignee])
+    remediation_user = relationship("User", foreign_keys=[remediation_assignee])
+    # Assign original_test = relationship("Test", remote_side="Test.id", foreign_keys=[retest_of])
+    original_test = relationship("Test", remote_side="Test.id", foreign_keys=[retest_of])
+    # Assign retests = relationship("Test", foreign_keys=[retest_of], back_populates="orig...
+    retests = relationship("Test", foreign_keys=[retest_of], back_populates="original_test")
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index("ix_tests_technique_id", "technique_id"),
+        Index("ix_tests_state", "state"),
+        Index("ix_tests_created_at", "created_at"),
+        Index("ix_tests_technique_state", "technique_id", "state"),
+        Index("ix_tests_state_created_at", "state", "created_at"),
+    )

backend/app/models/test_detection_result.py

@@ -0,0 +1,84 @@
+"""TestDetectionResult — tracks which detection rules triggered during a test.
+
+When the Blue Team evaluates a test, they mark each associated detection
+rule as triggered / not triggered / not applicable, along with notes.
+"""
+
+# Import uuid
+import uuid
+
+# Import  from sqlalchemy
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Text,
+    UniqueConstraint,
+)
+
+# Import UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import UUID
+
+# Import relationship from sqlalchemy.orm
+from sqlalchemy.orm import relationship
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class TestDetectionResult
+class TestDetectionResult(Base):
+    """Per-test, per-rule evaluation result.
+
+    - ``triggered`` = True: rule detected the attack
+    - ``triggered`` = False: rule did NOT detect the attack
+    - ``triggered`` = None: not yet evaluated
+    """
+    # Assign __tablename__ = "test_detection_results"
+    __tablename__ = "test_detection_results"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign test_id = Column(
+    test_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("tests.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign detection_rule_id = Column(
+    detection_rule_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("detection_rules.id", ondelete="CASCADE"),
+        # Keyword argument: nullable
+        nullable=False,
+    )
+    # Assign triggered = Column(Boolean, nullable=True)       # None = not evaluated
+    triggered = Column(Boolean, nullable=True)       # None = not evaluated
+    # Assign notes = Column(Text, nullable=True)
+    notes = Column(Text, nullable=True)
+    # Assign evaluated_by = Column(
+    evaluated_by = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        # Keyword argument: nullable
+        nullable=True,
+    )
+    # Assign evaluated_at = Column(DateTime, nullable=True)
+    evaluated_at = Column(DateTime, nullable=True)
+
+    # Relationships
+    test = relationship("Test")
+    # Assign detection_rule = relationship("DetectionRule")
+    detection_rule = relationship("DetectionRule")
+    # Assign evaluator = relationship("User", foreign_keys=[evaluated_by])
+    evaluator = relationship("User", foreign_keys=[evaluated_by])
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_tdr_test', 'test_id'),
+        Index('ix_tdr_rule', 'detection_rule_id'),
+        UniqueConstraint('test_id', 'detection_rule_id', name='uq_tdr_test_rule'),
+    )

backend/app/models/test_template.py

@@ -0,0 +1,67 @@
+"""TestTemplate model — predefined test catalog entries."""
+
+# Import uuid
+import uuid
+
+# Import Boolean, Column, DateTime, Index, String, Text,... from sqlalchemy
+from sqlalchemy import Boolean, Column, DateTime, Index, String, Text, func
+
+# Import UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy.dialects.postgresql import UUID
+
+# Import Base from app.database
+from app.database import Base
+
+
+# Define class TestTemplate
+class TestTemplate(Base):
+    """Predefined test template mapped to a MITRE ATT&CK technique.
+
+    Templates come from several sources:
+      - **atomic_red_team**: Atomic Red Team by Red Canary
+      - **mitre**: MITRE ATT&CK procedure examples
+      - **custom**: Manually created by teams
+
+    Users can instantiate a real Test from a template.
+    """
+    # Assign __tablename__ = "test_templates"
+    __tablename__ = "test_templates"
+
+    # Assign id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    # Assign mitre_technique_id = Column(String, nullable=False)          # e.g. "T1059.001"
+    mitre_technique_id = Column(String, nullable=False)          # e.g. "T1059.001"
+    # Assign name = Column(String, nullable=False)
+    name = Column(String, nullable=False)
+    # Assign description = Column(Text, nullable=True)
+    description = Column(Text, nullable=True)
+    # Assign source = Column(String, nullable=False)                      # atomic_red_te...
+    source = Column(String, nullable=False)                      # atomic_red_team / mitre / custom
+    # Assign source_url = Column(String, nullable=True)
+    source_url = Column(String, nullable=True)
+    # Assign attack_procedure = Column(Text, nullable=True)               # Suggested attack procedure
+    attack_procedure = Column(Text, nullable=True)               # Suggested attack procedure
+    # Assign expected_detection = Column(Text, nullable=True)             # What blue team should detect
+    expected_detection = Column(Text, nullable=True)             # What blue team should detect
+    # Assign platform = Column(String, nullable=True)                     # windows / linux...
+    platform = Column(String, nullable=True)                     # windows / linux / macos
+    # Assign tool_suggested = Column(String, nullable=True)
+    tool_suggested = Column(String, nullable=True)
+    # Assign severity = Column(String, nullable=True)                     # low / medium / ...
+    severity = Column(String, nullable=True)                     # low / medium / high / critical
+    # Assign atomic_test_id = Column(String, nullable=True)               # ID in Atomic Red Team...
+    atomic_test_id = Column(String, nullable=True)               # ID in Atomic Red Team repo
+    # Assign suggested_remediation = Column(Text, nullable=True)
+    suggested_remediation = Column(Text, nullable=True)
+    # Assign is_active = Column(Boolean, default=True)
+    is_active = Column(Boolean, default=True)
+    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    # Assign __table_args__ = (
+    __table_args__ = (
+        Index('ix_test_templates_mitre_technique_id', 'mitre_technique_id'),
+        Index('ix_test_templates_source', 'source'),
+        Index('ix_test_templates_platform', 'platform'),
+        Index('ix_test_templates_severity', 'severity'),
+    )