fix(security): remediate CVE-2026-42043 — upgrade axios ^1.14.0

- package.json: bump axios constraint from ^1.13.5 to ^1.14.0
- Dockerfile build stage: npm ci -> npm install so the semver range
  in package.json is honoured at build time (npm ci uses the lockfile
  exactly, bypassing the updated constraint)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.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)

.github/workflows/snyk.yml

@@ -1,71 +0,0 @@
-name: Snyk Security Scan
-
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main]
-  schedule:
-    - cron: '0 6 * * 1'   # Weekly on Monday 06:00 UTC
-
-jobs:
-  snyk-backend:
-    name: Python vulnerabilities (backend)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Install backend dependencies
-        run: pip install -r backend/requirements-lock.txt
-
-      - name: Snyk — scan Python packages
-        uses: snyk/actions/python@master
-        env:
-          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
-        with:
-          args: --file=backend/requirements-lock.txt --severity-threshold=high
-        continue-on-error: true   # report without blocking CI during initial cleanup
-
-  snyk-frontend:
-    name: npm vulnerabilities (frontend)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install frontend dependencies
-        run: npm ci
-        working-directory: frontend
-
-      - name: Snyk — scan npm packages
-        uses: snyk/actions/node@master
-        env:
-          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
-        with:
-          args: --file=frontend/package.json --severity-threshold=high
-        continue-on-error: true
-
-  snyk-docker-backend:
-    name: Docker image vulnerabilities (backend)
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Build backend image for scanning
-        run: docker build -t aegis-backend:scan backend/
-
-      - name: Snyk — scan Docker image
-        uses: snyk/actions/docker@master
-        env:
-          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
-        with:
-          image: aegis-backend:scan
-          args: --severity-threshold=high
-        continue-on-error: true

.gitignore

@@ -60,12 +60,3 @@ Thumbs.db
 
 # Local development
 *.local
-
-# Documentation drafts — never commit, delivered directly in chat
-docs/confluence/
-docs/drafts/
-
-# Editor / AI assistant working files — never commit
-.claude/
-.cursor/
-CLAUDE.md

backend/.bandit

@@ -1,2 +0,0 @@
-skips:
-  - B311

backend/Dockerfile

@@ -3,7 +3,7 @@ FROM python:3.11-slim
 WORKDIR /app
 
 # Install system dependencies
-RUN apt-get update && apt-get upgrade -y && apt-get install -y \
+RUN apt-get update && apt-get install -y \
     gcc \
     libpq-dev \
     curl \

backend/alembic/versions/b048_evaluation_imports.py

@@ -1,39 +0,0 @@
-"""Add evaluation_imports table.
-
-Revision ID: b048
-Revises: b047
-Create Date: 2026-06-05
-"""
-
-from alembic import op
-import sqlalchemy as sa
-from sqlalchemy.dialects.postgresql import UUID
-
-revision = "b048"
-down_revision = "b047"
-branch_labels = None
-depends_on = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "evaluation_imports",
-        sa.Column("id", UUID(as_uuid=True), primary_key=True),
-        sa.Column("adversary_name", sa.String, nullable=False),
-        sa.Column("adversary_display", sa.String, nullable=False),
-        sa.Column("eval_round", sa.Integer, nullable=False),
-        sa.Column("imported_at", sa.DateTime, nullable=False),
-        sa.Column("imported_by", UUID(as_uuid=True), sa.ForeignKey("users.id"), nullable=True),
-        sa.Column("tests_created", sa.Integer, default=0),
-        sa.Column("techniques_covered", sa.Integer, default=0),
-        sa.Column("status", sa.String, default="completed"),
-        sa.Column("notes", sa.Text, nullable=True),
-    )
-    op.create_index("ix_evaluation_imports_adversary", "evaluation_imports", ["adversary_name"])
-    op.create_index("ix_evaluation_imports_round", "evaluation_imports", ["eval_round"])
-
-
-def downgrade() -> None:
-    op.drop_index("ix_evaluation_imports_round", table_name="evaluation_imports")
-    op.drop_index("ix_evaluation_imports_adversary", table_name="evaluation_imports")
-    op.drop_table("evaluation_imports")

backend/app/__init__.py

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

backend/app/auth.py

@@ -1,32 +1,23 @@
-"""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 PyJWT.
+- Creating JWT access tokens using python-jose.
 - 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
 
-# Import jwt (PyJWT)
-import jwt
-
-# Import CryptContext from passlib.context
+from jose import jwt
 from passlib.context import CryptContext
 
-# Import settings from app.config
 from app.config import settings
 
-# Assign logger = logging.getLogger(__name__)
 logger = logging.getLogger(__name__)
 
 # ---------------------------------------------------------------------------
@@ -36,17 +27,13 @@ logger = logging.getLogger(__name__)
 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)
 
 
@@ -61,21 +48,14 @@ def create_access_token(data: dict) -> str:
     - ``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,
     )
-    # 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)
 
 
@@ -93,7 +73,6 @@ def create_access_token(data: dict) -> str:
 _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*.
 
@@ -101,38 +80,23 @@ def blacklist_token(jti: str, exp: float) -> None:
     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,21 +1,7 @@
-"""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
 
 # ---------------------------------------------------------------------------
@@ -24,11 +10,7 @@ from pydantic_settings import BaseSettings
 _is_production = os.environ.get("AEGIS_ENV", "").lower() == "production"
 
 
-# Define class Settings
 class Settings(BaseSettings):
-    """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 ──────────────────────────────────────────────────────
@@ -37,7 +19,6 @@ class Settings(BaseSettings):
     # 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"
     ACCESS_TOKEN_EXPIRE_MINUTES: int = 480  # 8 hours — /auth/refresh extends active sessions
 
@@ -45,7 +26,6 @@ class Settings(BaseSettings):
     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 ─────────────────────────────────────────────────────────
@@ -61,11 +41,8 @@ class Settings(BaseSettings):
     # the browser can reach MinIO directly.  Defaults to MINIO_ENDPOINT.
     MINIO_PUBLIC_ENDPOINT: str = ""
     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 ───────────────────────────────────────────────────
@@ -73,15 +50,10 @@ class Settings(BaseSettings):
 
     # ── 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 = ""
     JIRA_ISSUE_TYPE_TEST: str = "Task"       # tests (campaign or standalone)
     JIRA_ISSUE_TYPE_CAMPAIGN: str = "Epic"   # campaigns (under Initiative)
@@ -91,11 +63,8 @@ class Settings(BaseSettings):
 
     # ── 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"
     # Tempo API base URL — use https://api.eu.tempo.io/4 for EU workspaces.
     # Can also be set via system_configs key "tempo.base_url" at runtime.
@@ -103,16 +72,12 @@ class Settings(BaseSettings):
 
     # ── 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 = "/app/reports"
-    # Assign COMPANY_NAME = "Organization"
+    REPORT_OUTPUT_DIR: str = "/tmp/aegis_reports"
     COMPANY_NAME: str = "Organization"
-    # Assign COMPANY_LOGO_PATH = "app/templates/reports/assets/logo.png"
     COMPANY_LOGO_PATH: str = "app/templates/reports/assets/logo.png"
 
     # ── Email / SMTP ──────────────────────────────────────────────────
@@ -127,68 +92,43 @@ class Settings(BaseSettings):
 
     # ── 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,
     )
 
@@ -196,16 +136,12 @@ if settings.SECRET_KEY in _UNSAFE_SECRETS:
 # 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 "

backend/app/database.py

@@ -1,164 +1,68 @@
-"""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
 
-# Import Engine from sqlalchemy.engine
-from sqlalchemy.engine import 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
 
 
-# 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
+def _get_engine():
     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
+def _get_session_factory():
     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."""
+    """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)
+    def __call__(self, *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)
+    def __getattr__(self, 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)
+    def __getattr__(self, 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()
+def get_db():
     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

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

backend/app/dependencies/auth.py

@@ -1,4 +1,5 @@
-"""Authentication and RBAC dependencies for FastAPI.
+"""
+Authentication and RBAC dependencies for FastAPI.
 
 Provides:
 - ``get_current_user``: decodes JWT from HttpOnly cookie (preferred) or
@@ -8,34 +9,16 @@ Provides:
   (admins always pass).
 """
 
-# 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
-
-# Import jwt (PyJWT)
-import jwt
-
-# Import Session from sqlalchemy.orm
+from jose import JWTError, jwt
 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
 from app.models.api_key import KEY_PREFIX
 
@@ -54,11 +37,8 @@ _COOKIE_NAME = "aegis_token"
 
 
 async def get_current_user(
-    # 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, look up the user in *db*, and return it.
@@ -74,30 +54,20 @@ async def get_current_user(
     - 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
 
     # ── API Key path (Bearer token starts with "aegis_") ──────────────────
@@ -110,38 +80,25 @@ async def get_current_user(
 
     # ── JWT path ──────────────────────────────────────────────────────────
     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
         # 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
+    except JWTError:
         raise credentials_exception
 
-    # Assign user = db.query(User).filter(User.username == username).first()
     user = db.query(User).filter(User.username == username).first()
-    # 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
 
 
@@ -151,7 +108,6 @@ async def get_current_user(
 
 
 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.
@@ -159,16 +115,11 @@ async def require_password_changed(
     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
 
 
@@ -196,30 +147,22 @@ 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",
             )
         scope = "admin" if required_role == "admin" else "write"
         _check_api_key_scope(current_user, scope)
         return current_user
 
-    # Return role_checker
     return role_checker
 
 
-# Define function require_any_role
-def require_any_role(*roles: str) -> Callable[..., object]:
+def require_any_role(*roles: str):
     """Return a FastAPI dependency that enforces **any** of the given *roles*.
 
     Admins always pass.  Also enforces API key scopes: if the only accepted
@@ -231,25 +174,18 @@ def require_any_role(*roles: str) -> Callable[..., object]:
         @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",
             )
         scope = "admin" if set(roles) == {"admin"} else "write"
         _check_api_key_scope(current_user, scope)
         return current_user
 
-    # Return role_checker
     return role_checker
 
 

backend/app/dependencies/repositories.py

@@ -4,41 +4,27 @@ 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

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

backend/app/domain/entities/__init__.py

@@ -1,34 +1,18 @@
-"""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

@@ -3,59 +3,30 @@
 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
+from typing import Any
 
-# 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],
@@ -64,156 +35,69 @@ VALID_TRANSITIONS: dict[CampaignStatus, list[CampaignStatus]] = {
 }
 
 
-# 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 [])
+    def from_orm(cls, orm: Any) -> CampaignEntity:
+        """Build a CampaignEntity from a SQLAlchemy Campaign model."""
         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

@@ -3,161 +3,68 @@
 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

@@ -12,211 +12,105 @@ Usage::
     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
+from typing import Any
 
-# 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)
+        """Create a new technique, validating the MITRE ID format."""
         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
+    def from_orm(cls, model: Any) -> TechniqueEntity:
+        """Build a TechniqueEntity from a SQLAlchemy Technique model."""
         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
+    def apply_to(self, model: Any) -> None:
+        """Copy mutable fields back onto the ORM model."""
         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.
@@ -224,93 +118,61 @@ class TechniqueEntity:
         Rules (v3):
           1. No tests -> not_evaluated
           2. All tests validated -> inspect detection results:
-             a. All detected AND ≥ 1 validated test -> validated
-             b. Any partially_detected -> partial
+             a. All detected AND ≥ 2 validated tests -> validated
+             b. All detected but only 1 validated test -> partial
+                (single test is not enough evidence for full coverage)
+             c. Any partially_detected -> partial
              d. Otherwise (no detected results) -> not_covered
           3. Some validated, others in intermediate states -> partial
           4. All tests in intermediate states (draft/executing/evaluating/review/rejected)
              -> in_progress
 
-        Minimum validated count for "validated": 1 test.
+        Minimum validated count for "validated": 2 tests.
+        With only 1 validated+detected test the technique is "partial" to
+        signal that more testing is recommended.
 
-        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.
+        Returns the new status (also set on the entity).
         """
-        min_validated_for_full = 1  # require ≥ N validated tests for "validated"
+        _MIN_VALIDATED_FOR_FULL = 2  # require ≥ N validated tests for "validated"
 
         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):
             validated_count = len(tests)
             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):
-                # Need at least min_validated_for_full tests for "validated"
-                if validated_count >= min_validated_for_full:
+                # Need at least _MIN_VALIDATED_FOR_FULL tests for "validated"
+                if validated_count >= _MIN_VALIDATED_FOR_FULL:
                     self.status_global = TechniqueStatus.validated
                 else:
                     self.status_global = TechniqueStatus.partial
             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
+        """Mark the technique as reviewed, clearing the review flag."""
         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
+        """Flag the technique as needing review."""
         self.review_required = True

backend/app/domain/entities/threat_actor.py

@@ -3,204 +3,94 @@
 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
+from typing import Any
 
 
-# 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 = []
+    def from_orm(cls, orm: Any) -> ThreatActorEntity:
         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

@@ -5,78 +5,41 @@ 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"
     disputed = "disputed"   # one lead approved, the other 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

@@ -9,30 +9,15 @@ 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)
 
 
@@ -42,45 +27,18 @@ class DomainError(Exception):
 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",
         )
 
@@ -88,67 +46,34 @@ class DuplicateEntityError(DomainError):
 # ── State machine ────────────────────────────────────────────────────
 
 
-class InvalidStateTransition(DomainError):  # noqa: N818 — DDD term, renaming would break 96 call sites
+class InvalidStateTransition(DomainError):
     """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
+class BusinessRuleViolation(DomainError):
     """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.
 
@@ -156,37 +81,16 @@ class InvalidOperationError(BusinessRuleViolation):
     :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
+class PermissionViolation(DomainError):
     """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

@@ -6,7 +6,6 @@ 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,
@@ -19,7 +18,5 @@ from app.domain.errors import (  # noqa: F401
 
 # Legacy aliases — old name → new name
 DomainException = DomainError
-# Assign InvalidTransitionError = InvalidStateTransition
 InvalidTransitionError = InvalidStateTransition
-# Assign AuthorizationError = PermissionViolation
 AuthorizationError = PermissionViolation

backend/app/domain/ports/__init__.py

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

backend/app/domain/ports/import_service.py

@@ -12,19 +12,14 @@ 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.
 
@@ -32,134 +27,62 @@ class ImportService(Protocol):
     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).
-        """
-        # ...
-        ...
+    def __call__(self, db: Session) -> dict[str, Any]: ...
 
 
-# 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

@@ -1,9 +1,4 @@
-"""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

@@ -4,157 +4,54 @@ 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.
+    def find_by_id(self, technique_id: uuid.UUID) -> TechniqueEntity | None: ...
 
-        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.
-        """
-        # ...
-        ...
+    def find_by_mitre_id(self, mitre_id: str) -> TechniqueEntity | 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.
+    ) -> list[TechniqueEntity]: ...
 
-        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.
-        """
-        # ...
-        ...
+    def list_by_ids(self, ids: list[uuid.UUID]) -> list[TechniqueEntity]: ...
 
     # -- Batch queries (scoring/heatmap performance) -----------------------
 
-    def count_by_status(self) -> dict[TechniqueStatus, int]:
-        """Return a count of techniques grouped by their global status.
+    def count_by_status(self) -> dict[TechniqueStatus, int]: ...
 
-        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.
-        """
-        # ...
-        ...
+    def find_all_with_test_counts(self) -> list[TechniqueWithCounts]: ...
 
     # -- Mutations ---------------------------------------------------------
 
-    def save(self, technique: TechniqueEntity) -> TechniqueEntity:
-        """Persist a technique entity and return the saved state.
+    def save(self, technique: TechniqueEntity) -> TechniqueEntity: ...
 
-        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.
-        """
-        # ...
-        ...
+    def exists_by_mitre_id(self, mitre_id: str) -> bool: ...

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

@@ -3,20 +3,14 @@
 This is a domain contract — implementations live in infrastructure/.
 """
 
-# Enable future language features for compatibility
 from __future__ import annotations
 
-# Import uuid
 import uuid
+from typing import Protocol, runtime_checkable
 
-# 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."""
 
@@ -28,81 +22,31 @@ class TestRepository(Protocol):
         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.
+    def list_by_technique(self, technique_id: uuid.UUID) -> list[object]: ...
 
-        Args:
-            technique_id (uuid.UUID): Primary key of the technique whose tests to retrieve.
+    def list_by_state(self, state: TestState) -> list[object]: ...
 
-        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.
-        """
-        # ...
+        """Return test counts grouped by state for a single 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

@@ -20,58 +20,34 @@ 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
+from typing import Any
 
-# 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"
     disputed = "disputed"   # one lead approved, the other rejected
 
 
-# Assign VALID_TRANSITIONS = {
 VALID_TRANSITIONS: dict[TestState, list[TestState]] = {
     TestState.draft:           [TestState.red_executing],
     TestState.red_executing:   [TestState.blue_evaluating],
@@ -82,7 +58,6 @@ VALID_TRANSITIONS: dict[TestState, list[TestState]] = {
     TestState.validated:       [],
 }
 
-# Assign _PAUSABLE_STATES = frozenset({TestState.red_executing, TestState.blue_evaluating})
 _PAUSABLE_STATES = frozenset({TestState.red_executing, TestState.blue_evaluating})
 
 
@@ -90,13 +65,8 @@ _PAUSABLE_STATES = frozenset({TestState.red_executing, TestState.blue_evaluating
 
 
 @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)
 
 
@@ -104,44 +74,30 @@ class DomainEvent:
 
 
 @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)
@@ -150,134 +106,58 @@ class TestEntity:
     # -- 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
+    def from_orm(cls, model: Any) -> TestEntity:
+        """Build a TestEntity from a SQLAlchemy ``Test`` model instance."""
         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
+    def apply_to(self, model: Any) -> None:
+        """Copy the entity's mutable fields back onto the ORM model."""
         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 ------------------------------------------------
@@ -291,305 +171,148 @@ class TestEntity:
         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)
+        """Internal: validate and apply; return previous state value."""
         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()
+        """``draft`` -> ``red_executing``."""
         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``.
+        """``red_executing`` -> ``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``.
+        """``blue_evaluating`` -> ``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
+        """Pause the active phase timer."""
         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
+        """Resume a paused timer.  Returns seconds that were paused."""
         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()
+        """Record Red Lead's validation decision."""
         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()
+        """Record Blue Lead's validation decision."""
         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()
