chore(gitignore): exclude docs/confluence, CLAUDE.md, .claude/, qa scripts

SystemPage now only shows operational content: MITRE Sync, Intel Scan,
ATT&CK Evaluations, Scheduled Jobs, and Template Management.

Settings gets two new admin-only tabs:
- "SSO / Azure AD": full SAML 2.0 wizard (5-step setup for Azure AD)
- "System": System Status + Version Info + Configuration Export/Import

.gitignore

@@ -60,3 +60,11 @@ Thumbs.db
 
 # Local development
 *.local
+
+# Documentation drafts — never commit, delivered directly in chat
+docs/confluence/
+docs/drafts/
+
+# Claude working files — contain credentials, never commit
+.claude/
+CLAUDE.md

backend/Dockerfile

@@ -7,6 +7,10 @@ RUN apt-get update && apt-get install -y \
     gcc \
     libpq-dev \
     curl \
+    pkg-config \
+    libxml2-dev \
+    libxmlsec1-dev \
+    libxmlsec1-openssl \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy requirements first for better caching

backend/alembic/versions/b031_phase6_webhooks.py

@@ -0,0 +1,32 @@
+"""Phase 6.1: webhook_configs table.
+
+Revision ID: b031phase6
+Revises: b030phase5
+"""
+from typing import Sequence, Union
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from alembic import op
+
+revision: str = "b031phase6"
+down_revision: Union[str, None] = "b030phase5"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+def upgrade() -> None:
+    op.create_table(
+        "webhook_configs",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("name", sa.String(200), nullable=False),
+        sa.Column("url", sa.Text, nullable=False),
+        sa.Column("secret", sa.String(256), nullable=True),
+        sa.Column("events", postgresql.JSONB, nullable=False, server_default="[]"),
+        sa.Column("is_active", sa.Boolean, nullable=False, server_default="true"),
+        sa.Column("created_by", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("last_triggered_at", sa.DateTime, nullable=True),
+        sa.Column("failure_count", sa.Integer, nullable=False, server_default="0"),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+    )
+
+def downgrade() -> None:
+    op.drop_table("webhook_configs")

backend/alembic/versions/b032_phase7_user_prefs.py

@@ -0,0 +1,41 @@
+"""Phase 7.2: user notification_preferences and jira_account_id columns.
+
+Revision ID: b032phase7
+Revises: b031phase6
+"""
+from typing import Sequence, Union
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from alembic import op
+
+revision: str = "b032phase7"
+down_revision: Union[str, None] = "b031phase6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_DEFAULT_PREFS = '{"email_on_test_validated": true, "email_on_campaign_completed": true, "email_on_new_mitre_techniques": false, "in_app_all": true}'
+
+def _column_names(table: str) -> set[str]:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    return {c["name"] for c in insp.get_columns(table)}
+
+def upgrade() -> None:
+    user_cols = _column_names("users")
+    if "notification_preferences" not in user_cols:
+        op.add_column(
+            "users",
+            sa.Column("notification_preferences", postgresql.JSONB, nullable=True, server_default=_DEFAULT_PREFS),
+        )
+    if "jira_account_id" not in user_cols:
+        op.add_column(
+            "users",
+            sa.Column("jira_account_id", sa.String(100), nullable=True),
+        )
+
+def downgrade() -> None:
+    user_cols = _column_names("users")
+    if "jira_account_id" in user_cols:
+        op.drop_column("users", "jira_account_id")
+    if "notification_preferences" in user_cols:
+        op.drop_column("users", "notification_preferences")

backend/alembic/versions/b033_system_configs.py

@@ -0,0 +1,43 @@
+"""Phase 8: system_configs table for runtime configuration.
+
+Revision ID: b033syscfg
+Revises: b032phase7
+"""
+from typing import Sequence, Union
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from alembic import op
+
+revision: str = "b033syscfg"
+down_revision: Union[str, None] = "b032phase7"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _table_exists(name: str) -> bool:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    return name in insp.get_table_names()
+
+
+def upgrade() -> None:
+    if not _table_exists("system_configs"):
+        op.create_table(
+            "system_configs",
+            sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+            sa.Column("key", sa.String(200), unique=True, nullable=False),
+            sa.Column("value", sa.Text, nullable=True),
+            sa.Column("description", sa.String(500), nullable=True),
+            sa.Column(
+                "updated_at",
+                sa.DateTime(timezone=True),
+                server_default=sa.text("now()"),
+            ),
+        )
+        op.create_index("ix_system_configs_key", "system_configs", ["key"])
+
+
+def downgrade() -> None:
+    if _table_exists("system_configs"):
+        op.drop_index("ix_system_configs_key", table_name="system_configs")
+        op.drop_table("system_configs")

backend/alembic/versions/b034_detection_lifecycle.py

@@ -0,0 +1,174 @@
+"""Phase 8: Detection Lifecycle Management tables.
+
+Revision ID: b034dlm
+Revises: b033syscfg
+"""
+from typing import Sequence, Union
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from alembic import op
+
+revision: str = "b034dlm"
+down_revision: Union[str, None] = "b033syscfg"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _table_exists(name: str) -> bool:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    return name in insp.get_table_names()
+
+
+def upgrade() -> None:
+    if not _table_exists("detection_assets"):
+        op.create_table(
+            "detection_assets",
+            sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+            sa.Column("name", sa.String(500), nullable=False),
+            sa.Column("description", sa.Text),
+            sa.Column("asset_type", sa.String(50), nullable=False),
+            sa.Column("platform", sa.String(100)),
+            sa.Column("rule_content", sa.Text),
+            sa.Column("rule_language", sa.String(50)),
+            sa.Column("rule_repository_url", sa.Text),
+            sa.Column("rule_file_path", sa.String(500)),
+            sa.Column("rule_version", sa.String(50)),
+            sa.Column("rule_hash", sa.String(64)),
+            sa.Column("last_rule_change_at", sa.DateTime),
+            sa.Column("log_source_name", sa.String(200)),
+            sa.Column("log_source_version", sa.String(50)),
+            sa.Column("log_source_config", postgresql.JSONB, server_default="{}"),
+            sa.Column("infrastructure_hash", sa.String(64)),
+            sa.Column("infrastructure_details", postgresql.JSONB, server_default="{}"),
+            sa.Column("health_status", sa.String(20), server_default="untested", nullable=False),
+            sa.Column("last_alert_at", sa.DateTime),
+            sa.Column("alert_count_30d", sa.Integer, server_default="0"),
+            sa.Column("false_positive_rate", sa.Float),
+            sa.Column("expected_alert_frequency", sa.String(50)),
+            sa.Column("owner_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL")),
+            sa.Column("backup_owner_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL")),
+            sa.Column("team", sa.String(100)),
+            sa.Column("is_active", sa.Boolean, server_default="true", nullable=False),
+            sa.Column("tags", postgresql.JSONB, server_default="[]"),
+            sa.Column("asset_metadata", postgresql.JSONB, server_default="{}"),
+            sa.Column("created_by", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL")),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
+        )
+        op.create_index("ix_detection_assets_platform", "detection_assets", ["platform"])
+        op.create_index("ix_detection_assets_health_status", "detection_assets", ["health_status"])
+        op.create_index("ix_detection_assets_owner_id", "detection_assets", ["owner_id"])
+
+    if not _table_exists("detection_technique_mappings"):
+        op.create_table(
+            "detection_technique_mappings",
+            sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+            sa.Column("detection_asset_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("detection_assets.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("technique_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("techniques.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("coverage_type", sa.String(50), server_default="detect"),
+            sa.Column("confidence_level", sa.String(20), server_default="medium"),
+            sa.Column("notes", sa.Text),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()")),
+        )
+        op.create_index("ix_detection_technique_mappings_technique_id", "detection_technique_mappings", ["technique_id"])
+        op.create_index("ix_detection_technique_mappings_asset_id", "detection_technique_mappings", ["detection_asset_id"])
+
+    if not _table_exists("detection_validations"):
+        op.create_table(
+            "detection_validations",
+            sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+            sa.Column("detection_asset_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("detection_assets.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("technique_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("techniques.id", ondelete="SET NULL")),
+            sa.Column("test_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("tests.id", ondelete="SET NULL")),
+            sa.Column("validated_at", sa.DateTime),
+            sa.Column("expires_at", sa.DateTime, nullable=False),
+            sa.Column("is_valid", sa.Boolean, server_default="true", nullable=False),
+            sa.Column("validation_result", sa.String(50)),
+            sa.Column("validation_method", sa.String(100)),
+            sa.Column("rule_hash_at_validation", sa.String(64)),
+            sa.Column("log_source_version_at_validation", sa.String(50)),
+            sa.Column("infrastructure_hash_at_validation", sa.String(64)),
+            sa.Column("environment_snapshot", postgresql.JSONB, server_default="{}"),
+            sa.Column("invalidated_at", sa.DateTime),
+            sa.Column("invalidation_reason", sa.String(50)),
+            sa.Column("invalidation_details", sa.Text),
+            sa.Column("invalidated_by", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL")),
+            sa.Column("validated_by", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=False),
+            sa.Column("integrity_hash", sa.String(64)),
+            sa.Column("notes", sa.Text),
+            sa.Column("evidence_ids", postgresql.JSONB, server_default="[]"),
+        )
+        op.create_index("ix_detection_validations_asset_id_valid", "detection_validations", ["detection_asset_id", "is_valid"])
+        op.create_index("ix_detection_validations_expires_at", "detection_validations", ["expires_at"])
+
+    if not _table_exists("technique_confidence_scores"):
+        op.create_table(
+            "technique_confidence_scores",
+            sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+            sa.Column("technique_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("techniques.id", ondelete="CASCADE"), nullable=False, unique=True),
+            sa.Column("confidence_level", sa.String(20), server_default="unknown"),
+            sa.Column("confidence_score", sa.Float, server_default="0.0"),
+            sa.Column("detection_count", sa.Integer, server_default="0"),
+            sa.Column("valid_detection_count", sa.Integer, server_default="0"),
+            sa.Column("last_validated_at", sa.DateTime),
+            sa.Column("next_validation_due", sa.DateTime),
+            sa.Column("last_recalculated_at", sa.DateTime),
+            sa.Column("recency_factor", sa.Float, server_default="0.0"),
+            sa.Column("coverage_factor", sa.Float, server_default="0.0"),
+            sa.Column("health_factor", sa.Float, server_default="0.0"),
+            sa.Column("diversity_factor", sa.Float, server_default="0.0"),
+            sa.Column("score_breakdown", postgresql.JSONB, server_default="{}"),
+            sa.Column("risk_factors", postgresql.JSONB, server_default="[]"),
+            sa.Column("updated_at", sa.DateTime),
+        )
+        op.create_index("ix_technique_confidence_scores_technique_id", "technique_confidence_scores", ["technique_id"])
+        op.create_index("ix_technique_confidence_scores_confidence_level", "technique_confidence_scores", ["confidence_level"])
+
+    if not _table_exists("infrastructure_change_logs"):
+        op.create_table(
+            "infrastructure_change_logs",
+            sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+            sa.Column("change_type", sa.String(100), nullable=False),
+            sa.Column("description", sa.Text, nullable=False),
+            sa.Column("affected_platforms", postgresql.JSONB, server_default="[]"),
+            sa.Column("affected_log_sources", postgresql.JSONB, server_default="[]"),
+            sa.Column("change_date", sa.DateTime),
+            sa.Column("reported_by", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL")),
+            sa.Column("auto_invalidate", sa.Boolean, server_default="true"),
+            sa.Column("invalidated_count", sa.Integer, server_default="0"),
+            sa.Column("change_metadata", postgresql.JSONB, server_default="{}"),
+            sa.Column("created_at", sa.DateTime),
+        )
+        op.create_index("ix_infrastructure_change_logs_change_date", "infrastructure_change_logs", ["change_date"])
+
+    if not _table_exists("decay_policies"):
+        op.create_table(
+            "decay_policies",
+            sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+            sa.Column("name", sa.String(200), nullable=False),
+            sa.Column("description", sa.Text),
+            sa.Column("applies_to_platform", sa.String(100)),
+            sa.Column("applies_to_asset_type", sa.String(50)),
+            sa.Column("applies_to_tactic", sa.String(100)),
+            sa.Column("fresh_days", sa.Integer, server_default="90"),
+            sa.Column("aging_days", sa.Integer, server_default="180"),
+            sa.Column("stale_days", sa.Integer, server_default="365"),
+            sa.Column("default_validity_days", sa.Integer, server_default="180"),
+            sa.Column("silent_threshold_days", sa.Integer, server_default="30"),
+            sa.Column("noisy_threshold_daily", sa.Integer, server_default="100"),
+            sa.Column("recency_weight", sa.Float, server_default="0.3"),
+            sa.Column("coverage_weight", sa.Float, server_default="0.3"),
+            sa.Column("health_weight", sa.Float, server_default="0.25"),
+            sa.Column("diversity_weight", sa.Float, server_default="0.15"),
+            sa.Column("is_default", sa.Boolean, server_default="false"),
+            sa.Column("is_active", sa.Boolean, server_default="true"),
+            sa.Column("created_at", sa.DateTime),
+            sa.Column("updated_at", sa.DateTime),
+        )
+
+
+def downgrade() -> None:
+    for table in ["decay_policies", "infrastructure_change_logs", "technique_confidence_scores", "detection_validations", "detection_technique_mappings", "detection_assets"]:
+        if _table_exists(table):
+            op.drop_table(table)

backend/alembic/versions/b035_ownership_queue.py

@@ -0,0 +1,118 @@
+"""Phase 9: Ownership & Revalidation Queue
+
+Revision ID: b035ownerq
+Revises: b034dlm
+Create Date: 2026-05-19
+
+Uses raw SQL for all DDL to avoid SQLAlchemy before_create hook issues
+with existing enum types.
+"""
+
+from typing import Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "b035ownerq"
+down_revision: Union[str, None] = "b034dlm"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── Enums (idempotent) ────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        DO $$ BEGIN
+            CREATE TYPE queue_priority AS ENUM ('critical', 'high', 'medium', 'low');
+        EXCEPTION WHEN duplicate_object THEN NULL;
+        END $$
+    """))
+    conn.execute(sa.text("""
+        DO $$ BEGIN
+            CREATE TYPE queue_status AS ENUM ('pending', 'in_progress', 'completed', 'dismissed');
+        EXCEPTION WHEN duplicate_object THEN NULL;
+        END $$
+    """))
+    conn.execute(sa.text("""
+        DO $$ BEGIN
+            CREATE TYPE queue_reason AS ENUM (
+                'validation_expired', 'infra_change', 'osint_alert',
+                'mitre_update', 'rule_modified', 'low_confidence', 'manual');
+        EXCEPTION WHEN duplicate_object THEN NULL;
+        END $$
+    """))
+
+    # ── technique_ownerships ──────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS technique_ownerships (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            technique_id UUID NOT NULL UNIQUE
+                REFERENCES techniques(id) ON DELETE CASCADE,
+            owner_id UUID
+                REFERENCES users(id) ON DELETE SET NULL,
+            backup_owner_id UUID
+                REFERENCES users(id) ON DELETE SET NULL,
+            team VARCHAR(200),
+            notes TEXT,
+            assigned_at TIMESTAMP,
+            assigned_by UUID
+                REFERENCES users(id) ON DELETE SET NULL,
+            created_at TIMESTAMP DEFAULT now(),
+            updated_at TIMESTAMP DEFAULT now()
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_techown_owner_id ON technique_ownerships (owner_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_techown_technique_id ON technique_ownerships (technique_id)"
+    ))
+
+    # ── revalidation_queue_items ──────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS revalidation_queue_items (
+            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            technique_id UUID
+                REFERENCES techniques(id) ON DELETE CASCADE,
+            detection_asset_id UUID
+                REFERENCES detection_assets(id) ON DELETE CASCADE,
+            priority queue_priority NOT NULL DEFAULT 'medium',
+            reason queue_reason NOT NULL,
+            reason_detail TEXT,
+            status queue_status NOT NULL DEFAULT 'pending',
+            assigned_to UUID
+                REFERENCES users(id) ON DELETE SET NULL,
+            due_date TIMESTAMP,
+            created_at TIMESTAMP DEFAULT now(),
+            completed_at TIMESTAMP,
+            dismissed_at TIMESTAMP,
+            completed_by UUID
+                REFERENCES users(id) ON DELETE SET NULL,
+            extra JSONB
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_rqueue_status ON revalidation_queue_items (status)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_rqueue_priority ON revalidation_queue_items (priority)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_rqueue_assigned_to ON revalidation_queue_items (assigned_to)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_rqueue_technique_id ON revalidation_queue_items (technique_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_rqueue_asset_id ON revalidation_queue_items (detection_asset_id)"
+    ))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS revalidation_queue_items"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS technique_ownerships"))
+    conn.execute(sa.text("DROP TYPE IF EXISTS queue_reason"))
+    conn.execute(sa.text("DROP TYPE IF EXISTS queue_status"))
+    conn.execute(sa.text("DROP TYPE IF EXISTS queue_priority"))

backend/alembic/versions/b036_attack_paths.py

@@ -0,0 +1,184 @@
+"""Phase 10: Attack Paths & Advanced Purple Team
+
+Revision ID: b036atk
+Revises: b035ownerq
+Create Date: 2026-05-19
+
+Uses raw SQL to avoid SQLAlchemy DDL hook issues with enum types.
+"""
+
+from typing import Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "b036atk"
+down_revision: Union[str, None] = "b035ownerq"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── Enums ─────────────────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        DO $$ BEGIN
+            CREATE TYPE execution_status AS ENUM
+                ('planned','in_progress','completed','aborted');
+        EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    """))
+    conn.execute(sa.text("""
+        DO $$ BEGIN
+            CREATE TYPE step_result_status AS ENUM
+                ('pending','executing','detected','not_detected','skipped');
+        EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    """))
+    conn.execute(sa.text("""
+        DO $$ BEGIN
+            CREATE TYPE timeline_actor_side AS ENUM ('red','blue','system');
+        EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    """))
+    conn.execute(sa.text("""
+        DO $$ BEGIN
+            CREATE TYPE timeline_entry_type AS ENUM
+                ('action','detection','note','phase_transition','flag');
+        EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    """))
+
+    # ── attack_paths ──────────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS attack_paths (
+            id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            name            VARCHAR(300) NOT NULL,
+            description     TEXT,
+            objective       TEXT,
+            is_template     BOOLEAN DEFAULT FALSE,
+            threat_actor_id UUID REFERENCES threat_actors(id) ON DELETE SET NULL,
+            created_by      UUID REFERENCES users(id) ON DELETE SET NULL,
+            tags            JSONB,
+            is_active       BOOLEAN DEFAULT TRUE,
+            created_at      TIMESTAMP DEFAULT now(),
+            updated_at      TIMESTAMP DEFAULT now()
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_attack_paths_created_by ON attack_paths (created_by)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_attack_paths_is_template ON attack_paths (is_template)"
+    ))
+
+    # ── attack_path_steps ─────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS attack_path_steps (
+            id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            attack_path_id      UUID NOT NULL REFERENCES attack_paths(id) ON DELETE CASCADE,
+            order_index         INTEGER NOT NULL DEFAULT 0,
+            kill_chain_phase    VARCHAR(60),
+            technique_id        UUID REFERENCES techniques(id) ON DELETE SET NULL,
+            test_id             UUID REFERENCES tests(id) ON DELETE SET NULL,
+            name                VARCHAR(300),
+            description         TEXT,
+            expected_detection  BOOLEAN DEFAULT TRUE,
+            notes               TEXT
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ap_steps_path_id ON attack_path_steps (attack_path_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ap_steps_technique_id ON attack_path_steps (technique_id)"
+    ))
+
+    # ── attack_path_executions ────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS attack_path_executions (
+            id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            attack_path_id   UUID NOT NULL REFERENCES attack_paths(id) ON DELETE CASCADE,
+            status           execution_status NOT NULL DEFAULT 'planned',
+            environment      VARCHAR(100),
+            red_team_lead    UUID REFERENCES users(id) ON DELETE SET NULL,
+            blue_team_lead   UUID REFERENCES users(id) ON DELETE SET NULL,
+            started_by       UUID REFERENCES users(id) ON DELETE SET NULL,
+            started_at       TIMESTAMP,
+            completed_at     TIMESTAMP,
+            notes            TEXT,
+            created_at       TIMESTAMP DEFAULT now(),
+            -- kill-chain metrics (populated on completion)
+            total_steps              INTEGER,
+            detected_steps           INTEGER,
+            not_detected_steps       INTEGER,
+            skipped_steps            INTEGER,
+            detection_rate           FLOAT,
+            mttd_seconds             FLOAT,
+            furthest_undetected_step INTEGER
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ap_exec_path_id ON attack_path_executions (attack_path_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ap_exec_status ON attack_path_executions (status)"
+    ))
+
+    # ── attack_path_step_results ──────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS attack_path_step_results (
+            id                     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            execution_id           UUID NOT NULL
+                                   REFERENCES attack_path_executions(id) ON DELETE CASCADE,
+            step_id                UUID NOT NULL
+                                   REFERENCES attack_path_steps(id) ON DELETE CASCADE,
+            step_order             INTEGER NOT NULL DEFAULT 0,
+            status                 step_result_status NOT NULL DEFAULT 'pending',
+            executed_by            UUID REFERENCES users(id) ON DELETE SET NULL,
+            executed_at            TIMESTAMP,
+            detected_at            TIMESTAMP,
+            time_to_detect_seconds FLOAT,
+            detection_asset_id     UUID
+                                   REFERENCES detection_assets(id) ON DELETE SET NULL,
+            notes                  TEXT,
+            evidence_ids           JSONB
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ap_stepres_exec ON attack_path_step_results (execution_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ap_stepres_step ON attack_path_step_results (step_id)"
+    ))
+
+    # ── attack_path_timeline ──────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS attack_path_timeline (
+            id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            execution_id UUID NOT NULL
+                         REFERENCES attack_path_executions(id) ON DELETE CASCADE,
+            step_id      UUID REFERENCES attack_path_steps(id) ON DELETE SET NULL,
+            timestamp    TIMESTAMP NOT NULL DEFAULT now(),
+            actor_side   timeline_actor_side NOT NULL,
+            actor_id     UUID REFERENCES users(id) ON DELETE SET NULL,
+            entry_type   timeline_entry_type NOT NULL,
+            content      TEXT NOT NULL,
+            extra        JSONB
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_timeline_execution_id ON attack_path_timeline (execution_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_timeline_timestamp ON attack_path_timeline (timestamp)"
+    ))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS attack_path_timeline"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS attack_path_step_results"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS attack_path_executions"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS attack_path_steps"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS attack_paths"))
+    conn.execute(sa.text("DROP TYPE IF EXISTS timeline_entry_type"))
+    conn.execute(sa.text("DROP TYPE IF EXISTS timeline_actor_side"))
+    conn.execute(sa.text("DROP TYPE IF EXISTS step_result_status"))
+    conn.execute(sa.text("DROP TYPE IF EXISTS execution_status"))