+        """``rejected`` -> ``draft``, clearing all validation/timing fields."""
         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 paused, accumulate pause time and clear.  Returns extra seconds."""
         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.
 
@@ -601,10 +324,8 @@ class TestEntity:
 
         Called automatically by :meth:`validate_red` and :meth:`validate_blue`.
         """
-        # Call self._check_dual_validation()
         self._check_dual_validation()
 
-    # Define function _assert_in_review
     def _assert_in_review(self, side: str) -> None:
         if self.state not in (TestState.in_review, TestState.disputed):
             raise InvalidOperationError(
@@ -612,37 +333,27 @@ class TestEntity:
                 f"'{self.state.value}' state (must be in_review or disputed)"
             )
 
-    # 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 the test state once both leads have voted."""
         r, b = self.red_validation_status, self.blue_validation_status
 
         if r == "approved" and b == "approved":
             self.state = TestState.validated
-            # Call self._events.append()
             self._events.append(DomainEvent("dual_validation_approved"))
 
-        elif r == "rejected" or b == "rejected":
-            # Any rejection is a veto — one lead can reject without waiting for the other
+        elif r == "rejected" and b == "rejected":
+            # Full consensus to reject
             self.state = TestState.rejected
             self._events.append(DomainEvent("dual_validation_rejected"))
+
+        elif (r == "approved" and b == "rejected") or (r == "rejected" and b == "approved"):
+            # Conflict: one approves, one rejects → needs discussion
+            self.state = TestState.disputed
+            self._events.append(DomainEvent("dual_validation_disputed"))

backend/app/domain/unit_of_work.py

@@ -20,84 +20,36 @@ Services should **never** call ``db.commit()``; they use ``db.add()`` /
   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
+    def __exit__(self, exc_type, exc_val, exc_tb) -> 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

@@ -1,9 +1,4 @@
-"""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

@@ -5,111 +5,47 @@ 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
+        """Return the parent technique ID (e.g. T1059 for T1059.001)."""
         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

@@ -3,38 +3,22 @@
 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,
@@ -42,66 +26,32 @@ class ScoringWeights:
             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 the default weight distribution."""
         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

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

backend/app/infrastructure/persistence/__init__.py

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

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

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

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

@@ -1,28 +1,20 @@
 """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
+from app.domain.enums import TechniqueStatus
 
 
-# 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

@@ -1,13 +1,8 @@
-"""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

@@ -4,95 +4,44 @@ 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 -------------------------------------------------------
@@ -100,111 +49,57 @@ class SATechniqueRepository:
     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.
+        """Single query replacing the N+1 pattern.
 
-        Uses a single query with subqueries to avoid the N+1 pattern.
-
-        Returns:
-            list[TechniqueWithCounts]: All techniques with their associated counts.
+        Returns all techniques with pre-aggregated test and detection
+        rule counts via subqueries.
         """
-        # Assign test_count_sq = (
         test_count_sq = (
             self._session.query(
                 Test.technique_id,
@@ -213,24 +108,18 @@ class SATechniqueRepository:
                     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,
@@ -238,29 +127,20 @@ class SATechniqueRepository:
                 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
@@ -269,112 +149,55 @@ class SATechniqueRepository:
     # -- 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:
+    def _int_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

@@ -1,163 +1,78 @@
 """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.
+        """Return lightweight (state, detection_result) pairs.
 
-        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``).
+        Used by TechniqueEntity.recalculate_status() without loading
+        full Test models.
         """
-        # 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),

backend/app/infrastructure/redis_client.py

@@ -13,79 +13,54 @@ Usage::
     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

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

backend/app/jobs/jira_sync_job.py

@@ -1,65 +1,37 @@
 """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

@@ -10,44 +10,22 @@ Each job manages its own database session (created on entry, closed in
 sessions.
 """
 
-# Import logging
 import logging
 from datetime import datetime, timedelta, timezone
 
-# 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.services.mitre_sync_service import sync_mitre
+from app.services.intel_service import scan_intel
+from app.services.notification_service import cleanup_old_notifications
+from app.services.snapshot_service import create_snapshot, cleanup_old_snapshots
+from app.services.campaign_scheduler_service import check_and_run_recurring_campaigns
 from app.jobs.jira_sync_job import sync_all_jira_links
-
-# Import run_retention_job from app.jobs.retention_job
+from app.services.osint_enrichment_service import enrich_all_techniques
+from app.services.stale_detection_service import detect_stale_coverage
 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__)
 
 # ---------------------------------------------------------------------------
@@ -66,101 +44,60 @@ def _run_mitre_sync() -> None:
     """Execute a MITRE sync inside its own DB session."""
     from app.services.webhook_service import dispatch_webhook
     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)
         dispatch_webhook("mitre.synced", {"created": summary.get("created", 0), "updated": summary.get("updated", 0)})
     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()
 
 
-# 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()
 
 
-# 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()
 
 
@@ -256,122 +193,27 @@ def _run_scheduled_campaign_activation() -> None:
 
 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()
-
-
-def _run_evaluation_round_check() -> None:
-    """Weekly job: check if a new ATT&CK Evaluation round is available.
-
-    If a new round is found it is imported automatically and an admin
-    notification is created so the team knows new baseline data is available.
-    """
-    logger.info("ATT&CK Evaluations new-round check starting...")
-    db = SessionLocal()
-    try:
-        from app.services.attck_evaluations_service import check_for_new_round, import_evaluation_round
-        from app.models.user import User as UserModel
-
-        result = check_for_new_round(db)
-        if result.get("error"):
-            logger.warning("ATT&CK Evaluations check failed: %s", result["error"])
-            return
-
-        if not result.get("new_round_available"):
-            logger.info(
-                "ATT&CK Evaluations check — latest round '%s' already imported",
-                result.get("latest_round", {}).get("display_name", "?"),
-            )
-            return
-
-        latest = result["latest_round"]
-        logger.info(
-            "New ATT&CK Evaluation round detected: %s (round %d) — starting auto-import",
-            latest["display_name"], latest["eval_round"],
-        )
-
-        # Use the first admin user as the importer (system action)
-        admin = db.query(UserModel).filter(UserModel.role == "admin").first()
-        if not admin:
-            logger.warning("ATT&CK Evaluations auto-import: no admin user found — skipping")
-            return
-
-        summary = import_evaluation_round(
-            db,
-            latest["name"],
-            latest["display_name"],
-            latest["eval_round"],
-            admin,
-        )
-        logger.info(
-            "ATT&CK Evaluations auto-import complete — round %d (%s): %d tests created",
-            latest["eval_round"], latest["display_name"], summary["created"],
-        )
-
-        # Notify all admins
-        try:
-            from app.services.notification_service import create_notification
-            admins = db.query(UserModel).filter(UserModel.role == "admin").all()
-            for adm in admins:
-                create_notification(
-                    db,
-                    user_id=adm.id,
-                    title="New ATT&CK Evaluation round imported",
-                    message=(
-                        f"Round {latest['eval_round']} — {latest['display_name']} — "
-                        f"has been automatically imported. "
-                        f"{summary['created']} tests created in In Review state. "
-                        f"Blue Leads must validate each result before it counts as coverage."
-                    ),
-                    notification_type="eval_import",
-                    entity_type="evaluation",
-                    entity_id=None,
-                )
-            db.commit()
-        except Exception:
-            logger.warning("Failed to send eval import notifications", exc_info=True)
-
-    except Exception:
-        logger.exception("ATT&CK Evaluations round check job failed")
     finally:
         db.close()
 
 
 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()
 
 
@@ -432,23 +274,14 @@ def _run_data_sources_sync() -> None:
 
 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()
 
 
@@ -514,67 +347,40 @@ def start_scheduler() -> None:
 
     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_scheduled_campaign_activation,
         trigger="interval",
@@ -585,71 +391,42 @@ def start_scheduler() -> None:
     )
     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,
     )
     scheduler.add_job(
@@ -686,27 +463,12 @@ def start_scheduler() -> None:
         name="Operational alert evaluation (hourly)",
         replace_existing=True,
     )
-    scheduler.add_job(
-        _run_evaluation_round_check,
-        trigger="cron",
-        day_of_week="mon",
-        hour=6,
-        minute=0,
-        id="attck_evaluation_check",
-        name="ATT&CK Evaluations new-round check (Mondays 06:00)",
-        replace_existing=True,
-    )
     scheduler.start()
-    # 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), "
         "retention_policies (daily), data_sources_sync (6h), "
-        "alert_evaluation (1h), attck_evaluation_check (Mondays 06:00)"
+        "alert_evaluation (1h)"
     )

backend/app/jobs/retention_job.py

@@ -1,89 +1,53 @@
 """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

@@ -1,10 +1,6 @@
 """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

@@ -8,101 +8,60 @@ 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,41 +1,13 @@
-"""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
 
-# 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 fastapi.exceptions import RequestValidationError
 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
 
 from app.routers import auth as auth_router
@@ -78,48 +50,24 @@ from app.routers import api_keys as api_keys_router
 from app.routers import sso as sso_router
 from app.routers import operational_alerts as alerts_router
 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
+from app.limiter import limiter
 from app.storage import ensure_bucket_exists
-from app.config import settings as _settings
-from starlette.middleware.base import BaseHTTPMiddleware
-
-# Configure structured logging before any module initialises its own logger
-setup_logging()
-
-logger = logging.getLogger(__name__)
+from app.jobs.mitre_sync_job import start_scheduler, scheduler
 
 # ── Environment detection ─────────────────────────────────────────────────
 _IS_PRODUCTION = os.environ.get("AEGIS_ENV", "").lower() == "production"
 
-# Apply the @asynccontextmanager decorator
+# ── Logging ───────────────────────────────────────────────────────────────
+from app.logging_config import setup_logging
+
+setup_logging()
+
 @asynccontextmanager
-# 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()
+async def lifespan(app: FastAPI):
+    """Startup / shutdown logic."""
     ensure_bucket_exists()
-    # Call start_scheduler()
     start_scheduler()
     # Seed decay policies
     from app.database import SessionLocal
@@ -127,8 +75,8 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     db = SessionLocal()
     try:
         seed_decay_policies(db)
-    except Exception as e:
-        logger.warning("seed_decay_policies failed at startup: %s", e)
+    except Exception:
+        pass
     finally:
         db.close()
     # Seed operational alert system rules
@@ -136,8 +84,8 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     try:
         from app.services.operational_alert_service import seed_system_rules
         seed_system_rules(db2)
-    except Exception as e:
-        logger.warning("seed_system_rules failed at startup: %s", e)
+    except Exception:
+        pass
     finally:
         db2.close()
     yield
@@ -147,30 +95,26 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
 
 # ── 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)
 
 
 # ── No-cache middleware for all /api/ responses ───────────────────────────
 # Prevents Cloudflare and browser caches from storing API responses,
 # which would cause stale/empty data to be served after backend restarts.
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import Response as StarletteResponse
+
 class NoCacheAPIMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request: Request, call_next):
         response = await call_next(request)
@@ -186,77 +130,49 @@ app.add_middleware(NoCacheAPIMiddleware)
 app.add_exception_handler(DomainError, domain_exception_handler)
 
 # ── CORS ──────────────────────────────────────────────────────────────────
+from app.config import settings as _settings
+
 _cors_origins: list[str] = [
     o.strip() for o in _settings.CORS_ORIGINS.split(",") if o.strip()
 ]
 
-# Call app.add_middleware()
 app.add_middleware(
     CORSMiddleware,
-    # Keyword argument: allow_origins
     allow_origins=_cors_origins,
-    # Keyword argument: allow_credentials
     allow_credentials=True,
-    # 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")
 app.include_router(intel_router.router, prefix="/api/v1")
 app.include_router(admin_config_router.router, prefix="/api/v1")
 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.include_router(webhooks_router.router, prefix="/api/v1")
 app.include_router(detection_lifecycle_router.router, prefix="/api/v1")
@@ -270,19 +186,13 @@ app.include_router(sso_router.router, prefix="/api/v1")
 app.include_router(alerts_router.router, prefix="/api/v1")
 
 
-# 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.
+def health():
+    """Minimal health check — returns only an HTTP 200 with no service metadata.
 
     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"}
 
 
@@ -290,117 +200,51 @@ def health() -> dict[str, str]:
 
 
 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 = []
+    """Return validation errors safe for JSON (no raw exception objects)."""
     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(
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Handle validation errors with consistent format."""
     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}"
+async def sqlalchemy_exception_handler(request: Request, exc: SQLAlchemyError):
+    """Handle database errors."""
     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}"
+async def general_exception_handler(request: Request, exc: Exception):
+    """Handle all unhandled exceptions."""
     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

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

backend/app/middleware/error_handler.py

@@ -5,13 +5,9 @@ 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,
@@ -22,45 +18,28 @@ from app.domain.errors import (
     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

@@ -1,74 +1,26 @@
 """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")
+    """Extract the client IP, honouring ``X-Forwarded-For`` when present."""
     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()
+    async def dispatch(self, request: Request, call_next):
         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,5 +1,10 @@
-"""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.test_template import TestTemplate
+from app.models.evidence import Evidence
+from app.models.intel import IntelItem
 from app.models.audit import AuditLog
 from app.models.notification import Notification
 from app.models.data_source import DataSource
@@ -39,41 +44,22 @@ from app.models.executive_dashboard import PostureSnapshot
 from app.models.api_key import ApiKey
 from app.models.sso_config import SsoConfig
 from app.models.operational_alert import AlertRule, AlertInstance
-from app.models.evidence import Evidence
-from app.models.intel import IntelItem
-from app.models.technique import Technique
-from app.models.test import Test
-from app.models.test_template import TestTemplate
-from app.models.user import User
 
-# Assign __all__ = [
 __all__ = [
-    # 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",
     "WebhookConfig", "SystemConfig",
     "DetectionAsset", "DetectionTechniqueMapping", "DetectionValidation",
-    "TechniqueConfidenceScore", "InfrastructureChangeLog",
-    "DetectionConfidence", "DetectionHealthStatus", "InvalidationReason", "DecayPolicy",
+    "TechniqueConfidenceScore", "InfrastructureChangeLog", "DecayPolicy",
     "TechniqueOwnership", "RevalidationQueueItem",
     "QueuePriority", "QueueStatus", "QueueReason",
     "AttackPath", "AttackPathStep", "AttackPathExecution",

backend/app/models/audit.py

@@ -1,58 +1,35 @@
-"""SQLAlchemy model for the audit log table."""
-
-# 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 import Column, String, DateTime, ForeignKey, Index, func
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 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)
-    # 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"),

backend/app/models/campaign.py

@@ -4,35 +4,20 @@ 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,
+    Column, String, Text, Integer, Boolean, DateTime,
+    ForeignKey, Index, func,
 )
-
-# Import JSONB, UUID from sqlalchemy.dialects.postgresql
-from sqlalchemy.dialects.postgresql import JSONB, UUID
-
-# Import relationship from sqlalchemy.orm
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 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.
+    """
+    A campaign groups multiple tests into a sequenced attack chain.
 
     Types:
     - custom: manually created campaign
@@ -46,97 +31,62 @@ class Campaign(Base):
     - 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,
     )
     start_date = Column(DateTime, nullable=True)   # campaign won't activate before this date
     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'),
@@ -148,83 +98,56 @@ class Campaign(Base):
 
 # 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.
+    """
+    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

@@ -4,145 +4,92 @@ 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,
+    Column, String, Text, Boolean, DateTime,
+    ForeignKey, Index, 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

@@ -5,125 +5,76 @@ 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,
+    Column, String, Float, Integer, DateTime,
+    ForeignKey, Index, 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

@@ -1,56 +1,36 @@
 """DataSource model — registry of external data sources for import."""
 
-# Import uuid
 import uuid
+from sqlalchemy import Column, String, Text, Boolean, DateTime, Index, func
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 
-# 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"
+    Unified registry of all external data sources (attack procedures,
+    detection rules, threat intel, defensive techniques).
+
+    Each source can be independently enabled/disabled and tracks its own
+    synchronisation state.
+    """
     __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...
+    type = Column(String, nullable=False)                          # attack_procedure / detection_rule / threat_intel / defensive_technique
     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

@@ -4,108 +4,74 @@ 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,
+    Column, String, Text, DateTime,
+    ForeignKey, Index, 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.
+    """
+    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"
+    """
+    Association between a MITRE ATT&CK technique and a D3FEND
+    defensive technique.
+    """
     __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

@@ -1,61 +1,38 @@
 """DetectionRule model — detection rules from multiple sources."""
 
-# Import uuid
 import uuid
+from sqlalchemy import Column, String, Text, Boolean, DateTime, Index, func
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 
-# 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).
+    """
+    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'),

backend/app/models/enums.py

@@ -5,7 +5,6 @@ re-exports every enum so that existing model and router code keeps
 working with ``from app.models.enums import ...``.
 """
 
-# Import # noqa: F401 from app.domain.enums
 from app.domain.enums import (  # noqa: F401
     DataClassification,
     TeamSide,

backend/app/models/evaluation_import.py

@@ -1,34 +0,0 @@
-"""SQLAlchemy model for tracking imported ATT&CK Evaluation rounds."""
-import uuid
-from datetime import datetime
-
-from sqlalchemy import Column, String, Integer, DateTime, Text, ForeignKey, Index
-from sqlalchemy.dialects.postgresql import UUID
-
-from app.database import Base
-
-
-class EvaluationImport(Base):
-    """Tracks which ATT&CK Evaluation rounds have been imported into the platform.
-
-    Each row represents one vendor+adversary combination that has been processed
-    and turned into Test records. Used to avoid duplicate imports and to show
-    the admin panel which rounds are available vs imported.
-    """
-    __tablename__ = "evaluation_imports"
-
-    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    adversary_name = Column(String, nullable=False)        # "apt29", "turla"
-    adversary_display = Column(String, nullable=False)     # "APT29", "Turla"
-    eval_round = Column(Integer, nullable=False)           # 1, 2, 3 …
-    imported_at = Column(DateTime, nullable=False, default=datetime.utcnow)
-    imported_by = Column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=True)
-    tests_created = Column(Integer, default=0)
-    techniques_covered = Column(Integer, default=0)
-    status = Column(String, default="completed")           # "completed" | "failed"
-    notes = Column(Text, nullable=True)
-
-    __table_args__ = (
-        Index("ix_evaluation_imports_adversary", "adversary_name"),
-        Index("ix_evaluation_imports_round", "eval_round"),
-    )

backend/app/models/evidence.py