backend/alembic/versions/b037_knowledge.py

@@ -0,0 +1,106 @@
+"""Phase 11: Knowledge Management — Playbooks + Lessons Learned
+
+Revision ID: b037know
+Revises: b036atk
+Create Date: 2026-05-20
+
+Uses raw SQL to bypass SQLAlchemy DDL hooks (no enum types — string columns
+with Pydantic-layer validation instead, so no PostgreSQL enums needed).
+"""
+
+from typing import Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "b037know"
+down_revision: Union[str, None] = "b036atk"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── playbooks ──────────────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS playbooks (
+            id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            technique_id   UUID NOT NULL REFERENCES techniques(id) ON DELETE CASCADE,
+            playbook_type  VARCHAR(32) NOT NULL,
+            title          VARCHAR(255) NOT NULL,
+            content        TEXT NOT NULL DEFAULT '',
+            version        INTEGER NOT NULL DEFAULT 1,
+            tools          JSONB,
+            prerequisites  JSONB,
+            created_by     UUID REFERENCES users(id) ON DELETE SET NULL,
+            updated_by     UUID REFERENCES users(id) ON DELETE SET NULL,
+            created_at     TIMESTAMP DEFAULT now(),
+            updated_at     TIMESTAMP DEFAULT now(),
+            is_active      BOOLEAN DEFAULT TRUE,
+            CONSTRAINT uq_playbook_technique_type UNIQUE (technique_id, playbook_type)
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_playbooks_technique_id ON playbooks (technique_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_playbooks_type ON playbooks (playbook_type)"
+    ))
+
+    # ── playbook_versions ──────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS playbook_versions (
+            id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            playbook_id   UUID NOT NULL REFERENCES playbooks(id) ON DELETE CASCADE,
+            version       INTEGER NOT NULL,
+            title         VARCHAR(255) NOT NULL,
+            content       TEXT NOT NULL DEFAULT '',
+            tools         JSONB,
+            prerequisites JSONB,
+            changed_by    UUID REFERENCES users(id) ON DELETE SET NULL,
+            change_note   VARCHAR(500),
+            created_at    TIMESTAMP DEFAULT now()
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_pb_versions_playbook_id ON playbook_versions (playbook_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_pb_versions_version ON playbook_versions (playbook_id, version)"
+    ))
+
+    # ── lessons_learned ────────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS lessons_learned (
+            id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            title         VARCHAR(255) NOT NULL,
+            what_happened TEXT NOT NULL DEFAULT '',
+            root_cause    TEXT NOT NULL DEFAULT '',
+            fix_applied   TEXT,
+            severity      VARCHAR(16) NOT NULL DEFAULT 'medium',
+            entity_type   VARCHAR(32) NOT NULL DEFAULT 'manual',
+            entity_id     UUID,
+            technique_ids JSONB,
+            tags          JSONB,
+            created_by    UUID REFERENCES users(id) ON DELETE SET NULL,
+            created_at    TIMESTAMP DEFAULT now(),
+            updated_at    TIMESTAMP DEFAULT now(),
+            is_active     BOOLEAN DEFAULT TRUE
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ll_entity ON lessons_learned (entity_type, entity_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ll_severity ON lessons_learned (severity)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_ll_created_by ON lessons_learned (created_by)"
+    ))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS lessons_learned"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS playbook_versions"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS playbooks"))

backend/alembic/versions/b038_risk_intelligence.py