@@ -1,59 +1,35 @@
-"""SQLAlchemy model for the evidence table."""
-
-# 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 import Column, String, Text, DateTime, ForeignKey, Enum, func
 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)
-    # 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/executive_dashboard.py

@@ -4,7 +4,7 @@ import uuid
 from datetime import datetime
 
 from sqlalchemy import (
-    Column, Date, DateTime, Float, ForeignKey,
+    Boolean, Column, Date, DateTime, Float, ForeignKey,
     Index, Integer, UniqueConstraint,
 )
 from sqlalchemy.dialects.postgresql import UUID, JSONB

backend/app/models/intel.py

@@ -1,44 +1,26 @@
-"""SQLAlchemy model for the intel_items table."""
-
-# 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 import Column, String, Boolean, DateTime, ForeignKey, func
 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)
-    # 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

@@ -1,99 +1,53 @@
 """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 import Column, String, DateTime, ForeignKey, Enum as SQLEnum, Index, func
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 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"),

backend/app/models/notification.py

@@ -1,54 +1,35 @@
 """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 import Column, String, Text, Boolean, DateTime, ForeignKey, Index, func
 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.
+    """
+    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"),

backend/app/models/osint_item.py

@@ -1,58 +1,37 @@
 """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 import Column, String, Text, Boolean, DateTime, ForeignKey, func
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 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.
+    """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 ─────────────────────────────────────────────────

backend/app/models/scoring_config.py

@@ -1,43 +1,25 @@
 """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 import Column, Float, DateTime, ForeignKey, func
 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/sso_config.py

@@ -4,7 +4,7 @@ import uuid
 from datetime import datetime
 
 from sqlalchemy import Boolean, Column, DateTime, String, Text
-from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.dialects.postgresql import JSONB, UUID
 
 from app.database import Base
 

backend/app/models/technique.py

@@ -1,63 +1,38 @@
-"""SQLAlchemy model for the techniques table."""
-
-# Import uuid
 import uuid
+from datetime import datetime
 
-# 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 import Column, String, Text, Boolean, DateTime, Enum
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 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,140 +1,80 @@
-"""SQLAlchemy model for the tests table."""
-
-# 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 import Column, String, Text, Boolean, Integer, DateTime, ForeignKey, Enum, Index, func
 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 TestResult, TestState from app.models.enums
-from app.models.enums import TestResult, TestState
+from app.models.enums import TestState, TestResult
 
 
-# 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.  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)
-    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
     created_at = Column(DateTime(timezone=True), server_default=func.now())
 
     # ── 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)
     blue_work_started_at = Column(DateTime, nullable=True)  # when blue tech picks up (Tempo start)
     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])
-    # 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"),

backend/app/models/test_detection_result.py

@@ -4,79 +4,51 @@ 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
+from datetime import datetime
 
-# Import  from sqlalchemy
-from sqlalchemy import (
-    Boolean,
-    Column,
-    DateTime,
-    ForeignKey,
-    Index,
-    Text,
-    UniqueConstraint,
-)
-
-# Import UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy import Column, String, Text, Boolean, DateTime, ForeignKey, Index, UniqueConstraint
 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.
+    """
+    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'),

backend/app/models/test_template.py

@@ -1,21 +1,15 @@
 """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 import Column, String, Text, Boolean, DateTime, Index, func
 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.
+    """
+    Predefined test template mapped to a MITRE ATT&CK technique.
 
     Templates come from several sources:
       - **atomic_red_team**: Atomic Red Team by Red Canary
@@ -24,41 +18,24 @@ class TestTemplate(Base):
 
     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'),

backend/app/models/test_template_detection_rule.py

@@ -4,64 +4,47 @@ Enables the Blue Team to see which detection rules should fire
 for a given test template / attack procedure.
 """
 
-# Import uuid
 import uuid
+from datetime import datetime
 
-# Import Boolean, Column, ForeignKey, Index, UniqueConst... from sqlalchemy
-from sqlalchemy import Boolean, Column, ForeignKey, Index, UniqueConstraint
-
-# Import UUID from sqlalchemy.dialects.postgresql
+from sqlalchemy import Column, Boolean, ForeignKey, Index, UniqueConstraint
 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 TestTemplateDetectionRule
 class TestTemplateDetectionRule(Base):
-    """Association between a test template and a detection rule.
+    """
+    Association between a test template and a detection rule.
 
     Auto-generated by matching mitre_technique_id, or manually curated.
     ``is_primary`` marks rules with severity >= high as primary detections.
     """
-    # Assign __tablename__ = "test_template_detection_rules"
     __tablename__ = "test_template_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 test_template_id = Column(
     test_template_id = Column(
         UUID(as_uuid=True),
         ForeignKey("test_templates.id", ondelete="CASCADE"),
-        # Keyword argument: nullable
         nullable=True,
     )
-    # 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 is_primary = Column(Boolean, default=False)
     is_primary = Column(Boolean, default=False)
 
     # Relationships
     test_template = relationship("TestTemplate")
-    # Assign detection_rule = relationship("DetectionRule")
     detection_rule = relationship("DetectionRule")
 
-    # Assign __table_args__ = (
     __table_args__ = (
         Index('ix_ttdr_template', 'test_template_id'),
         Index('ix_ttdr_rule', 'detection_rule_id'),
         UniqueConstraint(
-            # Literal argument value
             'test_template_id', 'detection_rule_id',
-            # Keyword argument: name
             name='uq_template_detection_rule',
         ),
     )

backend/app/models/threat_actor.py

@@ -4,135 +4,87 @@ Stores profiles of APT groups and their associated MITRE ATT&CK
 techniques, imported from MITRE CTI (STIX 2.0).
 """
 
-# Import uuid
 import uuid
-
-# Import  from sqlalchemy
 from sqlalchemy import (
-    Boolean,
-    Column,
-    DateTime,
-    ForeignKey,
-    Index,
-    String,
-    Text,
-    UniqueConstraint,
-    func,
+    Column, String, Text, Boolean, DateTime,
+    ForeignKey, Index, UniqueConstraint, func,
 )
-
-# Import JSONB, UUID from sqlalchemy.dialects.postgresql
-from sqlalchemy.dialects.postgresql import JSONB, UUID
-
-# Import relationship from sqlalchemy.orm
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 from sqlalchemy.orm import relationship
 
-# Import Base from app.database
 from app.database import Base
 
 
-# Define class ThreatActor
 class ThreatActor(Base):
-    """Threat actor / APT group profile.
+    """
+    Threat actor / APT group profile.
 
     Imported from MITRE CTI ``intrusion-set`` STIX objects.
     """
-    # Assign __tablename__ = "threat_actors"
     __tablename__ = "threat_actors"
 
-    # 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=True)              # e.g. "G00...
     mitre_id = Column(String, unique=True, nullable=True)              # e.g. "G0016" (APT29)
-    # Assign name = Column(String, nullable=False)
     name = Column(String, nullable=False)
-    # Assign aliases = Column(JSONB, nullable=True, default=[])                  # ["Cozy ...
     aliases = Column(JSONB, nullable=True, default=[])                  # ["Cozy Bear", "The Dukes", ...]
-    # Assign description = Column(Text, nullable=True)
     description = Column(Text, nullable=True)
-    # Assign country = Column(String, nullable=True)
     country = Column(String, nullable=True)
-    # Assign target_sectors = Column(JSONB, nullable=True, default=[])           # ["government",...
     target_sectors = Column(JSONB, nullable=True, default=[])           # ["government", "defense", ...]
-    # Assign target_regions = Column(JSONB, nullable=True, default=[])           # ["north-americ...
     target_regions = Column(JSONB, nullable=True, default=[])           # ["north-america", "europe", ...]
-    # Assign motivation = Column(String, nullable=True)                          # espionage ...
     motivation = Column(String, nullable=True)                          # espionage / financial / destruction / ...
-    # Assign sophistication = Column(String, nullable=True)                      # low / medium /...
     sophistication = Column(String, nullable=True)                      # low / medium / high / advanced
-    # Assign first_seen = Column(String, nullable=True)
     first_seen = Column(String, nullable=True)
-    # Assign last_seen = Column(String, nullable=True)
     last_seen = Column(String, nullable=True)
-    # Assign references = Column(JSONB, nullable=True, default=[])               # [{"url": "...
     references = Column(JSONB, nullable=True, default=[])               # [{"url": "...", "description": "..."}]
-    # Assign mitre_url = Column(String, nullable=True)
     mitre_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
     techniques = relationship(
-        # Literal argument value
         "ThreatActorTechnique",
-        # Keyword argument: back_populates
         back_populates="threat_actor",
-        # Keyword argument: cascade
         cascade="all, delete-orphan",
     )
 
-    # Assign __table_args__ = (
     __table_args__ = (
         Index('ix_threat_actors_country', 'country'),
         Index('ix_threat_actors_motivation', 'motivation'),
     )
 
 
-# Define class ThreatActorTechnique
 class ThreatActorTechnique(Base):
-    """Association between a threat actor and a MITRE ATT&CK technique.
+    """
+    Association between a threat actor and a MITRE ATT&CK technique.
 
     Stores additional context about how the actor uses the technique
     (from the STIX ``relationship`` ``uses`` objects).
     """
-    # Assign __tablename__ = "threat_actor_techniques"
     __tablename__ = "threat_actor_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 threat_actor_id = Column(
     threat_actor_id = Column(
         UUID(as_uuid=True),
         ForeignKey("threat_actors.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 usage_description = Column(Text, nullable=True)
     usage_description = Column(Text, nullable=True)
-    # Assign first_seen_using = Column(String, nullable=True)
     first_seen_using = Column(String, nullable=True)
 
     # Relationships
     threat_actor = relationship("ThreatActor", back_populates="techniques")
-    # Assign technique = relationship("Technique")
     technique = relationship("Technique")
 
-    # Assign __table_args__ = (
     __table_args__ = (
         Index('ix_threat_actor_techniques_actor', 'threat_actor_id'),
         Index('ix_threat_actor_techniques_technique', 'technique_id'),
         UniqueConstraint(
-            # Literal argument value
             'threat_actor_id', 'technique_id',
-            # Keyword argument: name
             name='uq_actor_technique',
         ),
     )

backend/app/models/user.py

@@ -1,18 +1,14 @@
-"""SQLAlchemy model for the users table."""
-
-# Import uuid
 import uuid
 from sqlalchemy import Column, String, Boolean, DateTime, func
 from sqlalchemy.dialects.postgresql import UUID, JSONB
 
-# Import Base from app.database
 from app.database import Base
 
 
-# Define class User
 class User(Base):
-    """User model for authentication and authorization.
-
+    """
+    User model for authentication and authorization.
+    
     Possible roles:
     - admin: Full system access
     - red_tech: Red team technician - can create and edit tests
@@ -21,26 +17,16 @@ class User(Base):
     - blue_lead: Blue team lead - can validate tests
     - viewer: Read-only access (default)
     """
-    # Assign __tablename__ = "users"
     __tablename__ = "users"
 
-    # 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 username = Column(String, unique=True, nullable=False)
     username = Column(String, unique=True, nullable=False)
-    # Assign email = Column(String, nullable=True)
     email = Column(String, nullable=True)
-    # Assign hashed_password = Column(String, nullable=False)
     hashed_password = Column(String, nullable=False)
-    # Assign role = Column(String, nullable=False, default="viewer")
     role = Column(String, nullable=False, default="viewer")
-    # Assign is_active = Column(Boolean, default=True)
     is_active = Column(Boolean, default=True)
-    # Assign must_change_password = Column(Boolean, default=True)
     must_change_password = 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 last_login = Column(DateTime, nullable=True)
     last_login = Column(DateTime, nullable=True)
     notification_preferences = Column(JSONB, nullable=True, server_default='{"email_on_test_validated": true, "email_on_campaign_completed": true, "email_on_new_mitre_techniques": false, "in_app_all": true}')
     jira_account_id = Column(String(100), nullable=True)

backend/app/models/webhook_config.py

@@ -1,5 +1,6 @@
 """WebhookConfig model — outbound HTTP notification endpoints."""
 import uuid
+from datetime import datetime
 from sqlalchemy import Column, String, Boolean, DateTime, Integer, Text, ForeignKey, func
 from sqlalchemy.dialects.postgresql import UUID, JSONB
 from app.database import Base

backend/app/models/worklog.py

@@ -1,22 +1,13 @@
 """Worklog model — immutable internal time-tracking records."""
 
-# Import uuid
 import uuid
-
-# Import Column, DateTime, ForeignKey, Index, Integer, S... from sqlalchemy
-from sqlalchemy import 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 import Column, String, Integer, DateTime, ForeignKey, Text, Index, func
+from sqlalchemy.dialects.postgresql import UUID, JSONB
 from sqlalchemy.orm import relationship
 
-# Import Base from app.database
 from app.database import Base
 
 
-# Define class Worklog
 class Worklog(Base):
     """Internal worklog entry with integrity hash for audit compliance.
 
@@ -25,42 +16,25 @@ class Worklog(Base):
     the immutable fields so tampering can be detected.
     """
 
-    # Assign __tablename__ = "worklogs"
     __tablename__ = "worklogs"
 
-    # 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(String(50), nullable=False)
     entity_type = Column(String(50), nullable=False)
-    # Assign entity_id = Column(UUID(as_uuid=True), nullable=False)
     entity_id = Column(UUID(as_uuid=True), nullable=False)
-    # 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 activity_type = Column(String(100), nullable=False)
     activity_type = Column(String(100), nullable=False)
-    # Assign started_at = Column(DateTime, nullable=False)
     started_at = Column(DateTime, nullable=False)
-    # Assign ended_at = Column(DateTime)
     ended_at = Column(DateTime)
-    # Assign duration_seconds = Column(Integer, nullable=False)
     duration_seconds = Column(Integer, nullable=False)
-    # Assign description = Column(Text)
     description = Column(Text)
-    # Assign tempo_synced = Column(DateTime)
     tempo_synced = Column(DateTime)
-    # Assign tempo_worklog_id = Column(String(100))
     tempo_worklog_id = Column(String(100))
-    # Assign integrity_hash = Column(String(64))
     integrity_hash = Column(String(64))
-    # Assign created_at = Column(DateTime(timezone=True), server_default=func.now())
     created_at = Column(DateTime(timezone=True), server_default=func.now())
-    # Assign extra_metadata = Column("metadata", JSONB, default={})
     extra_metadata = Column("metadata", JSONB, default={})
 
-    # Assign user = relationship("User", foreign_keys=[user_id])
     user = relationship("User", foreign_keys=[user_id])
 
-    # Assign __table_args__ = (
     __table_args__ = (
         Index("ix_worklogs_entity_id", "entity_id"),
         Index("ix_worklogs_user_id", "user_id"),

backend/app/routers/__init__.py

@@ -1 +0,0 @@
-"""FastAPI router modules — one router per feature domain."""

backend/app/routers/admin_config.py

@@ -13,6 +13,7 @@ What is exported (and what is NOT):
   ✗ atomic/sigma/elastic templates, techniques, tests, campaigns, reports
 """
 
+import uuid
 from datetime import datetime
 from typing import Any
 
@@ -22,7 +23,7 @@ from sqlalchemy.orm import Session
 
 from app.auth import hash_password
 from app.database import get_db
-from app.dependencies.auth import require_role
+from app.dependencies.auth import get_current_user, require_role
 from app.models.scoring_config import ScoringConfig
 from app.models.sso_config import SsoConfig
 from app.models.system_config import SystemConfig
@@ -149,7 +150,7 @@ def export_config(
             "email": u.email if hasattr(u, "email") else None,
             "role": u.role,
             "is_active": u.is_active,
-            "must_change_password": True,  # force password reset on new instance  # nosec B105
+            "must_change_password": True,  # force password reset on new instance
         }
         for u in db.query(User).order_by(User.username).all()
     ]

backend/app/routers/advanced_metrics.py

@@ -1,81 +1,50 @@
 """Advanced metrics endpoints — coverage by tactic, never-tested, avg validation time."""
 
-# Import APIRouter, Depends from fastapi
 from fastapi import APIRouter, Depends
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user from app.dependencies.auth
 from app.dependencies.auth import get_current_user
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import advanced_metrics_service from app.services
 from app.services import advanced_metrics_service
 
-# Assign router = APIRouter(prefix="/metrics/advanced", tags=["advanced-metrics"])
 router = APIRouter(prefix="/metrics/advanced", tags=["advanced-metrics"])
 
 
-# Apply the @router.get decorator
 @router.get("/coverage-by-tactic")
-# Define function coverage_by_tactic
 def coverage_by_tactic(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> list:
+):
     """Coverage percentage broken down by MITRE ATT&CK tactic."""
-    # Return advanced_metrics_service.get_coverage_by_tactic(db)
     return advanced_metrics_service.get_coverage_by_tactic(db)
 
 
-# Apply the @router.get decorator
 @router.get("/never-tested")
-# Define function never_tested_techniques
 def never_tested_techniques(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> list:
+):
     """Techniques that have never had a test created."""
-    # Return advanced_metrics_service.get_never_tested_techniques(db)
     return advanced_metrics_service.get_never_tested_techniques(db)
 
 
-# Apply the @router.get decorator
 @router.get("/avg-validation-time")
-# Define function avg_validation_time
 def avg_validation_time(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> dict:
+):
     """Average time from test creation to validation, computed from audit logs.
 
     Returns overall average and per-phase averages where data is available.
     """
-    # Return advanced_metrics_service.get_avg_validation_time(db)
     return advanced_metrics_service.get_avg_validation_time(db)
 
 
-# Apply the @router.get decorator
 @router.get("/detection-rate-trend")
-# Define function detection_rate_trend
 def detection_rate_trend(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> list:
+):
     """Monthly detection rate trend for the last 12 months."""
-    # Return advanced_metrics_service.get_detection_rate_trend(db)
     return advanced_metrics_service.get_detection_rate_trend(db)

backend/app/routers/analytics.py

@@ -4,85 +4,52 @@ Returns complete datasets without pagination so BI tools can ingest
 directly from URL. All endpoints require authentication.
 """
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user, require_role from app.dependencies.auth
 from app.dependencies.auth import get_current_user, require_role
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import analytics_service from app.services
 from app.services import analytics_service
 
-# Assign router = APIRouter(prefix="/analytics", tags=["analytics"])
 router = APIRouter(prefix="/analytics", tags=["analytics"])
 
 
-# Apply the @router.get decorator
 @router.get("/coverage")
-# Define function analytics_coverage
 def analytics_coverage(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> list:
+):
     """Coverage per technique — flat format for BI dashboards."""
-    # Return analytics_service.get_coverage_analytics(db)
     return analytics_service.get_coverage_analytics(db)
 
 
-# Apply the @router.get decorator
 @router.get("/tests")
-# Define function analytics_tests
 def analytics_tests(
-    # Entry: date_from
     date_from: str = Query(None, description="ISO date filter (>=)"),
-    # Entry: date_to
     date_to: str = Query(None, description="ISO date filter (<=)"),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> list:
+):
     """All tests with timestamps — flat format for BI dashboards."""
-    # Return analytics_service.get_tests_analytics(
     return analytics_service.get_tests_analytics(
         db, date_from=date_from, date_to=date_to
     )
 
 
-# Apply the @router.get decorator
 @router.get("/trends")
-# Define function analytics_trends
 def analytics_trends(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> list:
+):
     """Historical coverage snapshots for trend visualization."""
-    # Return analytics_service.get_trends_analytics(db)
     return analytics_service.get_trends_analytics(db)
 
 
-# Apply the @router.get decorator
 @router.get("/operators")
-# Define function analytics_operators
 def analytics_operators(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(require_role("admin")),
-) -> list:
+):
     """Per-operator metrics — for workload management dashboards."""
-    # Return analytics_service.get_operators_analytics(db)
     return analytics_service.get_operators_analytics(db)

backend/app/routers/api_keys.py

@@ -1,6 +1,6 @@
 """Phase 14: API Key management router."""
 
-from typing import List
+from typing import List, Optional
 from uuid import UUID
 
 from fastapi import APIRouter, Depends, Query

backend/app/routers/attack_paths.py

@@ -3,7 +3,7 @@
 from typing import Optional
 from uuid import UUID
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Query
 from sqlalchemy.orm import Session
 
 from app.database import get_db
@@ -14,6 +14,7 @@ from app.schemas.attack_path_schema import (
     ExecutionCreate, ExecutionOut,
     StepExecuteRequest, StepResultOut,
     TimelineEntryCreate, TimelineEntryOut,
+    KillChainMetrics,
 )
 from app.services import attack_path_service as svc
 

backend/app/routers/audit.py

@@ -1,127 +1,77 @@
 """Audit log viewer router (admin only)."""
 
-# Import datetime from datetime
 from datetime import datetime
-
-# Import Optional from typing
 from typing import Optional
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import require_role from app.dependencies.auth
 from app.dependencies.auth import require_role
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import AuditLogOut, AuditLogPage from app.schemas.audit
 from app.schemas.audit import AuditLogOut, AuditLogPage
-
-# Import  from app.services.audit_query_service
 from app.services.audit_query_service import (
     list_distinct_actions,
     list_distinct_entity_types,
     list_logs,
 )
 
-# Assign router = APIRouter(prefix="/audit-logs", tags=["audit"])
 router = APIRouter(prefix="/audit-logs", tags=["audit"])
 
 
-# Apply the @router.get decorator
 @router.get("", response_model=AuditLogPage)
-# Define function list_audit_logs
 def list_audit_logs(
-    # Entry: user_id
     user_id: Optional[str] = Query(None, description="Filter by user ID"),
-    # Entry: action
     action: Optional[str] = Query(None, description="Filter by action type"),
-    # Entry: entity_type
     entity_type: Optional[str] = Query(None, description="Filter by entity type"),
-    # Entry: start_date
     start_date: Optional[datetime] = Query(None, description="Filter by start date"),
-    # Entry: end_date
     end_date: Optional[datetime] = Query(None, description="Filter by end date"),
-    # Entry: offset
     offset: int = Query(0, ge=0, description="Number of records to skip"),
-    # Entry: limit
     limit: int = Query(50, ge=1, le=100, description="Max records to return"),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> AuditLogPage:
+):
     """Return paginated audit logs with optional filters.
 
     **Requires admin role.**
     """
-    # Assign result = list_logs(
     result = list_logs(
         db,
-        # Keyword argument: user_id
         user_id=user_id,
-        # Keyword argument: action
         action=action,
-        # Keyword argument: entity_type
         entity_type=entity_type,
-        # Keyword argument: start_date
         start_date=start_date,
-        # Keyword argument: end_date
         end_date=end_date,
-        # Keyword argument: offset
         offset=offset,
-        # Keyword argument: limit
         limit=limit,
     )
-    # Return AuditLogPage(
     return AuditLogPage(
-        # Keyword argument: items
         items=[AuditLogOut(**item) for item in result["items"]],
-        # Keyword argument: total
         total=result["total"],
-        # Keyword argument: offset
         offset=result["offset"],
-        # Keyword argument: limit
         limit=result["limit"],
     )
 
 
-# Apply the @router.get decorator
 @router.get("/actions", response_model=list[str])
-# Define function list_actions
 def list_actions(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> list[str]:
+):
     """Return a list of distinct action types in the audit log.
 
     **Requires admin role.**
     """
-    # Return list_distinct_actions(db)
     return list_distinct_actions(db)
 
 
-# Apply the @router.get decorator
 @router.get("/entity-types", response_model=list[str])
-# Define function list_entity_types
 def list_entity_types(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> list[str]:
+):
     """Return a list of distinct entity types in the audit log.
 
     **Requires admin role.**
     """
-    # Return list_distinct_entity_types(db)
     return list_distinct_entity_types(db)

backend/app/routers/auth.py

@@ -7,69 +7,31 @@ the token in the body for backwards compatibility and for clients that
 cannot use cookies (e.g. Swagger UI).
 """
 
-# Import os
 import os
 
-# Import APIRouter, Cookie, Depends, Request, Response from fastapi
 from fastapi import APIRouter, Cookie, Depends, Request, Response
-
-# Import OAuth2PasswordRequestForm from fastapi.security
 from fastapi.security import OAuth2PasswordRequestForm
-
-# Import jwt (PyJWT)
-import jwt
-from jwt.exceptions import PyJWTError as JWTError
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import blacklist_token, create_access_token, verify_pa... from app.auth
-from app.auth import blacklist_token, create_access_token, verify_password
+from jose import jwt, JWTError
 
-# Import settings from app.config
+from app.auth import create_access_token, blacklist_token, verify_password
 from app.config import settings
-
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user from app.dependencies.auth
 from app.dependencies.auth import get_current_user
-
-# Import BusinessRuleViolation, PermissionViolation from app.domain.errors
 from app.domain.errors import BusinessRuleViolation, PermissionViolation
-
-# Import UnitOfWork from app.domain.unit_of_work
 from app.domain.unit_of_work import UnitOfWork
-
-# Import limiter from app.limiter
 from app.limiter import limiter
-
-# Import resolve_client_ip from app.middleware.request_context
 from app.middleware.request_context import resolve_client_ip
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import TokenResponse, UserOut from app.schemas.auth
-from app.schemas.auth import TokenResponse, UserOut
-
-# Import PasswordChange from app.schemas.user
-from app.schemas.user import PasswordChange
-
-# Import log_action from app.services.audit_service
-from app.services.audit_service import log_action
-
-# Import  from app.services.auth_service
 from app.services.auth_service import (
     _DUMMY_HASH,
-)
-
-# Import  from app.services.auth_service
-from app.services.auth_service import (
     change_password as auth_change_password,
 )
+from app.services.audit_service import log_action
+from app.schemas.auth import TokenResponse, UserOut
+from app.schemas.user import PasswordChange
 
-# Assign router = APIRouter(prefix="/auth", tags=["auth"])
 router = APIRouter(prefix="/auth", tags=["auth"])
 
 # SECURE_COOKIES desacopla la seguridad de la cookie del entorno de ejecucion.
@@ -85,182 +47,111 @@ else:  # "auto" — activo solo si AEGIS_ENV=production
 _COOKIE_NAME = "aegis_token"
 
 
-# Apply the @router.post decorator
 @router.post("/login", response_model=TokenResponse)
-# Apply the @limiter.limit decorator
 @limiter.limit("5/minute")
-# Define function login
 def login(
-    # Entry: request
     request: Request,
-    # Entry: response
     response: Response,
-    # Entry: form_data
     form_data: OAuth2PasswordRequestForm = Depends(),
-    # Entry: db
     db: Session = Depends(get_db),
-) -> TokenResponse:
+):
     """Authenticate a user and return a JWT access token.
 
     Rate-limited to **5 attempts per minute per IP**.  Failed and successful
     logins are recorded in the audit log (SEC-009).
     """
-    # Assign user = db.query(User).filter(User.username == form_data.username).first()
     user = db.query(User).filter(User.username == form_data.username).first()
-    # Assign target_hash = user.hashed_password if user else _DUMMY_HASH
     target_hash = user.hashed_password if user else _DUMMY_HASH
-    # Assign password_valid = verify_password(form_data.password, target_hash)
     password_valid = verify_password(form_data.password, target_hash)
-    # Assign ip = resolve_client_ip(request)
     ip = resolve_client_ip(request)
 
-    # Check: user is None or not password_valid
     if user is None or not password_valid:
-        # Open context manager
         with UnitOfWork(db) as uow:
-            # Call log_action()
             log_action(
                 db,
                 user.id if user else None,
-                # Literal argument value
                 "LOGIN_FAILED",
-                # Literal argument value
                 "auth",
-                # Literal argument value
                 None,
-                # Keyword argument: details
                 details={
-                    # Literal argument value
                     "username": form_data.username,
-                    # Literal argument value
                     "ip": ip,
-                    # Literal argument value
                     "reason": "invalid_credentials",
                 },
-                # Keyword argument: ip_address
                 ip_address=ip,
             )
-            # Call uow.commit()
             uow.commit()
-        # Raise BusinessRuleViolation
         raise BusinessRuleViolation("Incorrect username or password")
 
-    # Check: not user.is_active
     if not user.is_active:
-        # Raise PermissionViolation
         raise PermissionViolation("Account is disabled. Contact an administrator.")
 
-    # Assign access_token = create_access_token(data={"sub": user.username})
     access_token = create_access_token(data={"sub": user.username})
 
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Call log_action()
         log_action(
             db,
             user.id,
-            # Literal argument value
             "LOGIN_SUCCESS",
-            # Literal argument value
             "auth",
             str(user.id),
-            # Keyword argument: details
             details={"username": user.username, "ip": ip},
-            # Keyword argument: ip_address
             ip_address=ip,
         )
-        # Call uow.commit()
         uow.commit()
 
-    # Call response.set_cookie()
     response.set_cookie(
-        # Keyword argument: key
         key=_COOKIE_NAME,
-        # Keyword argument: value
         value=access_token,
-        # Keyword argument: httponly
         httponly=True,
-        # Keyword argument: secure
         secure=_IS_HTTPS,
-        # Keyword argument: samesite
         samesite="strict",
-        # Keyword argument: max_age
         max_age=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60,
-        # Keyword argument: path
         path="/",
     )
 
-    # Return TokenResponse(access_token=access_token)
     return TokenResponse(access_token=access_token)
 
 
-# Apply the @router.post decorator
 @router.post("/logout")
-# Define function logout
 def logout(
-    # Entry: request
     request: Request,
-    # Entry: response
     response: Response,
-    # Entry: aegis_token
     aegis_token: str | None = Cookie(None),
-) -> dict:
+):
     """Clear the authentication cookie and revoke the current token."""
-    # Assign bearer = (
     bearer = (
         request.headers.get("Authorization")
         or request.headers.get("authorization")
         or ""
     )
-    # Assign bearer = bearer.removeprefix("Bearer ").removeprefix("bearer ").strip()
     bearer = bearer.removeprefix("Bearer ").removeprefix("bearer ").strip()
 
-    # Assign seen = set()
     seen: set[str] = set()
-    # Iterate over (aegis_token, bearer)
     for raw in (aegis_token, bearer):
-        # Check: not raw or raw in seen
         if not raw or raw in seen:
-            # Skip to the next loop iteration
             continue
-        # Call seen.add()
         seen.add(raw)
-        # Attempt the following; catch errors below
         try:
-            # Assign payload = jwt.decode(
             payload = jwt.decode(
                 raw,
                 settings.SECRET_KEY,
-                # Keyword argument: algorithms
                 algorithms=[settings.ALGORITHM],
             )
-            # Assign jti = payload.get("jti")
             jti = payload.get("jti")
-            # Assign exp = payload.get("exp", 0)
             exp = payload.get("exp", 0)
-            # Check: jti
             if jti:
-                # Call blacklist_token()
                 blacklist_token(jti, float(exp))
-        # Handle any JWT validation error during logout (token may be expired or malformed)
-        except jwt.exceptions.InvalidTokenError:
-            # Intentional no-op placeholder
+        except JWTError:
             pass
 
-    # Call response.delete_cookie()
     response.delete_cookie(
-        # Keyword argument: key
         key=_COOKIE_NAME,
-        # Keyword argument: httponly
         httponly=True,
-        # Keyword argument: secure
         secure=_IS_HTTPS,
-        # Keyword argument: samesite
         samesite="strict",
-        # Keyword argument: path
         path="/",
     )
-    # Return {"detail": "Logged out"}
     return {"detail": "Logged out"}
 
 
@@ -316,38 +207,25 @@ def refresh_token(
 
 
 @router.get("/me", response_model=UserOut)
-# Define function read_current_user
-def read_current_user(current_user: User = Depends(get_current_user)) -> UserOut:
+def read_current_user(current_user: User = Depends(get_current_user)):
     """Return the profile of the currently authenticated user."""
-    # Return current_user
     return current_user
 
 
-# Apply the @router.post decorator
 @router.post("/change-password")
-# Define function change_password
 def change_password(
-    # Entry: body
     body: PasswordChange,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Change the current user's password."""
-    # Call auth_change_password()
     auth_change_password(
         db,
         current_user,
-        # Keyword argument: current_password
         current_password=body.current_password,
-        # Keyword argument: new_password
         new_password=body.new_password,
     )
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Call uow.commit()
         uow.commit()
 
-    # Return {"detail": "Password changed successfully"}
     return {"detail": "Password changed successfully"}

backend/app/routers/campaigns.py

@@ -1,174 +1,80 @@
 """Campaign endpoints — CRUD, test management, activation, and auto-generation.
 
-Provides comprehensive campaign lifecycle management including test ordering,
-progress tracking, and threat actor integration.
+Provides comprehensive campaign lifecycle management including
+test ordering, progress tracking, and threat actor integration.
 """
 
-# Import logging
 import logging
-
-# Import uuid
 import uuid
 from datetime import datetime
 from typing import Optional
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import BaseModel, Field from pydantic
+from sqlalchemy.orm import Session
 from pydantic import BaseModel, Field
 
-# Import Session from sqlalchemy.orm
-from sqlalchemy.orm import Session
-
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user, require_any_role from app.dependencies.auth
 from app.dependencies.auth import get_current_user, require_any_role
-
-# Import UnitOfWork from app.domain.unit_of_work
-from app.domain.unit_of_work import UnitOfWork
-
-# Import User from app.models.user
 from app.models.user import User
 from app.models.campaign import Campaign, CampaignTest
 from app.models.test import Test
 from app.services.campaign_service import generate_campaign_from_threat_actor
 from app.services.campaign_crud_service import (
     add_test_to_campaign as crud_add_test,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
+    activate_campaign as crud_activate,
     complete_campaign as crud_complete,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
     create_campaign as crud_create,
     delete_campaign as crud_delete,
     get_campaign_detail as crud_get_detail,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
     get_campaign_history as crud_get_history,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
     get_campaign_progress_data as crud_get_progress,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
     list_campaigns as crud_list,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
     remove_test_from_campaign as crud_remove_test,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
     schedule_campaign as crud_schedule,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
     serialize_campaign,
-)
-
-# Import  from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
     update_campaign as crud_update,
 )
-
-# Import activate_campaign from app.services.campaign_crud_service
-from app.services.campaign_crud_service import (
-    activate_campaign as crud_activate,
-)
-
-# Import log_action from app.services.audit_service
+from app.domain.unit_of_work import UnitOfWork
 from app.services.audit_service import log_action
-
-# Import notify_role from app.services.notification_service
 from app.services.notification_service import notify_role
 from app.services.webhook_service import dispatch_webhook
 
-# Assign logger = logging.getLogger(__name__)
 logger = logging.getLogger(__name__)
 
-# Assign router = APIRouter(prefix="/campaigns", tags=["campaigns"])
 router = APIRouter(prefix="/campaigns", tags=["campaigns"])
 
 
 # ── Pydantic schemas ─────────────────────────────────────────────────
 
 class CampaignCreate(BaseModel):
-    """Payload for creating a new campaign."""
-
-    # name: str
     name: str
-    # Assign description = None
     description: Optional[str] = None
-    # Assign type = "custom"
     type: str = "custom"
-    # Assign threat_actor_id = None
     threat_actor_id: Optional[str] = None
-    # Assign target_platform = None
     target_platform: Optional[str] = None
-    # Assign tags = Field(default_factory=list)
     tags: Optional[list[str]] = Field(default_factory=list)
-    # Assign scheduled_at = None
     scheduled_at: Optional[str] = None
     start_date: Optional[str] = None  # ISO date — campaign won't activate before this
 
-
-# Define class CampaignUpdate
 class CampaignUpdate(BaseModel):
-    """Payload for updating an existing campaign's metadata."""
-
-    # Assign name = None
     name: Optional[str] = None
-    # Assign description = None
     description: Optional[str] = None
-    # Assign type = None
     type: Optional[str] = None
-    # Assign target_platform = None
     target_platform: Optional[str] = None
-    # Assign tags = None
     tags: Optional[list[str]] = None
-    # Assign scheduled_at = None
     scheduled_at: Optional[str] = None
     start_date: Optional[str] = None  # ISO date — can be updated while still in draft
 
-
-# Define class AddTestPayload
 class AddTestPayload(BaseModel):
-    """Payload for adding a test to a campaign."""
-
-    # test_id: str
     test_id: str
-    # Assign order_index = None
     order_index: Optional[int] = None
-    # Assign depends_on = None
     depends_on: Optional[str] = None
-    # Assign phase = None
     phase: Optional[str] = None
 
 
-# Define class SchedulePayload
 class SchedulePayload(BaseModel):
-    """Payload for scheduling or rescheduling a campaign run."""
-
-    # is_recurring: bool
     is_recurring: bool
-    # Assign recurrence_pattern = None  # weekly, monthly, quarterly
     recurrence_pattern: Optional[str] = None  # weekly, monthly, quarterly
-    # Assign next_run_at = None
     next_run_at: Optional[str] = None
 
 
@@ -177,54 +83,24 @@ class SchedulePayload(BaseModel):
 # ---------------------------------------------------------------------------
 
 @router.get("")
-# Define function list_campaigns
 def list_campaigns(
-    # Entry: type
     type: Optional[str] = Query(None),
-    # Entry: status
     status: Optional[str] = Query(None),
-    # Entry: threat_actor_id
     threat_actor_id: Optional[str] = Query(None),
-    # Entry: search
     search: Optional[str] = Query(None),
-    # Entry: offset
     offset: int = Query(0, ge=0),
-    # Entry: limit
     limit: int = Query(50, ge=1, le=200),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
-    """List campaigns with optional filters and pagination.
-
-    Args:
-        type (Optional[str]): Filter by campaign type (e.g. ``custom``, ``threat_actor``).
-        status (Optional[str]): Filter by campaign status (e.g. ``draft``, ``active``).
-        threat_actor_id (Optional[str]): Filter campaigns linked to a specific threat actor.
-        search (Optional[str]): Free-text search against campaign name.
-        offset (int): Number of records to skip for pagination.
-        limit (int): Maximum number of records to return.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        list: Serialised list of campaign summary dicts.
-    """
-    # Return crud_list(
+):
+    """List campaigns with optional filters and pagination."""
     return crud_list(
         db,
-        # Keyword argument: type
         type=type,
-        # Keyword argument: status
         status=status,
-        # Keyword argument: threat_actor_id
         threat_actor_id=threat_actor_id,
-        # Keyword argument: search
         search=search,
-        # Keyword argument: offset
         offset=offset,
-        # Keyword argument: limit
         limit=limit,
     )
 
@@ -234,64 +110,36 @@ def list_campaigns(
 # ---------------------------------------------------------------------------
 
 @router.post("", status_code=201)
-# Define function create_campaign
 def create_campaign(
-    # Entry: payload
     payload: CampaignCreate,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("red_lead", "blue_lead")),
-) -> dict:
-    """Create a new campaign.
-
-    Args:
-        payload (CampaignCreate): Fields for the new campaign (name, type, threat actor, etc.).
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated red_lead or blue_lead creating the campaign.
-
-    Returns:
-        dict: Serialised representation of the newly created campaign.
-    """
-    # Open context manager
+):
+    """Create a new campaign."""
     with UnitOfWork(db) as uow:
-        # Assign result = crud_create(
         result = crud_create(
             db,
-            # Keyword argument: creator_id
             creator_id=current_user.id,
-            # Keyword argument: name
             name=payload.name,
-            # Keyword argument: description
             description=payload.description,
-            # Keyword argument: type
             type=payload.type,
-            # Keyword argument: threat_actor_id
             threat_actor_id=payload.threat_actor_id,
-            # Keyword argument: target_platform
             target_platform=payload.target_platform,
-            # Keyword argument: tags
             tags=payload.tags,
-            # Keyword argument: scheduled_at
             scheduled_at=payload.scheduled_at,
             start_date=payload.start_date,
         )
         campaign_id = result["id"]
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="create_campaign",
-            # Keyword argument: entity_type
             entity_type="campaign",
             entity_id=campaign_id,
             details={"name": payload.name, "type": payload.type},
         )
-        # Call uow.commit()
         uow.commit()
 
-    # Return result
     return result
 
 
@@ -300,26 +148,12 @@ def create_campaign(
 # ---------------------------------------------------------------------------
 
 @router.get("/{campaign_id}")
-# Define function get_campaign
 def get_campaign(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
-    """Get detailed campaign info including tests and progress.
-
-    Args:
-        campaign_id (str): UUID string of the campaign to retrieve.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        dict: Campaign detail including associated tests and progress metrics.
-    """
-    # Return crud_get_detail(db, campaign_id)
+):
+    """Get detailed campaign info including tests and progress."""
     return crud_get_detail(db, campaign_id)
 
 
@@ -328,60 +162,32 @@ def get_campaign(
 # ---------------------------------------------------------------------------
 
 @router.patch("/{campaign_id}")
-# Define function update_campaign
 def update_campaign(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: payload
     payload: CampaignUpdate,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("red_lead", "blue_lead")),
-) -> dict:
-    """Update a campaign. Only allowed in draft or active state.
-
-    Args:
-        campaign_id (str): UUID string of the campaign to update.
-        payload (CampaignUpdate): Partial update payload; only set fields are applied.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated red_lead or blue_lead performing the update.
-
-    Returns:
-        dict: Serialised representation of the updated campaign.
-    """
-    # Assign update_data = payload.model_dump(exclude_unset=True)
+):
+    """Update a campaign. Only allowed in draft or active state."""
     update_data = payload.model_dump(exclude_unset=True)
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Assign result = crud_update(
         result = crud_update(
             db,
             campaign_id,
-            # Keyword argument: updater_id
             updater_id=current_user.id,
-            # Keyword argument: updater_role
             updater_role=current_user.role,
             **update_data,
         )
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="update_campaign",
-            # Keyword argument: entity_type
             entity_type="campaign",
-            # Keyword argument: entity_id
             entity_id=campaign_id,
-            # Keyword argument: details
             details={"updated_fields": list(update_data.keys())},
         )
-        # Call uow.commit()
         uow.commit()
 
-    # Return result
     return result
 
 
@@ -421,44 +227,22 @@ def delete_campaign(
 # ---------------------------------------------------------------------------
 
 @router.post("/{campaign_id}/tests")
-# Define function add_test_to_campaign
 def add_test_to_campaign(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: payload
     payload: AddTestPayload,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("red_lead", "blue_lead")),
-) -> dict:
-    """Add a test to a campaign with optional ordering and dependency.
-
-    Args:
-        campaign_id (str): UUID string of the target campaign.
-        payload (AddTestPayload): Test ID plus optional order index, dependency, and phase.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated red_lead or blue_lead adding the test.
-
-    Returns:
-        dict: The created campaign-test association record.
-    """
-    # Open context manager
+):
+    """Add a test to a campaign with optional ordering and dependency."""
     with UnitOfWork(db) as uow:
-        # Assign result = crud_add_test(
         result = crud_add_test(
             db,
             campaign_id,
-            # Keyword argument: test_id
             test_id=payload.test_id,
-            # Keyword argument: order_index
             order_index=payload.order_index,
-            # Keyword argument: depends_on
             depends_on=payload.depends_on,
-            # Keyword argument: phase
             phase=payload.phase,
         )
-        # Call uow.commit()
         uow.commit()
 
     return result
@@ -469,35 +253,16 @@ def add_test_to_campaign(
 # ---------------------------------------------------------------------------
 
 @router.delete("/{campaign_id}/tests/{campaign_test_id}")
-# Define function remove_test_from_campaign
 def remove_test_from_campaign(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: campaign_test_id
     campaign_test_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("red_lead", "blue_lead")),
-) -> dict:
-    """Remove a test from a campaign.
-
-    Args:
-        campaign_id (str): UUID string of the campaign.
-        campaign_test_id (str): UUID string of the campaign-test association to remove.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated red_lead or blue_lead removing the test.
-
-    Returns:
-        dict: Confirmation message with key ``detail``.
-    """
-    # Open context manager
+):
+    """Remove a test from a campaign."""
     with UnitOfWork(db) as uow:
-        # Call crud_remove_test()
         crud_remove_test(db, campaign_id, campaign_test_id)
-        # Call uow.commit()
         uow.commit()
-    # Return {"detail": "Test removed from campaign"}
     return {"detail": "Test removed from campaign"}
 
 
@@ -506,76 +271,52 @@ def remove_test_from_campaign(
 # ---------------------------------------------------------------------------
 
 @router.post("/{campaign_id}/activate")
-# Define function activate_campaign
 def activate_campaign(
-    # Entry: campaign_id
     campaign_id: str,
-    force: bool = Query(False, description="Activate even if start_date is in the future"),
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("red_lead", "blue_lead")),
 ):
     """Activate a campaign, moving it from draft to active.
 
-    If the campaign has a start_date in the future and force=False, returns a 409
-    with a warning so the frontend can show a confirmation modal. If force=True,
-    activates immediately regardless of start_date.
+    If the campaign has a start_date in the future, manual activation is blocked —
+    the campaign will be auto-activated by the scheduler when the date arrives.
     """
-    from fastapi import HTTPException
+    # Guard: start_date must have been reached before manual activation
     campaign_obj = db.query(Campaign).filter(Campaign.id == campaign_id).first()
-    if campaign_obj and campaign_obj.start_date and not force:
+    if campaign_obj and campaign_obj.start_date:
         now = datetime.utcnow()
         if campaign_obj.start_date > now:
+            from fastapi import HTTPException
             raise HTTPException(
-                status_code=409,
-                detail={
-                    "code": "start_date_in_future",
-                    "start_date": campaign_obj.start_date.strftime("%Y-%m-%d"),
-                    "message": (
-                        f"This campaign is scheduled to start on "
-                        f"{campaign_obj.start_date.strftime('%d %b %Y')}. "
-                        f"It will activate automatically on that date. "
-                        f"Do you want to activate it now anyway?"
-                    ),
-                },
+                status_code=422,
+                detail=(
+                    f"This campaign is scheduled to start on "
+                    f"{campaign_obj.start_date.strftime('%Y-%m-%d')}. "
+                    f"It will be activated automatically on that date. "
+                    f"To activate it now, remove the start date first."
+                ),
             )
 
     with UnitOfWork(db) as uow:
-        # Assign campaign = crud_activate(db, campaign_id)
         campaign = crud_activate(db, campaign_id)
-        # Call notify_role()
         notify_role(
             db,
-            # Keyword argument: role
             role="red_tech",
-            # Keyword argument: type
             type="campaign_activated",
-            # Keyword argument: title
             title="Campaign activated",
-            # Keyword argument: message
             message=f'Campaign "{campaign.name}" has been activated.',
-            # Keyword argument: entity_type
             entity_type="campaign",
-            # Keyword argument: entity_id
             entity_id=campaign.id,
         )
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="activate_campaign",
-            # Keyword argument: entity_type
             entity_type="campaign",
-            # Keyword argument: entity_id
             entity_id=campaign.id,
-            # Keyword argument: details
             details={"name": campaign.name},
         )
-        # Call uow.commit()
         uow.commit()
-    # Reload ORM object attributes from the database
     db.refresh(campaign)
 
     # Create Jira tickets for campaign and tests at activation time (non-fatal).
@@ -613,50 +354,26 @@ def activate_campaign(
 # ---------------------------------------------------------------------------
 
 @router.post("/{campaign_id}/complete")
-# Define function complete_campaign
 def complete_campaign(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("red_lead", "admin")),
-) -> dict:
-    """Mark a campaign as completed.
-
-    Args:
-        campaign_id (str): UUID string of the campaign to complete.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated red_lead or admin completing the campaign.
-
-    Returns:
-        dict: Serialised representation of the completed campaign.
-    """
-    # Open context manager
+):
+    """Mark a campaign as completed."""
     with UnitOfWork(db) as uow:
-        # Assign campaign = crud_complete(db, campaign_id)
         campaign = crud_complete(db, campaign_id)
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="complete_campaign",
-            # Keyword argument: entity_type
             entity_type="campaign",
-            # Keyword argument: entity_id
             entity_id=campaign.id,
-            # Keyword argument: details
             details={"name": campaign.name},
         )
-        # Call uow.commit()
         uow.commit()
-    # Reload ORM object attributes from the database
     db.refresh(campaign)
     dispatch_webhook("campaign.completed", {"campaign_id": str(campaign.id), "name": campaign.name})
 
-    # Return serialize_campaign(db, campaign)
     return serialize_campaign(db, campaign)
 
 
@@ -665,26 +382,12 @@ def complete_campaign(
 # ---------------------------------------------------------------------------
 
 @router.get("/{campaign_id}/progress")
-# Define function get_campaign_progress_endpoint
 def get_campaign_progress_endpoint(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
-    """Get progress statistics for a campaign.
-
-    Args:
-        campaign_id (str): UUID string of the campaign.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        dict: Progress breakdown including counts by test state and overall percentage.
-    """
-    # Return crud_get_progress(db, campaign_id)
+):
+    """Get progress statistics for a campaign."""
     return crud_get_progress(db, campaign_id)
 
 
@@ -692,63 +395,34 @@ def get_campaign_progress_endpoint(
 # POST /campaigns/from-threat-actor/{actor_id} — Auto-generate campaign
 # ---------------------------------------------------------------------------
 
-class GenerateFromActorPayload(BaseModel):
-    start_date: Optional[str] = None  # ISO date YYYY-MM-DD
-
-
 @router.post("/from-threat-actor/{actor_id}", status_code=201)
-# Define function generate_campaign_from_actor
 def generate_campaign_from_actor(
-    # Entry: actor_id
     actor_id: str,
-    payload: GenerateFromActorPayload = GenerateFromActorPayload(),
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("red_lead", "blue_lead")),
-) -> dict:
+):
     """Auto-generate a campaign from a threat actor's uncovered techniques.
 
     Creates tests from the best available templates and orders them
     by kill chain phase.
-
-    Args:
-        actor_id (str): UUID string of the threat actor to generate a campaign for.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated red_lead or blue_lead requesting the generation.
-
-    Returns:
-        dict: Serialised representation of the newly generated campaign.
     """
-    start_date_parsed = (
-        datetime.fromisoformat(payload.start_date) if payload.start_date else None
-    )
     campaign = generate_campaign_from_threat_actor(
         db,
         uuid.UUID(actor_id),
         current_user,
-        start_date=start_date_parsed,
     )
 
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="generate_campaign",
-            # Keyword argument: entity_type
             entity_type="campaign",
-            # Keyword argument: entity_id
             entity_id=campaign.id,
-            # Keyword argument: details
             details={"actor_id": actor_id, "campaign_name": campaign.name},
         )
-        # Call uow.commit()
         uow.commit()
 
-    # Return serialize_campaign(db, campaign)
     return serialize_campaign(db, campaign)
 
 
@@ -757,74 +431,41 @@ def generate_campaign_from_actor(
 # ---------------------------------------------------------------------------
 
 @router.patch("/{campaign_id}/schedule")
-# Define function schedule_campaign
 def schedule_campaign(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: payload
     payload: SchedulePayload,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("red_lead", "blue_lead")),
-) -> dict:
+):
     """Configure or update the recurrence schedule for a campaign.
 
     Only the campaign creator or admin can change scheduling.
-
-    Args:
-        campaign_id (str): UUID string of the campaign to schedule.
-        payload (SchedulePayload): Recurrence flag, pattern, and next run timestamp.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated red_lead or blue_lead (must be owner or admin).
-
-    Returns:
-        dict: Serialised representation of the campaign with updated schedule fields.
     """
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Assign campaign = crud_schedule(
         campaign = crud_schedule(
             db,
             campaign_id,
-            # Keyword argument: owner_id
             owner_id=current_user.id,
-            # Keyword argument: owner_role
             owner_role=current_user.role,
-            # Keyword argument: is_recurring
             is_recurring=payload.is_recurring,
-            # Keyword argument: recurrence_pattern
             recurrence_pattern=payload.recurrence_pattern,
-            # Keyword argument: next_run_at
             next_run_at=payload.next_run_at,
         )
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="schedule_campaign",
-            # Keyword argument: entity_type
             entity_type="campaign",
-            # Keyword argument: entity_id
             entity_id=campaign.id,
-            # Keyword argument: details
             details={
-                # Literal argument value
                 "is_recurring": campaign.is_recurring,
-                # Literal argument value
                 "recurrence_pattern": campaign.recurrence_pattern,
-                # Literal argument value
                 "next_run_at": campaign.next_run_at.isoformat() if campaign.next_run_at else None,
             },
         )
-        # Call uow.commit()
         uow.commit()
-    # Reload ORM object attributes from the database
     db.refresh(campaign)
 
-    # Return serialize_campaign(db, campaign)
     return serialize_campaign(db, campaign)
 
 