@@ -0,0 +1,62 @@
+"""Phase 12: Risk Intelligence — technique_risk_profiles table
+
+Revision ID: b038risk
+Revises: b037know
+Create Date: 2026-05-20
+
+Uses raw SQL to bypass SQLAlchemy DDL hooks.
+"""
+
+from typing import Union
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "b038risk"
+down_revision: Union[str, None] = "b037know"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS technique_risk_profiles (
+            id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+            technique_id        UUID NOT NULL REFERENCES techniques(id) ON DELETE CASCADE,
+            risk_score          FLOAT NOT NULL DEFAULT 0.0,
+            likelihood          FLOAT NOT NULL DEFAULT 0.0,
+            impact              FLOAT NOT NULL DEFAULT 0.0,
+            risk_level          VARCHAR(16) NOT NULL DEFAULT 'info',
+            detection_gap       FLOAT NOT NULL DEFAULT 1.0,
+            threat_actor_count  INTEGER NOT NULL DEFAULT 0,
+            osint_signal_count  INTEGER NOT NULL DEFAULT 0,
+            test_fail_count     INTEGER NOT NULL DEFAULT 0,
+            test_total_count    INTEGER NOT NULL DEFAULT 0,
+            test_failure_rate   FLOAT NOT NULL DEFAULT 0.0,
+            confidence_level    FLOAT NOT NULL DEFAULT 0.0,
+            scoring_breakdown   JSONB,
+            recommendations     JSONB,
+            computed_at         TIMESTAMP DEFAULT now(),
+            is_stale            BOOLEAN DEFAULT TRUE,
+            CONSTRAINT uq_risk_profile_technique UNIQUE (technique_id)
+        )
+    """))
+
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_risk_profiles_risk_score "
+        "ON technique_risk_profiles (risk_score)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_risk_profiles_risk_level "
+        "ON technique_risk_profiles (risk_level)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_risk_profiles_stale "
+        "ON technique_risk_profiles (is_stale)"
+    ))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS technique_risk_profiles"))

backend/alembic/versions/b039_executive_dashboard.py

@@ -0,0 +1,77 @@
+"""Phase 13: Executive Dashboard — posture_snapshots table.
+
+Revision ID: b039exec
+Revises:     b038risk
+Create Date: 2026-05-20
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision       = "b039exec"
+down_revision  = "b038risk"
+branch_labels  = None
+depends_on     = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS posture_snapshots (
+            id              UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+            snapshot_date   DATE         NOT NULL,
+
+            -- Coverage
+            total_techniques   INTEGER NOT NULL DEFAULT 0,
+            validated_count    INTEGER NOT NULL DEFAULT 0,
+            partial_count      INTEGER NOT NULL DEFAULT 0,
+            not_covered_count  INTEGER NOT NULL DEFAULT 0,
+            coverage_pct       FLOAT   NOT NULL DEFAULT 0.0,
+
+            -- Risk
+            avg_risk_score     FLOAT   NOT NULL DEFAULT 0.0,
+            critical_count     INTEGER NOT NULL DEFAULT 0,
+            high_count         INTEGER NOT NULL DEFAULT 0,
+            medium_count       INTEGER NOT NULL DEFAULT 0,
+            low_count          INTEGER NOT NULL DEFAULT 0,
+
+            -- Operations
+            open_queue_items   INTEGER NOT NULL DEFAULT 0,
+            orphan_techniques  INTEGER NOT NULL DEFAULT 0,
+
+            -- Knowledge
+            playbook_count     INTEGER NOT NULL DEFAULT 0,
+            lesson_count       INTEGER NOT NULL DEFAULT 0,
+
+            -- MTTD
+            mttd_avg_seconds   FLOAT,
+            executions_30d     INTEGER NOT NULL DEFAULT 0,
+            detection_rate_30d FLOAT,
+
+            -- Meta
+            created_by  UUID REFERENCES users(id) ON DELETE SET NULL,
+            created_at  TIMESTAMP WITHOUT TIME ZONE DEFAULT now(),
+            extra       JSONB
+        )
+    """))
+
+    # Unique constraint: one snapshot per calendar day
+    conn.execute(sa.text("""
+        DO $$ BEGIN
+            ALTER TABLE posture_snapshots
+                ADD CONSTRAINT uq_posture_snapshot_date UNIQUE (snapshot_date);
+        EXCEPTION WHEN duplicate_table THEN NULL;
+                 WHEN duplicate_object THEN NULL;
+        END $$
+    """))
+
+    # Index for date-range trend queries
+    conn.execute(sa.text("""
+        CREATE INDEX IF NOT EXISTS ix_posture_snapshots_date
+            ON posture_snapshots (snapshot_date)
+    """))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS posture_snapshots CASCADE"))

backend/alembic/versions/b040_enterprise_readiness.py

@@ -0,0 +1,75 @@
+"""Phase 14: Enterprise Readiness — api_keys and sso_configs tables.
+
+Revision ID: b040ent
+Revises:     b039exec
+Create Date: 2026-05-20
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision       = "b040ent"
+down_revision  = "b039exec"
+branch_labels  = None
+depends_on     = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── api_keys ──────────────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS api_keys (
+            id           UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+            name         VARCHAR(200) NOT NULL,
+            description  TEXT,
+            key_prefix   VARCHAR(13)  NOT NULL,
+            key_hash     VARCHAR(64)  NOT NULL UNIQUE,
+            user_id      UUID         NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+            scopes       JSONB        NOT NULL DEFAULT '["read"]',
+            last_used_at TIMESTAMP WITHOUT TIME ZONE,
+            expires_at   TIMESTAMP WITHOUT TIME ZONE,
+            is_active    BOOLEAN      NOT NULL DEFAULT TRUE,
+            created_at   TIMESTAMP WITHOUT TIME ZONE DEFAULT now()
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_api_keys_user_id  ON api_keys (user_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_api_keys_key_hash ON api_keys (key_hash)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_api_keys_active   ON api_keys (is_active)"
+    ))
+
+    # ── sso_configs ───────────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS sso_configs (
+            id               UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+            is_enabled       BOOLEAN      NOT NULL DEFAULT FALSE,
+            provider_name    VARCHAR(200),
+            sp_entity_id     VARCHAR(500),
+            sp_acs_url       VARCHAR(500),
+            sp_slo_url       VARCHAR(500),
+            sp_certificate   TEXT,
+            sp_private_key   TEXT,
+            idp_entity_id    VARCHAR(500),
+            idp_sso_url      VARCHAR(500),
+            idp_slo_url      VARCHAR(500),
+            idp_certificate  TEXT,
+            attr_email       VARCHAR(200) DEFAULT 'email',
+            attr_username    VARCHAR(200) DEFAULT 'username',
+            attr_role        VARCHAR(200) DEFAULT 'role',
+            default_role     VARCHAR(50)  DEFAULT 'viewer',
+            auto_provision   BOOLEAN      NOT NULL DEFAULT TRUE,
+            created_at       TIMESTAMP WITHOUT TIME ZONE DEFAULT now(),
+            updated_at       TIMESTAMP WITHOUT TIME ZONE DEFAULT now()
+        )
+    """))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS api_keys CASCADE"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS sso_configs CASCADE"))

backend/alembic/versions/b041_operational_alerts.py

@@ -0,0 +1,82 @@
+"""Phase 13: Operational Alerts — alert_rules and alert_instances tables.
+
+Revision ID: b041alerts
+Revises:     b040ent
+Create Date: 2026-05-21
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision       = "b041alerts"
+down_revision  = "b040ent"
+branch_labels  = None
+depends_on     = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── alert_rules ───────────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS alert_rules (
+            id             UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+            name           VARCHAR(300) NOT NULL,
+            description    TEXT,
+            rule_type      VARCHAR(50)  NOT NULL,
+            severity       VARCHAR(20)  NOT NULL DEFAULT 'medium',
+            is_enabled     BOOLEAN      NOT NULL DEFAULT TRUE,
+            is_system      BOOLEAN      NOT NULL DEFAULT FALSE,
+            config         JSONB        NOT NULL DEFAULT '{}',
+            notify_in_app  BOOLEAN      NOT NULL DEFAULT TRUE,
+            notify_webhook BOOLEAN      NOT NULL DEFAULT FALSE,
+            webhook_id     UUID REFERENCES webhook_configs(id) ON DELETE SET NULL,
+            cooldown_hours INTEGER      NOT NULL DEFAULT 24,
+            created_by     UUID REFERENCES users(id) ON DELETE SET NULL,
+            created_at     TIMESTAMP WITHOUT TIME ZONE DEFAULT now(),
+            last_fired_at  TIMESTAMP WITHOUT TIME ZONE
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_alert_rules_type    ON alert_rules (rule_type)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_alert_rules_enabled ON alert_rules (is_enabled)"
+    ))
+
+    # ── alert_instances ───────────────────────────────────────────────────────
+    conn.execute(sa.text("""
+        CREATE TABLE IF NOT EXISTS alert_instances (
+            id              UUID         PRIMARY KEY DEFAULT gen_random_uuid(),
+            rule_id         UUID REFERENCES alert_rules(id) ON DELETE SET NULL,
+            rule_name       VARCHAR(300) NOT NULL,
+            rule_type       VARCHAR(50)  NOT NULL,
+            severity        VARCHAR(20)  NOT NULL,
+            title           VARCHAR(500) NOT NULL,
+            message         TEXT         NOT NULL,
+            details         JSONB,
+            status          VARCHAR(20)  NOT NULL DEFAULT 'open',
+            acknowledged_by UUID REFERENCES users(id) ON DELETE SET NULL,
+            acknowledged_at TIMESTAMP WITHOUT TIME ZONE,
+            resolved_at     TIMESTAMP WITHOUT TIME ZONE,
+            created_at      TIMESTAMP WITHOUT TIME ZONE DEFAULT now()
+        )
+    """))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_alert_instances_rule_id  ON alert_instances (rule_id)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_alert_instances_status   ON alert_instances (status)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_alert_instances_severity ON alert_instances (severity)"
+    ))
+    conn.execute(sa.text(
+        "CREATE INDEX IF NOT EXISTS ix_alert_instances_created  ON alert_instances (created_at)"
+    ))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP TABLE IF EXISTS alert_instances CASCADE"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS alert_rules CASCADE"))

backend/alembic/versions/b042_jira_user_token.py