@@ -833,26 +474,12 @@ def schedule_campaign(
 # ---------------------------------------------------------------------------
 
 @router.get("/{campaign_id}/history")
-# Define function get_campaign_history
 def get_campaign_history(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list:
-    """List all child campaigns (execution history) of a recurring campaign.
-
-    Args:
-        campaign_id (str): UUID string of the parent recurring campaign.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        list: Serialised list of child campaign dicts ordered by creation date.
-    """
-    # Return crud_get_history(db, campaign_id)
+):
+    """List all child campaigns (execution history) of a recurring campaign."""
     return crud_get_history(db, campaign_id)
 
 

backend/app/routers/compliance.py

@@ -1,46 +1,32 @@
 """Compliance endpoints — framework status, reports, and gap analysis.
 
-Thin HTTP adapter that delegates all data logic to compliance_service.
+Thin HTTP adapter: delegates all data logic to compliance_service.
+
 Provides compliance posture assessment by mapping MITRE ATT&CK technique
 coverage to compliance framework controls.
 """
 
-# Import APIRouter, Depends from fastapi
 from fastapi import APIRouter, Depends
-
-# Import StreamingResponse from fastapi.responses
 from fastapi.responses import StreamingResponse
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user, require_role from app.dependencies.auth
 from app.dependencies.auth import get_current_user, require_role
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import  from app.services.compliance_import_service
+from app.services.compliance_service import (
+    list_frameworks,
+    get_framework_status,
+    build_framework_report_csv,
+    get_framework_gaps,
+)
 from app.services.compliance_import_service import (
+    import_nist_800_53_mappings,
     import_cis_controls_v8_mappings,
     import_dora_mappings,
     import_iso_27001_mappings,
     import_iso_42001_mappings,
-    import_nist_800_53_mappings,
 )
 
-# Import  from app.services.compliance_service
-from app.services.compliance_service import (
-    build_framework_report_csv,
-    get_framework_gaps,
-    get_framework_status,
-    list_frameworks,
-)
-
-# Assign router = APIRouter(prefix="/compliance", tags=["compliance"])
 router = APIRouter(prefix="/compliance", tags=["compliance"])
 
 
@@ -48,23 +34,11 @@ router = APIRouter(prefix="/compliance", tags=["compliance"])
 
 
 @router.get("/frameworks")
-# Define function list_frameworks_endpoint
 def list_frameworks_endpoint(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list:
-    """List all available compliance frameworks.
-
-    Args:
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        list: List of framework summary dicts containing id, name, and control counts.
-    """
-    # Return list_frameworks(db)
+):
+    """List all available compliance frameworks."""
     return list_frameworks(db)
 
 
@@ -72,26 +46,12 @@ def list_frameworks_endpoint(
 
 
 @router.get("/frameworks/{framework_id}/status")
-# Define function framework_status
 def framework_status(
-    # Entry: framework_id
     framework_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
-    """Get compliance status for each control in a framework.
-
-    Args:
-        framework_id (str): Identifier of the compliance framework (e.g. ``nist-800-53``).
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        dict: Mapping of control IDs to their coverage status and linked techniques.
-    """
-    # Return get_framework_status(db, framework_id)
+):
+    """Get compliance status for each control in a framework."""
     return get_framework_status(db, framework_id)
 
 
@@ -99,26 +59,12 @@ def framework_status(
 
 
 @router.get("/frameworks/{framework_id}/report")
-# Define function framework_report
 def framework_report(
-    # Entry: framework_id
     framework_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
-    """Get the full compliance report (same as status but marked as report).
-
-    Args:
-        framework_id (str): Identifier of the compliance framework.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        dict: Full compliance report with per-control coverage details.
-    """
-    # Return get_framework_status(db, framework_id)
+):
+    """Get the full compliance report (same as status but marked as report)."""
     return get_framework_status(db, framework_id)
 
 
@@ -126,35 +72,17 @@ def framework_report(
 
 
 @router.get("/frameworks/{framework_id}/report/csv")
-# Define function framework_report_csv
 def framework_report_csv(
-    # Entry: framework_id
     framework_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> StreamingResponse:
-    """Export compliance report as CSV.
-
-    Args:
-        framework_id (str): Identifier of the compliance framework to export.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        StreamingResponse: CSV file attachment with compliance coverage data.
-    """
-    # csv_bytes, filename = build_framework_report_csv(db, framework_id)
+):
+    """Export compliance report as CSV."""
     csv_bytes, filename = build_framework_report_csv(db, framework_id)
-    # Return StreamingResponse(
     return StreamingResponse(
         iter([csv_bytes]),
-        # Keyword argument: media_type
         media_type="text/csv",
-        # Keyword argument: headers
         headers={
-            # Literal argument value
             "Content-Disposition": f"attachment; filename={filename}",
         },
     )
@@ -164,26 +92,12 @@ def framework_report_csv(
 
 
 @router.get("/frameworks/{framework_id}/gaps")
-# Define function framework_gaps
 def framework_gaps(
-    # Entry: framework_id
     framework_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
-    """Get controls with techniques that are not adequately covered.
-
-    Args:
-        framework_id (str): Identifier of the compliance framework to analyse.
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated user making the request.
-
-    Returns:
-        dict: Controls flagged as gaps, with linked technique IDs and coverage ratios.
-    """
-    # Return get_framework_gaps(db, framework_id)
+):
+    """Get controls with techniques that are not adequately covered."""
     return get_framework_gaps(db, framework_id)
 
 
@@ -191,49 +105,22 @@ def framework_gaps(
 
 
 @router.post("/import/nist-800-53")
-# Define function import_nist
 def import_nist(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> dict:
-    """Import NIST 800-53 Rev 5 mappings (admin only).
-
-    Args:
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated admin user.
-
-    Returns:
-        dict: Import result with counts of created and updated control mappings.
-    """
-    # Assign result = import_nist_800_53_mappings(db)
+):
+    """Import NIST 800-53 Rev 5 mappings (admin only)."""
     result = import_nist_800_53_mappings(db)
-    # Return result
     return result
 
 
-# Apply the @router.post decorator
 @router.post("/import/cis-controls-v8")
-# Define function import_cis
 def import_cis(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> dict:
-    """Import CIS Controls v8 mappings (admin only).
-
-    Args:
-        db (Session): SQLAlchemy database session.
-        current_user (User): Authenticated admin user.
-
-    Returns:
-        dict: Import result with counts of created and updated control mappings.
-    """
-    # Assign result = import_cis_controls_v8_mappings(db)
+):
+    """Import CIS Controls v8 mappings (admin only)."""
     result = import_cis_controls_v8_mappings(db)
-    # Return result
     return result
 
 

backend/app/routers/d3fend.py

@@ -1,47 +1,26 @@
 """D3FEND endpoints — defensive technique listings, mappings, and import trigger."""
 
-# Import logging
 import logging
-
-# Import Optional from typing
 from typing import Optional
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user, require_role from app.dependencies.auth
 from app.dependencies.auth import get_current_user, require_role
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import  from app.services.d3fend_import_service
 from app.services.d3fend_import_service import (
-    import_d3fend_mappings,
     import_d3fend_techniques,
+    import_d3fend_mappings,
 )
-
-# Import  from app.services.d3fend_query_service
-from app.services.d3fend_query_service import (
-    get_defenses_for_attack_technique,
-    list_d3fend_tactics,
-)
-
-# Import  from app.services.d3fend_query_service
 from app.services.d3fend_query_service import (
     list_defensive_techniques as list_defensive_techniques_svc,
+    list_d3fend_tactics,
+    get_defenses_for_attack_technique,
 )
 
-# Assign logger = logging.getLogger(__name__)
 logger = logging.getLogger(__name__)
 
-# Assign router = APIRouter(prefix="/d3fend", tags=["d3fend"])
 router = APIRouter(prefix="/d3fend", tags=["d3fend"])
 
 
@@ -50,23 +29,15 @@ router = APIRouter(prefix="/d3fend", tags=["d3fend"])
 # ---------------------------------------------------------------------------
 
 @router.get("")
-# Define function list_defensive_techniques
 def list_defensive_techniques(
-    # Entry: tactic
     tactic: Optional[str] = Query(None),
-    # Entry: search
     search: Optional[str] = Query(None),
-    # Entry: offset
     offset: int = Query(0, ge=0),
-    # Entry: limit
     limit: int = Query(50, ge=1, le=200),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """List all D3FEND defensive techniques with optional filters."""
-    # Return list_defensive_techniques_svc(
     return list_defensive_techniques_svc(
         db, tactic=tactic, search=search, offset=offset, limit=limit
     )
@@ -77,15 +48,11 @@ def list_defensive_techniques(
 # ---------------------------------------------------------------------------
 
 @router.get("/tactics")
-# Define function list_d3fend_tactics_endpoint
 def list_d3fend_tactics_endpoint(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list:
+):
     """Return a list of all D3FEND tactics with counts."""
-    # Return list_d3fend_tactics(db)
     return list_d3fend_tactics(db)
 
 
@@ -94,17 +61,12 @@ def list_d3fend_tactics_endpoint(
 # ---------------------------------------------------------------------------
 
 @router.get("/for-technique/{mitre_id}")
-# Define function get_defenses_for_attack_technique_endpoint
 def get_defenses_for_attack_technique_endpoint(
-    # Entry: mitre_id
     mitre_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Get all D3FEND defensive techniques mapped to a given ATT&CK technique."""
-    # Return get_defenses_for_attack_technique(db, mitre_id)
     return get_defenses_for_attack_technique(db, mitre_id)
 
 
@@ -113,23 +75,15 @@ def get_defenses_for_attack_technique_endpoint(
 # ---------------------------------------------------------------------------
 
 @router.post("/import")
-# Define function trigger_d3fend_import
 def trigger_d3fend_import(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> dict:
+):
     """Import D3FEND techniques and ATT&CK mappings. Admin only."""
-    # Assign tech_result = import_d3fend_techniques(db)
     tech_result = import_d3fend_techniques(db)
-    # Assign mapping_result = import_d3fend_mappings(db)
     mapping_result = import_d3fend_mappings(db)
 
-    # Return {
     return {
-        # Literal argument value
         "techniques": tech_result,
-        # Literal argument value
         "mappings": mapping_result,
     }

backend/app/routers/data_sources.py

@@ -5,34 +5,16 @@ Provides a centralized panel for managing all external data sources
 including sync triggers, enable/disable toggles, and statistics.
 """
 
-# Import Optional from typing
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
 from typing import Optional
 
-# Import APIRouter, Depends from fastapi
-from fastapi import APIRouter, Depends
-
-# Import BaseModel from pydantic
-from pydantic import BaseModel
-
-# Import Session from sqlalchemy.orm
-from sqlalchemy.orm import Session
-
-# Import get_db from app.database
 from app.database import get_db
-
-# Import require_role from app.dependencies.auth
 from app.dependencies.auth import require_role
-
-# Import UnitOfWork from app.domain.unit_of_work
 from app.domain.unit_of_work import UnitOfWork
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import log_action from app.services.audit_service
 from app.services.audit_service import log_action
-
-# Import  from app.services.data_source_service
 from app.services.data_source_service import (
     get_source_stats,
     list_sources,
@@ -41,21 +23,18 @@ from app.services.data_source_service import (
     update_source,
 )
 
+
 # ---------------------------------------------------------------------------
 # Pydantic schemas for request validation
 # ---------------------------------------------------------------------------
 
 class DataSourceUpdate(BaseModel):
     """Payload for updating a data source — only allowed fields."""
-    # Assign is_enabled = None
     is_enabled: Optional[bool] = None
-    # Assign sync_frequency = None
     sync_frequency: Optional[str] = None
-    # Assign config = None
     config: Optional[dict] = None
 
 
-# Assign router = APIRouter(prefix="/data-sources", tags=["data-sources"])
 router = APIRouter(prefix="/data-sources", tags=["data-sources"])
 
 
@@ -65,137 +44,90 @@ router = APIRouter(prefix="/data-sources", tags=["data-sources"])
 
 
 @router.get("")
-# Define function list_data_sources
 def list_data_sources(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> list:
+):
     """List all registered data sources.
 
     **Requires** the ``admin`` role.
     """
-    # Return list_sources(db)
     return list_sources(db)
 
 
-# Apply the @router.patch decorator
 @router.patch("/{source_id}")
-# Define function update_data_source
 def update_data_source(
-    # Entry: source_id
     source_id: str,
-    # Entry: body
     body: DataSourceUpdate,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> dict:
+):
     """Update a data source (enable/disable, change config).
 
     **Requires** the ``admin`` role.
     """
-    # Assign update_data = body.model_dump(exclude_unset=True)
     update_data = body.model_dump(exclude_unset=True)
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Call update_source()
         update_source(db, source_id, **update_data)
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="update_data_source",
-            # Keyword argument: entity_type
             entity_type="data_source",
-            # Keyword argument: entity_id
             entity_id=source_id,
-            # Keyword argument: details
             details={"updates": update_data},
         )
-        # Call uow.commit()
         uow.commit()
 
-    # Return {"message": "Data source updated", "id": source_id}
     return {"message": "Data source updated", "id": source_id}
 
 
-# Apply the @router.post decorator
 @router.post("/{source_id}/sync")
-# Define function sync_data_source
 def sync_data_source(
-    # Entry: source_id
     source_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> dict:
+):
     """Trigger sync/import for a specific data source.
 
     **Requires** the ``admin`` role.
     """
-    # Return sync_source(db, source_id)
     return sync_source(db, source_id)
 
 
-# Apply the @router.post decorator
 @router.post("/sync-all")
-# Define function sync_all_data_sources
 def sync_all_data_sources(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> dict:
+):
     """Trigger sync for all enabled data sources (sequentially).
 
     **Requires** the ``admin`` role.
     """
-    # Assign results = sync_all_sources(db)
     results = sync_all_sources(db)
 
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="sync_all_data_sources",
-            # Keyword argument: entity_type
             entity_type="data_source",
-            # Keyword argument: entity_id
             entity_id=None,
-            # Keyword argument: details
             details={"results": results},
         )
-        # Call uow.commit()
         uow.commit()
 
-    # Return {"message": "Sync all complete", "results": results}
     return {"message": "Sync all complete", "results": results}
 
 
-# Apply the @router.get decorator
 @router.get("/{source_id}/stats")
-# Define function get_data_source_stats
 def get_data_source_stats(
-    # Entry: source_id
     source_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> dict:
+):
     """Get detailed statistics for a specific data source.
 
     **Requires** the ``admin`` role.
     """
-    # Return get_source_stats(db, source_id)
     return get_source_stats(db, source_id)

backend/app/routers/detection_rules.py

@@ -6,55 +6,36 @@ Provides endpoints for browsing detection rules, querying rules by technique,
 and managing the template ↔ detection rule associations.
 """
 
-# Import uuid
 import uuid
-
-# Import Optional from typing
 from typing import Optional
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import BaseModel from pydantic
 from pydantic import BaseModel
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user, require_any_role, require_role from app.dependencies.auth
-from app.dependencies.auth import get_current_user, require_any_role, require_role
-
-# Import User from app.models.user
+from app.dependencies.auth import get_current_user, require_role, require_any_role
 from app.models.user import User
-
-# Import  from app.services.detection_rule_service
 from app.services.detection_rule_service import (
-    auto_associate_rules,
-    evaluate_rule,
-    get_rules_for_template,
-    get_rules_for_test,
     list_rules,
+    get_rules_for_template,
+    auto_associate_rules,
+    get_rules_for_test,
+    evaluate_rule,
 )
 
+
 # ── Pydantic schemas for request validation ────────────────────────────
 
 
 class DetectionRuleEvaluate(BaseModel):
     """Payload for evaluating a detection rule against a test."""
-    # test_id: uuid.UUID
     test_id: uuid.UUID
-    # detection_rule_id: uuid.UUID
     detection_rule_id: uuid.UUID
-    # Assign triggered = None
     triggered: Optional[bool] = None
-    # Assign notes = None
     notes: Optional[str] = None
 
 
-# Assign router = APIRouter(prefix="/detection-rules", tags=["detection-rules"])
 router = APIRouter(prefix="/detection-rules", tags=["detection-rules"])
 
 
@@ -62,40 +43,24 @@ router = APIRouter(prefix="/detection-rules", tags=["detection-rules"])
 
 
 @router.get("")
-# Define function list_detection_rules
 def list_detection_rules(
-    # Entry: technique
     technique: Optional[str] = Query(None, description="Filter by MITRE technique ID"),
-    # Entry: source
     source: Optional[str] = Query(None, description="Filter by source (sigma, elastic, splunk, custom)"),
-    # Entry: severity
     severity: Optional[str] = Query(None),
-    # Entry: search
     search: Optional[str] = Query(None),
-    # Entry: offset
     offset: int = Query(0, ge=0),
-    # Entry: limit
     limit: int = Query(50, ge=1, le=200),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """List detection rules with optional filters and pagination."""
-    # Return list_rules(
     return list_rules(
         db,
-        # Keyword argument: technique
         technique=technique,
-        # Keyword argument: source
         source=source,
-        # Keyword argument: severity
         severity=severity,
-        # Keyword argument: search
         search=search,
-        # Keyword argument: offset
         offset=offset,
-        # Keyword argument: limit
         limit=limit,
     )
 
@@ -104,17 +69,12 @@ def list_detection_rules(
 
 
 @router.get("/for-template/{template_id}")
-# Define function get_detection_rules_for_template
 def get_detection_rules_for_template(
-    # Entry: template_id
     template_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Get detection rules associated with a test template."""
-    # Return get_rules_for_template(db, template_id)
     return get_rules_for_template(db, template_id)
 
 
@@ -122,20 +82,16 @@ def get_detection_rules_for_template(
 
 
 @router.post("/auto-associate")
-# Define function auto_associate_detection_rules
 def auto_associate_detection_rules(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_role("admin")),
-) -> dict:
+):
     """Auto-associate test templates with detection rules by MITRE technique ID.
 
     For each active template, find all active detection rules for the same
     technique and create associations. Rules with severity >= high are marked
     as primary.
     """
-    # Return auto_associate_rules(db)
     return auto_associate_rules(db)
 
 
@@ -143,21 +99,16 @@ def auto_associate_detection_rules(
 
 
 @router.get("/for-test/{test_id}")
-# Define function get_detection_rules_for_test
 def get_detection_rules_for_test(
-    # Entry: test_id
     test_id: str,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Get detection rules relevant to a test, along with their evaluation results.
 
     Finds rules by matching the test's technique_id to detection rules,
     and returns any existing evaluation results.
     """
-    # Return get_rules_for_test(db, test_id)
     return get_rules_for_test(db, test_id)
 
 
@@ -165,27 +116,17 @@ def get_detection_rules_for_test(
 
 
 @router.post("/evaluate")
-# Define function evaluate_detection_rule
 def evaluate_detection_rule(
-    # Entry: payload
     payload: DetectionRuleEvaluate,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(require_any_role("blue_tech", "blue_lead")),
-) -> dict:
+):
     """Save or update the evaluation result for a detection rule on a test."""
-    # Return evaluate_rule(
     return evaluate_rule(
         db,
-        # Keyword argument: test_id
         test_id=payload.test_id,
-        # Keyword argument: detection_rule_id
         detection_rule_id=payload.detection_rule_id,
-        # Keyword argument: triggered
         triggered=payload.triggered,
-        # Keyword argument: notes
         notes=payload.notes,
-        # Keyword argument: evaluator_id
         evaluator_id=current_user.id,
     )

backend/app/routers/evidence.py

@@ -20,63 +20,39 @@ Access Control
   ``validated``, or ``rejected``.
 """
 
-# Import hashlib
 import hashlib
 import logging
 import os
-
-# Import uuid
 import uuid as _uuid
 from datetime import datetime
 from typing import Optional
 
-# Import APIRouter, Depends, File, Form, Query, Request,... from fastapi
 from fastapi import APIRouter, Depends, File, Form, Query, Request, UploadFile, status
 from fastapi.responses import StreamingResponse
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user from app.dependencies.auth
-from app.dependencies.auth import get_current_user
-
-# Import UnitOfWork from app.domain.unit_of_work
 from app.domain.unit_of_work import UnitOfWork
-
-# Import limiter from app.limiter
-from app.limiter import limiter
-
-# Import TeamSide from app.models.enums
+from app.dependencies.auth import get_current_user
 from app.models.enums import TeamSide
-
-# Import Evidence from app.models.evidence
 from app.models.evidence import Evidence
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import EvidenceOut from app.schemas.evidence
 from app.schemas.evidence import EvidenceOut
-
-# Import log_action from app.services.audit_service
 from app.services.audit_service import log_action
-
-# Import  from app.services.evidence_service
 from app.services.evidence_service import (
-    MAX_UPLOAD_SIZE,
     get_evidence_or_raise,
     get_test_or_raise,
     list_evidence_for_test,
+    MAX_UPLOAD_SIZE,
     validate_delete_permission,
     validate_file,
     validate_upload_permission,
 )
+from app.limiter import limiter
 from app.storage import download_file, upload_file
 
 logger = logging.getLogger(__name__)
 
-# Assign router = APIRouter(tags=["evidence"])
 router = APIRouter(tags=["evidence"])
 
 
@@ -91,21 +67,13 @@ def _evidence_to_out(evidence: Evidence) -> EvidenceOut:
     never needs direct access to MinIO.
     """
     return EvidenceOut(
-        # Keyword argument: id
         id=evidence.id,
-        # Keyword argument: test_id
         test_id=evidence.test_id,
-        # Keyword argument: file_name
         file_name=evidence.file_name,
-        # Keyword argument: sha256_hash
         sha256_hash=evidence.sha256_hash,
-        # Keyword argument: uploaded_by
         uploaded_by=evidence.uploaded_by,
-        # Keyword argument: uploaded_at
         uploaded_at=evidence.uploaded_at,
-        # Keyword argument: team
         team=evidence.team,
-        # Keyword argument: notes
         notes=evidence.notes,
         download_url=f"/api/v1/evidence/{evidence.id}/file",
     )
@@ -117,47 +85,30 @@ def _evidence_to_out(evidence: Evidence) -> EvidenceOut:
 
 
 @router.post(
-    # Literal argument value
     "/tests/{test_id}/evidence",
-    # Keyword argument: response_model
     response_model=EvidenceOut,
-    # Keyword argument: status_code
     status_code=status.HTTP_201_CREATED,
 )
-# Apply the @limiter.limit decorator
 @limiter.limit("10/minute")
-# Define async function upload_evidence
 async def upload_evidence(
-    # Entry: request
     request: Request,
-    # Entry: test_id
     test_id: _uuid.UUID,
-    # Entry: file
     file: UploadFile = File(...),
-    # Entry: team
     team: TeamSide = Form(TeamSide.red),
-    # Entry: notes
     notes: Optional[str] = Form(None),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> EvidenceOut:
+):
     """Upload a file as evidence for the given test.
 
     The ``team`` field (sent as form data) determines whether this is
     Red Team (attack) or Blue Team (detection) evidence.
     """
-    # Assign test = get_test_or_raise(db, test_id)
     test = get_test_or_raise(db, test_id)
-    # Call validate_upload_permission()
     validate_upload_permission(test, team, current_user.role)
 
-    # Assign file_name = file.filename or "unnamed"
     file_name = file.filename or "unnamed"
-    # Assign content = await file.read(MAX_UPLOAD_SIZE + 1)
     content = await file.read(MAX_UPLOAD_SIZE + 1)
-    # Call validate_file()
     validate_file(file_name, len(content))
 
     # Hash
@@ -165,7 +116,6 @@ async def upload_evidence(
 
     # 4. Object key (sanitise filename to prevent path traversal in storage)
     safe_name = os.path.basename(file_name)
-    # Assign key = f"{test_id}/{_uuid.uuid4()}_{safe_name}"
     key = f"{test_id}/{_uuid.uuid4()}_{safe_name}"
 
     # 5. Upload to MinIO
@@ -173,53 +123,32 @@ async def upload_evidence(
 
     # 6. Persist metadata and audit
     with UnitOfWork(db) as uow:
-        # Assign evidence = Evidence(
         evidence = Evidence(
-            # Keyword argument: test_id
             test_id=test_id,
-            # Keyword argument: file_name
             file_name=safe_name,
-            # Keyword argument: file_path
             file_path=key,
-            # Keyword argument: sha256_hash
             sha256_hash=sha256,
-            # Keyword argument: uploaded_by
             uploaded_by=current_user.id,
             uploaded_at=datetime.utcnow(),  # set explicitly — DB column has no server default
             team=team,
-            # Keyword argument: notes
             notes=notes,
         )
-        # Stage new record(s) for database insertion
         db.add(evidence)
-        # Flush changes to DB without committing the transaction
         db.flush()  # Get evidence.id for audit
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="upload_evidence",
-            # Keyword argument: entity_type
             entity_type="evidence",
-            # Keyword argument: entity_id
             entity_id=evidence.id,
-            # Keyword argument: details
             details={
-                # Literal argument value
                 "file_name": safe_name,
-                # Literal argument value
                 "sha256": sha256,
-                # Literal argument value
                 "test_id": str(test_id),
-                # Literal argument value
                 "team": team.value,
             },
         )
-        # Call uow.commit()
         uow.commit()
-    # Reload ORM object attributes from the database
     db.refresh(evidence)
 
     # 7. Attach to Jira ticket if one exists (non-fatal)
@@ -265,23 +194,15 @@ def _attach_evidence_to_jira(
 
 
 @router.get("/tests/{test_id}/evidence", response_model=list[EvidenceOut])
-# Define function list_evidence
 def list_evidence(
-    # Entry: test_id
     test_id: _uuid.UUID,
-    # Entry: team
     team: Optional[str] = Query(None, description="Filter by team: red or blue"),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list[EvidenceOut]:
+):
     """List all evidences for a test, optionally filtered by team."""
-    # Call get_test_or_raise()
     get_test_or_raise(db, test_id)
-    # Assign evidences = list_evidence_for_test(db, test_id, team=team)
     evidences = list_evidence_for_test(db, test_id, team=team)
-    # Return [_evidence_to_out(e) for e in evidences]
     return [_evidence_to_out(e) for e in evidences]
 
 
@@ -291,18 +212,13 @@ def list_evidence(
 
 
 @router.get("/evidence/{evidence_id}", response_model=EvidenceOut)
-# Define function get_evidence
 def get_evidence(
-    # Entry: evidence_id
     evidence_id: _uuid.UUID,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
 ):
     """Return evidence metadata. ``download_url`` is a backend proxy URL."""
     evidence = get_evidence_or_raise(db, evidence_id)
-    # Return _evidence_to_out(evidence)
     return _evidence_to_out(evidence)
 
 
@@ -349,15 +265,11 @@ def download_evidence_file(
 
 
 @router.delete("/evidence/{evidence_id}", status_code=status.HTTP_200_OK)
-# Define function delete_evidence
 def delete_evidence(
-    # Entry: evidence_id
     evidence_id: _uuid.UUID,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Delete an evidence record.
 
     Only allowed in editable states:
@@ -365,40 +277,24 @@ def delete_evidence(
     - Blue evidence: ``blue_evaluating``
     - No deletions in ``in_review``, ``validated``, ``rejected``
     """
-    # Assign evidence = get_evidence_or_raise(db, evidence_id)
     evidence = get_evidence_or_raise(db, evidence_id)
-    # Assign test = get_test_or_raise(db, evidence.test_id)
     test = get_test_or_raise(db, evidence.test_id)
-    # Call validate_delete_permission()
     validate_delete_permission(test, evidence, current_user.role, current_user.id)
 
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Call log_action()
         log_action(
             db,
-            # Keyword argument: user_id
             user_id=current_user.id,
-            # Keyword argument: action
             action="delete_evidence",
-            # Keyword argument: entity_type
             entity_type="evidence",
-            # Keyword argument: entity_id
             entity_id=evidence.id,
-            # Keyword argument: details
             details={
-                # Literal argument value
                 "file_name": evidence.file_name,
-                # Literal argument value
                 "test_id": str(evidence.test_id),
-                # Literal argument value
                 "team": evidence.team.value if evidence.team else None,
             },
         )
-        # Mark record for deletion on next commit
         db.delete(evidence)
-        # Call uow.commit()
         uow.commit()
 
-    # Return {"detail": "Evidence deleted"}
     return {"detail": "Evidence deleted"}

backend/app/routers/executive_dashboard.py

@@ -1,6 +1,7 @@
 """Phase 13: Executive Dashboard router."""
 
-from typing import List
+from typing import List, Optional
+from uuid import UUID
 
 from fastapi import APIRouter, Depends, Query
 from sqlalchemy.orm import Session

backend/app/routers/heatmap.py

@@ -5,169 +5,101 @@ No business logic lives here — only request validation and response
 formatting.
 """
 
-# Import io
 import io
-
-# Import json
 import json
-
-# Import Optional from typing
 from typing import Optional
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import StreamingResponse from fastapi.responses
 from fastapi.responses import StreamingResponse
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user from app.dependencies.auth
 from app.dependencies.auth import get_current_user
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import heatmap_service from app.services
 from app.services import heatmap_service
 
-# Assign router = APIRouter(prefix="/heatmap", tags=["heatmap"])
 router = APIRouter(prefix="/heatmap", tags=["heatmap"])
 
 
-# Apply the @router.get decorator
 @router.get("/coverage")
-# Define function heatmap_coverage
 def heatmap_coverage(
-    # Entry: platforms
     platforms: Optional[str] = Query(None, description="Comma-separated platforms"),
-    # Entry: tactics
     tactics: Optional[str] = Query(None, description="Comma-separated tactics"),
-    # Entry: min_score
     min_score: int = Query(0, ge=0, le=100),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Coverage layer — score based on status_global of each technique."""
-    # Return heatmap_service.build_coverage_layer(
     return heatmap_service.build_coverage_layer(
         db, platforms=platforms, tactics=tactics, min_score=min_score,
     )
 
 
-# Apply the @router.get decorator
 @router.get("/threat-actor/{actor_id}")
-# Define function heatmap_threat_actor
 def heatmap_threat_actor(
-    # Entry: actor_id
     actor_id: str,
-    # Entry: platforms
     platforms: Optional[str] = Query(None),
-    # Entry: tactics
     tactics: Optional[str] = Query(None),
-    # Entry: min_score
     min_score: int = Query(0, ge=0, le=100),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Threat actor layer — techniques used by an actor with coverage color."""
-    # Return heatmap_service.build_threat_actor_layer(
     return heatmap_service.build_threat_actor_layer(
         db, actor_id, platforms=platforms, tactics=tactics, min_score=min_score,
     )
 
 
-# Apply the @router.get decorator
 @router.get("/detection-rules")
-# Define function heatmap_detection_rules
 def heatmap_detection_rules(
-    # Entry: platforms
     platforms: Optional[str] = Query(None),
-    # Entry: tactics
     tactics: Optional[str] = Query(None),
-    # Entry: min_score
     min_score: int = Query(0, ge=0, le=100),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Detection rules layer — score based on ratio of rules available vs total."""
-    # Return heatmap_service.build_detection_rules_layer(
     return heatmap_service.build_detection_rules_layer(
         db, platforms=platforms, tactics=tactics, min_score=min_score,
     )
 
 
-# Apply the @router.get decorator
 @router.get("/campaign/{campaign_id}")
-# Define function heatmap_campaign
 def heatmap_campaign(
-    # Entry: campaign_id
     campaign_id: str,
-    # Entry: platforms
     platforms: Optional[str] = Query(None),
-    # Entry: tactics
     tactics: Optional[str] = Query(None),
-    # Entry: min_score
     min_score: int = Query(0, ge=0, le=100),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Campaign layer — only techniques in the campaign, colored by test state."""
-    # Return heatmap_service.build_campaign_layer(
     return heatmap_service.build_campaign_layer(
         db, campaign_id, platforms=platforms, tactics=tactics, min_score=min_score,
     )
 
 
-# Apply the @router.get decorator
 @router.get("/export-navigator")
-# Define function export_navigator
 def export_navigator(
-    # Entry: layer
     layer: str = Query(..., description="Layer type: coverage, threat-actor, detection-rules, campaign"),
-    # Entry: layer_id
     layer_id: Optional[str] = Query(None, description="Actor ID or Campaign ID (if applicable)"),
-    # Entry: platforms
     platforms: Optional[str] = Query(None),
-    # Entry: tactics
     tactics: Optional[str] = Query(None),
-    # Entry: min_score
     min_score: int = Query(0, ge=0, le=100),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> StreamingResponse:
+):
     """Export a heatmap layer as a downloadable JSON file for ATT&CK Navigator."""
-    # Assign data = heatmap_service.build_navigator_export(
     data = heatmap_service.build_navigator_export(
         db, layer, layer_id=layer_id,
-        # Keyword argument: platforms
         platforms=platforms, tactics=tactics, min_score=min_score,
     )
 
-    # Assign json_content = json.dumps(data, indent=2, default=str)
     json_content = json.dumps(data, indent=2, default=str)
-    # Assign buffer = io.BytesIO(json_content.encode("utf-8"))
     buffer = io.BytesIO(json_content.encode("utf-8"))
 
-    # Return StreamingResponse(
     return StreamingResponse(
         buffer,
-        # Keyword argument: media_type
         media_type="application/json",
-        # Keyword argument: headers
         headers={"Content-Disposition": f"attachment; filename=aegis_{layer}_layer.json"},
     )

backend/app/routers/jira.py

@@ -1,235 +1,138 @@
 """Jira integration router — link, search, sync, create issues."""
 
-# Import logging
 import logging
-
-# Import Optional from typing
 from typing import Optional
-
-# Import UUID from uuid
 from uuid import UUID
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user, require_role from app.dependencies.auth
 from app.dependencies.auth import get_current_user, require_role
-
-# Import UnitOfWork from app.domain.unit_of_work
 from app.domain.unit_of_work import UnitOfWork
-
-# Import JiraLinkEntityType from app.models.jira_link
 from app.models.jira_link import JiraLinkEntityType
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import  from app.schemas.jira_schema
 from app.schemas.jira_schema import (
     JiraIssueResult,
     JiraLinkCreate,
     JiraLinkOut,
 )
+from app.services import jira_service, audit_service
 
-# Import audit_service, jira_service from app.services
-from app.services import audit_service, jira_service
-
-# Assign logger = logging.getLogger(__name__)
 logger = logging.getLogger(__name__)
 
-# Assign router = APIRouter(prefix="/jira", tags=["jira"])
 router = APIRouter(prefix="/jira", tags=["jira"])
 
 
-# Apply the @router.get decorator
 @router.get("/search", response_model=list[JiraIssueResult])
-# Define function search_issues
 def search_issues(
-    # Entry: q
     q: str = Query(..., min_length=2),
-    # Entry: max_results
     max_results: int = Query(10, le=50),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> list[JiraIssueResult]:
+):
     """Search Jira issues by JQL or free text."""
-    # Return jira_service.search_jira_issues(q, max_results)
     return jira_service.search_jira_issues(q, max_results)
 
 
-# Apply the @router.post decorator
 @router.post("/links", response_model=JiraLinkOut, status_code=201)
-# Define function create_link
 def create_link(
-    # Entry: body
     body: JiraLinkCreate,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> JiraLinkOut:
+):
     """Associate an Aegis entity with a Jira issue."""
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Assign link = jira_service.create_link(
         link = jira_service.create_link(
             db,
-            # Keyword argument: entity_type
             entity_type=body.entity_type,
-            # Keyword argument: entity_id
             entity_id=body.entity_id,
-            # Keyword argument: jira_issue_key
             jira_issue_key=body.jira_issue_key,
-            # Keyword argument: sync_direction
             sync_direction=body.sync_direction,
-            # Keyword argument: created_by
             created_by=user.id,
         )
-        # Call audit_service.log_action()
         audit_service.log_action(
             db,
-            # Keyword argument: user_id
             user_id=user.id,
-            # Keyword argument: action
             action="JIRA_LINK_CREATED",
-            # Keyword argument: entity_type
             entity_type="jira_link",
-            # Keyword argument: entity_id
             entity_id=str(link.id),
-            # Keyword argument: details
             details={
-                # Literal argument value
                 "linked_entity_type": body.entity_type.value,
-                # Literal argument value
                 "linked_entity_id": str(body.entity_id),
-                # Literal argument value
                 "jira_issue_key": body.jira_issue_key,
             },
         )
-        # Call uow.commit()
         uow.commit()
-    # Reload ORM object attributes from the database
     db.refresh(link)
 
-    # Return link
     return link
 
 
-# Apply the @router.get decorator
 @router.get("/links", response_model=list[JiraLinkOut])
-# Define function list_links
 def list_links(
-    # Entry: entity_type
     entity_type: Optional[JiraLinkEntityType] = None,
-    # Entry: entity_id
     entity_id: Optional[UUID] = None,
     entity_ids: Optional[list[UUID]] = Query(default=None, description="Filter by multiple entity IDs"),
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
 ):
     """List Jira links, optionally filtered by entity or a list of entity IDs."""
     return jira_service.list_links(
         db,
-        # Keyword argument: entity_type
         entity_type=entity_type,
-        # Keyword argument: entity_id
         entity_id=entity_id,
         entity_ids=entity_ids,
     )
 
 
-# Apply the @router.post decorator
 @router.post("/links/{link_id}/sync")
-# Define function sync_link
 def sync_link(
-    # Entry: link_id
     link_id: UUID,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(require_role("admin")),
-) -> dict:
+):
     """Force bidirectional sync for a specific Jira link."""
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Assign link = jira_service.get_link_or_raise(db, link_id)
         link = jira_service.get_link_or_raise(db, link_id)
-        # Call jira_service.sync_jira_to_aegis()
         jira_service.sync_jira_to_aegis(db, link)
-        # Call uow.commit()
         uow.commit()
-    # Return {"message": "Sync completed", "jira_status": link.jira_status}
     return {"message": "Sync completed", "jira_status": link.jira_status}
 
 
-# Apply the @router.delete decorator
 @router.delete("/links/{link_id}", status_code=204)
-# Define function delete_link
 def delete_link(
-    # Entry: link_id
     link_id: UUID,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> None:
+):
     """Remove a Jira link."""
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Assign link = jira_service.delete_link(db, link_id)
         link = jira_service.delete_link(db, link_id)
-        # Call audit_service.log_action()
         audit_service.log_action(
             db,
-            # Keyword argument: user_id
             user_id=user.id,
-            # Keyword argument: action
             action="jira_link_deleted",
-            # Keyword argument: entity_type
             entity_type="jira_link",
-            # Keyword argument: entity_id
             entity_id=str(link_id),
-            # Keyword argument: details
             details={"jira_issue_key": link.jira_issue_key},
         )
-        # Call uow.commit()
         uow.commit()
 
 
-# Apply the @router.post decorator
 @router.post("/create-issue")
-# Define function create_issue_from_entity
 def create_issue_from_entity(
-    # Entry: entity_type
     entity_type: JiraLinkEntityType,
-    # Entry: entity_id
     entity_id: UUID,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> dict:
+):
     """Auto-create a Jira issue from an Aegis entity and link them."""
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Assign result = jira_service.create_issue_and_link(
         result = jira_service.create_issue_and_link(
             db,
-            # Keyword argument: entity_type
             entity_type=entity_type,
-            # Keyword argument: entity_id
             entity_id=entity_id,
-            # Keyword argument: created_by
             created_by=user.id,
         )
-        # Call uow.commit()
         uow.commit()
-    # Return result
     return result

backend/app/routers/knowledge.py

@@ -3,7 +3,7 @@
 from typing import List, Optional
 from uuid import UUID
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, Query
 from sqlalchemy.orm import Session
 
 from app.database import get_db

backend/app/routers/metrics.py

@@ -7,22 +7,12 @@ validation-rate endpoints for the Red/Blue workflow.
 Thin HTTP adapter: delegates all data logic to metrics_query_service.
 """
 
-# Import APIRouter, Depends from fastapi
 from fastapi import APIRouter, Depends
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user from app.dependencies.auth
 from app.dependencies.auth import get_current_user
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import  from app.schemas.metrics
 from app.schemas.metrics import (
     CoverageSummary,
     RecentTestItem,
@@ -31,8 +21,6 @@ from app.schemas.metrics import (
     TestPipelineCounts,
     ValidationRate,
 )
-
-# Import  from app.services.metrics_query_service
 from app.services.metrics_query_service import (
     get_coverage_by_tactic,
     get_coverage_summary,
@@ -42,7 +30,6 @@ from app.services.metrics_query_service import (
     get_validation_rate,
 )
 
-# Assign router = APIRouter(prefix="/metrics", tags=["metrics"])
 router = APIRouter(prefix="/metrics", tags=["metrics"])
 
 
@@ -52,15 +39,11 @@ router = APIRouter(prefix="/metrics", tags=["metrics"])
 
 
 @router.get("/summary", response_model=CoverageSummary)
-# Define function coverage_summary
 def coverage_summary(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> CoverageSummary:
+):
     """Return a global coverage summary across all techniques."""
-    # Return get_coverage_summary(db)
     return get_coverage_summary(db)
 
 
@@ -70,15 +53,11 @@ def coverage_summary(
 
 
 @router.get("/by-tactic", response_model=list[TacticCoverage])
-# Define function coverage_by_tactic
 def coverage_by_tactic(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list[TacticCoverage]:
+):
     """Return coverage breakdown grouped by tactic."""
-    # Return get_coverage_by_tactic(db)
     return get_coverage_by_tactic(db)
 
 
@@ -88,15 +67,11 @@ def coverage_by_tactic(
 
 
 @router.get("/test-pipeline", response_model=TestPipelineCounts)
-# Define function test_pipeline
 def test_pipeline(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> TestPipelineCounts:
+):
     """Return how many tests are in each pipeline state."""
-    # Return get_test_pipeline_counts(db)
     return get_test_pipeline_counts(db)
 
 
@@ -106,15 +81,11 @@ def test_pipeline(
 
 
 @router.get("/team-activity", response_model=list[TeamActivity])
-# Define function team_activity
 def team_activity(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list[TeamActivity]:
+):
     """Return activity summary for Red and Blue teams."""
-    # Return get_team_activity(db)
     return get_team_activity(db)
 
 
@@ -124,15 +95,11 @@ def team_activity(
 
 
 @router.get("/validation-rate", response_model=list[ValidationRate])
-# Define function validation_rate
 def validation_rate(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list[ValidationRate]:
+):
     """Return approval and rejection rates for Red Lead and Blue Lead."""
-    # Return get_validation_rate(db)
     return get_validation_rate(db)
 
 
@@ -142,13 +109,9 @@ def validation_rate(
 
 
 @router.get("/recent-tests", response_model=list[RecentTestItem])
-# Define function recent_tests
 def recent_tests(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list[RecentTestItem]:
+):
     """Return the 10 most recently created tests."""
-    # Return get_recent_tests(db, limit=10)
     return get_recent_tests(db, limit=10)

backend/app/routers/notifications.py

@@ -8,39 +8,23 @@ PATCH  /notifications/{id}/read   — mark one notification as read
 POST   /notifications/read-all    — mark all as read
 """
 
-# Import uuid
 import uuid
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user from app.dependencies.auth
 from app.dependencies.auth import get_current_user
-
-# Import UnitOfWork from app.domain.unit_of_work
 from app.domain.unit_of_work import UnitOfWork
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import NotificationOut, UnreadCountOut from app.schemas.notification
 from app.schemas.notification import NotificationOut, UnreadCountOut
-
-# Import  from app.services.notification_service
 from app.services.notification_service import (
-    get_unread_count,
     list_notifications,
-    mark_all_as_read,
     mark_as_read,
+    mark_all_as_read,
+    get_unread_count,
 )
 
-# Assign router = APIRouter(prefix="/notifications", tags=["notifications"])
 router = APIRouter(prefix="/notifications", tags=["notifications"])
 
 
@@ -50,19 +34,13 @@ router = APIRouter(prefix="/notifications", tags=["notifications"])
 
 
 @router.get("", response_model=list[NotificationOut])
-# Define function list_notifications_endpoint
 def list_notifications_endpoint(
-    # Entry: offset
     offset: int = Query(0, ge=0),
-    # Entry: limit
     limit: int = Query(20, ge=1, le=100),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> list[NotificationOut]:
+):
     """Return paginated notifications for the current user, newest first."""
-    # Return list_notifications(db, current_user.id, offset=offset, limit=limit)
     return list_notifications(db, current_user.id, offset=offset, limit=limit)
 
 
@@ -72,17 +50,12 @@ def list_notifications_endpoint(
 
 
 @router.get("/unread-count", response_model=UnreadCountOut)
-# Define function unread_count
 def unread_count(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> UnreadCountOut:
+):
     """Return the number of unread notifications for the current user."""
-    # Assign count = get_unread_count(db, current_user.id)
     count = get_unread_count(db, current_user.id)
-    # Return UnreadCountOut(unread_count=count)
     return UnreadCountOut(unread_count=count)
 
 
@@ -92,23 +65,15 @@ def unread_count(
 
 
 @router.patch("/{notification_id}/read", response_model=NotificationOut)
-# Define function read_notification
 def read_notification(
-    # Entry: notification_id
     notification_id: uuid.UUID,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> NotificationOut:
+):
     """Mark a single notification as read."""
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Assign notif = mark_as_read(db, notification_id, current_user.id)
         notif = mark_as_read(db, notification_id, current_user.id)
-        # Call uow.commit()
         uow.commit()
-    # Return notif
     return notif
 
 
@@ -118,19 +83,12 @@ def read_notification(
 
 
 @router.post("/read-all")
-# Define function read_all_notifications
 def read_all_notifications(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Mark all notifications for the current user as read."""
-    # Open context manager
     with UnitOfWork(db) as uow:
-        # Assign count = mark_all_as_read(db, current_user.id)
         count = mark_all_as_read(db, current_user.id)
-        # Call uow.commit()
         uow.commit()
-    # Return {"detail": f"Marked {count} notifications as read"}
     return {"detail": f"Marked {count} notifications as read"}

backend/app/routers/operational_metrics.py

@@ -4,28 +4,18 @@ Provides operational KPIs for security teams with trend analysis
 and team-level breakdowns.
 """
 
-# Import APIRouter, Depends, Query from fastapi
 from fastapi import APIRouter, Depends, Query
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user from app.dependencies.auth
 from app.dependencies.auth import get_current_user
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import  from app.services.operational_metrics_service
 from app.services.operational_metrics_service import (
-    get_metrics_by_team,
+    get_all_operational_metrics,
     get_operational_trend,
+    get_metrics_by_team,
 )
 
-# Assign router = APIRouter(prefix="/metrics/operational", tags=["operational-metrics"])
 router = APIRouter(prefix="/metrics/operational", tags=["operational-metrics"])
 
 
@@ -33,18 +23,13 @@ router = APIRouter(prefix="/metrics/operational", tags=["operational-metrics"])
 
 
 @router.get("")
-# Define function operational_metrics
 def operational_metrics(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Get all operational metrics (MTTD, MTTR, etc.) — cached for 5 min."""
-    # Import get_operational_metrics_cached from app.services.score_cache
     from app.services.score_cache import get_operational_metrics_cached
 
-    # Return get_operational_metrics_cached(db)
     return get_operational_metrics_cached(db)
 
 
@@ -52,17 +37,12 @@ def operational_metrics(
 
 
 @router.get("/trend")
-# Define function operational_trend
 def operational_trend(
-    # Entry: period
     period: str = Query("90d", pattern="^(30d|90d|1y)$"),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Get weekly trend data for operational metrics."""
-    # Return get_operational_trend(db, period)
     return get_operational_trend(db, period)
 
 
@@ -70,13 +50,9 @@ def operational_trend(
 
 
 @router.get("/by-team")
-# Define function metrics_by_team
 def metrics_by_team(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: current_user
     current_user: User = Depends(get_current_user),
-) -> dict:
+):
     """Get metrics broken down by Red Team vs Blue Team."""
-    # Return get_metrics_by_team(db)
     return get_metrics_by_team(db)

backend/app/routers/osint.py

@@ -1,44 +1,26 @@
-"""OSINT enrichment endpoints — view, review, and trigger enrichment of OSINT items linked to techniques."""
+"""OSINT enrichment endpoints — view, review, and trigger enrichment of
+OSINT items (CVEs, advisories, etc.) linked to techniques.
+"""
 
-# Import UUID from uuid
 from uuid import UUID
 
-# Import APIRouter, Depends, HTTPException, Query, status from fastapi
-from fastapi import APIRouter, Depends, HTTPException, Query, status
-
-# Import BaseModel from pydantic
+from fastapi import APIRouter, Depends, Query, HTTPException, status
 from pydantic import BaseModel
-
-# Import Session from sqlalchemy.orm
 from sqlalchemy.orm import Session
 
-# Import get_db from app.database
 from app.database import get_db
-
-# Import get_current_user, require_any_role from app.dependencies.auth
 from app.dependencies.auth import get_current_user, require_any_role
-
-# Import UnitOfWork from app.domain.unit_of_work
 from app.domain.unit_of_work import UnitOfWork
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import  from app.services.osint_enrichment_service
 from app.services.osint_enrichment_service import (
     enrich_technique_with_cves,
     get_osint_items_for_technique,
     get_osint_summary,
     get_technique_or_raise,
+    list_osint_items as service_list_osint_items,
     mark_osint_reviewed,
 )
 
-# Import  from app.services.osint_enrichment_service
-from app.services.osint_enrichment_service import (
-    list_osint_items as service_list_osint_items,
-)
-
-# Assign router = APIRouter(prefix="/osint", tags=["osint"])
 router = APIRouter(prefix="/osint", tags=["osint"])
 
 
@@ -46,34 +28,18 @@ router = APIRouter(prefix="/osint", tags=["osint"])
 
 
 class OsintItemOut(BaseModel):
-    """Serialized OSINT item returned by the API."""
-
-    # id: str
     id: str
-    # technique_id: str
     technique_id: str
-    # source_type: str
     source_type: str
-    # source_url: str
     source_url: str
-    # title: str
     title: str
-    # description: str | None
     description: str | None
-    # severity: str | None
     severity: str | None
-    # discovered_at: str | None
     discovered_at: str | None
-    # reviewed: bool
     reviewed: bool
-    # Assign metadata_ = None
     metadata_: dict | None = None
 
-    # Define class Config
     class Config:
-        """ORM mode configuration for SQLAlchemy model mapping."""
-
-        # Assign from_attributes = True
         from_attributes = True
 
 
@@ -81,207 +47,94 @@ class OsintItemOut(BaseModel):
 
 
 @router.get("/items")
-# Define function list_osint_items
 def list_osint_items(
-    # Entry: technique_id
     technique_id: UUID | None = Query(None),
-    # Entry: source_type
     source_type: str | None = Query(None),
-    # Entry: reviewed
     reviewed: bool | None = Query(None),
-    # Entry: offset
     offset: int = Query(0, ge=0),
-    # Entry: limit
     limit: int = Query(50, ge=1, le=200),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> dict:
-    """List OSINT items with optional filters.
-
-    Args:
-        technique_id (UUID | None): Filter by the technique's UUID.
-        source_type (str | None): Filter by source type (e.g. ``nvd_cve``, ``advisory``).
-        reviewed (bool | None): Filter by review status; ``None`` returns all.
-        offset (int): Number of records to skip for pagination.
-        limit (int): Maximum number of records to return.
-        db (Session): SQLAlchemy database session.
-        user (User): Authenticated user making the request.
-
-    Returns:
-        list: Serialised list of OSINT item dicts matching the filters.
-    """
-    # Return service_list_osint_items(
+):
+    """List OSINT items with optional filters."""
     return service_list_osint_items(
         db,
-        # Keyword argument: technique_id
         technique_id=technique_id,
-        # Keyword argument: source_type
         source_type=source_type,
-        # Keyword argument: reviewed
         reviewed=reviewed,
-        # Keyword argument: offset
         offset=offset,
-        # Keyword argument: limit
         limit=limit,
     )
 
 
-# Apply the @router.get decorator
 @router.get("/summary")
-# Define function osint_summary
 def osint_summary(
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> dict:
-    """Return summary statistics for OSINT items.
-
-    Args:
-        db (Session): SQLAlchemy database session.
-        user (User): Authenticated user making the request.
-
-    Returns:
-        dict: Counts of total, reviewed, and unreviewed items broken down by source type.
-    """
-    # Return get_osint_summary(db)
+):
+    """Summary statistics for OSINT items."""
     return get_osint_summary(db)
 
 
-# Apply the @router.post decorator
 @router.post("/items/{item_id}/review")
-# Define function review_osint_item
 def review_osint_item(
-    # Entry: item_id
     item_id: UUID,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> dict:
-    """Mark an OSINT item as reviewed.
-
-    Args:
-        item_id (UUID): Primary key of the OSINT item to mark reviewed.
-        db (Session): SQLAlchemy database session.
-        user (User): Authenticated user performing the review.
-
-    Returns:
-        dict: Contains ``id`` (str) and ``reviewed`` (bool ``True``).
-    """
-    # Open context manager
+):
+    """Mark an OSINT item as reviewed."""
     with UnitOfWork(db) as uow:
-        # Assign item = mark_osint_reviewed(db, str(item_id))
         item = mark_osint_reviewed(db, str(item_id))
-        # Check: not item
         if not item:
-            # Raise HTTPException
             raise HTTPException(
-                # Keyword argument: status_code
                 status_code=status.HTTP_404_NOT_FOUND,
-                # Keyword argument: detail
                 detail="OSINT item not found",
             )
-        # Call uow.commit()
         uow.commit()
-    # Return {"id": str(item.id), "reviewed": True}
     return {"id": str(item.id), "reviewed": True}
 
 
-# Apply the @router.post decorator
 @router.post("/enrich/{technique_id}")
-# Define function trigger_technique_enrichment
 def trigger_technique_enrichment(
-    # Entry: technique_id
     technique_id: UUID,
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(require_any_role("red_lead", "blue_lead")),
-) -> dict:
-    """Manually trigger OSINT enrichment for a single technique.
-
-    Args:
-        technique_id (UUID): Primary key of the technique to enrich.
-        db (Session): SQLAlchemy database session.
-        user (User): Authenticated red_lead or blue_lead requesting enrichment.
-
-    Returns:
-        dict: Contains ``technique_id`` (str), ``mitre_id`` (str), and ``new_items`` (int).
-    """
-    # Assign technique = get_technique_or_raise(db, technique_id)
+):
+    """Manually trigger OSINT enrichment for a single technique."""
     technique = get_technique_or_raise(db, technique_id)
-    # Assign count = enrich_technique_with_cves(db, technique)
     count = enrich_technique_with_cves(db, technique)
-    # Return {
     return {
-        # Literal argument value
         "technique_id": str(technique.id),
-        # Literal argument value
         "mitre_id": technique.mitre_id,
-        # Literal argument value
         "new_items": count,
     }
 
 
-# Apply the @router.get decorator
 @router.get("/technique/{technique_id}")
-# Define function get_technique_osint
 def get_technique_osint(
-    # Entry: technique_id
     technique_id: UUID,
-    # Entry: source_type
     source_type: str | None = Query(None),
-    # Entry: reviewed
     reviewed: bool | None = Query(None),
-    # Entry: db
     db: Session = Depends(get_db),
-    # Entry: user
     user: User = Depends(get_current_user),
-) -> list:
-    """Get all OSINT items for a specific technique.
-
-    Args:
-        technique_id (UUID): Primary key of the technique.
-        source_type (str | None): Filter by source type (e.g. ``nvd_cve``).
-        reviewed (bool | None): Filter by review status; ``None`` returns all.
-        db (Session): SQLAlchemy database session.
-        user (User): Authenticated user making the request.
-
-    Returns:
-        list: Dicts with OSINT item fields including source URL, severity, and review status.
-    """
-    # Assign items = get_osint_items_for_technique(
+):
+    """Get all OSINT items for a specific technique."""
     items = get_osint_items_for_technique(
         db,
         str(technique_id),
-        # Keyword argument: source_type
         source_type=source_type,
-        # Keyword argument: reviewed
         reviewed=reviewed,
     )
-    # Return [
     return [
         {
-            # Literal argument value
             "id": str(item.id),
-            # Literal argument value
             "source_type": item.source_type,
-            # Literal argument value
             "source_url": item.source_url,
-            # Literal argument value
             "title": item.title,
-            # Literal argument value
             "description": item.description,
-            # Literal argument value
             "severity": item.severity,
-            # Literal argument value
             "discovered_at": item.discovered_at.isoformat() if item.discovered_at else None,
-            # Literal argument value
             "reviewed": item.reviewed,
-            # Literal argument value
             "metadata": item.metadata_,
         }
         for item in items

backend/app/routers/ownership.py

@@ -14,6 +14,7 @@ from app.schemas.ownership_queue_schema import (
     DetectionAssetOwnershipPatch,
     BulkAssignRequest, BulkAssignResult,
     QueueItemCreate, QueueItemPatch, QueueItemOut,
+    AnalystDashboard,
 )
 from app.services import ownership_service, revalidation_queue_service
 from app.models.ownership_queue import RevalidationQueueItem