@@ -0,0 +1,25 @@
+"""Add jira_api_token to users table.
+
+Revision ID: b042
+Revises: b041_operational_alerts
+Create Date: 2026-05-26
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "b042"
+down_revision = "b041alerts"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column("jira_api_token", sa.String(500), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("users", "jira_api_token")

backend/alembic/versions/b043_jira_email.py

@@ -0,0 +1,28 @@
+"""Add jira_email to users table.
+
+Allows each user to specify a separate email for Jira authentication,
+independent of their Aegis account email.
+
+Revision ID: b043
+Revises: b042
+Create Date: 2026-05-26
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "b043"
+down_revision = "b042"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column("jira_email", sa.String(255), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("users", "jira_email")

backend/alembic/versions/b044_tempo_user_token.py

@@ -0,0 +1,25 @@
+"""add tempo_api_token to users
+
+Revision ID: b044
+Revises: b043
+Create Date: 2026-05-27
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "b044"
+down_revision = "b043"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.add_column(
+        "users",
+        sa.Column("tempo_api_token", sa.String(500), nullable=True),
+    )
+
+
+def downgrade():
+    op.drop_column("users", "tempo_api_token")

backend/alembic/versions/b045_blue_work_started_at.py

@@ -0,0 +1,16 @@
+"""Add blue_work_started_at to tests table."""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "b045"
+down_revision = "b044"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.add_column("tests", sa.Column("blue_work_started_at", sa.DateTime(), nullable=True))
+
+
+def downgrade():
+    op.drop_column("tests", "blue_work_started_at")

backend/alembic/versions/b046_add_disputed_test_state.py

@@ -0,0 +1,22 @@
+"""Add 'disputed' value to teststate enum.
+
+Revision ID: b046
+Revises: b045
+Create Date: 2026-06-03
+"""
+
+from alembic import op
+
+revision = "b046"
+down_revision = "b045"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("ALTER TYPE teststate ADD VALUE IF NOT EXISTS 'disputed'")
+
+
+def downgrade() -> None:
+    # PostgreSQL does not support removing enum values; downgrade is a no-op.
+    pass

backend/alembic/versions/b047_campaign_start_date.py

@@ -0,0 +1,27 @@
+"""Add start_date to campaigns.
+
+Revision ID: b047
+Revises: b046
+Create Date: 2026-06-03
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "b047"
+down_revision = "b046"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "campaigns",
+        sa.Column("start_date", sa.DateTime(), nullable=True),
+    )
+    op.create_index("ix_campaigns_start_date", "campaigns", ["start_date"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_campaigns_start_date", table_name="campaigns")
+    op.drop_column("campaigns", "start_date")

backend/alembic/versions/b048_evaluation_imports.py

@@ -0,0 +1,39 @@
+"""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,16 +19,13 @@ 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"
-    # Assign ACCESS_TOKEN_EXPIRE_MINUTES = 15  # short-lived for security; configurable via env
-    ACCESS_TOKEN_EXPIRE_MINUTES: int = 15  # short-lived for security; configurable via env
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 480  # 8 hours — /auth/refresh extends active sessions
 
     # ── Redis ─────────────────────────────────────────────────────────
     REDIS_URL: str = "redis://redis:6379/0"
     # Logical DB indices on the same Redis instance (PATH in URL is overridden).
     REDIS_TOKEN_BLACKLIST_DB: int = 1
-    # Assign REDIS_CACHE_DB = 2
     REDIS_CACHE_DB: int = 2
 
     # ── CORS ─────────────────────────────────────────────────────────
@@ -57,13 +36,13 @@ class Settings(BaseSettings):
 
     # ── MinIO / S3 ───────────────────────────────────────────────────
     MINIO_ENDPOINT: str = "minio:9000"
-    # Assign MINIO_ACCESS_KEY = "minioadmin"
+    # Public hostname used in presigned URLs returned to browsers.
+    # In production set this to <server-ip>:9000 (or a public FQDN) so
+    # 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 ───────────────────────────────────────────────────
@@ -71,108 +50,85 @@ 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 = ""
-    # Assign JIRA_ISSUE_TYPE_TEST = "Task"
-    JIRA_ISSUE_TYPE_TEST: str = "Task"
-    # Assign JIRA_ISSUE_TYPE_CAMPAIGN = "Epic"
-    JIRA_ISSUE_TYPE_CAMPAIGN: str = "Epic"
+    JIRA_ISSUE_TYPE_TEST: str = "Task"       # tests (campaign or standalone)
+    JIRA_ISSUE_TYPE_CAMPAIGN: str = "Epic"   # campaigns (under Initiative)
+    # Jira custom field ID for "Start date" — Jira Cloud team-managed: customfield_10015
+    # Override with the correct field ID for your Jira instance if different.
+    JIRA_START_DATE_FIELD: str = "customfield_10015"
 
     # ── 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.
+    TEMPO_BASE_URL: str = ""  # empty → falls back to https://api.tempo.io/4
 
     # ── OSINT / Intelligence ────────────────────────────────────────
     NVD_API_KEY: str = ""  # optional; increases NVD rate limit from 5/30s to 50/30s
-    # Assign STALE_THRESHOLD_DAYS = 365  # days before coverage is considered stale
     STALE_THRESHOLD_DAYS: int = 365  # days before coverage is considered stale
 
     # ── Reporting ─────────────────────────────────────────────────────
     REPORT_TEMPLATES_DIR: str = "app/templates/reports"
-    # Assign REPORT_OUTPUT_DIR = "/tmp/aegis_reports"
     REPORT_OUTPUT_DIR: str = "/tmp/aegis_reports"
-    # Assign COMPANY_NAME = "Organization"
     COMPANY_NAME: str = "Organization"
-    # Assign COMPANY_LOGO_PATH = "app/templates/reports/assets/logo.png"
     COMPANY_LOGO_PATH: str = "app/templates/reports/assets/logo.png"
 
+    # ── Email / SMTP ──────────────────────────────────────────────────
+    SMTP_ENABLED: bool = False
+    SMTP_HOST: str = ""
+    SMTP_PORT: int = 587
+    SMTP_USERNAME: str = ""
+    SMTP_PASSWORD: str = ""
+    SMTP_FROM_EMAIL: str = "aegis@company.com"
+    SMTP_USE_TLS: bool = True
+    PLATFORM_URL: str = "http://localhost:5173"  # base URL for links in emails
+
     # ── 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,
     )
 
@@ -180,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,41 +1,26 @@
-"""Authentication and RBAC dependencies for FastAPI.
+"""
+Authentication and RBAC dependencies for FastAPI.
 
 Provides:
 - ``get_current_user``: decodes JWT from HttpOnly cookie (preferred) or
   Authorization header (fallback), fetches user from DB, raises 401 on failure.
+  Also accepts Aegis API keys (``aegis_…`` prefix) as Bearer tokens.
 - ``require_role``: factory that returns a dependency enforcing a specific role
   (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
 
 # ---------------------------------------------------------------------------
 # OAuth2 scheme (reads Authorization header — used as fallback / Swagger UI)
@@ -52,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.
@@ -72,66 +54,51 @@ 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
 
-    # Attempt the following; catch errors below
+    # ── API Key path (Bearer token starts with "aegis_") ──────────────────
+    if token.startswith(KEY_PREFIX):
+        from app.services.api_key_service import authenticate_raw_key
+        user = authenticate_raw_key(db, token)
+        if user is None:
+            raise credentials_exception
+        return 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
 
 
@@ -141,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.
@@ -149,74 +115,94 @@ 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
 
 
-# Define function require_role
-def require_role(required_role: str) -> Callable[..., object]:
+def _check_api_key_scope(user: User, required_scope: str) -> None:
+    """Raise 403 if the request was authenticated via an API key that lacks *required_scope*.
+
+    When authenticated via JWT (browser session), ``_api_key_scopes`` is not set
+    and the check is skipped — full access is granted based on role alone.
+    """
+    key_scopes = getattr(user, "_api_key_scopes", None)
+    if key_scopes is not None and required_scope not in key_scopes:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"API key scope '{required_scope}' required for this operation",
+        )
+
+
+def require_role(required_role: str):
     """Return a FastAPI dependency that enforces *required_role*.
 
     The dependency allows the request to proceed when
     ``user.role == required_role`` **or** ``user.role == "admin"``.
+    Also enforces API key scopes: admin-role endpoints require the ``admin``
+    scope; all other role-restricted endpoints require ``write``.
     Otherwise it raises :class:`~fastapi.HTTPException` **403**.
     """
 
-    # Define async function role_checker
     async def role_checker(
-        # Entry: current_user
         current_user: User = Depends(get_current_user),
     ) -> User:
-        # Check: current_user.role != required_role and current_user.role != "admin"
         if current_user.role != required_role and current_user.role != "admin":
-            # Raise HTTPException
             raise HTTPException(
-                # Keyword argument: status_code
                 status_code=status.HTTP_403_FORBIDDEN,
-                # Keyword argument: detail
                 detail="Not enough permissions",
             )
-        # Return current_user
+        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.  Usage example::
+    Admins always pass.  Also enforces API key scopes: if the only accepted
+    role is ``admin``, the key must carry the ``admin`` scope; otherwise the
+    ``write`` scope is required.
+
+    Usage example::
 
         @router.patch("/resource", dependencies=[Depends(require_any_role("red_lead", "blue_lead"))])
     """
 
-    # Define async function role_checker
     async def role_checker(
-        # Entry: current_user
         current_user: User = Depends(get_current_user),
     ) -> User:
-        # Check: current_user.role != "admin" and current_user.role not in roles
         if current_user.role != "admin" and current_user.role not in roles:
-            # Raise HTTPException
             raise HTTPException(
-                # Keyword argument: status_code
                 status_code=status.HTTP_403_FORBIDDEN,
-                # Keyword argument: detail
                 detail="Not enough permissions",
             )
-        # Return current_user
+        scope = "admin" if set(roles) == {"admin"} else "write"
+        _check_api_key_scope(current_user, scope)
         return current_user
 
-    # Return role_checker
     return role_checker
+
+
+def require_scope(scope: str):
+    """Return a dependency that enforces the API key carries *scope*.
+
+    JWT-authenticated requests (browser sessions) bypass this check entirely.
+    Use on mutation endpoints that don't already use ``require_role`` /
+    ``require_any_role``::
+
+        @router.post("/resource", dependencies=[Depends(require_scope("write"))])
+    """
+
+    async def scope_checker(
+        current_user: User = Depends(get_current_user),
+    ) -> User:
+        _check_api_key_scope(current_user, scope)
+        return current_user
+
+    return scope_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,299 +12,167 @@ 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.
 
-        Rules (v2):
+        Rules (v3):
           1. No tests -> not_evaluated
-          2. All validated -> inspect detection results:
-             - All detected -> validated
-             - Any partially_detected -> partial
-             - Otherwise -> not_covered
-          3. Some validated, others in progress -> partial
-          4. All in intermediate states -> in_progress
+          2. All tests validated -> inspect detection results:
+             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
 
-        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``.
+        Minimum validated count for "validated": 2 tests.
+        With only 1 validated+detected test the technique is "partial" to
+        signal that more testing is recommended.
 
-        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).
         """
-        # Assign tests = [
+        _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):
-            # Assign results = [t.detection_result for t in tests if t.detection_result]
+            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):
-                # Assign self.status_global = TechniqueStatus.validated
-                self.status_global = TechniqueStatus.validated
-            # elif any(
+                # 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,77 +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,67 +20,44 @@ 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],
     TestState.blue_evaluating: [TestState.in_review],
-    TestState.in_review:       [TestState.validated, TestState.rejected],
+    TestState.in_review:       [TestState.validated, TestState.rejected, TestState.disputed],
+    TestState.disputed:        [TestState.validated, TestState.rejected],
     TestState.rejected:        [TestState.draft],
     TestState.validated:       [],
 }
 
-# Assign _PAUSABLE_STATES = frozenset({TestState.red_executing, TestState.blue_evaluating})
 _PAUSABLE_STATES = frozenset({TestState.red_executing, TestState.blue_evaluating})
 
 
@@ -88,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)
 
 
@@ -102,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)
@@ -148,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 ------------------------------------------------
@@ -289,379 +171,189 @@ 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.
 
-        - Both **approved** -> ``validated``
-        - Either **rejected** -> ``rejected``
-        - Otherwise no change (waiting for the other lead).
+        Rules (v2 — consensus required):
+        - Both **approved**  -> ``validated``
+        - Both **rejected**  -> ``rejected``
+        - One approved + one rejected -> ``disputed`` (conflict, needs discussion)
+        - Otherwise (one or both still pending) -> no change
 
         Called automatically by :meth:`validate_red` and :meth:`validate_blue`.
-        Also available as a standalone entry point for backward compatibility
-        when validation fields are set externally.
-
-        Returns:
-            None
         """
-        # Call self._check_dual_validation()
         self._check_dual_validation()
 
-    # Define function _assert_in_review
     def _assert_in_review(self, side: str) -> None:
-        """Raise InvalidOperationError unless the test is in ``in_review`` state.
-
-        Args:
-            side (str): The team side being validated (``"red"`` or ``"blue"``),
-                used in the error message.
-
-        Returns:
-            None
-        """
-        # Check: self.state != TestState.in_review
-        if self.state != TestState.in_review:
-            # Raise InvalidOperationError
+        if self.state not in (TestState.in_review, TestState.disputed):
             raise InvalidOperationError(
                 f"Cannot validate {side} side while test is in "
-                f"'{self.state.value}' state (must be in_review)"
+                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 to ``validated`` or ``rejected`` once both leads have voted.
-
-        Returns:
-            None
-        """
-        # r, b = self.red_validation_status, self.blue_validation_status
+        """Advance the test state once both leads have voted."""
         r, b = self.red_validation_status, self.blue_validation_status
-        # Check: r == "rejected" or b == "rejected"
-        if r == "rejected" or b == "rejected":
-            # Assign self.state = TestState.rejected
-            self.state = TestState.rejected
-            # Call self._events.append()
-            self._events.append(DomainEvent("dual_validation_rejected"))
-        # Alternative: r == "approved" and b == "approved"
-        elif r == "approved" and b == "approved":
-            # Assign self.state = TestState.validated
+
+        if r == "approved" and b == "approved":
             self.state = TestState.validated
-            # Call self._events.append()
             self._events.append(DomainEvent("dual_validation_approved"))
+
+        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,43 +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__)
 
 # ---------------------------------------------------------------------------
@@ -63,172 +42,370 @@ scheduler = BackgroundScheduler()
 
 def _run_mitre_sync() -> None:
     """Execute a MITRE sync inside its own DB session."""
-    # Log info: "Scheduled MITRE sync job starting..."
+    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)
-    # Handle Exception
+        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()
 
 
-# Define function _run_intel_scan
+def _run_scheduled_campaign_activation() -> None:
+    """Auto-activate campaigns whose start_date has arrived.
+
+    Finds all campaigns in 'draft' state with a start_date <= now,
+    activates them, creates Jira tickets, and notifies the red_tech team.
+    Runs every hour so campaigns activate within ~1 hour of their scheduled time.
+    """
+    logger.info("Scheduled campaign auto-activation check starting...")
+    db = SessionLocal()
+    try:
+        from datetime import datetime as _dt
+        from app.models.campaign import Campaign
+        from app.models.user import User
+        from app.services.campaign_crud_service import activate_campaign as _activate
+        from app.services.notification_service import notify_role
+        from app.services.audit_service import log_action
+
+        now = _dt.utcnow()
+        due_campaigns = (
+            db.query(Campaign)
+            .filter(
+                Campaign.status == "draft",
+                Campaign.start_date != None,  # noqa: E711
+                Campaign.start_date <= now,
+            )
+            .all()
+        )
+
+        activated = 0
+        for campaign in due_campaigns:
+            try:
+                _activate(db, str(campaign.id))
+                notify_role(
+                    db,
+                    role="red_tech",
+                    type="campaign_activated",
+                    title="Campaign auto-activated",
+                    message=f'Campaign "{campaign.name}" has been automatically activated on its scheduled start date.',
+                    entity_type="campaign",
+                    entity_id=campaign.id,
+                )
+                log_action(
+                    db,
+                    user_id=None,
+                    action="auto_activate_campaign",
+                    entity_type="campaign",
+                    entity_id=campaign.id,
+                    details={"name": campaign.name, "start_date": str(campaign.start_date)},
+                )
+
+                # Create Jira tickets non-fatally
+                try:
+                    from app.services.jira_service import (
+                        auto_create_campaign_issue,
+                        auto_create_test_issue,
+                        get_campaign_jira_key,
+                        get_test_jira_key,
+                    )
+                    # Use first admin user as actor for Jira auth
+                    admin_user = db.query(User).filter(User.role == "admin").first()
+                    if admin_user:
+                        db.refresh(campaign)
+                        campaign_jira_key = get_campaign_jira_key(db, str(campaign.id))
+                        if not campaign_jira_key:
+                            campaign_jira_key = auto_create_campaign_issue(db, campaign, admin_user)
+                        if campaign_jira_key:
+                            for ct in campaign.campaign_tests:
+                                if ct.test and not get_test_jira_key(db, ct.test.id):
+                                    auto_create_test_issue(
+                                        db, ct.test, admin_user,
+                                        parent_ticket_override=campaign_jira_key,
+                                        campaign_start_date=campaign.start_date,
+                                    )
+                except Exception:
+                    logger.exception("Jira auto-create failed for auto-activated campaign %s", campaign.id)
+
+                db.commit()
+                activated += 1
+                logger.info("Auto-activated campaign %s (%s)", campaign.id, campaign.name)
+            except Exception:
+                logger.exception("Failed to auto-activate campaign %s", campaign.id)
+                db.rollback()
+
+        logger.info("Campaign auto-activation check finished — activated %d campaigns", activated)
+    except Exception:
+        logger.exception("Campaign auto-activation job failed")
+    finally:
+        db.close()
+
+
 def _run_intel_scan() -> None:
     """Execute an intel scan inside its own DB session."""
-    # Log info: "Scheduled intel scan job starting..."
     logger.info("Scheduled intel scan job starting...")
-    # Assign db = SessionLocal()
     db = SessionLocal()
-    # Attempt the following; catch errors below
     try:
-        # Assign summary = scan_intel(db)
         summary = scan_intel(db)
-        # Log info: "Scheduled intel scan job finished — %s", summary
         logger.info("Scheduled intel scan job finished — %s", summary)
-    # Handle Exception
     except Exception:
-        # Log exception: "Scheduled intel scan job failed"
         logger.exception("Scheduled intel scan job failed")
-    # Always execute this cleanup block
     finally:
-        # Close the database session
         db.close()
 
 
-# Define function _run_osint_enrichment
+def _run_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()
 
 
-# Define function _run_stale_detection
+_FREQUENCY_INTERVALS: dict[str, timedelta] = {
+    "daily": timedelta(days=1),
+    "weekly": timedelta(weeks=1),
+    "monthly": timedelta(days=30),
+}
+
+
+def _run_data_sources_sync() -> None:
+    """Check all enabled data sources and sync those that are overdue."""
+    logger.info("Scheduled data sources sync check starting...")
+    db = SessionLocal()
+    try:
+        from app.models.data_source import DataSource
+        from app.services.data_source_service import sync_source
+
+        now = datetime.now(timezone.utc)
+        sources = (
+            db.query(DataSource)
+            .filter(DataSource.is_enabled == True)  # noqa: E712
+            .all()
+        )
+        synced = 0
+        for ds in sources:
+            freq = ds.sync_frequency
+            if not freq or freq == "manual":
+                continue
+            interval = _FREQUENCY_INTERVALS.get(freq)
+            if interval is None:
+                continue
+            last = ds.last_sync_at
+            if last is None:
+                # Never synced — run it now
+                overdue = True
+            else:
+                # Make last timezone-aware if needed
+                if last.tzinfo is None:
+                    last = last.replace(tzinfo=timezone.utc)
+                overdue = now - last >= interval
+            if overdue:
+                logger.info(
+                    "Data source '%s' is overdue (freq=%s, last=%s) — syncing",
+                    ds.name, freq, last,
+                )
+                try:
+                    sync_source(db, str(ds.id))
+                    synced += 1
+                except Exception:
+                    logger.exception("Failed to sync data source '%s'", ds.name)
+        logger.info("Data sources sync check finished — %d source(s) synced", synced)
+    except Exception:
+        logger.exception("Data sources sync check failed")
+    finally:
+        db.close()
+
+
 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()
+
+
+def _run_decay_engine() -> None:
+    """Execute the decay engine inside its own DB session."""
+    logger.info("Scheduled decay engine job starting...")
+    db = SessionLocal()
+    try:
+        from app.services.decay_engine_service import run_decay_engine
+        results = run_decay_engine(db)
+        logger.info("Decay engine job finished — %s", results)
+    except Exception:
+        logger.exception("Decay engine job failed")
+    finally:
+        db.close()
+
+
+def _run_queue_generation() -> None:
+    """Generate revalidation queue items for analysts — runs after decay engine."""
+    logger.info("Scheduled revalidation queue generation starting...")
+    db = SessionLocal()
+    try:
+        from app.services.revalidation_queue_service import generate_queue_items
+        results = generate_queue_items(db)
+        logger.info("Queue generation finished — %s", results)
+    except Exception:
+        logger.exception("Queue generation job failed")
+    finally:
+        db.close()
+
+
+def _run_alert_evaluation() -> None:
+    """Evaluate all enabled operational alert rules (hourly)."""
+    logger.info("Scheduled alert evaluation job starting...")
+    db = SessionLocal()
+    try:
+        from app.services.operational_alert_service import evaluate_all_rules
+        result = evaluate_all_rules(db)
+        logger.info(
+            "Alert evaluation finished — %d rules, %d alerts fired in %.3fs",
+            result["rules_evaluated"],
+            result["alerts_fired"],
+            result["duration_seconds"],
+        )
+    except Exception:
+        logger.exception("Alert evaluation job failed")
+    finally:
         db.close()
 
 
@@ -247,148 +424,138 @@ 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",
+        hours=1,
+        id="scheduled_campaign_activation",
+        name="Auto-activate campaigns on start_date (hourly)",
+        replace_existing=True,
+    )
     scheduler.add_job(
         _run_recurring_campaigns,
-        # Keyword argument: trigger
         trigger="interval",
-        # Keyword argument: hours
         hours=24,
-        # Keyword argument: id
         id="recurring_campaigns",
-        # Keyword argument: name
         name="Recurring campaigns check (daily)",
-        # Keyword argument: replace_existing
         replace_existing=True,
     )
-    # Call scheduler.add_job()
     scheduler.add_job(
         sync_all_jira_links,
-        # Keyword argument: trigger
         trigger="interval",
-        # Keyword argument: hours
         hours=1,
-        # Keyword argument: id
         id="jira_sync",
-        # Keyword argument: name
         name="Jira link sync (hourly)",
-        # Keyword argument: replace_existing
         replace_existing=True,
     )
-    # Call scheduler.add_job()
     scheduler.add_job(
         _run_osint_enrichment,
-        # Keyword argument: trigger
         trigger="interval",
-        # Keyword argument: weeks
         weeks=1,
-        # Keyword argument: id
         id="osint_enrichment",
-        # Keyword argument: name
         name="OSINT enrichment (weekly)",
-        # Keyword argument: replace_existing
         replace_existing=True,
     )
-    # Call scheduler.add_job()
     scheduler.add_job(
         _run_stale_detection,
-        # Keyword argument: trigger
         trigger="interval",
-        # Keyword argument: hours
         hours=24,
-        # Keyword argument: id
         id="stale_detection",
-        # Keyword argument: name
         name="Stale coverage detection (daily)",
-        # Keyword argument: replace_existing
         replace_existing=True,
     )
-    # Call scheduler.add_job()
     scheduler.add_job(
         run_retention_job,
-        # Keyword argument: trigger
         trigger="interval",
-        # Keyword argument: hours
         hours=24,
-        # Keyword argument: id
         id="retention_policies",
-        # Keyword argument: name
         name="Data retention policies (daily)",
-        # Keyword argument: replace_existing
         replace_existing=True,
     )
-    # Call scheduler.start()
-    scheduler.start()
-    # Log info:
-    logger.info(
-        # Literal argument value
-        "Background scheduler started — mitre_sync (24h), intel_scan (7d), "
-        # Literal argument value
-        "notification_cleanup (24h), weekly_snapshot (Sundays 00:00), "
-        # Literal argument value
-        "recurring_campaigns (daily), jira_sync (1h), "
-        # Literal argument value
-        "osint_enrichment (weekly), stale_detection (daily), "
-        # Literal argument value
-        "retention_policies (daily)"
+    scheduler.add_job(
+        _run_data_sources_sync,
+        trigger="interval",
+        hours=6,
+        id="data_sources_sync",
+        name="Data sources auto-sync (every 6h)",
+        replace_existing=True,
+    )
+    scheduler.add_job(
+        _run_decay_engine,
+        trigger="cron",
+        hour=2,
+        minute=0,
+        id="decay_engine",
+        name="Detection decay engine (daily 02:00)",
+        replace_existing=True,
+    )
+    scheduler.add_job(
+        _run_queue_generation,
+        trigger="cron",
+        hour=2,
+        minute=30,
+        id="queue_generation",
+        name="Revalidation queue generation (daily 02:30)",
+        replace_existing=True,
+    )
+    scheduler.add_job(
+        _run_alert_evaluation,
+        trigger="interval",
+        hours=1,
+        id="alert_evaluation",
+        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()
+    logger.info(
+        "Background scheduler started — mitre_sync (24h), intel_scan (7d), "
+        "notification_cleanup (24h), weekly_snapshot (Sundays 00:00), "
+        "recurring_campaigns (daily), jira_sync (1h), "
+        "osint_enrichment (weekly), stale_detection (daily), "
+        "retention_policies (daily), data_sources_sync (6h), "
+        "alert_evaluation (1h), attck_evaluation_check (Mondays 06:00)"
     )

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,171 +1,93 @@
-"""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
 
-# Import settings as _settings from app.config
-from app.config import settings as _settings
-
-# Import DomainError from app.domain.errors
-from app.domain.errors import DomainError
-
-# Import scheduler, start_scheduler from app.jobs.mitre_sync_job
-from app.jobs.mitre_sync_job import scheduler, start_scheduler
-
-# Import limiter from app.limiter
-from app.limiter import limiter
-
-# Import setup_logging from app.logging_config
-from app.logging_config import setup_logging
-
-# Import domain_exception_handler from app.middleware.error_handler
-from app.middleware.error_handler import domain_exception_handler
-
-# Import RequestContextMiddleware from app.middleware.request_context
-from app.middleware.request_context import RequestContextMiddleware
-
-# Import advanced_metrics as advanced_metrics_router from app.routers
-from app.routers import advanced_metrics as advanced_metrics_router
-
-# Import analytics as analytics_router from app.routers
-from app.routers import analytics as analytics_router
-
-# Import audit as audit_router from app.routers
-from app.routers import audit as audit_router
-
-# Import auth as auth_router from app.routers
 from app.routers import auth as auth_router
-
-# Import campaigns as campaigns_router from app.routers
-from app.routers import campaigns as campaigns_router
-
-# Import compliance as compliance_router from app.routers
-from app.routers import compliance as compliance_router
-
-# Import d3fend as d3fend_router from app.routers
-from app.routers import d3fend as d3fend_router
-
-# Import data_sources as data_sources_router from app.routers
-from app.routers import data_sources as data_sources_router
-
-# Import detection_rules as detection_rules_router from app.routers
-from app.routers import detection_rules as detection_rules_router
-
-# Import evidence as evidence_router from app.routers
-from app.routers import evidence as evidence_router
-
-# Import heatmap as heatmap_router from app.routers
-from app.routers import heatmap as heatmap_router
-
-# Import jira as jira_router from app.routers
-from app.routers import jira as jira_router
-
-# Import metrics as metrics_router from app.routers
-from app.routers import metrics as metrics_router
-
-# Import notifications as notifications_router from app.routers
-from app.routers import notifications as notifications_router
-
-# Import operational_metrics as operational_metrics_router from app.routers
-from app.routers import operational_metrics as operational_metrics_router
-
-# Import osint as osint_router from app.routers
-from app.routers import osint as osint_router
-
-# Import professional_reports as professional_reports_ro... from app.routers
-from app.routers import professional_reports as professional_reports_router
-
-# Import reports as reports_router from app.routers
-from app.routers import reports as reports_router
-
-# Import scores as scores_router from app.routers
-from app.routers import scores as scores_router
-
-# Import snapshots as snapshots_router from app.routers
-from app.routers import snapshots as snapshots_router
-
-# Import system as system_router from app.routers
-from app.routers import system as system_router
-
-# Import techniques as techniques_router from app.routers
 from app.routers import techniques as techniques_router
-
-# Import test_templates as test_templates_router from app.routers
-from app.routers import test_templates as test_templates_router
-
-# Import tests as tests_router from app.routers
 from app.routers import tests as tests_router
-
-# Import threat_actors as threat_actors_router from app.routers
-from app.routers import threat_actors as threat_actors_router
-
-# Import users as users_router from app.routers
+from app.routers import evidence as evidence_router
+from app.routers import test_templates as test_templates_router
+from app.routers import system as system_router
+from app.routers import metrics as metrics_router
 from app.routers import users as users_router
-
-# Import worklogs as worklogs_router from app.routers
+from app.routers import audit as audit_router
+from app.routers import notifications as notifications_router
+from app.routers import reports as reports_router
+from app.routers import data_sources as data_sources_router
+from app.routers import threat_actors as threat_actors_router
+from app.routers import d3fend as d3fend_router
+from app.routers import detection_rules as detection_rules_router
+from app.routers import campaigns as campaigns_router
+from app.routers import heatmap as heatmap_router
+from app.routers import scores as scores_router
+from app.routers import operational_metrics as operational_metrics_router
+from app.routers import compliance as compliance_router
+from app.routers import snapshots as snapshots_router
+from app.routers import jira as jira_router
 from app.routers import worklogs as worklogs_router
-
-# Import ensure_bucket_exists from app.storage
+from app.routers import professional_reports as professional_reports_router
+from app.routers import analytics as analytics_router
+from app.routers import advanced_metrics as advanced_metrics_router
+from app.routers import osint as osint_router
+from app.routers import webhooks as webhooks_router
+from app.routers import detection_lifecycle as detection_lifecycle_router
+from app.routers import intel as intel_router
+from app.routers import admin_config as admin_config_router
+from app.routers import ownership as ownership_router
+from app.routers import attack_paths as attack_paths_router
+from app.routers import knowledge as knowledge_router
+from app.routers import risk_intelligence as risk_router
+from app.routers import executive_dashboard as dashboard_router
+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
+from app.middleware.error_handler import domain_exception_handler
+from app.middleware.request_context import RequestContextMiddleware
+from app.limiter import limiter
 from app.storage import ensure_bucket_exists
-
-# Configure structured logging before any module initialises its own logger
-setup_logging()
+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()
-    # Yield value
+    # Seed decay policies
+    from app.database import SessionLocal
+    from app.seed_decay_policies import seed_decay_policies
+    db = SessionLocal()
+    try:
+        seed_decay_policies(db)
+    except Exception:
+        pass
+    finally:
+        db.close()
+    # Seed operational alert system rules
+    db2 = SessionLocal()
+    try:
+        from app.services.operational_alert_service import seed_system_rules
+        seed_system_rules(db2)
+    except Exception:
+        pass
+    finally:
+        db2.close()
     yield
     # Graceful shutdown of the background scheduler
     scheduler.shutdown(wait=False)
@@ -173,116 +95,104 @@ 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)
+        if request.url.path.startswith("/api/"):
+            response.headers["Cache-Control"] = "no-store, no-cache, must-revalidate"
+            response.headers["Pragma"] = "no-cache"
+        return response
+
+app.add_middleware(NoCacheAPIMiddleware)
+
+
 # ── Domain exception → HTTP mapping ──────────────────────────────────────
 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")
-# Call app.include_router()
+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")
+app.include_router(ownership_router.router, prefix="/api/v1")
+app.include_router(attack_paths_router.router, prefix="/api/v1")
+app.include_router(knowledge_router.router, prefix="/api/v1")
+app.include_router(risk_router.router, prefix="/api/v1")
+app.include_router(dashboard_router.router, prefix="/api/v1")
+app.include_router(api_keys_router.router, prefix="/api/v1")
+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,96 +1,75 @@
-"""SQLAlchemy ORM model definitions for all database tables."""
 # Import all models here so Alembic can detect them
-from app.models.audit import AuditLog
-
-# Import Campaign, CampaignTest from app.models.campaign
-from app.models.campaign import Campaign, CampaignTest
-
-# Import  from app.models.compliance
-from app.models.compliance import (
-    ComplianceControl,
-    ComplianceControlMapping,
-    ComplianceFramework,
-)
-
-# Import CoverageSnapshot, SnapshotTechniqueState from app.models.coverage_snapshot
-from app.models.coverage_snapshot import CoverageSnapshot, SnapshotTechniqueState
-
-# Import DataSource from app.models.data_source
-from app.models.data_source import DataSource
-
-# Import DefensiveTechnique, DefensiveTechniqueMapping from app.models.defensive_technique
-from app.models.defensive_technique import DefensiveTechnique, DefensiveTechniqueMapping
-
-# Import DetectionRule from app.models.detection_rule
-from app.models.detection_rule import DetectionRule
-
-# Import TeamSide, TechniqueStatus, TestResult, TestState from app.models.enums
-from app.models.enums import TeamSide, TechniqueStatus, TestResult, TestState
-
-# Import Evidence from app.models.evidence
-from app.models.evidence import Evidence
-
-# Import IntelItem from app.models.intel
-from app.models.intel import IntelItem
-
-# Import JiraLink, JiraLinkEntityType, JiraSyncDirection from app.models.jira_link
-from app.models.jira_link import JiraLink, JiraLinkEntityType, JiraSyncDirection
-
-# Import Notification from app.models.notification
-from app.models.notification import Notification
-
-# Import OsintItem from app.models.osint_item
-from app.models.osint_item import OsintItem
-
-# Import ScoringConfig from app.models.scoring_config
-from app.models.scoring_config import ScoringConfig
-
-# Import Technique from app.models.technique
-from app.models.technique import Technique
-
-# Import Test from app.models.test
-from app.models.test import Test
-
-# Import TestDetectionResult from app.models.test_detection_result
-from app.models.test_detection_result import TestDetectionResult
-
-# Import TestTemplate from app.models.test_template
-from app.models.test_template import TestTemplate
-
-# Import TestTemplateDetectionRule from app.models.test_template_detection_rule
-from app.models.test_template_detection_rule import TestTemplateDetectionRule
-
-# Import ThreatActor, ThreatActorTechnique from app.models.threat_actor
-from app.models.threat_actor import ThreatActor, ThreatActorTechnique
-
-# Import User from app.models.user
 from app.models.user import User
-
-# Import Worklog from app.models.worklog
+from app.models.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
+from app.models.detection_rule import DetectionRule
+from app.models.threat_actor import ThreatActor, ThreatActorTechnique
+from app.models.defensive_technique import DefensiveTechnique, DefensiveTechniqueMapping
+from app.models.test_template_detection_rule import TestTemplateDetectionRule
+from app.models.test_detection_result import TestDetectionResult
+from app.models.campaign import Campaign, CampaignTest
+from app.models.compliance import ComplianceFramework, ComplianceControl, ComplianceControlMapping
+from app.models.coverage_snapshot import CoverageSnapshot, SnapshotTechniqueState
+from app.models.jira_link import JiraLink, JiraLinkEntityType, JiraSyncDirection
 from app.models.worklog import Worklog
+from app.models.osint_item import OsintItem
+from app.models.scoring_config import ScoringConfig
+from app.models.enums import TechniqueStatus, TestState, TestResult, TeamSide
+from app.models.webhook_config import WebhookConfig
+from app.models.system_config import SystemConfig
+from app.models.detection_lifecycle import (
+    DetectionAsset, DetectionTechniqueMapping, DetectionValidation,
+    TechniqueConfidenceScore, InfrastructureChangeLog,
+    DetectionConfidence, DetectionHealthStatus, InvalidationReason,
+)
+from app.models.decay_policy import DecayPolicy
+from app.models.ownership_queue import (
+    TechniqueOwnership, RevalidationQueueItem,
+    QueuePriority, QueueStatus, QueueReason,
+)
+from app.models.attack_path import (
+    AttackPath, AttackPathStep, AttackPathExecution,
+    AttackPathStepResult, TimelineEntry,
+    ExecutionStatus, StepResultStatus, TimelineActorSide, TimelineEntryType,
+)
+from app.models.knowledge import Playbook, PlaybookVersion, LessonLearned
+from app.models.risk_intelligence import TechniqueRiskProfile
+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
 
-# 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", "DecayPolicy",
+    "TechniqueOwnership", "RevalidationQueueItem",
+    "QueuePriority", "QueueStatus", "QueueReason",
+    "AttackPath", "AttackPathStep", "AttackPathExecution",
+    "AttackPathStepResult", "TimelineEntry",
+    "ExecutionStatus", "StepResultStatus", "TimelineActorSide", "TimelineEntryType",
+    "Playbook", "PlaybookVersion", "LessonLearned",
+    "TechniqueRiskProfile",
+    "PostureSnapshot",
+    "ApiKey",
+    "SsoConfig",
+    "AlertRule",
+    "AlertInstance",
 ]

backend/app/models/api_key.py

@@ -0,0 +1,81 @@
+"""Phase 14: API Key model for programmatic access."""
+
+import hashlib
+import secrets
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Index, String, Text
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+# ── Key generation constants ──────────────────────────────────────────────────
+KEY_PREFIX  = "aegis_"
+KEY_BYTES   = 32    # 32 random bytes → 64 hex chars → 70-char key total
+DISPLAY_LEN = 12    # chars stored as prefix for UI display
+
+
+def generate_raw_key() -> str:
+    """Generate a fresh raw API key (must be shown to user only once)."""
+    return KEY_PREFIX + secrets.token_hex(KEY_BYTES)
+
+
+def hash_key(raw_key: str) -> str:
+    """SHA-256 hash of a raw API key for secure storage."""
+    return hashlib.sha256(raw_key.encode()).hexdigest()
+
+
+def key_prefix_display(raw_key: str) -> str:
+    """First DISPLAY_LEN characters of the raw key (safe for UI)."""
+    return raw_key[:DISPLAY_LEN]
+
+
+# ── Valid scopes ──────────────────────────────────────────────────────────────
+VALID_SCOPES = {"read", "write", "admin"}
+
+
+class ApiKey(Base):
+    """
+    Scoped API key for programmatic / BI / SOAR access.
+
+    The full raw key is **never stored** — only a SHA-256 hash.
+    The first 12 characters (``key_prefix``) are retained for display.
+    """
+
+    __tablename__ = "api_keys"
+
+    id          = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name        = Column(String(200), nullable=False)
+    description = Column(Text, nullable=True)
+
+    # Display only — never use for auth
+    key_prefix  = Column(String(DISPLAY_LEN + 1), nullable=False)
+
+    # Auth token — SHA-256 of the full raw key
+    key_hash    = Column(String(64), nullable=False, unique=True)
+
+    # Owner
+    user_id     = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    # Permissions
+    scopes      = Column(JSONB, nullable=False, default=["read"])   # ["read","write","admin"]
+
+    # Lifecycle
+    last_used_at = Column(DateTime, nullable=True)
+    expires_at   = Column(DateTime, nullable=True)
+    is_active    = Column(Boolean, nullable=False, default=True)
+    created_at   = Column(DateTime, default=datetime.utcnow)
+
+    user = relationship("User", foreign_keys=[user_id])
+
+    __table_args__ = (
+        Index("ix_api_keys_user_id",  "user_id"),
+        Index("ix_api_keys_key_hash", "key_hash"),
+        Index("ix_api_keys_active",   "is_active"),
+    )

backend/app/models/attack_path.py

@@ -0,0 +1,253 @@
+"""Phase 10: Attack Paths & Advanced Purple Team models."""
+
+import enum
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean, Column, DateTime, Enum, Float, ForeignKey,
+    Index, Integer, String, Text,
+)
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+class ExecutionStatus(str, enum.Enum):
+    planned    = "planned"
+    in_progress = "in_progress"
+    completed  = "completed"
+    aborted    = "aborted"
+
+
+class StepResultStatus(str, enum.Enum):
+    pending      = "pending"
+    executing    = "executing"
+    detected     = "detected"
+    not_detected = "not_detected"
+    skipped      = "skipped"
+
+
+class TimelineActorSide(str, enum.Enum):
+    red    = "red"
+    blue   = "blue"
+    system = "system"
+
+
+class TimelineEntryType(str, enum.Enum):
+    action           = "action"
+    detection        = "detection"
+    note             = "note"
+    phase_transition = "phase_transition"
+    flag             = "flag"
+
+
+# ---------------------------------------------------------------------------
+
+class AttackPath(Base):
+    """
+    A reusable attack scenario composed of ordered kill-chain steps.
+    Can be a template (shared) or a one-off scenario.
+    """
+    __tablename__ = "attack_paths"
+
+    id          = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name        = Column(String(300), nullable=False)
+    description = Column(Text, nullable=True)
+    objective   = Column(Text, nullable=True)            # what the attacker aims to achieve
+    is_template = Column(Boolean, default=False)         # reusable template flag
+    threat_actor_id = Column(
+        UUID(as_uuid=True), ForeignKey("threat_actors.id", ondelete="SET NULL"), nullable=True
+    )
+    created_by  = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    tags        = Column(JSONB, nullable=True, default=list)
+    is_active   = Column(Boolean, default=True)
+    created_at  = Column(DateTime, default=datetime.utcnow)
+    updated_at  = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    steps      = relationship(
+        "AttackPathStep", back_populates="attack_path",
+        cascade="all, delete-orphan",
+        order_by="AttackPathStep.order_index",
+    )
+    executions = relationship("AttackPathExecution", back_populates="attack_path")
+    creator    = relationship("User", foreign_keys=[created_by])
+    threat_actor = relationship("ThreatActor", foreign_keys=[threat_actor_id])
+
+    __table_args__ = (
+        Index("ix_attack_paths_created_by", "created_by"),
+        Index("ix_attack_paths_is_template", "is_template"),
+    )
+
+
+class AttackPathStep(Base):
+    """One step in an attack path — maps to a kill-chain phase + technique."""
+
+    __tablename__ = "attack_path_steps"
+
+    id              = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    attack_path_id  = Column(
+        UUID(as_uuid=True), ForeignKey("attack_paths.id", ondelete="CASCADE"), nullable=False
+    )
+    order_index     = Column(Integer, nullable=False, default=0)
+    kill_chain_phase = Column(String(60), nullable=True)   # initial_access, execution, …
+    technique_id    = Column(
+        UUID(as_uuid=True), ForeignKey("techniques.id", ondelete="SET NULL"), nullable=True
+    )
+    test_id         = Column(
+        UUID(as_uuid=True), ForeignKey("tests.id", ondelete="SET NULL"), nullable=True
+    )
+    name            = Column(String(300), nullable=True)   # human label for the step
+    description     = Column(Text, nullable=True)
+    expected_detection = Column(Boolean, default=True)    # do we expect blue to detect this?
+    notes           = Column(Text, nullable=True)
+
+    attack_path = relationship("AttackPath", back_populates="steps")
+    technique   = relationship("Technique", foreign_keys=[technique_id])
+    test        = relationship("Test", foreign_keys=[test_id])
+
+    __table_args__ = (
+        Index("ix_ap_steps_path_id", "attack_path_id"),
+        Index("ix_ap_steps_technique_id", "technique_id"),
+    )
+
+
+class AttackPathExecution(Base):
+    """
+    A single run of an attack path.
+    Tracks Red/Blue participants, timing, and aggregated kill-chain metrics.
+    """
+    __tablename__ = "attack_path_executions"
+
+    id             = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    attack_path_id = Column(
+        UUID(as_uuid=True), ForeignKey("attack_paths.id", ondelete="CASCADE"), nullable=False
+    )
+    status         = Column(
+        Enum(ExecutionStatus, name="execution_status"), nullable=False,
+        default=ExecutionStatus.planned,
+    )
+    environment    = Column(String(100), nullable=True)   # prod, staging, lab
+    red_team_lead  = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    blue_team_lead = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    started_by     = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    started_at     = Column(DateTime, nullable=True)
+    completed_at   = Column(DateTime, nullable=True)
+    notes          = Column(Text, nullable=True)
+    created_at     = Column(DateTime, default=datetime.utcnow)
+
+    # ── Computed kill-chain metrics (written on complete) ─────────────────
+    total_steps             = Column(Integer, nullable=True)
+    detected_steps          = Column(Integer, nullable=True)
+    not_detected_steps      = Column(Integer, nullable=True)
+    skipped_steps           = Column(Integer, nullable=True)
+    detection_rate          = Column(Float, nullable=True)   # 0.0–1.0
+    mttd_seconds            = Column(Float, nullable=True)   # mean time to detect (avg across detected)
+    furthest_undetected_step = Column(Integer, nullable=True)  # order_index of deepest undetected step
+
+    attack_path  = relationship("AttackPath", back_populates="executions")
+    step_results = relationship(
+        "AttackPathStepResult", back_populates="execution",
+        cascade="all, delete-orphan",
+        order_by="AttackPathStepResult.step_order",
+    )
+    timeline     = relationship(
+        "TimelineEntry", back_populates="execution",
+        cascade="all, delete-orphan",
+        order_by="TimelineEntry.timestamp",
+    )
+    red_lead_user  = relationship("User", foreign_keys=[red_team_lead])
+    blue_lead_user = relationship("User", foreign_keys=[blue_team_lead])
+
+    __table_args__ = (
+        Index("ix_ap_exec_path_id", "attack_path_id"),
+        Index("ix_ap_exec_status", "status"),
+    )
+
+
+class AttackPathStepResult(Base):
+    """Result of executing one step in an attack path execution."""
+
+    __tablename__ = "attack_path_step_results"
+
+    id              = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    execution_id    = Column(
+        UUID(as_uuid=True), ForeignKey("attack_path_executions.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    step_id         = Column(
+        UUID(as_uuid=True), ForeignKey("attack_path_steps.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    step_order      = Column(Integer, nullable=False, default=0)  # denormalized for sorting
+    status          = Column(
+        Enum(StepResultStatus, name="step_result_status"), nullable=False,
+        default=StepResultStatus.pending,
+    )
+    executed_by     = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    executed_at     = Column(DateTime, nullable=True)
+    detected_at     = Column(DateTime, nullable=True)
+    time_to_detect_seconds = Column(Float, nullable=True)
+    detection_asset_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("detection_assets.id", ondelete="SET NULL"), nullable=True
+    )
+    notes           = Column(Text, nullable=True)
+    evidence_ids    = Column(JSONB, nullable=True, default=list)
+
+    execution       = relationship("AttackPathExecution", back_populates="step_results")
+    step            = relationship("AttackPathStep")
+    detection_asset = relationship("DetectionAsset", foreign_keys=[detection_asset_id])
+    executor        = relationship("User", foreign_keys=[executed_by])
+
+    __table_args__ = (
+        Index("ix_ap_stepres_execution_id", "execution_id"),
+        Index("ix_ap_stepres_step_id", "step_id"),
+    )
+
+
+class TimelineEntry(Base):
+    """Timestamped Red/Blue action during an execution — used for MTTD/MTTR."""
+
+    __tablename__ = "attack_path_timeline"
+
+    id           = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    execution_id = Column(
+        UUID(as_uuid=True), ForeignKey("attack_path_executions.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    step_id      = Column(
+        UUID(as_uuid=True), ForeignKey("attack_path_steps.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    timestamp    = Column(DateTime, nullable=False, default=datetime.utcnow)
+    actor_side   = Column(
+        Enum(TimelineActorSide, name="timeline_actor_side"), nullable=False,
+    )
+    actor_id     = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    entry_type   = Column(
+        Enum(TimelineEntryType, name="timeline_entry_type"), nullable=False,
+    )
+    content      = Column(Text, nullable=False)
+    extra        = Column(JSONB, nullable=True)
+
+    execution = relationship("AttackPathExecution", back_populates="timeline")
+    actor     = relationship("User", foreign_keys=[actor_id])
+
+    __table_args__ = (
+        Index("ix_timeline_execution_id", "execution_id"),
+        Index("ix_timeline_timestamp", "timestamp"),
+    )

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,
     )
-    # Assign scheduled_at = Column(DateTime, 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/decay_policy.py

@@ -0,0 +1,32 @@
+"""Decay Policy model — configurable detection validity rules."""
+
+import uuid
+from datetime import datetime
+from sqlalchemy import Column, String, Integer, Float, Boolean, DateTime, Text
+from sqlalchemy.dialects.postgresql import UUID
+from app.database import Base
+
+
+class DecayPolicy(Base):
+    __tablename__ = "decay_policies"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name = Column(String(200), nullable=False)
+    description = Column(Text)
+    applies_to_platform = Column(String(100))
+    applies_to_asset_type = Column(String(50))
+    applies_to_tactic = Column(String(100))
+    fresh_days = Column(Integer, default=90, server_default='90')
+    aging_days = Column(Integer, default=180, server_default='180')
+    stale_days = Column(Integer, default=365, server_default='365')
+    default_validity_days = Column(Integer, default=180, server_default='180')
+    silent_threshold_days = Column(Integer, default=30, server_default='30')
+    noisy_threshold_daily = Column(Integer, default=100, server_default='100')
+    recency_weight = Column(Float, default=0.3, server_default='0.3')
+    coverage_weight = Column(Float, default=0.3, server_default='0.3')
+    health_weight = Column(Float, default=0.25, server_default='0.25')
+    diversity_weight = Column(Float, default=0.15, server_default='0.15')
+    is_default = Column(Boolean, default=False, server_default='false')
+    is_active = Column(Boolean, default=True, server_default='true')
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow)

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_lifecycle.py

@@ -0,0 +1,168 @@
+"""Detection Lifecycle Management models."""
+
+import uuid
+import enum
+from datetime import datetime
+from sqlalchemy import (
+    Column, String, Integer, Float, Boolean, DateTime,
+    ForeignKey, Text, Enum as SQLEnum
+)
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from sqlalchemy.orm import relationship
+from app.database import Base
+
+
+class DetectionConfidence(str, enum.Enum):
+    fresh = "fresh"
+    aging = "aging"
+    stale = "stale"
+    broken = "broken"
+    unknown = "unknown"
+
+
+class DetectionHealthStatus(str, enum.Enum):
+    healthy = "healthy"
+    silent = "silent"
+    noisy = "noisy"
+    orphan = "orphan"
+    deprecated = "deprecated"
+    untested = "untested"
+
+
+class InvalidationReason(str, enum.Enum):
+    time_decay = "time_decay"
+    mitre_update = "mitre_update"
+    log_source_change = "log_source_change"
+    siem_update = "siem_update"
+    edr_update = "edr_update"
+    infrastructure_change = "infrastructure_change"
+    parser_change = "parser_change"
+    manual = "manual"
+    rule_modified = "rule_modified"
+
+
+class DetectionAsset(Base):
+    __tablename__ = "detection_assets"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name = Column(String(500), nullable=False)
+    description = Column(Text)
+    asset_type = Column(String(50), nullable=False)
+    platform = Column(String(100))
+    rule_content = Column(Text)
+    rule_language = Column(String(50))
+    rule_repository_url = Column(Text)
+    rule_file_path = Column(String(500))
+    rule_version = Column(String(50))
+    rule_hash = Column(String(64))
+    last_rule_change_at = Column(DateTime)
+    log_source_name = Column(String(200))
+    log_source_version = Column(String(50))
+    log_source_config = Column(JSONB, server_default='{}')
+    infrastructure_hash = Column(String(64))
+    infrastructure_details = Column(JSONB, server_default='{}')
+    health_status = Column(
+        SQLEnum(DetectionHealthStatus, name="detectionhealthstatus"),
+        default=DetectionHealthStatus.untested,
+        nullable=False,
+        server_default="untested",
+    )
+    last_alert_at = Column(DateTime)
+    alert_count_30d = Column(Integer, default=0, server_default='0')
+    false_positive_rate = Column(Float)
+    expected_alert_frequency = Column(String(50))
+    owner_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    backup_owner_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    team = Column(String(100))
+    is_active = Column(Boolean, default=True, nullable=False, server_default='true')
+    tags = Column(JSONB, server_default='[]')
+    asset_metadata = Column(JSONB, server_default='{}')
+    created_by = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default='now()')
+    updated_at = Column(DateTime(timezone=True), server_default='now()')
+
+    technique_mappings = relationship("DetectionTechniqueMapping", back_populates="detection_asset", cascade="all, delete-orphan")
+    validations = relationship("DetectionValidation", back_populates="detection_asset", cascade="all, delete-orphan")
+
+
+class DetectionTechniqueMapping(Base):
+    __tablename__ = "detection_technique_mappings"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    detection_asset_id = Column(UUID(as_uuid=True), ForeignKey("detection_assets.id", ondelete="CASCADE"), nullable=False)
+    technique_id = Column(UUID(as_uuid=True), ForeignKey("techniques.id", ondelete="CASCADE"), nullable=False)
+    coverage_type = Column(String(50), default="detect", server_default="detect")
+    confidence_level = Column(String(20), default="medium", server_default="medium")
+    notes = Column(Text)
+    created_at = Column(DateTime(timezone=True), server_default='now()')
+
+    detection_asset = relationship("DetectionAsset", back_populates="technique_mappings")
+
+
+class DetectionValidation(Base):
+    __tablename__ = "detection_validations"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    detection_asset_id = Column(UUID(as_uuid=True), ForeignKey("detection_assets.id", ondelete="CASCADE"), nullable=False)
+    technique_id = Column(UUID(as_uuid=True), ForeignKey("techniques.id", ondelete="SET NULL"), nullable=True)
+    test_id = Column(UUID(as_uuid=True), ForeignKey("tests.id", ondelete="SET NULL"), nullable=True)
+    validated_at = Column(DateTime, default=datetime.utcnow)
+    expires_at = Column(DateTime, nullable=False)
+    is_valid = Column(Boolean, default=True, nullable=False, server_default='true')
+    validation_result = Column(String(50))
+    validation_method = Column(String(100))
+    rule_hash_at_validation = Column(String(64))
+    log_source_version_at_validation = Column(String(50))
+    infrastructure_hash_at_validation = Column(String(64))
+    environment_snapshot = Column(JSONB, server_default='{}')
+    invalidated_at = Column(DateTime)
+    invalidation_reason = Column(SQLEnum(InvalidationReason, name="invalidationreason"), nullable=True)
+    invalidation_details = Column(Text)
+    invalidated_by = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    validated_by = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=False)
+    integrity_hash = Column(String(64))
+    notes = Column(Text)
+    evidence_ids = Column(JSONB, server_default='[]')
+
+    detection_asset = relationship("DetectionAsset", back_populates="validations")
+
+
+class TechniqueConfidenceScore(Base):
+    __tablename__ = "technique_confidence_scores"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    technique_id = Column(UUID(as_uuid=True), ForeignKey("techniques.id", ondelete="CASCADE"), nullable=False, unique=True)
+    confidence_level = Column(
+        SQLEnum(DetectionConfidence, name="detectionconfidence"),
+        default=DetectionConfidence.unknown,
+        server_default="unknown",
+    )
+    confidence_score = Column(Float, default=0.0, server_default='0.0')
+    detection_count = Column(Integer, default=0, server_default='0')
+    valid_detection_count = Column(Integer, default=0, server_default='0')
+    last_validated_at = Column(DateTime)
+    next_validation_due = Column(DateTime)
+    last_recalculated_at = Column(DateTime, default=datetime.utcnow)
+    recency_factor = Column(Float, default=0.0, server_default='0.0')
+    coverage_factor = Column(Float, default=0.0, server_default='0.0')
+    health_factor = Column(Float, default=0.0, server_default='0.0')
+    diversity_factor = Column(Float, default=0.0, server_default='0.0')
+    score_breakdown = Column(JSONB, server_default='{}')
+    risk_factors = Column(JSONB, server_default='[]')
+    updated_at = Column(DateTime, default=datetime.utcnow)
+
+
+class InfrastructureChangeLog(Base):
+    __tablename__ = "infrastructure_change_logs"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    change_type = Column(String(100), nullable=False)
+    description = Column(Text, nullable=False)
+    affected_platforms = Column(JSONB, server_default='[]')
+    affected_log_sources = Column(JSONB, server_default='[]')
+    change_date = Column(DateTime, default=datetime.utcnow)
+    reported_by = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    auto_invalidate = Column(Boolean, default=True, server_default='true')
+    invalidated_count = Column(Integer, default=0, server_default='0')
+    change_metadata = Column(JSONB, server_default='{}')
+    created_at = Column(DateTime, default=datetime.utcnow)

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

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

@@ -0,0 +1,68 @@
+"""Phase 13: Executive Dashboard — PostureSnapshot model."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean, Column, Date, DateTime, Float, ForeignKey,
+    Index, Integer, UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+class PostureSnapshot(Base):
+    """
+    Daily point-in-time capture of the organisation's security posture.
+
+    Aggregates data from all phases (coverage, risk, ownership, knowledge,
+    attack-paths) into a single row that can be trended over time.
+    """
+
+    __tablename__ = "posture_snapshots"
+
+    id             = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    snapshot_date  = Column(Date, nullable=False)    # one per calendar day
+
+    # ── Coverage ──────────────────────────────────────────────────────────────
+    total_techniques  = Column(Integer, nullable=False, default=0)
+    validated_count   = Column(Integer, nullable=False, default=0)
+    partial_count     = Column(Integer, nullable=False, default=0)
+    not_covered_count = Column(Integer, nullable=False, default=0)
+    coverage_pct      = Column(Float, nullable=False, default=0.0)  # 0–100
+
+    # ── Risk ─────────────────────────────────────────────────────────────────
+    avg_risk_score     = Column(Float, nullable=False, default=0.0)
+    critical_count     = Column(Integer, nullable=False, default=0)
+    high_count         = Column(Integer, nullable=False, default=0)
+    medium_count       = Column(Integer, nullable=False, default=0)
+    low_count          = Column(Integer, nullable=False, default=0)
+
+    # ── Operations ────────────────────────────────────────────────────────────
+    open_queue_items   = Column(Integer, nullable=False, default=0)
+    orphan_techniques  = Column(Integer, nullable=False, default=0)
+
+    # ── Knowledge ─────────────────────────────────────────────────────────────
+    playbook_count     = Column(Integer, nullable=False, default=0)
+    lesson_count       = Column(Integer, nullable=False, default=0)
+
+    # ── MTTD (from attack-path executions completed in last 30 d) ────────────
+    mttd_avg_seconds   = Column(Float, nullable=True)     # None if no data
+    executions_30d     = Column(Integer, nullable=False, default=0)
+    detection_rate_30d = Column(Float, nullable=True)     # avg across executions
+
+    # ── Meta ─────────────────────────────────────────────────────────────────
+    created_by  = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    created_at  = Column(DateTime, default=datetime.utcnow)
+    extra       = Column(JSONB, nullable=True)   # full breakdown / by-tactic
+
+    creator = relationship("User", foreign_keys=[created_by])
+
+    __table_args__ = (
+        UniqueConstraint("snapshot_date", name="uq_posture_snapshot_date"),
+        Index("ix_posture_snapshots_date", "snapshot_date"),
+    )

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/knowledge.py

@@ -0,0 +1,129 @@
+"""Phase 11: Knowledge Management models — Playbooks + Lessons Learned."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean, Column, DateTime, ForeignKey,
+    Index, Integer, String, Text, UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+# ── Playbooks ──────────────────────────────────────────────────────────────────
+
+class Playbook(Base):
+    """
+    Structured runbook for a specific technique and playbook type.
+
+    playbook_type: attack | detect | investigate | respond | hunt
+    One playbook per (technique, type).  Edits increment ``version``
+    and save a snapshot to ``PlaybookVersion``.
+    """
+    __tablename__ = "playbooks"
+
+    id             = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    technique_id   = Column(
+        UUID(as_uuid=True), ForeignKey("techniques.id", ondelete="CASCADE"), nullable=False
+    )
+    playbook_type  = Column(String(32), nullable=False)   # attack/detect/investigate/respond/hunt
+    title          = Column(String(255), nullable=False)
+    content        = Column(Text, nullable=False, default="")
+    version        = Column(Integer, default=1, nullable=False)
+    tools          = Column(JSONB, default=list)          # list of tool name strings
+    prerequisites  = Column(JSONB, default=list)          # list of prerequisite strings
+    created_by     = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    updated_by     = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    created_at     = Column(DateTime, default=datetime.utcnow)
+    updated_at     = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    is_active      = Column(Boolean, default=True)
+
+    # Relationships
+    technique  = relationship("Technique", foreign_keys=[technique_id])
+    creator    = relationship("User", foreign_keys=[created_by])
+    updater    = relationship("User", foreign_keys=[updated_by])
+    versions   = relationship(
+        "PlaybookVersion", back_populates="playbook",
+        cascade="all, delete-orphan",
+        order_by="PlaybookVersion.version.desc()",
+    )
+
+    __table_args__ = (
+        UniqueConstraint("technique_id", "playbook_type", name="uq_playbook_technique_type"),
+        Index("ix_playbooks_technique_id", "technique_id"),
+        Index("ix_playbooks_type", "playbook_type"),
+    )
+
+
+class PlaybookVersion(Base):
+    """Immutable snapshot of a playbook at a given version number."""
+
+    __tablename__ = "playbook_versions"
+
+    id           = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    playbook_id  = Column(
+        UUID(as_uuid=True), ForeignKey("playbooks.id", ondelete="CASCADE"), nullable=False
+    )
+    version      = Column(Integer, nullable=False)
+    title        = Column(String(255), nullable=False)
+    content      = Column(Text, nullable=False, default="")
+    tools        = Column(JSONB, default=list)
+    prerequisites = Column(JSONB, default=list)
+    changed_by   = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    change_note  = Column(String(500), nullable=True)
+    created_at   = Column(DateTime, default=datetime.utcnow)
+
+    playbook  = relationship("Playbook", back_populates="versions")
+    changer   = relationship("User", foreign_keys=[changed_by])
+
+    __table_args__ = (
+        Index("ix_pb_versions_playbook_id", "playbook_id"),
+        Index("ix_pb_versions_version",     "playbook_id", "version"),
+    )
+
+
+# ── Lessons Learned ────────────────────────────────────────────────────────────
+
+class LessonLearned(Base):
+    """
+    Immutable post-mortem record linked to a test, campaign, attack-path or
+    created manually.
+
+    severity:    critical | high | medium | low | info
+    entity_type: test | campaign | attack_path | manual
+    """
+    __tablename__ = "lessons_learned"
+
+    id            = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    title         = Column(String(255), nullable=False)
+    what_happened = Column(Text, nullable=False, default="")
+    root_cause    = Column(Text, nullable=False, default="")
+    fix_applied   = Column(Text, nullable=True)
+    severity      = Column(String(16), nullable=False, default="medium")
+    entity_type   = Column(String(32), nullable=False, default="manual")
+    entity_id     = Column(UUID(as_uuid=True), nullable=True)
+    technique_ids = Column(JSONB, default=list)  # list of UUID strings
+    tags          = Column(JSONB, default=list)
+    created_by    = Column(
+        UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+    )
+    created_at    = Column(DateTime, default=datetime.utcnow)
+    updated_at    = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    is_active     = Column(Boolean, default=True)   # soft-delete (admin only)
+
+    creator = relationship("User", foreign_keys=[created_by])
+
+    __table_args__ = (
+        Index("ix_ll_entity", "entity_type", "entity_id"),
+        Index("ix_ll_severity", "severity"),
+        Index("ix_ll_created_by", "created_by"),
+    )

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/operational_alert.py

@@ -0,0 +1,144 @@
+"""Phase 13: Operational Alerts — AlertRule and AlertInstance models."""
+
+import enum
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean, Column, DateTime, ForeignKey,
+    Index, Integer, String, Text,
+)
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+# ── Enumerations ──────────────────────────────────────────────────────────────
+
+class AlertSeverity(str, enum.Enum):
+    critical = "critical"
+    high     = "high"
+    medium   = "medium"
+    low      = "low"
+    info     = "info"
+
+
+class AlertStatus(str, enum.Enum):
+    open         = "open"
+    acknowledged = "acknowledged"
+    resolved     = "resolved"
+    dismissed    = "dismissed"
+
+
+class AlertRuleType(str, enum.Enum):
+    high_risk           = "high_risk"           # risk_score >= threshold
+    stale_technique     = "stale_technique"     # not validated in N days
+    coverage_regression = "coverage_regression" # coverage_pct dropped
+    low_coverage        = "low_coverage"        # coverage below min
+    expiry_wave         = "expiry_wave"         # many pending queue items
+    new_technique       = "new_technique"       # new MITRE techniques added
+    orphan_spike        = "orphan_spike"        # many unowned techniques
+    custom              = "custom"              # future extension placeholder
+
+
+# ── AlertRule ─────────────────────────────────────────────────────────────────
+
+class AlertRule(Base):
+    """
+    Defines a condition that, when satisfied, fires an AlertInstance.
+
+    System rules (is_system=True) are seeded at startup and cannot be deleted.
+    Custom rules (is_system=False) can be created by admins.
+    """
+
+    __tablename__ = "alert_rules"
+
+    id          = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name        = Column(String(300), nullable=False)
+    description = Column(Text, nullable=True)
+    rule_type   = Column(String(50),  nullable=False)
+    severity    = Column(String(20),  nullable=False, default=AlertSeverity.medium.value)
+    is_enabled  = Column(Boolean,     nullable=False, default=True)
+    is_system   = Column(Boolean,     nullable=False, default=False)  # seeded, not deletable
+
+    # Rule-specific thresholds/config (varies by rule_type)
+    config = Column(JSONB, nullable=False, default={})
+
+    # Delivery
+    notify_in_app  = Column(Boolean, nullable=False, default=True)
+    notify_webhook = Column(Boolean, nullable=False, default=False)
+    webhook_id     = Column(
+        UUID(as_uuid=True),
+        ForeignKey("webhook_configs.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+
+    # Cooldown — don't re-fire within N hours of last firing
+    cooldown_hours = Column(Integer, nullable=False, default=24)
+
+    # Meta
+    created_by    = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    created_at    = Column(DateTime, default=datetime.utcnow)
+    last_fired_at = Column(DateTime, nullable=True)
+
+    creator  = relationship("User",          foreign_keys=[created_by])
+    instances = relationship("AlertInstance", back_populates="rule",
+                             cascade="all, delete-orphan")
+
+    __table_args__ = (
+        Index("ix_alert_rules_type",      "rule_type"),
+        Index("ix_alert_rules_enabled",   "is_enabled"),
+    )
+
+
+# ── AlertInstance ─────────────────────────────────────────────────────────────
+
+class AlertInstance(Base):
+    """
+    A single firing of an AlertRule.
+
+    Transitions: open → acknowledged → resolved
+                 open → dismissed
+    """
+
+    __tablename__ = "alert_instances"
+
+    id        = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    rule_id   = Column(
+        UUID(as_uuid=True),
+        ForeignKey("alert_rules.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    # Denormalised fields kept for history even after rule deletion
+    rule_name = Column(String(300), nullable=False)
+    rule_type = Column(String(50),  nullable=False)
+    severity  = Column(String(20),  nullable=False)
+
+    title   = Column(String(500), nullable=False)
+    message = Column(Text,        nullable=False)
+    details = Column(JSONB,       nullable=True)   # structured context
+
+    status          = Column(String(20),  nullable=False, default=AlertStatus.open.value)
+    acknowledged_by = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    acknowledged_at = Column(DateTime, nullable=True)
+    resolved_at     = Column(DateTime, nullable=True)
+    created_at      = Column(DateTime, default=datetime.utcnow)
+
+    rule             = relationship("AlertRule",    back_populates="instances")
+    acknowledger     = relationship("User",         foreign_keys=[acknowledged_by])
+
+    __table_args__ = (
+        Index("ix_alert_instances_rule_id",   "rule_id"),
+        Index("ix_alert_instances_status",    "status"),
+        Index("ix_alert_instances_severity",  "severity"),
+        Index("ix_alert_instances_created",   "created_at"),
+    )

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/ownership_queue.py

@@ -0,0 +1,136 @@
+"""Phase 9: Ownership & Revalidation Queue models."""
+
+import enum
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Column, DateTime, Enum, ForeignKey, Index, String, Text
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+class QueuePriority(str, enum.Enum):
+    critical = "critical"
+    high = "high"
+    medium = "medium"
+    low = "low"
+
+
+class QueueStatus(str, enum.Enum):
+    pending = "pending"
+    in_progress = "in_progress"
+    completed = "completed"
+    dismissed = "dismissed"
+
+
+class QueueReason(str, enum.Enum):
+    validation_expired = "validation_expired"
+    infra_change = "infra_change"
+    osint_alert = "osint_alert"
+    mitre_update = "mitre_update"
+    rule_modified = "rule_modified"
+    low_confidence = "low_confidence"
+    manual = "manual"
+
+
+class TechniqueOwnership(Base):
+    """Ownership assignment for a MITRE technique."""
+
+    __tablename__ = "technique_ownerships"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    technique_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("techniques.id", ondelete="CASCADE"),
+        nullable=False,
+        unique=True,
+    )
+    owner_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    backup_owner_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    team = Column(String(200), nullable=True)
+    notes = Column(Text, nullable=True)
+    assigned_at = Column(DateTime, nullable=True)
+    assigned_by = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    technique = relationship("Technique", foreign_keys=[technique_id])
+    owner = relationship("User", foreign_keys=[owner_id])
+    backup_owner = relationship("User", foreign_keys=[backup_owner_id])
+
+
+class RevalidationQueueItem(Base):
+    """A prioritised work item for the analyst's daily queue."""
+
+    __tablename__ = "revalidation_queue_items"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    technique_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("techniques.id", ondelete="CASCADE"),
+        nullable=True,
+    )
+    detection_asset_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("detection_assets.id", ondelete="CASCADE"),
+        nullable=True,
+    )
+
+    priority = Column(
+        Enum(QueuePriority, name="queue_priority"),
+        nullable=False,
+        default=QueuePriority.medium,
+    )
+    reason = Column(
+        Enum(QueueReason, name="queue_reason"),
+        nullable=False,
+    )
+    reason_detail = Column(Text, nullable=True)
+    status = Column(
+        Enum(QueueStatus, name="queue_status"),
+        nullable=False,
+        default=QueueStatus.pending,
+    )
+
+    assigned_to = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    due_date = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    completed_at = Column(DateTime, nullable=True)
+    dismissed_at = Column(DateTime, nullable=True)
+    completed_by = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    extra = Column(JSONB, nullable=True)  # arbitrary metadata
+
+    technique = relationship("Technique", foreign_keys=[technique_id])
+    detection_asset = relationship("DetectionAsset", foreign_keys=[detection_asset_id])
+    assignee = relationship("User", foreign_keys=[assigned_to])
+
+
+# Indexes
+Index("ix_rqueue_status", RevalidationQueueItem.status)
+Index("ix_rqueue_priority", RevalidationQueueItem.priority)
+Index("ix_rqueue_assigned_to", RevalidationQueueItem.assigned_to)
+Index("ix_rqueue_technique_id", RevalidationQueueItem.technique_id)
+Index("ix_rqueue_asset_id", RevalidationQueueItem.detection_asset_id)
+Index("ix_techown_owner_id", TechniqueOwnership.owner_id)

backend/app/models/risk_intelligence.py

@@ -0,0 +1,69 @@
+"""Phase 12: Risk Intelligence model — per-technique risk scoring."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import (
+    Boolean, Column, DateTime, Float, ForeignKey,
+    Index, Integer, String, UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+class TechniqueRiskProfile(Base):
+    """
+    Aggregated risk profile for one technique.
+
+    Combines four weighted factors:
+      • detection_gap      (35 %) — 0=fully covered → 1=no coverage
+      • threat_actor_rel   (30 %) — normalised actor count
+      • osint_signals      (20 %) — normalised recent OSINT items (30 d)
+      • test_failure_rate  (15 %) — proportion of tests where blue didn't detect
+
+    risk_score = weighted sum × 100  → 0–100
+    risk_level: critical ≥75 | high ≥50 | medium ≥25 | low ≥10 | info
+    """
+
+    __tablename__ = "technique_risk_profiles"
+
+    id            = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    technique_id  = Column(
+        UUID(as_uuid=True),
+        ForeignKey("techniques.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    # ── Computed scores ───────────────────────────────────────────────────────
+    risk_score    = Column(Float, nullable=False, default=0.0)   # 0–100
+    likelihood    = Column(Float, nullable=False, default=0.0)   # 0–100
+    impact        = Column(Float, nullable=False, default=0.0)   # 0–100
+    risk_level    = Column(String(16), nullable=False, default="info")
+
+    # ── Raw factor values ─────────────────────────────────────────────────────
+    detection_gap       = Column(Float, nullable=False, default=1.0)  # 0–1
+    threat_actor_count  = Column(Integer, nullable=False, default=0)
+    osint_signal_count  = Column(Integer, nullable=False, default=0)  # last 30 d
+    test_fail_count     = Column(Integer, nullable=False, default=0)
+    test_total_count    = Column(Integer, nullable=False, default=0)
+    test_failure_rate   = Column(Float, nullable=False, default=0.0)  # 0–1
+    confidence_level    = Column(Float, nullable=False, default=0.0)  # DLC 0–1
+
+    # ── Rich detail ──────────────────────────────────────────────────────────
+    scoring_breakdown   = Column(JSONB, nullable=True)  # per-factor contributions
+    recommendations     = Column(JSONB, nullable=True)  # list[str]
+
+    # ── Meta ─────────────────────────────────────────────────────────────────
+    computed_at   = Column(DateTime, default=datetime.utcnow)
+    is_stale      = Column(Boolean, default=True)
+
+    technique = relationship("Technique", foreign_keys=[technique_id])
+
+    __table_args__ = (
+        UniqueConstraint("technique_id", name="uq_risk_profile_technique"),
+        Index("ix_risk_profiles_risk_score", "risk_score"),
+        Index("ix_risk_profiles_risk_level", "risk_level"),
+        Index("ix_risk_profiles_stale",      "is_stale"),
+    )

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

@@ -0,0 +1,49 @@
+"""Phase 14: SSO / SAML 2.0 configuration model."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, Column, DateTime, String, Text
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+
+from app.database import Base
+
+
+class SsoConfig(Base):
+    """
+    SAML 2.0 Identity Provider configuration.
+
+    Exactly one row is expected (use upsert).  The SP metadata endpoint
+    reads from this row to generate XML for IdP registration.
+    """
+
+    __tablename__ = "sso_configs"
+
+    id           = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    is_enabled   = Column(Boolean, nullable=False, default=False)
+    provider_name = Column(String(200), nullable=True)  # e.g., "Okta", "Azure AD"
+
+    # ── Service Provider (Aegis) settings ────────────────────────────────────
+    sp_entity_id  = Column(String(500), nullable=True)   # e.g., https://aegis.co/api/v1/sso/metadata
+    sp_acs_url    = Column(String(500), nullable=True)   # Assertion Consumer Service URL
+    sp_slo_url    = Column(String(500), nullable=True)   # Single Logout URL (optional)
+    sp_certificate = Column(Text, nullable=True)         # SP public cert for signed requests
+    sp_private_key = Column(Text, nullable=True)         # SP private key (stored encrypted in future)
+
+    # ── Identity Provider settings ────────────────────────────────────────────
+    idp_entity_id  = Column(String(500), nullable=True)
+    idp_sso_url    = Column(String(500), nullable=True)  # IdP redirect/POST binding URL
+    idp_slo_url    = Column(String(500), nullable=True)  # IdP SLO URL
+    idp_certificate = Column(Text, nullable=True)        # IdP X.509 cert for response validation
+
+    # ── Attribute mapping ─────────────────────────────────────────────────────
+    # SAML attribute name → Aegis field
+    attr_email    = Column(String(200), nullable=True, default="email")
+    attr_username = Column(String(200), nullable=True, default="username")
+    attr_role     = Column(String(200), nullable=True, default="role")
+    default_role  = Column(String(50),  nullable=True, default="viewer")
+    auto_provision = Column(Boolean, nullable=False, default=True)  # create user on first login
+
+    # ── Meta ─────────────────────────────────────────────────────────────────
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

backend/app/models/system_config.py

@@ -0,0 +1,26 @@
+"""SystemConfig model — runtime key-value configuration store."""
+
+import uuid
+
+from sqlalchemy import Column, String, Text, DateTime, func
+from sqlalchemy.dialects.postgresql import UUID
+
+from app.database import Base
+
+
+class SystemConfig(Base):
+    """Generic key-value store for runtime system configuration.
+
+    Currently used for:
+    - SMTP email settings (overrides .env values when present)
+
+    Keys are namespaced by convention: ``smtp.host``, ``smtp.port``, etc.
+    """
+
+    __tablename__ = "system_configs"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    key = Column(String(200), unique=True, nullable=False, index=True)
+    value = Column(Text, nullable=True)
+    description = Column(String(500), nullable=True)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())

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)
-    # Assign paused_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,22 +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 Boolean, Column, DateTime, String, func from sqlalchemy
-from sqlalchemy import Boolean, Column, DateTime, String, func
-
-# Import UUID from sqlalchemy.dialects.postgresql
-from sqlalchemy.dialects.postgresql import UUID
-
-# Import Base from app.database
 from app.database import Base
 
 
-# Define class 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
@@ -25,24 +17,19 @@ 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)
+    jira_api_token = Column(String(500), nullable=True)   # personal Atlassian token
+    jira_email = Column(String(255), nullable=True)        # Atlassian email (overrides account email)
+    tempo_api_token = Column(String(500), nullable=True)  # personal Tempo API token

backend/app/models/webhook_config.py

@@ -0,0 +1,19 @@
+"""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
+
+class WebhookConfig(Base):
+    __tablename__ = "webhook_configs"
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    name = Column(String(200), nullable=False)
+    url = Column(Text, nullable=False)
+    secret = Column(String(256), nullable=True)  # HMAC signature key
+    events = Column(JSONB, nullable=False, server_default="[]")  # list of event types
+    is_active = Column(Boolean, default=True, nullable=False)
+    created_by = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    last_triggered_at = Column(DateTime, nullable=True)
+    failure_count = Column(Integer, default=0, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())

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"),