Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

fix(db): make migrations portable

Mafifrizi17cc0070e8b2
diff --git a/migrations/env.py b/migrations/env.py
index 80e0760..f3fb5f5 100644
--- a/migrations/env.py
+++ b/migrations/env.py
@@ -1,78 +1,207 @@
-"""
-Alembic migration environment for ARES.
-
-Supports both sync SQLite (for alembic CLI) and async aiosqlite (for runtime).
-Run migrations:
- alembic upgrade head # Apply all pending migrations
- alembic revision -m "add_X" # Create new migration
- alembic history # Show migration history
- alembic current # Show current version
- alembic downgrade -1 # Roll back one step
-
-ARES also runs migrations automatically at startup via AresDatabase.run_migrations().
-"""
+"""Alembic migration environment for the persistent ARES schema history."""
from __future__ import annotations
import asyncio
+import configparser
+import os
+import sqlite3
+import sys
from logging.config import fileConfig
-from pathlib import Path
from typing import Any
from alembic import context
-from alembic.config import Config
-from sqlalchemy import pool, text
+from sqlalchemy import event, pool
+from sqlalchemy.engine import URL, make_url
+from sqlalchemy.exc import SQLAlchemyError
from sqlalchemy.ext.asyncio import async_engine_from_config
-# ── Alembic config ────────────────────────────────────────────────────────────
-
config = context.config
-if config.config_file_name is not None:
- fileConfig(config.config_file_name)
-
-# ── Determine DB URL ──────────────────────────────────────────────────────────
-
-def _get_db_url() -> str:
- """Resolve database URL from environment or alembic.ini."""
- import os
- url = os.environ.get("ARES_DATABASE_URL", "")
- if url:
- # alembic needs sqlite:/// not sqlite+aiosqlite:///
- return url.replace("sqlite+aiosqlite:///", "sqlite:///")
- # Fallback from alembic.ini
- return config.get_main_option("sqlalchemy.url", "sqlite:///ares.db")
+_OFFLINE_ERROR = (
+ "Offline migration is not supported for the ARES historical chain"
+)
+_UNSUPPORTED_DIALECT_ERROR = "Unsupported Alembic database dialect"
+_INVALID_URL_ERROR = "Invalid Alembic database URL"
+
+
+class _AlembicSanitizedError(RuntimeError):
+ """Fixed migration-environment failure safe for operator diagnostics."""
+
+
+def _configure_logging() -> None:
+ """Apply Alembic logging without exposing configuration details."""
+ if config.config_file_name is None:
+ return
+ try:
+ fileConfig(config.config_file_name)
+ except (
+ configparser.Error,
+ ImportError,
+ KeyError,
+ OSError,
+ RuntimeError,
+ TypeError,
+ ValueError,
+ ) as exc:
+ raise _AlembicSanitizedError(
+ "Alembic logging configuration failed "
+ f"[{type(exc).__name__}]"
+ ) from None
+
+
+_configure_logging()
+
+
+def _configured_url() -> str:
+ """Select the CLI override, environment URL, or configured Alembic URL."""
+ explicit_values: list[str] = []
+ for argument in context.get_x_argument():
+ key, separator, value = argument.partition("=")
+ if key != "db_url":
+ continue
+ if separator != "=":
+ raise _AlembicSanitizedError(_INVALID_URL_ERROR)
+ explicit_values.append(value)
+
+ if len(explicit_values) > 1:
+ raise _AlembicSanitizedError(_INVALID_URL_ERROR)
+ if explicit_values:
+ candidate = explicit_values[0]
+ elif "ARES_DATABASE_URL" in os.environ:
+ candidate = os.environ["ARES_DATABASE_URL"]
+ else:
+ candidate = config.get_main_option("sqlalchemy.url")
+
+ if (
+ not isinstance(candidate, str)
+ or not candidate
+ or candidate != candidate.strip()
+ ):
+ raise _AlembicSanitizedError(_INVALID_URL_ERROR)
+ return candidate
+
+
+def _async_url(raw_url: str) -> URL:
+ """Return a supported URL using an already-installed async driver."""
+ try:
+ url = make_url(raw_url)
+ except (SQLAlchemyError, TypeError, ValueError):
+ raise _AlembicSanitizedError(_INVALID_URL_ERROR) from None
+
+ backend = url.get_backend_name()
+ driver = url.drivername
+ if backend == "sqlite":
+ if driver not in {"sqlite", "sqlite+aiosqlite"}:
+ raise _AlembicSanitizedError(_UNSUPPORTED_DIALECT_ERROR)
+ return url.set(drivername="sqlite+aiosqlite")
+ if backend == "postgresql":
+ if driver not in {"postgresql", "postgresql+asyncpg"}:
+ raise _AlembicSanitizedError(_UNSUPPORTED_DIALECT_ERROR)
+ return url.set(drivername="postgresql+asyncpg")
+ raise _AlembicSanitizedError(_UNSUPPORTED_DIALECT_ERROR)
def run_migrations_offline() -> None:
- """Run migrations in 'offline' mode (generates SQL without connecting)."""
- url = _get_db_url()
- context.configure(url=url, literal_binds=True,
- dialect_opts={"paramstyle": "named"})
- with context.begin_transaction():
- context.run_migrations()
+ """Reject SQL rendering because historical revisions inspect live catalogs."""
+ raise RuntimeError(_OFFLINE_ERROR)
def do_run_migrations(connection: Any) -> None:
+ """Run Alembic operations through one real synchronous facade."""
context.configure(connection=connection)
with context.begin_transaction():
context.run_migrations()
+def _configure_sqlite_connection(
+ dbapi_connection: Any,
+ _connection_record: Any,
+) -> None:
+ """Apply SQLite policy before Alembic begins migration work."""
+ cursor = dbapi_connection.cursor()
+ try:
+ cursor.execute("PRAGMA journal_mode = WAL")
+ cursor.execute("PRAGMA foreign_keys = ON")
+ finally:
+ cursor.close()
+
+
async def run_async_migrations() -> None:
- """Run migrations in async mode (for aiosqlite/asyncpg)."""
- db_url = _get_db_url().replace("sqlite:///", "sqlite+aiosqlite:///")
- cfg = config.get_section(config.config_ini_section, {})
- cfg["sqlalchemy.url"] = db_url
- connectable = async_engine_from_config(
- cfg, prefix="sqlalchemy.", poolclass=pool.NullPool
- )
- async with connectable.connect() as connection:
- await connection.run_sync(do_run_migrations)
- await connectable.dispose()
+ """Run online migrations using aiosqlite or asyncpg."""
+ url = _async_url(_configured_url())
+ section = config.get_section(config.config_ini_section, {})
+ section["sqlalchemy.url"] = url.render_as_string(hide_password=False)
+ try:
+ connectable = async_engine_from_config(
+ section,
+ prefix="sqlalchemy.",
+ poolclass=pool.NullPool,
+ )
+ except (
+ ImportError,
+ KeyError,
+ OSError,
+ SQLAlchemyError,
+ TypeError,
+ ValueError,
+ ) as exc:
+ raise _AlembicSanitizedError(
+ "Alembic engine configuration failed "
+ f"[{type(exc).__name__}]"
+ ) from None
+ if url.get_backend_name() == "sqlite":
+ event.listen(
+ connectable.sync_engine,
+ "connect",
+ _configure_sqlite_connection,
+ )
+ try:
+ async with connectable.connect() as connection:
+ await connection.run_sync(do_run_migrations)
+ finally:
+ primary_failure = sys.exception()
+ try:
+ await connectable.dispose()
+ except Exception as exc:
+ if primary_failure is not None:
+ primary_failure.add_note(
+ "Alembic engine cleanup failed "
+ f"[{type(exc).__name__}]"
+ )
+ else:
+ raise _AlembicSanitizedError(
+ "Alembic engine cleanup failed "
+ f"[{type(exc).__name__}]"
+ ) from None
def run_migrations_online() -> None:
- asyncio.run(run_async_migrations())
+ """Run the online migration and sanitize operational diagnostics."""
+ try:
+ asyncio.run(run_async_migrations())
+ except (
+ asyncio.CancelledError,
+ KeyboardInterrupt,
+ SystemExit,
+ GeneratorExit,
+ ):
+ raise
+ except _AlembicSanitizedError:
+ raise
+ except (
+ configparser.Error,
+ ImportError,
+ OSError,
+ SQLAlchemyError,
+ sqlite3.Error,
+ ) as exc:
+ raise RuntimeError(
+ f"Alembic online migration failed [{type(exc).__name__}]"
+ ) from None
+ except Exception:
+ # Revision-owned, non-operational failures must retain object identity
+ # and traceback. Revisions are responsible for fixed public messages.
+ raise
if context.is_offline_mode():
diff --git a/migrations/versions/0001_initial_schema.py b/migrations/versions/0001_initial_schema.py
index c130e2c..384f0bc 100644
--- a/migrations/versions/0001_initial_schema.py
+++ b/migrations/versions/0001_initial_schema.py
@@ -1,172 +1,561 @@
-"""Initial schema — tables from schema.py v5
+"""Create the portable ARES baseline schema.
Revision ID: 0001
-Revises:
+Revises:
Create Date: 2025-01-01 00:00:00
"""
from __future__ import annotations
-from alembic import op
+
import sqlalchemy as sa
+from alembic import op
-revision: str = "0001"
+revision: str = "0001"
down_revision: str | None = None
branch_labels: str | None = None
-depends_on: str | None = None
+depends_on: str | None = None
+
+_DIALECT_ERROR = "Unsupported migration dialect"
+
+
+def _dialect() -> str:
+ name = op.get_bind().dialect.name
+ if name not in {"sqlite", "postgresql"}:
+ raise RuntimeError(_DIALECT_ERROR)
+ return name
+
+
+def _timestamp_type(dialect: str) -> sa.types.TypeEngine:
+ if dialect == "postgresql":
+ return sa.DateTime(timezone=True)
+ return sa.Text()
+
+
+def _database_now(dialect: str) -> sa.sql.elements.TextClause:
+ if dialect == "postgresql":
+ return sa.text("now()")
+ return sa.text("datetime('now')")
+
+
+def _finite_timestamp(
+ dialect: str,
+ column: str,
+ name: str,
+ *,
+ nullable: bool = False,
+) -> tuple[sa.CheckConstraint, ...]:
+ if dialect != "postgresql":
+ return ()
+ expression = (
+ f"{column} IS NULL OR isfinite({column})"
+ if nullable
+ else f"isfinite({column})"
+ )
+ return (sa.CheckConstraint(expression, name=name),)
def upgrade() -> None:
- op.execute("PRAGMA journal_mode = WAL")
- op.execute("PRAGMA foreign_keys = ON")
-
- op.create_table("campaigns",
- sa.Column("id", sa.Text, primary_key=True),
- sa.Column("name", sa.Text, nullable=False),
- sa.Column("client", sa.Text, nullable=False, server_default="Internal"),
- sa.Column("operator", sa.Text, nullable=False, server_default="unknown"),
- sa.Column("noise_profile", sa.Text, nullable=False, server_default="stealth"),
- sa.Column("status", sa.Text, nullable=False, server_default="created"),
- sa.Column("scope_json", sa.Text, nullable=False, server_default="[]"),
- sa.Column("targets_json", sa.Text, nullable=False, server_default="[]"),
- sa.Column("notes", sa.Text, server_default=""),
- sa.Column("created_at", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
- sa.Column("updated_at", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
+ dialect = _dialect()
+ timestamp = _timestamp_type(dialect)
+ database_now = _database_now(dialect)
+
+ if dialect == "sqlite":
+ op.create_table(
+ "schema_version",
+ sa.Column("version", sa.Integer(), primary_key=True),
+ sa.Column(
+ "applied_at",
+ sa.Text(),
+ nullable=False,
+ server_default=database_now,
+ ),
+ )
+
+ op.create_table(
+ "campaigns",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column("name", sa.Text(), nullable=False),
+ sa.Column(
+ "client", sa.Text(), nullable=False, server_default="Internal"
+ ),
+ sa.Column(
+ "operator", sa.Text(), nullable=False, server_default="unknown"
+ ),
+ sa.Column(
+ "noise_profile",
+ sa.Text(),
+ nullable=False,
+ server_default="stealth",
+ ),
+ sa.Column(
+ "status", sa.Text(), nullable=False, server_default="created"
+ ),
+ sa.Column(
+ "scope_json", sa.Text(), nullable=False, server_default="[]"
+ ),
+ sa.Column(
+ "targets_json", sa.Text(), nullable=False, server_default="[]"
+ ),
+ sa.Column("notes", sa.Text(), server_default=""),
+ sa.Column(
+ "created_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ sa.Column(
+ "updated_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "created_at",
+ "ck_campaigns_created_at_finite",
+ ),
+ *_finite_timestamp(
+ dialect,
+ "updated_at",
+ "ck_campaigns_updated_at_finite",
+ ),
+ )
+
+ op.create_table(
+ "module_runs",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column(
+ "campaign_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "campaigns.id",
+ name="fk_module_runs_campaign",
+ ondelete="CASCADE",
+ ),
+ nullable=False,
+ ),
+ sa.Column("module_id", sa.Text(), nullable=False),
+ sa.Column("outcome", sa.Text(), nullable=False),
+ sa.Column(
+ "success", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column(
+ "duration_ms", sa.Float(), nullable=False, server_default="0.0"
+ ),
+ sa.Column(
+ "completed_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "completed_at",
+ "ck_module_runs_completed_at_finite",
+ ),
+ )
+ op.create_index(
+ "idx_module_runs_campaign", "module_runs", ["campaign_id"]
+ )
+ op.create_index(
+ "idx_module_runs_completed", "module_runs", ["completed_at"]
)
- op.create_table("findings",
- sa.Column("id", sa.Text, primary_key=True),
- sa.Column("campaign_id", sa.Text, nullable=False),
- sa.Column("module_id", sa.Text, nullable=False),
- sa.Column("title", sa.Text, nullable=False),
- sa.Column("description", sa.Text, nullable=False),
- sa.Column("severity", sa.Text, nullable=False),
- sa.Column("cvss_score", sa.Float, server_default="0.0"),
- sa.Column("cvss_vector", sa.Text, server_default=""),
- sa.Column("confidence", sa.Float, nullable=False, server_default="1.0"),
- sa.Column("mitre_technique", sa.Text),
- sa.Column("mitre_tactic", sa.Text),
- sa.Column("evidence_json", sa.Text, nullable=False, server_default="{}"),
- sa.Column("remediation", sa.Text, server_default=""),
- sa.Column("host", sa.Text),
- sa.Column("validated", sa.Integer, nullable=False, server_default="0"),
- sa.Column("false_positive", sa.Integer, nullable=False, server_default="0"),
- sa.Column("discovered_at", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
+ op.create_table(
+ "findings",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column(
+ "campaign_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "campaigns.id",
+ name="fk_findings_campaign",
+ ondelete="CASCADE",
+ ),
+ nullable=False,
+ ),
+ sa.Column("module_id", sa.Text(), nullable=False),
+ sa.Column("title", sa.Text(), nullable=False),
+ sa.Column("description", sa.Text(), nullable=False),
+ sa.Column("severity", sa.Text(), nullable=False),
+ sa.Column(
+ "confidence", sa.Float(), nullable=False, server_default="1.0"
+ ),
+ sa.Column("mitre_technique", sa.Text()),
+ sa.Column("mitre_tactic", sa.Text()),
+ sa.Column(
+ "cvss_score", sa.Float(), nullable=False, server_default="0.0"
+ ),
+ sa.Column(
+ "cvss_vector", sa.Text(), nullable=False, server_default=""
+ ),
+ sa.Column(
+ "evidence_json", sa.Text(), nullable=False, server_default="{}"
+ ),
+ sa.Column("remediation", sa.Text(), server_default=""),
+ sa.Column("host", sa.Text()),
+ sa.Column(
+ "validated", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column(
+ "false_positive",
+ sa.Integer(),
+ nullable=False,
+ server_default="0",
+ ),
+ sa.Column(
+ "discovered_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "discovered_at",
+ "ck_findings_discovered_at_finite",
+ ),
)
- op.create_index("idx_findings_campaign", "findings", ["campaign_id"])
- op.create_index("idx_findings_severity", "findings", ["severity"])
- op.create_index("idx_findings_fp", "findings", ["false_positive"])
- op.create_index("idx_findings_validated", "findings", ["validated"])
- op.create_index("idx_findings_mitre", "findings", ["mitre_technique"])
-
- op.create_table("hosts",
- sa.Column("id", sa.Text, primary_key=True),
- sa.Column("campaign_id", sa.Text, nullable=False),
- sa.Column("ip_address", sa.Text, nullable=False),
- sa.Column("hostname", sa.Text),
- sa.Column("fqdn", sa.Text),
- sa.Column("os", sa.Text),
- sa.Column("os_version", sa.Text),
- sa.Column("domain", sa.Text),
- sa.Column("is_dc", sa.Integer, nullable=False, server_default="0"),
- sa.Column("open_ports_json", sa.Text, nullable=False, server_default="[]"),
- sa.Column("tags_json", sa.Text, nullable=False, server_default="[]"),
- sa.Column("first_seen", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
- sa.Column("last_seen", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
- sa.UniqueConstraint("campaign_id", "ip_address"),
+ op.create_index("idx_findings_campaign", "findings", ["campaign_id"])
+ op.create_index("idx_findings_severity", "findings", ["severity"])
+ op.create_index("idx_findings_fp", "findings", ["false_positive"])
+ op.create_index("idx_findings_mitre", "findings", ["mitre_technique"])
+
+ op.create_table(
+ "hosts",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column(
+ "campaign_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "campaigns.id",
+ name="fk_hosts_campaign",
+ ondelete="CASCADE",
+ ),
+ nullable=False,
+ ),
+ sa.Column("ip_address", sa.Text(), nullable=False),
+ sa.Column("hostname", sa.Text()),
+ sa.Column("fqdn", sa.Text()),
+ sa.Column("os", sa.Text()),
+ sa.Column("os_version", sa.Text()),
+ sa.Column("domain", sa.Text()),
+ sa.Column("is_dc", sa.Integer(), nullable=False, server_default="0"),
+ sa.Column(
+ "open_ports_json", sa.Text(), nullable=False, server_default="[]"
+ ),
+ sa.Column(
+ "tags_json", sa.Text(), nullable=False, server_default="[]"
+ ),
+ sa.Column(
+ "first_seen",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ sa.Column(
+ "last_seen",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "first_seen",
+ "ck_hosts_first_seen_finite",
+ ),
+ *_finite_timestamp(
+ dialect,
+ "last_seen",
+ "ck_hosts_last_seen_finite",
+ ),
+ sa.UniqueConstraint(
+ "campaign_id",
+ "ip_address",
+ name="uq_hosts_campaign_ip",
+ ),
)
op.create_index("idx_hosts_campaign", "hosts", ["campaign_id"])
- op.create_index("idx_hosts_ip", "hosts", ["ip_address"])
- op.create_index("idx_hosts_domain", "hosts", ["domain"])
-
- op.create_table("credentials",
- sa.Column("id", sa.Text, primary_key=True),
- sa.Column("campaign_id", sa.Text, nullable=False),
- sa.Column("host_id", sa.Text),
- sa.Column("username", sa.Text, nullable=False),
- sa.Column("secret_enc", sa.Text),
- sa.Column("cred_type", sa.Text, nullable=False),
- sa.Column("domain", sa.Text),
- sa.Column("source_module", sa.Text),
- sa.Column("notes", sa.Text, server_default=""),
- sa.Column("cracked", sa.Integer, nullable=False, server_default="0"),
- sa.Column("cracked_value", sa.Text),
- sa.Column("captured_at", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
+ op.create_index("idx_hosts_ip", "hosts", ["ip_address"])
+ op.create_index("idx_hosts_domain", "hosts", ["domain"])
+
+ op.create_table(
+ "credentials",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column(
+ "campaign_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "campaigns.id",
+ name="fk_credentials_campaign",
+ ondelete="CASCADE",
+ ),
+ nullable=False,
+ ),
+ sa.Column(
+ "host_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "hosts.id",
+ name="fk_credentials_host",
+ ondelete="SET NULL",
+ ),
+ ),
+ sa.Column("username", sa.Text(), nullable=False),
+ sa.Column("secret_enc", sa.Text()),
+ sa.Column("cred_type", sa.Text(), nullable=False),
+ sa.Column("domain", sa.Text()),
+ sa.Column("source_module", sa.Text()),
+ sa.Column("notes", sa.Text(), server_default=""),
+ sa.Column(
+ "cracked", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column("cracked_value", sa.Text()),
+ sa.Column(
+ "captured_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "captured_at",
+ "ck_credentials_captured_at_finite",
+ ),
)
op.create_index("idx_creds_campaign", "credentials", ["campaign_id"])
op.create_index("idx_creds_username", "credentials", ["username"])
- op.create_index("idx_creds_type", "credentials", ["cred_type"])
-
- op.create_table("loot",
- sa.Column("id", sa.Text, primary_key=True),
- sa.Column("campaign_id", sa.Text, nullable=False),
- sa.Column("host_id", sa.Text),
- sa.Column("loot_type", sa.Text, nullable=False),
- sa.Column("name", sa.Text, nullable=False),
- sa.Column("description", sa.Text, server_default=""),
- sa.Column("content_enc", sa.Text),
- sa.Column("size_bytes", sa.Integer, server_default="0"),
- sa.Column("path_on_target", sa.Text),
- sa.Column("source_module", sa.Text),
- sa.Column("tags_json", sa.Text, nullable=False, server_default="[]"),
- sa.Column("captured_at", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
+ op.create_index("idx_creds_type", "credentials", ["cred_type"])
+
+ op.create_table(
+ "loot",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column(
+ "campaign_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "campaigns.id",
+ name="fk_loot_campaign",
+ ondelete="CASCADE",
+ ),
+ nullable=False,
+ ),
+ sa.Column(
+ "host_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "hosts.id",
+ name="fk_loot_host",
+ ondelete="SET NULL",
+ ),
+ ),
+ sa.Column("loot_type", sa.Text(), nullable=False),
+ sa.Column("name", sa.Text(), nullable=False),
+ sa.Column("description", sa.Text(), server_default=""),
+ sa.Column("content_enc", sa.Text()),
+ sa.Column("size_bytes", sa.Integer(), server_default="0"),
+ sa.Column("path_on_target", sa.Text()),
+ sa.Column("source_module", sa.Text()),
+ sa.Column(
+ "tags_json", sa.Text(), nullable=False, server_default="[]"
+ ),
+ sa.Column(
+ "captured_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "captured_at",
+ "ck_loot_captured_at_finite",
+ ),
)
op.create_index("idx_loot_campaign", "loot", ["campaign_id"])
- op.create_index("idx_loot_type", "loot", ["loot_type"])
-
- op.create_table("audit_log",
- sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
- sa.Column("campaign_id", sa.Text),
- sa.Column("actor", sa.Text, nullable=False, server_default="system"),
- sa.Column("action", sa.Text, nullable=False),
- sa.Column("detail", sa.Text, server_default=""),
- sa.Column("module_id", sa.Text),
- sa.Column("timestamp", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
+ op.create_index("idx_loot_type", "loot", ["loot_type"])
+
+ op.create_table(
+ "audit_log",
+ sa.Column(
+ "id", sa.Integer(), primary_key=True, autoincrement=True
+ ),
+ sa.Column(
+ "campaign_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "campaigns.id",
+ name="fk_audit_campaign",
+ ondelete="SET NULL",
+ ),
+ ),
+ sa.Column(
+ "actor", sa.Text(), nullable=False, server_default="system"
+ ),
+ sa.Column("action", sa.Text(), nullable=False),
+ sa.Column("detail", sa.Text(), server_default=""),
+ sa.Column("module_id", sa.Text()),
+ sa.Column(
+ "timestamp",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "timestamp",
+ "ck_audit_log_timestamp_finite",
+ ),
+ sqlite_autoincrement=True,
)
op.create_index("idx_audit_campaign", "audit_log", ["campaign_id"])
- op.create_index("idx_audit_actor", "audit_log", ["actor"])
- op.create_index("idx_audit_action", "audit_log", ["action"])
-
- op.create_table("users",
- sa.Column("id", sa.Text, primary_key=True),
- sa.Column("username", sa.Text, nullable=False, unique=True),
- sa.Column("hashed_password", sa.Text, nullable=False),
- sa.Column("role", sa.Text, nullable=False, server_default="reporter"),
- sa.Column("is_active", sa.Integer, nullable=False, server_default="1"),
- sa.Column("created_by", sa.Text, nullable=False, server_default="system"),
- sa.Column("created_at", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
- sa.Column("last_login", sa.Text),
+ op.create_index("idx_audit_actor", "audit_log", ["actor"])
+ op.create_index("idx_audit_action", "audit_log", ["action"])
+
+ op.create_table(
+ "users",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column("username", sa.Text(), nullable=False),
+ sa.Column("hashed_password", sa.Text(), nullable=False),
+ sa.Column(
+ "role", sa.Text(), nullable=False, server_default="reporter"
+ ),
+ sa.Column(
+ "is_active", sa.Integer(), nullable=False, server_default="1"
+ ),
+ sa.Column(
+ "created_by", sa.Text(), nullable=False, server_default="system"
+ ),
+ sa.Column(
+ "created_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ sa.Column("last_login", timestamp),
+ *_finite_timestamp(
+ dialect,
+ "created_at",
+ "ck_users_created_at_finite",
+ ),
+ *_finite_timestamp(
+ dialect,
+ "last_login",
+ "ck_users_last_login_finite",
+ nullable=True,
+ ),
+ sa.UniqueConstraint("username", name="uq_users_username"),
)
op.create_index("idx_users_username", "users", ["username"])
- op.create_index("idx_users_role", "users", ["role"])
-
- op.create_table("api_keys",
- sa.Column("id", sa.Text, primary_key=True),
- sa.Column("user_id", sa.Text, nullable=False),
- sa.Column("name", sa.Text, nullable=False),
- sa.Column("key_hash", sa.Text, nullable=False),
- sa.Column("key_prefix", sa.Text, nullable=False),
- sa.Column("scopes", sa.Text, nullable=False, server_default="read"),
- sa.Column("is_active", sa.Integer, nullable=False, server_default="1"),
- sa.Column("last_used", sa.Text),
- sa.Column("expires_at", sa.Text),
- sa.Column("created_at", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
+ op.create_index("idx_users_role", "users", ["role"])
+
+ op.create_table(
+ "api_keys",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column(
+ "user_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "users.id",
+ name="fk_api_keys_user",
+ ondelete="CASCADE",
+ ),
+ nullable=False,
+ ),
+ sa.Column("name", sa.Text(), nullable=False),
+ sa.Column("key_hash", sa.Text(), nullable=False),
+ sa.Column("key_prefix", sa.Text(), nullable=False),
+ sa.Column(
+ "scopes", sa.Text(), nullable=False, server_default="read"
+ ),
+ sa.Column(
+ "is_active", sa.Integer(), nullable=False, server_default="1"
+ ),
+ sa.Column("last_used", timestamp),
+ sa.Column("expires_at", timestamp),
+ sa.Column(
+ "created_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "last_used",
+ "ck_api_keys_last_used_finite",
+ nullable=True,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "expires_at",
+ "ck_api_keys_expires_at_finite",
+ nullable=True,
+ ),
+ *_finite_timestamp(
+ dialect,
+ "created_at",
+ "ck_api_keys_created_at_finite",
+ ),
)
- op.create_index("idx_apikeys_user", "api_keys", ["user_id"])
+ op.create_index("idx_apikeys_user", "api_keys", ["user_id"])
op.create_index("idx_apikeys_prefix", "api_keys", ["key_prefix"])
- op.create_table("refresh_tokens",
- sa.Column("id", sa.Text, primary_key=True),
- sa.Column("user_id", sa.Text, nullable=False),
- sa.Column("is_revoked", sa.Integer, nullable=False, server_default="0"),
- sa.Column("expires_at", sa.Text, nullable=False),
- sa.Column("created_at", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
- sa.Column("used_at", sa.Text),
+ op.create_table(
+ "refresh_tokens",
+ sa.Column("id", sa.Text(), primary_key=True),
+ sa.Column(
+ "user_id",
+ sa.Text(),
+ sa.ForeignKey(
+ "users.id",
+ name="fk_refresh_tokens_user",
+ ondelete="CASCADE",
+ ),
+ nullable=False,
+ ),
+ sa.Column(
+ "is_revoked", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column("expires_at", timestamp, nullable=False),
+ sa.Column(
+ "created_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ sa.Column("used_at", timestamp),
+ *_finite_timestamp(
+ dialect,
+ "expires_at",
+ "ck_refresh_tokens_expires_at_finite",
+ ),
+ *_finite_timestamp(
+ dialect,
+ "created_at",
+ "ck_refresh_tokens_created_at_finite",
+ ),
+ *_finite_timestamp(
+ dialect,
+ "used_at",
+ "ck_refresh_tokens_used_at_finite",
+ nullable=True,
+ ),
)
op.create_index("idx_refresh_user", "refresh_tokens", ["user_id"])
- op.create_index("idx_refresh_exp", "refresh_tokens", ["expires_at"])
+ op.create_index("idx_refresh_exp", "refresh_tokens", ["expires_at"])
def downgrade() -> None:
- op.drop_index("idx_findings_validated", "findings")
- for t in ("refresh_tokens", "api_keys", "users", "audit_log",
- "loot", "credentials", "hosts", "findings", "campaigns"):
- op.drop_table(t)
+ dialect = _dialect()
+ for table_name in (
+ "refresh_tokens",
+ "api_keys",
+ "users",
+ "audit_log",
+ "loot",
+ "credentials",
+ "hosts",
+ "findings",
+ "module_runs",
+ "campaigns",
+ ):
+ op.drop_table(table_name)
+ if dialect == "sqlite":
+ op.drop_table("schema_version")
diff --git a/migrations/versions/0002_add_cvss_to_findings.py b/migrations/versions/0002_add_cvss_to_findings.py
index 4ccb09e..38b76ef 100644
--- a/migrations/versions/0002_add_cvss_to_findings.py
+++ b/migrations/versions/0002_add_cvss_to_findings.py
@@ -1,43 +1,173 @@
-"""Add CVSS score and vector to findings table
+"""Reconcile CVSS fields and introduce finding trace metadata.
Revision ID: 0002
Revises: 0001
Create Date: 2025-01-02 00:00:00
"""
from __future__ import annotations
-from alembic import op
+
import sqlalchemy as sa
+from alembic import op
-revision: str = "0002"
+revision: str = "0002"
down_revision: str | None = "0001"
branch_labels: str | None = None
-depends_on: str | None = None
+depends_on: str | None = None
+_CATALOG_ERROR = "Incompatible findings catalog for migration 0002"
+_DIALECT_ERROR = "Unsupported migration dialect"
-def upgrade() -> None:
+
+def _dialect() -> str:
+ name = op.get_bind().dialect.name
+ if name not in {"sqlite", "postgresql"}:
+ raise RuntimeError(_DIALECT_ERROR)
+ return name
+
+
+def _columns() -> dict[str, dict[str, object]]:
inspector = sa.inspect(op.get_bind())
- existing_columns = {col["name"] for col in inspector.get_columns("findings")}
- columns_to_add = [
- ("cvss_score", sa.Column("cvss_score", sa.Float, server_default="0.0")),
- ("cvss_vector", sa.Column("cvss_vector", sa.Text, server_default="")),
- ("trace_id", sa.Column("trace_id", sa.Text, server_default="")),
- ]
- missing_columns = [
- column for name, column in columns_to_add if name not in existing_columns
- ]
- if missing_columns:
- with op.batch_alter_table("findings") as batch_op:
- for column in missing_columns:
- batch_op.add_column(column)
-
- existing_indexes = {idx["name"] for idx in inspector.get_indexes("findings")}
- if "idx_findings_cvss" not in existing_indexes:
+ if "findings" not in inspector.get_table_names():
+ raise RuntimeError(_CATALOG_ERROR)
+ return {
+ str(column["name"]): column
+ for column in inspector.get_columns("findings")
+ }
+
+
+def _validate_existing(columns: dict[str, dict[str, object]]) -> None:
+ score = columns.get("cvss_score")
+ if score is not None and not isinstance(score["type"], sa.Float):
+ raise RuntimeError(_CATALOG_ERROR)
+ for name in ("cvss_vector", "trace_id"):
+ column = columns.get(name)
+ if column is not None and not isinstance(
+ column["type"], (sa.Text, sa.String)
+ ):
+ raise RuntimeError(_CATALOG_ERROR)
+
+
+def _harden_existing(
+ dialect: str,
+ columns: dict[str, dict[str, object]],
+) -> None:
+ specifications = (
+ ("cvss_score", sa.Float(), "0.0"),
+ ("cvss_vector", sa.Text(), ""),
+ )
+ for name, column_type, default in specifications:
+ column = columns[name]
+ if bool(column.get("nullable", True)):
+ if name == "cvss_score":
+ op.execute(
+ sa.text(
+ "UPDATE findings SET cvss_score=0.0 "
+ "WHERE cvss_score IS NULL"
+ )
+ )
+ else:
+ op.execute(
+ sa.text(
+ "UPDATE findings SET cvss_vector='' "
+ "WHERE cvss_vector IS NULL"
+ )
+ )
+ if dialect == "sqlite":
+ with op.batch_alter_table("findings") as batch_op:
+ batch_op.alter_column(
+ name,
+ existing_type=column_type,
+ nullable=False,
+ server_default=default,
+ )
+ else:
+ op.alter_column(
+ "findings",
+ name,
+ existing_type=column_type,
+ nullable=False,
+ server_default=default,
+ )
+
+
+def _ensure_cvss_index() -> None:
+ indexes = {
+ str(index["name"]): index
+ for index in sa.inspect(op.get_bind()).get_indexes("findings")
+ }
+ current = indexes.get("idx_findings_cvss")
+ if current is None:
op.create_index("idx_findings_cvss", "findings", ["cvss_score"])
+ return
+ if current.get("column_names") != ["cvss_score"] or bool(
+ current.get("unique", False)
+ ):
+ raise RuntimeError(_CATALOG_ERROR)
+
+
+def upgrade() -> None:
+ dialect = _dialect()
+ columns = _columns()
+ _validate_existing(columns)
+ missing = []
+ if "cvss_score" not in columns:
+ missing.append(
+ sa.Column(
+ "cvss_score",
+ sa.Float(),
+ nullable=False,
+ server_default="0.0",
+ )
+ )
+ if "cvss_vector" not in columns:
+ missing.append(
+ sa.Column(
+ "cvss_vector",
+ sa.Text(),
+ nullable=False,
+ server_default="",
+ )
+ )
+ if "trace_id" not in columns:
+ missing.append(
+ sa.Column(
+ "trace_id",
+ sa.Text(),
+ nullable=True,
+ server_default="",
+ )
+ )
+ if missing:
+ if dialect == "sqlite":
+ with op.batch_alter_table("findings") as batch_op:
+ for column in missing:
+ batch_op.add_column(column)
+ else:
+ for column in missing:
+ op.add_column("findings", column)
+
+ reconciled = _columns()
+ _validate_existing(reconciled)
+ _harden_existing(dialect, reconciled)
+ _ensure_cvss_index()
def downgrade() -> None:
- op.drop_index("idx_findings_cvss", "findings")
- with op.batch_alter_table("findings") as batch_op:
- batch_op.drop_column("trace_id")
- batch_op.drop_column("cvss_vector")
- batch_op.drop_column("cvss_score")
+ dialect = _dialect()
+ columns = _columns()
+ _validate_existing(columns)
+ indexes = {
+ str(index["name"]): index
+ for index in sa.inspect(op.get_bind()).get_indexes("findings")
+ }
+ cvss_index = indexes.get("idx_findings_cvss")
+ if cvss_index is not None:
+ if cvss_index.get("column_names") != ["cvss_score"]:
+ raise RuntimeError(_CATALOG_ERROR)
+ op.drop_index("idx_findings_cvss", table_name="findings")
+ if "trace_id" in columns:
+ if dialect == "sqlite":
+ with op.batch_alter_table("findings") as batch_op:
+ batch_op.drop_column("trace_id")
+ else:
+ op.drop_column("findings", "trace_id")
diff --git a/migrations/versions/0003_add_rate_limit_tracking.py b/migrations/versions/0003_add_rate_limit_tracking.py
index 7436698..ba8368b 100644
--- a/migrations/versions/0003_add_rate_limit_tracking.py
+++ b/migrations/versions/0003_add_rate_limit_tracking.py
@@ -1,32 +1,75 @@
-"""Add rate_limit_events table for audit/analytics
+"""Add portable rate-limit audit storage.
Revision ID: 0003
Revises: 0002
Create Date: 2025-01-03 00:00:00
"""
from __future__ import annotations
-from alembic import op
+
import sqlalchemy as sa
+from alembic import op
-revision: str = "0003"
+revision: str = "0003"
down_revision: str | None = "0002"
branch_labels: str | None = None
-depends_on: str | None = None
+depends_on: str | None = None
+
+
+def _timestamp_contract() -> tuple[
+ sa.types.TypeEngine,
+ sa.sql.elements.TextClause,
+]:
+ dialect = op.get_bind().dialect.name
+ if dialect == "sqlite":
+ return sa.Text(), sa.text("datetime('now')")
+ if dialect == "postgresql":
+ return sa.DateTime(timezone=True), sa.text("now()")
+ raise RuntimeError("Unsupported migration dialect")
def upgrade() -> None:
- op.create_table("rate_limit_events",
- sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
- sa.Column("ip_address", sa.Text, nullable=False),
- sa.Column("bucket", sa.Text, nullable=False),
- sa.Column("username", sa.Text),
- sa.Column("blocked", sa.Integer, nullable=False, server_default="0"),
- sa.Column("timestamp", sa.Text, nullable=False, server_default=sa.text("datetime('now')")),
+ timestamp, database_now = _timestamp_contract()
+ dialect = op.get_bind().dialect.name
+ op.create_table(
+ "rate_limit_events",
+ sa.Column(
+ "id", sa.Integer(), primary_key=True, autoincrement=True
+ ),
+ sa.Column("ip_address", sa.Text(), nullable=False),
+ sa.Column("bucket", sa.Text(), nullable=False),
+ sa.Column("username", sa.Text()),
+ sa.Column(
+ "blocked", sa.Integer(), nullable=False, server_default="0"
+ ),
+ sa.Column(
+ "timestamp",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ sa.CheckConstraint(
+ "blocked IN (0, 1)",
+ name="ck_rate_limit_events_blocked_bool",
+ ),
+ *(
+ (
+ sa.CheckConstraint(
+ "isfinite(timestamp)",
+ name="ck_rate_limit_events_timestamp_finite",
+ ),
+ )
+ if dialect == "postgresql"
+ else ()
+ ),
+ sqlite_autoincrement=True,
+ )
+ op.create_index("idx_rle_ip", "rate_limit_events", ["ip_address"])
+ op.create_index(
+ "idx_rle_timestamp", "rate_limit_events", ["timestamp"]
)
- op.create_index("idx_rle_ip", "rate_limit_events", ["ip_address"])
- op.create_index("idx_rle_timestamp", "rate_limit_events", ["timestamp"])
- op.create_index("idx_rle_blocked", "rate_limit_events", ["blocked"])
+ op.create_index("idx_rle_blocked", "rate_limit_events", ["blocked"])
def downgrade() -> None:
+ _timestamp_contract()
op.drop_table("rate_limit_events")
diff --git a/migrations/versions/0004_add_revoked_access_tokens.py b/migrations/versions/0004_add_revoked_access_tokens.py
index 3a856fb..593e159 100644
--- a/migrations/versions/0004_add_revoked_access_tokens.py
+++ b/migrations/versions/0004_add_revoked_access_tokens.py
@@ -1,35 +1,66 @@
-"""Add revoked_access_tokens table for JWT early revocation (logout)
+"""Add portable access-token revocation storage.
Revision ID: 0004
Revises: 0003
Create Date: 2025-01-04 00:00:00
-
-This table was present in schema.py CREATE TABLE IF NOT EXISTS path since v0.5
-but was never added to the alembic migration chain.
-All deployments using alembic upgrade head MUST run this migration.
"""
from __future__ import annotations
-from alembic import op
+
import sqlalchemy as sa
+from alembic import op
-revision: str = "0004"
+revision: str = "0004"
down_revision: str | None = "0003"
branch_labels: str | None = None
-depends_on: str | None = None
+depends_on: str | None = None
+
+
+def _timestamp_contract() -> tuple[
+ sa.types.TypeEngine,
+ sa.sql.elements.TextClause,
+]:
+ dialect = op.get_bind().dialect.name
+ if dialect == "sqlite":
+ return sa.Text(), sa.text("datetime('now')")
+ if dialect == "postgresql":
+ return sa.DateTime(timezone=True), sa.text("now()")
+ raise RuntimeError("Unsupported migration dialect")
def upgrade() -> None:
+ timestamp, database_now = _timestamp_contract()
+ dialect = op.get_bind().dialect.name
op.create_table(
"revoked_access_tokens",
- sa.Column("jti", sa.Text, primary_key=True),
- sa.Column("user_id", sa.Text, nullable=False),
- sa.Column("revoked_at", sa.Text, nullable=False,
- server_default=sa.text("datetime('now')")),
- sa.Column("expires_at", sa.Text, nullable=False),
+ sa.Column("jti", sa.Text(), primary_key=True),
+ sa.Column("user_id", sa.Text(), nullable=False),
+ sa.Column(
+ "revoked_at",
+ timestamp,
+ nullable=False,
+ server_default=database_now,
+ ),
+ sa.Column("expires_at", timestamp, nullable=False),
+ *(
+ (
+ sa.CheckConstraint(
+ "isfinite(revoked_at)",
+ name="ck_revoked_access_tokens_revoked_at_finite",
+ ),
+ sa.CheckConstraint(
+ "isfinite(expires_at)",
+ name="ck_revoked_access_tokens_expires_at_finite",
+ ),
+ )
+ if dialect == "postgresql"
+ else ()
+ ),
+ )
+ op.create_index(
+ "idx_rat_expires", "revoked_access_tokens", ["expires_at"]
)
- op.create_index("idx_rat_expires", "revoked_access_tokens", ["expires_at"])
def downgrade() -> None:
- op.drop_index("idx_rat_expires", "revoked_access_tokens")
+ _timestamp_contract()
op.drop_table("revoked_access_tokens")
diff --git a/migrations/versions/0005_add_trace_id_to_findings.py b/migrations/versions/0005_add_trace_id_to_findings.py
index c9b94b4..6551208 100644
--- a/migrations/versions/0005_add_trace_id_to_findings.py
+++ b/migrations/versions/0005_add_trace_id_to_findings.py
@@ -1,38 +1,189 @@
-"""Add trace_id column to findings table
+"""Harden finding trace metadata without taking ownership from revision 0002.
Revision ID: 0005
Revises: 0004
Create Date: 2025-01-05 00:00:00
-
-trace_id was present in schema.py (CREATE TABLE IF NOT EXISTS) since v0.5
-but was missing from the Alembic migration chain.
-Deployments using `alembic upgrade head` from scratch will get this
-column via migration 0001 (re-run safe via IF NOT EXISTS path),
-but existing deployments need this ALTER TABLE to add the column.
"""
from __future__ import annotations
-from alembic import op
-import sqlalchemy as sa
+from typing import Protocol, cast
+
+import sqlalchemy as sa
+from alembic import op
-revision: str = "0005"
+revision: str = "0005"
down_revision: str | None = "0004"
branch_labels: str | None = None
-depends_on: str | None = None
+depends_on: str | None = None
+_CATALOG_ERROR = "Incompatible findings catalog for migration 0005"
-def upgrade() -> None:
- inspector = sa.inspect(op.get_bind())
- existing_columns = {col["name"] for col in inspector.get_columns("findings")}
- if "trace_id" not in existing_columns:
- # Use batch_alter_table for SQLite compatibility (SQLite doesn't support
- # ADD COLUMN with constraints in all versions)
- with op.batch_alter_table("findings") as batch_op:
- batch_op.add_column(
- sa.Column("trace_id", sa.Text, nullable=False, server_default="")
+
+class _InvalidatableConnection(Protocol):
+ def invalidate(self) -> None: ...
+
+
+def _record_cleanup_failure(
+ primary: Exception,
+ action: str,
+ cleanup_error: Exception,
+) -> None:
+ primary.add_note(
+ "Migration 0005 savepoint cleanup failed "
+ f"[{action}: {type(cleanup_error).__name__}]"
+ )
+
+
+def _invalidate_connection(bind: object, primary: Exception) -> None:
+ try:
+ cast(_InvalidatableConnection, bind).invalidate()
+ except Exception as cleanup_error:
+ _record_cleanup_failure(
+ primary,
+ "invalidate-connection",
+ cleanup_error,
+ )
+
+
+def _catalog() -> tuple[str, dict[str, dict[str, object]]]:
+ bind = op.get_bind()
+ dialect = bind.dialect.name
+ if dialect not in {"sqlite", "postgresql"}:
+ raise RuntimeError("Unsupported migration dialect")
+ inspector = sa.inspect(bind)
+ if "findings" not in inspector.get_table_names():
+ raise RuntimeError(_CATALOG_ERROR)
+ columns = {
+ str(column["name"]): column
+ for column in inspector.get_columns("findings")
+ }
+ trace = columns.get("trace_id")
+ if trace is not None and not isinstance(
+ trace["type"], (sa.Text, sa.String)
+ ):
+ raise RuntimeError(_CATALOG_ERROR)
+ return dialect, columns
+
+
+def _alter_trace(dialect: str, *, nullable: bool) -> None:
+ if dialect == "sqlite":
+ bind = op.get_bind()
+ bind.exec_driver_sql("SAVEPOINT migration_0005_trace")
+ try:
+ with op.batch_alter_table("findings") as batch_op:
+ batch_op.alter_column(
+ "trace_id",
+ existing_type=sa.Text(),
+ nullable=nullable,
+ server_default="",
+ )
+ except Exception as primary:
+ primary_traceback = primary.__traceback__
+ rollback_succeeded = False
+ try:
+ bind.exec_driver_sql(
+ "ROLLBACK TO SAVEPOINT migration_0005_trace"
+ )
+ rollback_succeeded = True
+ except Exception as cleanup_error:
+ _record_cleanup_failure(
+ primary,
+ "rollback-savepoint",
+ cleanup_error,
+ )
+ _invalidate_connection(bind, primary)
+ if rollback_succeeded:
+ try:
+ bind.exec_driver_sql(
+ "RELEASE SAVEPOINT migration_0005_trace"
+ )
+ except Exception as cleanup_error:
+ _record_cleanup_failure(
+ primary,
+ "release-savepoint",
+ cleanup_error,
+ )
+ _invalidate_connection(bind, primary)
+ raise primary.with_traceback(primary_traceback) from None
+ else:
+ bind.exec_driver_sql(
+ "RELEASE SAVEPOINT migration_0005_trace"
)
+ else:
+ op.alter_column(
+ "findings",
+ "trace_id",
+ existing_type=sa.Text(),
+ nullable=nullable,
+ server_default="",
+ )
+
+
+def _trace_definition_matches(
+ column: dict[str, object],
+ *,
+ nullable: bool,
+) -> bool:
+ default = column.get("default")
+ normalized_default = (
+ ""
+ if default is None
+ else str(default)
+ .replace("(", "")
+ .replace(")", "")
+ .replace("::text", "")
+ .strip()
+ .strip("'")
+ )
+ return (
+ bool(column.get("nullable", True)) is nullable
+ and normalized_default == ""
+ and default is not None
+ )
+
+
+def upgrade() -> None:
+ dialect, columns = _catalog()
+ if "trace_id" not in columns:
+ column = sa.Column(
+ "trace_id",
+ sa.Text(),
+ nullable=False,
+ server_default="",
+ )
+ if dialect == "sqlite":
+ with op.batch_alter_table("findings") as batch_op:
+ batch_op.add_column(column)
+ else:
+ op.add_column("findings", column)
+ return
+
+ # Historical normalization policy:
+ # - SQL NULL means no legacy trace identifier was recorded.
+ # - It becomes the empty-string sentinel used for that same state.
+ # - Existing empty and non-empty values remain exactly unchanged.
+ # - No row is removed.
+ # Ordering is deliberate: normalize, verify, then harden. Downgrade
+ # relaxes nullability only because it cannot reconstruct which empty
+ # values were formerly NULL.
+ op.execute(
+ sa.text("UPDATE findings SET trace_id='' WHERE trace_id IS NULL")
+ )
+ remaining_nulls = op.get_bind().execute(
+ sa.text("SELECT count(*) FROM findings WHERE trace_id IS NULL")
+ ).scalar_one()
+ if remaining_nulls != 0:
+ raise RuntimeError(_CATALOG_ERROR)
+ if not _trace_definition_matches(
+ columns["trace_id"],
+ nullable=False,
+ ):
+ _alter_trace(dialect, nullable=False)
def downgrade() -> None:
- with op.batch_alter_table("findings") as batch_op:
- batch_op.drop_column("trace_id")
+ dialect, columns = _catalog()
+ if "trace_id" not in columns:
+ raise RuntimeError(_CATALOG_ERROR)
+ if not bool(columns["trace_id"].get("nullable", True)):
+ _alter_trace(dialect, nullable=True)
diff --git a/migrations/versions/0006_rename_cracked_value_to_enc.py b/migrations/versions/0006_rename_cracked_value_to_enc.py
index 5c9b413..fc49a59 100644
--- a/migrations/versions/0006_rename_cracked_value_to_enc.py
+++ b/migrations/versions/0006_rename_cracked_value_to_enc.py
@@ -1,104 +1,139 @@
-"""Rename cracked_value to cracked_value_enc in credentials table
+"""Rename credential cracked-value storage without guessing catalog state.
Revision ID: 0006
Revises: 0005
Create Date: 2026-03-22 00:00:00
-
-BUG-09 fix: schema.py uses cracked_value_enc (Fernet-encrypted) but
-migration 0001 created the column as cracked_value (unencrypted name).
-
-This migration renames the column so alembic-managed deployments match
-the CREATE_TABLES fallback schema in schema.py.
-
-SQLite does not support RENAME COLUMN before version 3.25.0 (2018-09-15).
-We use a safe copy-transform for compatibility with older SQLite versions.
-PostgreSQL supports ALTER TABLE ... RENAME COLUMN natively.
"""
from __future__ import annotations
-from alembic import op
import sqlalchemy as sa
-from sqlalchemy.engine import reflection
-
+from alembic import op
-revision: str = "0006"
+revision: str = "0006"
down_revision: str | None = "0005"
branch_labels: str | None = None
-depends_on: str | None = None
+depends_on: str | None = None
+_CATALOG_ERROR = "Incompatible credentials catalog for migration 0006"
+_AMBIGUOUS_ERROR = "Ambiguous credentials catalog for migration 0006"
-def upgrade() -> None:
+
+def _catalog() -> tuple[
+ str,
+ dict[str, dict[str, object]],
+ dict[str, tuple[str, object]],
+]:
bind = op.get_bind()
dialect = bind.dialect.name
-
- if dialect == "postgresql":
- # PostgreSQL — clean rename
- op.alter_column(
- "credentials",
- "cracked_value",
- new_column_name="cracked_value_enc",
- existing_type=sa.Text(),
- existing_nullable=True,
- )
+ if dialect not in {"sqlite", "postgresql"}:
+ raise RuntimeError("Unsupported migration dialect")
+ inspector = sa.inspect(bind)
+ if "credentials" not in inspector.get_table_names():
+ raise RuntimeError(_CATALOG_ERROR)
+ columns = {
+ str(column["name"]): column
+ for column in inspector.get_columns("credentials")
+ }
+ declared: dict[str, tuple[str, object]] = {}
+ if dialect == "sqlite":
+ rows = bind.exec_driver_sql(
+ 'PRAGMA table_info("credentials")'
+ ).fetchall()
+ declared = {
+ str(row[1]): (str(row[2]), row[4])
+ for row in rows
+ }
else:
- # SQLite — does not support RENAME COLUMN before 3.25.0.
- # Check if column already has the correct name (idempotent).
- insp = reflection.Inspector.from_engine(bind)
- cols = [c["name"] for c in insp.get_columns("credentials")]
-
- if "cracked_value_enc" in cols:
- # Already renamed (e.g. deployed from CREATE_TABLES) — nothing to do
- return
-
- if "cracked_value" not in cols:
- # Neither column exists — add the correct one
- op.add_column(
- "credentials",
- sa.Column("cracked_value_enc", sa.Text(), nullable=True),
+ rows = bind.execute(
+ sa.text(
+ """
+ SELECT
+ attribute.attname AS column_name,
+ format_type(
+ attribute.atttypid,
+ attribute.atttypmod
+ ) AS declared_type,
+ definition.oid IS NOT NULL AS has_default
+ FROM pg_attribute AS attribute
+ JOIN pg_class AS relation
+ ON relation.oid=attribute.attrelid
+ JOIN pg_namespace AS namespace
+ ON namespace.oid=relation.relnamespace
+ LEFT JOIN pg_attrdef AS definition
+ ON definition.adrelid=attribute.attrelid
+ AND definition.adnum=attribute.attnum
+ WHERE namespace.nspname=current_schema()
+ AND relation.relname='credentials'
+ AND attribute.attnum > 0
+ AND NOT attribute.attisdropped
+ """
)
- return
-
- # Rename via copy: add new col, copy data, drop old col.
- # This is safe — cracked_value was never encrypted in old schema,
- # so values (if any) are already plaintext and will remain as-is.
- with op.batch_alter_table("credentials") as batch_op:
- batch_op.add_column(
- sa.Column("cracked_value_enc", sa.Text(), nullable=True)
+ ).mappings()
+ declared = {
+ str(row["column_name"]): (
+ str(row["declared_type"]),
+ bool(row["has_default"]),
)
+ for row in rows
+ }
+ return dialect, columns, declared
+
+
+def _validate_column(
+ dialect: str,
+ name: str,
+ columns: dict[str, dict[str, object]],
+ declared: dict[str, tuple[str, object]],
+) -> None:
+ column = columns[name]
+ column_type = column["type"]
+ if (
+ not isinstance(column_type, sa.Text)
+ or type(column_type).__name__ != "TEXT"
+ or column.get("nullable") is not True
+ or column.get("default") is not None
+ ):
+ raise RuntimeError(_CATALOG_ERROR)
+ if dialect == "sqlite":
+ declared_type, declared_default = declared.get(name, ("", object()))
+ if declared_type != "TEXT" or declared_default is not None:
+ raise RuntimeError(_CATALOG_ERROR)
+ else:
+ declared_type, has_default = declared.get(name, ("", object()))
+ if declared_type != "text" or has_default is not False:
+ raise RuntimeError(_CATALOG_ERROR)
+
+
+def _rename(source: str, target: str) -> None:
+ dialect, columns, declared = _catalog()
+ source_exists = source in columns
+ target_exists = target in columns
+ if source_exists and target_exists:
+ raise RuntimeError(_AMBIGUOUS_ERROR)
+ if not source_exists and not target_exists:
+ raise RuntimeError(_CATALOG_ERROR)
+ existing_name = target if target_exists else source
+ _validate_column(dialect, existing_name, columns, declared)
+ if target_exists:
+ return
+
+ op.alter_column(
+ "credentials",
+ source,
+ new_column_name=target,
+ existing_type=sa.Text(),
+ existing_nullable=True,
+ )
+
+ after_dialect, after, after_declared = _catalog()
+ if source in after or target not in after:
+ raise RuntimeError(_CATALOG_ERROR)
+ _validate_column(after_dialect, target, after, after_declared)
- bind.execute(sa.text(
- "UPDATE credentials SET cracked_value_enc = cracked_value "
- "WHERE cracked_value IS NOT NULL"
- ))
- with op.batch_alter_table("credentials") as batch_op:
- batch_op.drop_column("cracked_value")
+def upgrade() -> None:
+ _rename("cracked_value", "cracked_value_enc")
def downgrade() -> None:
- bind = op.get_bind()
- dialect = bind.dialect.name
-
- if dialect == "postgresql":
- op.alter_column(
- "credentials",
- "cracked_value_enc",
- new_column_name="cracked_value",
- existing_type=sa.Text(),
- existing_nullable=True,
- )
- else:
- insp = reflection.Inspector.from_engine(bind)
- cols = [c["name"] for c in insp.get_columns("credentials")]
- if "cracked_value" in cols:
- return
- with op.batch_alter_table("credentials") as batch_op:
- batch_op.add_column(
- sa.Column("cracked_value", sa.Text(), nullable=True)
- )
- bind.execute(sa.text(
- "UPDATE credentials SET cracked_value = cracked_value_enc "
- "WHERE cracked_value_enc IS NOT NULL"
- ))
- with op.batch_alter_table("credentials") as batch_op:
- batch_op.drop_column("cracked_value_enc")
+ _rename("cracked_value_enc", "cracked_value")
diff --git a/tests/integration/test_postgres_migration_portability.py b/tests/integration/test_postgres_migration_portability.py
new file mode 100644
index 0000000..61071d8
--- /dev/null
+++ b/tests/integration/test_postgres_migration_portability.py
@@ -0,0 +1,6430 @@
+"""Real PostgreSQL execution tests for the historical Alembic chain."""
+from __future__ import annotations
+
+import asyncio
+import builtins
+import importlib
+import importlib.machinery
+import multiprocessing
+import os
+import re
+import sys
+import threading
+import time
+import types
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from contextlib import asynccontextmanager, contextmanager
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+import pytest
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_POSTGRES_ENV = (
+ "ARES_TEST_POSTGRES_HOST",
+ "ARES_TEST_POSTGRES_PORT",
+ "ARES_TEST_POSTGRES_USER",
+ "ARES_TEST_POSTGRES_DB",
+)
+_SAFE_DATABASE_NAME = re.compile(r"^ares_migration_[0-9a-f]{32}$")
+_SAFE_EXCEPTION_TYPE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+_WORKER_TIMEOUT_SECONDS = 45.0
+_WORKER_SETTLE_SECONDS = 5.0
+_POSTGRES_OPERATION_TIMEOUT_SECONDS = 15.0
+_WORKER_POLL_SECONDS = 0.01
+_OWNED_WORKERS: set[_OwnedWorker] = set()
+_EXPECTED_TABLES = {
+ "campaigns",
+ "module_runs",
+ "findings",
+ "hosts",
+ "credentials",
+ "loot",
+ "audit_log",
+ "users",
+ "api_keys",
+ "refresh_tokens",
+ "revoked_access_tokens",
+ "rate_limit_events",
+}
+_EXPECTED_FOREIGN_KEYS = {
+ ("module_runs", "campaign_id", "campaigns", "CASCADE"),
+ ("findings", "campaign_id", "campaigns", "CASCADE"),
+ ("hosts", "campaign_id", "campaigns", "CASCADE"),
+ ("credentials", "campaign_id", "campaigns", "CASCADE"),
+ ("credentials", "host_id", "hosts", "SET NULL"),
+ ("loot", "campaign_id", "campaigns", "CASCADE"),
+ ("loot", "host_id", "hosts", "SET NULL"),
+ ("audit_log", "campaign_id", "campaigns", "SET NULL"),
+ ("api_keys", "user_id", "users", "CASCADE"),
+ ("refresh_tokens", "user_id", "users", "CASCADE"),
+}
+_EXPECTED_INDEXES = {
+ "idx_module_runs_campaign": ("campaign_id",),
+ "idx_module_runs_completed": ("completed_at",),
+ "idx_findings_campaign": ("campaign_id",),
+ "idx_findings_severity": ("severity",),
+ "idx_findings_fp": ("false_positive",),
+ "idx_findings_mitre": ("mitre_technique",),
+ "idx_findings_cvss": ("cvss_score",),
+ "idx_hosts_campaign": ("campaign_id",),
+ "idx_hosts_ip": ("ip_address",),
+ "idx_hosts_domain": ("domain",),
+ "idx_creds_campaign": ("campaign_id",),
+ "idx_creds_username": ("username",),
+ "idx_creds_type": ("cred_type",),
+ "idx_loot_campaign": ("campaign_id",),
+ "idx_loot_type": ("loot_type",),
+ "idx_audit_campaign": ("campaign_id",),
+ "idx_audit_actor": ("actor",),
+ "idx_audit_action": ("action",),
+ "idx_users_username": ("username",),
+ "idx_users_role": ("role",),
+ "idx_apikeys_user": ("user_id",),
+ "idx_apikeys_prefix": ("key_prefix",),
+ "idx_refresh_user": ("user_id",),
+ "idx_refresh_exp": ("expires_at",),
+ "idx_rat_expires": ("expires_at",),
+ "idx_rle_ip": ("ip_address",),
+ "idx_rle_timestamp": ("timestamp",),
+ "idx_rle_blocked": ("blocked",),
+}
+_POSTGRES_INDEX_TABLES = {
+ "idx_module_runs_campaign": "module_runs",
+ "idx_module_runs_completed": "module_runs",
+ "idx_findings_campaign": "findings",
+ "idx_findings_severity": "findings",
+ "idx_findings_fp": "findings",
+ "idx_findings_mitre": "findings",
+ "idx_findings_cvss": "findings",
+ "idx_hosts_campaign": "hosts",
+ "idx_hosts_ip": "hosts",
+ "idx_hosts_domain": "hosts",
+ "idx_creds_campaign": "credentials",
+ "idx_creds_username": "credentials",
+ "idx_creds_type": "credentials",
+ "idx_loot_campaign": "loot",
+ "idx_loot_type": "loot",
+ "idx_audit_campaign": "audit_log",
+ "idx_audit_actor": "audit_log",
+ "idx_audit_action": "audit_log",
+ "idx_users_username": "users",
+ "idx_users_role": "users",
+ "idx_apikeys_user": "api_keys",
+ "idx_apikeys_prefix": "api_keys",
+ "idx_refresh_user": "refresh_tokens",
+ "idx_refresh_exp": "refresh_tokens",
+ "idx_rat_expires": "revoked_access_tokens",
+ "idx_rle_ip": "rate_limit_events",
+ "idx_rle_timestamp": "rate_limit_events",
+ "idx_rle_blocked": "rate_limit_events",
+}
+_EXPECTED_COLUMN_ORDER = {
+ "campaigns": (
+ "id", "name", "client", "operator", "noise_profile", "status",
+ "scope_json", "targets_json", "notes", "created_at", "updated_at",
+ ),
+ "module_runs": (
+ "id", "campaign_id", "module_id", "outcome", "success",
+ "duration_ms", "completed_at",
+ ),
+ "findings": (
+ "id", "campaign_id", "module_id", "title", "description",
+ "severity", "confidence", "mitre_technique", "mitre_tactic",
+ "cvss_score", "cvss_vector", "evidence_json", "remediation",
+ "host", "validated", "false_positive", "discovered_at", "trace_id",
+ ),
+ "hosts": (
+ "id", "campaign_id", "ip_address", "hostname", "fqdn", "os",
+ "os_version", "domain", "is_dc", "open_ports_json", "tags_json",
+ "first_seen", "last_seen",
+ ),
+ "credentials": (
+ "id", "campaign_id", "host_id", "username", "secret_enc",
+ "cred_type", "domain", "source_module", "notes", "cracked",
+ "cracked_value_enc", "captured_at",
+ ),
+ "loot": (
+ "id", "campaign_id", "host_id", "loot_type", "name",
+ "description", "content_enc", "size_bytes", "path_on_target",
+ "source_module", "tags_json", "captured_at",
+ ),
+ "audit_log": (
+ "id", "campaign_id", "actor", "action", "detail", "module_id",
+ "timestamp",
+ ),
+ "users": (
+ "id", "username", "hashed_password", "role", "is_active",
+ "created_by", "created_at", "last_login",
+ ),
+ "api_keys": (
+ "id", "user_id", "name", "key_hash", "key_prefix", "scopes",
+ "is_active", "last_used", "expires_at", "created_at",
+ ),
+ "refresh_tokens": (
+ "id", "user_id", "is_revoked", "expires_at", "created_at",
+ "used_at",
+ ),
+ "revoked_access_tokens": (
+ "jti", "user_id", "revoked_at", "expires_at",
+ ),
+ "rate_limit_events": (
+ "id", "ip_address", "bucket", "username", "blocked", "timestamp",
+ ),
+}
+_POSTGRES_INTEGER_COLUMNS = {
+ ("module_runs", "success"),
+ ("hosts", "is_dc"),
+ ("credentials", "cracked"),
+ ("loot", "size_bytes"),
+ ("audit_log", "id"),
+ ("users", "is_active"),
+ ("api_keys", "is_active"),
+ ("refresh_tokens", "is_revoked"),
+ ("rate_limit_events", "id"),
+ ("rate_limit_events", "blocked"),
+ ("findings", "validated"),
+ ("findings", "false_positive"),
+}
+_POSTGRES_FLOAT_COLUMNS = {
+ ("module_runs", "duration_ms"),
+ ("findings", "confidence"),
+ ("findings", "cvss_score"),
+}
+_POSTGRES_TIMESTAMP_COLUMNS = {
+ ("campaigns", "created_at"),
+ ("campaigns", "updated_at"),
+ ("module_runs", "completed_at"),
+ ("findings", "discovered_at"),
+ ("hosts", "first_seen"),
+ ("hosts", "last_seen"),
+ ("credentials", "captured_at"),
+ ("loot", "captured_at"),
+ ("audit_log", "timestamp"),
+ ("users", "created_at"),
+ ("users", "last_login"),
+ ("api_keys", "last_used"),
+ ("api_keys", "expires_at"),
+ ("api_keys", "created_at"),
+ ("refresh_tokens", "expires_at"),
+ ("refresh_tokens", "created_at"),
+ ("refresh_tokens", "used_at"),
+ ("revoked_access_tokens", "revoked_at"),
+ ("revoked_access_tokens", "expires_at"),
+ ("rate_limit_events", "timestamp"),
+}
+_POSTGRES_FINITE_TIMESTAMP_CONSTRAINTS = {
+ ("campaigns", "created_at"): (
+ "ck_campaigns_created_at_finite",
+ False,
+ ),
+ ("campaigns", "updated_at"): (
+ "ck_campaigns_updated_at_finite",
+ False,
+ ),
+ ("module_runs", "completed_at"): (
+ "ck_module_runs_completed_at_finite",
+ False,
+ ),
+ ("findings", "discovered_at"): (
+ "ck_findings_discovered_at_finite",
+ False,
+ ),
+ ("hosts", "first_seen"): ("ck_hosts_first_seen_finite", False),
+ ("hosts", "last_seen"): ("ck_hosts_last_seen_finite", False),
+ ("credentials", "captured_at"): (
+ "ck_credentials_captured_at_finite",
+ False,
+ ),
+ ("loot", "captured_at"): ("ck_loot_captured_at_finite", False),
+ ("audit_log", "timestamp"): ("ck_audit_log_timestamp_finite", False),
+ ("users", "created_at"): ("ck_users_created_at_finite", False),
+ ("users", "last_login"): ("ck_users_last_login_finite", True),
+ ("api_keys", "last_used"): ("ck_api_keys_last_used_finite", True),
+ ("api_keys", "expires_at"): ("ck_api_keys_expires_at_finite", True),
+ ("api_keys", "created_at"): ("ck_api_keys_created_at_finite", False),
+ ("refresh_tokens", "expires_at"): (
+ "ck_refresh_tokens_expires_at_finite",
+ False,
+ ),
+ ("refresh_tokens", "created_at"): (
+ "ck_refresh_tokens_created_at_finite",
+ False,
+ ),
+ ("refresh_tokens", "used_at"): (
+ "ck_refresh_tokens_used_at_finite",
+ True,
+ ),
+ ("revoked_access_tokens", "revoked_at"): (
+ "ck_revoked_access_tokens_revoked_at_finite",
+ False,
+ ),
+ ("revoked_access_tokens", "expires_at"): (
+ "ck_revoked_access_tokens_expires_at_finite",
+ False,
+ ),
+ ("rate_limit_events", "timestamp"): (
+ "ck_rate_limit_events_timestamp_finite",
+ False,
+ ),
+}
+_POSTGRES_NULLABLE_COLUMNS = {
+ ("campaigns", "notes"),
+ ("findings", "mitre_technique"),
+ ("findings", "mitre_tactic"),
+ ("findings", "remediation"),
+ ("findings", "host"),
+ ("hosts", "hostname"),
+ ("hosts", "fqdn"),
+ ("hosts", "os"),
+ ("hosts", "os_version"),
+ ("hosts", "domain"),
+ ("credentials", "host_id"),
+ ("credentials", "secret_enc"),
+ ("credentials", "domain"),
+ ("credentials", "source_module"),
+ ("credentials", "notes"),
+ ("credentials", "cracked_value_enc"),
+ ("loot", "host_id"),
+ ("loot", "description"),
+ ("loot", "content_enc"),
+ ("loot", "size_bytes"),
+ ("loot", "path_on_target"),
+ ("loot", "source_module"),
+ ("audit_log", "campaign_id"),
+ ("audit_log", "detail"),
+ ("audit_log", "module_id"),
+ ("users", "last_login"),
+ ("api_keys", "last_used"),
+ ("api_keys", "expires_at"),
+ ("refresh_tokens", "used_at"),
+ ("rate_limit_events", "username"),
+}
+_POSTGRES_DEFAULTS = {
+ ("campaigns", "client"): "literal:Internal",
+ ("campaigns", "operator"): "literal:unknown",
+ ("campaigns", "noise_profile"): "literal:stealth",
+ ("campaigns", "status"): "literal:created",
+ ("campaigns", "scope_json"): "literal:[]",
+ ("campaigns", "targets_json"): "literal:[]",
+ ("campaigns", "notes"): "literal:",
+ ("campaigns", "created_at"): "now",
+ ("campaigns", "updated_at"): "now",
+ ("module_runs", "success"): "literal:0",
+ ("module_runs", "duration_ms"): "literal:0.0",
+ ("module_runs", "completed_at"): "now",
+ ("findings", "confidence"): "literal:1.0",
+ ("findings", "cvss_score"): "literal:0.0",
+ ("findings", "cvss_vector"): "literal:",
+ ("findings", "evidence_json"): "literal:{}",
+ ("findings", "remediation"): "literal:",
+ ("findings", "validated"): "literal:0",
+ ("findings", "false_positive"): "literal:0",
+ ("findings", "discovered_at"): "now",
+ ("findings", "trace_id"): "literal:",
+ ("hosts", "is_dc"): "literal:0",
+ ("hosts", "open_ports_json"): "literal:[]",
+ ("hosts", "tags_json"): "literal:[]",
+ ("hosts", "first_seen"): "now",
+ ("hosts", "last_seen"): "now",
+ ("credentials", "notes"): "literal:",
+ ("credentials", "cracked"): "literal:0",
+ ("credentials", "captured_at"): "now",
+ ("loot", "description"): "literal:",
+ ("loot", "size_bytes"): "literal:0",
+ ("loot", "tags_json"): "literal:[]",
+ ("loot", "captured_at"): "now",
+ ("audit_log", "id"): "sequence",
+ ("audit_log", "actor"): "literal:system",
+ ("audit_log", "detail"): "literal:",
+ ("audit_log", "timestamp"): "now",
+ ("users", "role"): "literal:reporter",
+ ("users", "is_active"): "literal:1",
+ ("users", "created_by"): "literal:system",
+ ("users", "created_at"): "now",
+ ("api_keys", "scopes"): "literal:read",
+ ("api_keys", "is_active"): "literal:1",
+ ("api_keys", "created_at"): "now",
+ ("refresh_tokens", "is_revoked"): "literal:0",
+ ("refresh_tokens", "created_at"): "now",
+ ("revoked_access_tokens", "revoked_at"): "now",
+ ("rate_limit_events", "id"): "sequence",
+ ("rate_limit_events", "blocked"): "literal:0",
+ ("rate_limit_events", "timestamp"): "now",
+}
+
+
+@dataclass(frozen=True, eq=False)
+class _PostgresConfig:
+ host: str = field(repr=False)
+ port: int = field(repr=False)
+ user: str = field(repr=False)
+ maintenance_database: str = field(repr=False)
+
+
+@dataclass(frozen=True, eq=False)
+class _MigrationHarness:
+ config: _PostgresConfig = field(repr=False)
+ database_name: str = field(repr=False)
+
+
+@dataclass(eq=False)
+class _OwnedWorker:
+ process: Any = field(repr=False)
+ channel: Any = field(repr=False)
+ child_channel: Any = field(default=None, repr=False)
+ start_attempted: bool = False
+ may_have_started: bool = False
+ death_proven: bool = False
+ settled_exit_code: int | None = None
+ eof: bool = False
+ parent_closed: bool = False
+ child_closed: bool = False
+ process_closed: bool = False
+ closed: bool = False
+
+
+@dataclass(frozen=True)
+class _PostgresCatalogContract:
+ tables: tuple[str, ...]
+ columns: tuple[
+ tuple[str, str, str, bool, str | None], ...
+ ]
+ primary_keys: tuple[tuple[str, tuple[str, ...]], ...]
+ unique_constraints: tuple[
+ tuple[str, str, tuple[str, ...]], ...
+ ]
+ checks: tuple[tuple[str, str, str], ...]
+ foreign_keys: tuple[
+ tuple[
+ str,
+ str,
+ tuple[str, ...],
+ str,
+ tuple[str, ...],
+ str,
+ str,
+ ],
+ ...,
+ ]
+ indexes: tuple[
+ tuple[str, str, tuple[str, ...], bool, str | None], ...
+ ]
+ sequences: tuple[str, ...]
+
+
+@dataclass(frozen=True, repr=False)
+class _PostgresIsolationFingerprint:
+ schemas: tuple[str, ...] = field(repr=False)
+ relations: tuple[tuple[object, ...], ...] = field(repr=False)
+ columns: tuple[tuple[object, ...], ...] = field(repr=False)
+ constraints: tuple[tuple[object, ...], ...] = field(repr=False)
+ indexes: tuple[tuple[object, ...], ...] = field(repr=False)
+ sequences: tuple[tuple[object, ...], ...] = field(repr=False)
+ versions: tuple[tuple[str, str], ...] = field(repr=False)
+
+
+@dataclass(frozen=True)
+class _PostgresLegacyRecipe:
+ constraints_to_drop: tuple[tuple[str, str], ...]
+ tables_to_drop: tuple[str, ...]
+ nullable_columns: tuple[tuple[str, str], ...]
+ indexes_to_create: tuple[tuple[str, str, tuple[str, ...]], ...]
+
+
+class _BoundedTransaction:
+ def __init__(self, transaction: Any) -> None:
+ self._transaction = transaction
+
+ async def start(self) -> object:
+ return await asyncio.wait_for(
+ self._transaction.start(),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ async def commit(self) -> object:
+ return await asyncio.wait_for(
+ self._transaction.commit(),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ async def rollback(self) -> object:
+ return await asyncio.wait_for(
+ self._transaction.rollback(),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+
+class _BoundedConnection:
+ def __init__(self, connection: Any) -> None:
+ self._connection = connection
+
+ async def execute(self, *args: object) -> object:
+ return await asyncio.wait_for(
+ self._connection.execute(*args),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ async def fetch(self, *args: object) -> object:
+ return await asyncio.wait_for(
+ self._connection.fetch(*args),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ async def fetchrow(self, *args: object) -> object:
+ return await asyncio.wait_for(
+ self._connection.fetchrow(*args),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ async def fetchval(self, *args: object) -> object:
+ return await asyncio.wait_for(
+ self._connection.fetchval(*args),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ async def close(self) -> None:
+ await asyncio.wait_for(
+ self._connection.close(),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ def transaction(self) -> _BoundedTransaction:
+ return _BoundedTransaction(self._connection.transaction())
+
+
+def _require_fixed(condition: bool, message: str) -> None:
+ if not condition:
+ pytest.fail(message, pytrace=False)
+
+
+def _requires_candidate_origin(name: str) -> bool:
+ return (
+ name in {"ares", "migrations", "tests.unit", "tests.integration"}
+ or name.startswith(("ares.", "migrations."))
+ or name.startswith(("tests.unit.", "tests.integration."))
+ )
+
+
+def _path_is_within_candidate(path: object, candidate_root: Path) -> bool:
+ try:
+ resolved_path = os.path.normcase(
+ str(Path(path).resolve(strict=False))
+ )
+ resolved_root = os.path.normcase(
+ str(candidate_root.resolve(strict=True))
+ )
+ return os.path.commonpath((resolved_path, resolved_root)) == (
+ resolved_root
+ )
+ except (OSError, RuntimeError, TypeError, ValueError):
+ return False
+
+
+def _module_origin_is_candidate_local(
+ module: object,
+ candidate_root: Path,
+) -> bool:
+ spec = getattr(module, "__spec__", None)
+ concrete_origins: list[object] = []
+ module_file = getattr(module, "__file__", None)
+ if module_file is not None:
+ concrete_origins.append(module_file)
+ spec_origin = getattr(spec, "origin", None)
+ if spec_origin not in {None, "built-in", "frozen"}:
+ concrete_origins.append(spec_origin)
+ concrete_is_local = not concrete_origins or all(
+ _path_is_within_candidate(origin, candidate_root)
+ for origin in concrete_origins
+ )
+ search_locations = getattr(spec, "submodule_search_locations", None)
+ if search_locations is None:
+ search_locations = getattr(module, "__path__", None)
+ if search_locations is None:
+ locations_are_local = True
+ has_locations = False
+ else:
+ locations = tuple(search_locations)
+ has_locations = bool(locations)
+ locations_are_local = has_locations and all(
+ _path_is_within_candidate(location, candidate_root)
+ for location in locations
+ )
+ return (
+ concrete_is_local
+ and locations_are_local
+ and (bool(concrete_origins) or has_locations)
+ )
+
+
+def _spec_origin_is_candidate_local(
+ spec: object,
+ candidate_root: Path,
+) -> bool:
+ concrete_origins: list[object] = []
+ spec_origin = getattr(spec, "origin", None)
+ if spec_origin not in {None, "built-in", "frozen"}:
+ concrete_origins.append(spec_origin)
+ concrete_is_local = not concrete_origins or all(
+ _path_is_within_candidate(origin, candidate_root)
+ for origin in concrete_origins
+ )
+ search_locations = getattr(spec, "submodule_search_locations", None)
+ if search_locations is None:
+ locations_are_local = True
+ has_locations = False
+ else:
+ locations = tuple(search_locations)
+ has_locations = bool(locations)
+ locations_are_local = has_locations and all(
+ _path_is_within_candidate(location, candidate_root)
+ for location in locations
+ )
+ return (
+ concrete_is_local
+ and locations_are_local
+ and (bool(concrete_origins) or has_locations)
+ )
+
+
+def _relative_path_is_first_party(relative_path: Path) -> bool:
+ folded_parts = tuple(part.casefold() for part in relative_path.parts)
+ if not folded_parts:
+ return False
+ if folded_parts[0] in {"ares", "migrations"}:
+ return True
+ return (
+ len(folded_parts) >= 2
+ and folded_parts[:2] in {("tests", "unit"), ("tests", "integration")}
+ )
+
+
+def _frame_file_is_first_party(
+ module_file: object,
+ candidate_root: Path,
+) -> bool:
+ if not isinstance(module_file, (str, os.PathLike)):
+ return False
+ try:
+ resolved_file = Path(module_file).resolve()
+ except (OSError, RuntimeError, TypeError, ValueError):
+ return False
+ for root in (candidate_root, _REPO_ROOT):
+ try:
+ relative_path = resolved_file.relative_to(root.resolve())
+ except ValueError:
+ continue
+ if _relative_path_is_first_party(relative_path):
+ return True
+ folded_parts = tuple(part.casefold() for part in resolved_file.parts)
+ if len(folded_parts) >= 2 and folded_parts[-2:] == (
+ "migrations",
+ "env.py",
+ ):
+ return True
+ return (
+ len(folded_parts) >= 3
+ and folded_parts[-3:-1] == ("migrations", "versions")
+ and re.fullmatch(r"[0-9]{4}_[a-z0-9_]+\.py", folded_parts[-1])
+ is not None
+ )
+
+
+def _frame_is_first_party(
+ frame: types.FrameType,
+ candidate_root: Path,
+) -> bool:
+ globals_map = frame.f_globals
+ name = globals_map.get("__name__")
+ package = globals_map.get("__package__")
+ if isinstance(name, str) and _requires_candidate_origin(name):
+ return True
+ if isinstance(package, str) and _requires_candidate_origin(package):
+ return True
+ return _frame_file_is_first_party(
+ globals_map.get("__file__"),
+ candidate_root,
+ )
+
+
+class _CandidateOriginFinder:
+ def __init__(
+ self,
+ ledger: _CandidateOriginLedger,
+ delegates: tuple[object, ...],
+ ) -> None:
+ self._ledger = ledger
+ self._delegates = delegates
+
+ def find_spec(
+ self,
+ fullname: str,
+ path: object = None,
+ target: object = None,
+ ) -> object:
+ for finder in self._delegates:
+ find_spec = getattr(finder, "find_spec", None)
+ if find_spec is None:
+ continue
+ spec = find_spec(fullname, path, target)
+ if spec is not None:
+ self._ledger.observe_spec(fullname, spec)
+ return spec
+ return None
+
+
+@dataclass(slots=True, repr=False)
+class _CandidateOriginLedger:
+ candidate_root: Path
+ isolated: bool = False
+ violated: bool = False
+ _finder: _CandidateOriginFinder | None = field(
+ default=None,
+ init=False,
+ repr=False,
+ )
+ _previous_profile: object = field(default=None, init=False, repr=False)
+ _profile_callback: object = field(default=None, init=False, repr=False)
+ _previous_meta_path: tuple[object, ...] | None = field(
+ default=None,
+ init=False,
+ repr=False,
+ )
+ _observed_frame_origins: set[
+ tuple[
+ types.CodeType,
+ int,
+ str | None,
+ str | None,
+ str | None,
+ ]
+ ] = field(
+ default_factory=set,
+ init=False,
+ repr=False,
+ )
+
+ def observe_spec(self, name: str, spec: object) -> None:
+ if _requires_candidate_origin(name) and not (
+ _spec_origin_is_candidate_local(spec, self.candidate_root)
+ ):
+ self.violated = True
+
+ def observe_modules(self, modules: object) -> None:
+ if not _loaded_first_party_origins_are_candidate_local(
+ modules,
+ self.candidate_root,
+ ):
+ self.violated = True
+
+ def _profile(
+ self,
+ frame: types.FrameType,
+ event: str,
+ arg: object,
+ ) -> None:
+ if event == "call":
+ globals_map = frame.f_globals
+ raw_file = globals_map.get("__file__")
+ try:
+ normalized_file = (
+ os.fspath(raw_file)
+ if isinstance(raw_file, (str, os.PathLike))
+ else None
+ )
+ except TypeError:
+ normalized_file = None
+ raw_name = globals_map.get("__name__")
+ raw_package = globals_map.get("__package__")
+ observation = (
+ frame.f_code,
+ id(globals_map),
+ raw_name if isinstance(raw_name, str) else None,
+ raw_package if isinstance(raw_package, str) else None,
+ normalized_file,
+ )
+ if observation not in self._observed_frame_origins:
+ self._observed_frame_origins.add(observation)
+ if _frame_is_first_party(frame, self.candidate_root):
+ module_file = frame.f_globals.get("__file__")
+ if module_file is None or not _path_is_within_candidate(
+ module_file,
+ self.candidate_root,
+ ):
+ self.violated = True
+ previous = self._previous_profile
+ if not self.isolated and callable(previous):
+ previous(frame, event, arg)
+
+ def install(self) -> None:
+ self._previous_meta_path = tuple(sys.meta_path)
+ delegates = tuple(
+ finder
+ for finder in self._previous_meta_path
+ if not isinstance(finder, _CandidateOriginFinder)
+ )
+ self._finder = _CandidateOriginFinder(self, delegates)
+ sys.meta_path.insert(0, self._finder)
+ self._previous_profile = sys.getprofile()
+ self._profile_callback = self._profile
+ sys.setprofile(self._profile_callback)
+
+ def installed_exactly(self) -> bool:
+ return (
+ self._finder is not None
+ and bool(sys.meta_path)
+ and sys.meta_path[0] is self._finder
+ and sys.getprofile() is self._profile_callback
+ )
+
+ def close(self) -> None:
+ previous_meta_path = self._previous_meta_path
+ if previous_meta_path is not None:
+ sys.meta_path[:] = previous_meta_path
+ sys.setprofile(self._previous_profile)
+ self._finder = None
+ self._profile_callback = None
+ self._previous_profile = None
+ self._previous_meta_path = None
+ self._observed_frame_origins.clear()
+
+
+_ACTIVE_ORIGIN_LEDGERS: list[_CandidateOriginLedger] = []
+
+
+def _loaded_first_party_origins_are_candidate_local(
+ modules: object,
+ candidate_root: Path,
+) -> bool:
+ try:
+ loaded = tuple(modules.items())
+ except AttributeError:
+ return False
+ for name, module in loaded:
+ if not isinstance(name, str) or not _requires_candidate_origin(name):
+ continue
+ if module is None or not _module_origin_is_candidate_local(
+ module,
+ candidate_root,
+ ):
+ return False
+ return True
+
+
+def _assert_candidate_origin_boundary(
+ ledger: _CandidateOriginLedger | None = None,
+) -> None:
+ ledgers = (
+ (ledger,)
+ if ledger is not None
+ else tuple(_ACTIVE_ORIGIN_LEDGERS)
+ )
+ for active_ledger in ledgers:
+ active_ledger.observe_modules(sys.modules)
+ if not (
+ _path_is_within_candidate(__file__, _REPO_ROOT)
+ and all(
+ not active_ledger.violated
+ and active_ledger.installed_exactly()
+ for active_ledger in ledgers
+ )
+ and _loaded_first_party_origins_are_candidate_local(
+ sys.modules,
+ _REPO_ROOT,
+ )
+ ):
+ raise RuntimeError(
+ "first-party migration import escaped the source candidate"
+ )
+
+
+@contextmanager
+def _candidate_origin_boundary(
+ *,
+ isolated: bool = False,
+) -> Iterator[_CandidateOriginLedger]:
+ ledger = _CandidateOriginLedger(_REPO_ROOT, isolated=isolated)
+ ledger.install()
+ _ACTIVE_ORIGIN_LEDGERS.append(ledger)
+ try:
+ _assert_candidate_origin_boundary(ledger)
+ yield ledger
+ finally:
+ try:
+ _assert_candidate_origin_boundary(ledger)
+ finally:
+ for index in range(len(_ACTIVE_ORIGIN_LEDGERS) - 1, -1, -1):
+ if _ACTIVE_ORIGIN_LEDGERS[index] is ledger:
+ del _ACTIVE_ORIGIN_LEDGERS[index]
+ break
+ ledger.close()
+
+
[email protected](scope="module", autouse=True)
+def _final_candidate_origin_boundary() -> Iterator[None]:
+ with _candidate_origin_boundary():
+ yield
+
+
+def _postgres_config() -> _PostgresConfig:
+ present = [name for name in _POSTGRES_ENV if name in os.environ]
+ if not present:
+ pytest.skip("real PostgreSQL test environment is not configured")
+ if len(present) != len(_POSTGRES_ENV):
+ pytest.fail("Incomplete PostgreSQL test environment", pytrace=False)
+ values = {name: os.environ[name] for name in _POSTGRES_ENV}
+ if any(not value or value != value.strip() for value in values.values()):
+ pytest.fail("Invalid PostgreSQL test environment", pytrace=False)
+ raw_port = values["ARES_TEST_POSTGRES_PORT"]
+ if not raw_port.isascii() or not raw_port.isdecimal():
+ pytest.fail("PostgreSQL test port is invalid", pytrace=False)
+ try:
+ port = int(raw_port)
+ except ValueError:
+ pytest.fail("PostgreSQL test port is invalid", pytrace=False)
+ if str(port) != raw_port or not 1 <= port <= 65535:
+ pytest.fail(
+ "PostgreSQL test port is outside its valid range",
+ pytrace=False,
+ )
+ return _PostgresConfig(
+ host=values["ARES_TEST_POSTGRES_HOST"],
+ port=port,
+ user=values["ARES_TEST_POSTGRES_USER"],
+ maintenance_database=values["ARES_TEST_POSTGRES_DB"],
+ )
+
+
+def _child_postgres_config() -> _PostgresConfig:
+ present = [name for name in _POSTGRES_ENV if name in os.environ]
+ if len(present) != len(_POSTGRES_ENV):
+ raise RuntimeError("worker-postgres-config-error")
+ values = {name: os.environ[name] for name in _POSTGRES_ENV}
+ if any(not value or value != value.strip() for value in values.values()):
+ raise RuntimeError("worker-postgres-config-error")
+ raw_port = values["ARES_TEST_POSTGRES_PORT"]
+ if not raw_port.isascii() or not raw_port.isdecimal():
+ raise RuntimeError("worker-postgres-config-error")
+ try:
+ port = int(raw_port)
+ except ValueError:
+ raise RuntimeError("worker-postgres-config-error") from None
+ if str(port) != raw_port or not 1 <= port <= 65535:
+ raise RuntimeError("worker-postgres-config-error")
+ return _PostgresConfig(
+ host=values["ARES_TEST_POSTGRES_HOST"],
+ port=port,
+ user=values["ARES_TEST_POSTGRES_USER"],
+ maintenance_database=values["ARES_TEST_POSTGRES_DB"],
+ )
+
+
+def _migration_url(
+ config: _PostgresConfig,
+ database_name: str,
+ *,
+ ordinary_driver: bool = False,
+) -> str:
+ from sqlalchemy.engine import URL
+
+ driver = "postgresql" if ordinary_driver else "postgresql+asyncpg"
+ return URL.create(
+ driver,
+ username=config.user,
+ host=config.host,
+ port=config.port,
+ database=database_name,
+ ).render_as_string(hide_password=False)
+
+
+def _alembic_config(url: str) -> Any:
+ import argparse
+
+ from alembic.config import Config
+
+ config = Config(str(_REPO_ROOT / "alembic.ini"))
+ config.set_main_option(
+ "script_location",
+ str(_REPO_ROOT / "migrations"),
+ )
+ config.set_main_option(
+ "sqlalchemy.url",
+ os.environ.get("ARES_DATABASE_URL", "sqlite:///unused.db"),
+ )
+ config.cmd_opts = argparse.Namespace(x=[f"db_url={url}"])
+ return config
+
+
+def _redirect_child_output() -> None:
+ sink = os.open(os.devnull, os.O_WRONLY)
+ try:
+ os.dup2(sink, 1)
+ os.dup2(sink, 2)
+ finally:
+ os.close(sink)
+
+
+def _safe_exception_type(exc: Exception) -> str:
+ exception_type = type(exc).__name__
+ if _SAFE_EXCEPTION_TYPE.fullmatch(exception_type) is None:
+ return "Exception"
+ return exception_type
+
+
+def _worker_send(channel: Any, frame: tuple[str, ...]) -> None:
+ channel.send(frame)
+
+
+def _prepare_child_migration(
+ payload: dict[object, object],
+ command: Any,
+) -> tuple[Any, Any, str, str | None]:
+ allowed_keys = {
+ "mode",
+ "operation",
+ "revision",
+ "database_name",
+ "fault",
+ }
+ if set(payload) - allowed_keys:
+ raise RuntimeError("worker-payload-error")
+ postgres_config = _child_postgres_config()
+ database_name = payload.get("database_name")
+ if (
+ not isinstance(database_name, str)
+ or _SAFE_DATABASE_NAME.fullmatch(database_name) is None
+ ):
+ raise RuntimeError("worker-payload-error")
+ if database_name == postgres_config.maintenance_database:
+ raise RuntimeError("worker-payload-error")
+ migration_url = _migration_url(
+ postgres_config,
+ database_name,
+ ordinary_driver=True,
+ )
+ config = _alembic_config(migration_url)
+ operation = payload.get("operation")
+ revision = payload.get("revision")
+ fault = payload.get("fault")
+ if (
+ operation not in {"upgrade", "downgrade"}
+ or not isinstance(revision, str)
+ or not revision
+ or fault
+ not in {
+ None,
+ "0005-before-alter",
+ "0005-after-alter",
+ "0006-after-rename",
+ }
+ ):
+ raise RuntimeError("worker-payload-error")
+ action = (
+ command.upgrade if operation == "upgrade" else command.downgrade
+ )
+ return config, action, revision, fault
+
+
+def _prepared_child_target_is_authoritative(
+ config: object,
+ database_name: str,
+) -> bool:
+ from sqlalchemy.engine import make_url
+
+ command_options = getattr(config, "cmd_opts", None)
+ arguments = getattr(command_options, "x", None)
+ if not isinstance(arguments, list) or len(arguments) != 1:
+ return False
+ key, separator, raw_url = arguments[0].partition("=")
+ if key != "db_url" or separator != "=" or not raw_url:
+ return False
+ try:
+ parsed = make_url(raw_url)
+ except Exception:
+ return False
+ expected = _child_postgres_config()
+ return (
+ parsed.drivername == "postgresql"
+ and parsed.host == expected.host
+ and parsed.port == expected.port
+ and parsed.username == expected.user
+ and parsed.password is None
+ and parsed.database == database_name
+ and not parsed.query
+ )
+
+
+def _worker_import_then_remove_external_probe() -> None:
+ from tempfile import TemporaryDirectory
+
+ parent = importlib.import_module("ares")
+ package_path = getattr(parent, "__path__", None)
+ if package_path is None:
+ raise RuntimeError("worker-origin-probe-error")
+ original_locations = tuple(package_path)
+ name = "ares.worker_removed_origin_probe"
+ child_name = "worker_removed_origin_probe"
+ with TemporaryDirectory(prefix="ares-worker-origin-") as directory:
+ external_package = Path(directory) / "ares"
+ external_package.mkdir()
+ (external_package / f"{child_name}.py").write_text(
+ "def marker():\n return True\n",
+ encoding="utf-8",
+ )
+ package_path.append(str(external_package))
+ importlib.invalidate_caches()
+ try:
+ imported = importlib.import_module(name)
+ marker = getattr(imported, "marker", None)
+ if not callable(marker) or marker() is not True:
+ raise RuntimeError("worker-origin-probe-error")
+ finally:
+ sys.modules.pop(name, None)
+ if hasattr(parent, child_name):
+ delattr(parent, child_name)
+ package_path[:] = original_locations
+ importlib.invalidate_caches()
+
+
+def _alembic_worker_entry(channel: Any) -> None:
+ """Execute one operation after establishing a secret-free IPC boundary."""
+ _redirect_child_output()
+ exit_code = 0
+ try:
+ emit_success = False
+ with _candidate_origin_boundary():
+ forbidden_preloads = (
+ "alembic",
+ "sqlalchemy",
+ "asyncpg",
+ )
+ if any(
+ name == prefix or name.startswith(f"{prefix}.")
+ for name in sys.modules
+ for prefix in forbidden_preloads
+ ):
+ raise RuntimeError("worker-import-boundary-error")
+ from alembic import command
+
+ initial = channel.recv()
+ if (
+ not isinstance(initial, tuple)
+ or len(initial) != 2
+ or initial[0] != "PAYLOAD"
+ or not isinstance(initial[1], dict)
+ ):
+ raise RuntimeError("worker-payload-error")
+ payload = initial[1]
+ mode = payload.get("mode")
+
+ if mode == "protocol-ok-before-ready":
+ _worker_send(channel, ("OK",))
+ return
+ if mode == "setup-error":
+ raise RuntimeError("worker-setup-error")
+
+ if mode in {
+ "migrate",
+ "ipc-prepare-success",
+ "ipc-prepare-error",
+ }:
+ config, action, revision, fault = _prepare_child_migration(
+ payload,
+ command,
+ )
+ database_name = payload.get("database_name")
+ if not isinstance(database_name, str) or not (
+ _prepared_child_target_is_authoritative(
+ config,
+ database_name,
+ )
+ ):
+ raise RuntimeError("worker-target-error")
+ if mode == "migrate" and fault is not None:
+ from alembic.operations import Operations
+
+ original_alter = Operations.alter_column
+
+ def _failing_alter(
+ operations: Operations,
+ table_name: str,
+ column_name: str,
+ *args: object,
+ **kwargs: object,
+ ) -> object:
+ is_trace = (
+ table_name == "findings"
+ and column_name == "trace_id"
+ )
+ is_credential = (
+ table_name == "credentials"
+ and column_name
+ in {"cracked_value", "cracked_value_enc"}
+ )
+ if fault == "0005-before-alter" and is_trace:
+ raise RuntimeError("worker-test-error")
+ result = original_alter(
+ operations,
+ table_name,
+ column_name,
+ *args,
+ **kwargs,
+ )
+ if (
+ fault == "0005-after-alter"
+ and is_trace
+ ) or (
+ fault == "0006-after-rename"
+ and is_credential
+ ):
+ raise RuntimeError("worker-test-error")
+ return result
+
+ Operations.alter_column = _failing_alter
+ elif mode in {
+ "success",
+ "success-dirty-origin",
+ "success-dirty-origin-removed",
+ "migration-error",
+ "block",
+ "protocol-duplicate-ready",
+ "protocol-duplicate-ok",
+ "protocol-malformed",
+ "protocol-eof-before-terminal",
+ "protocol-success-crash",
+ "protocol-zero-without-success",
+ }:
+ revision = ""
+ config = None
+ action = None
+ else:
+ raise RuntimeError("worker-mode-error")
+
+ _worker_send(channel, ("READY",))
+ if mode == "protocol-duplicate-ready":
+ _worker_send(channel, ("READY",))
+ go = channel.recv()
+ if go != ("GO",):
+ raise RuntimeError("worker-go-error")
+
+ if mode == "block":
+ threading.Event().wait()
+ if mode in {"migration-error", "ipc-prepare-error"}:
+ raise RuntimeError("worker-test-error")
+ if mode == "protocol-malformed":
+ _worker_send(channel, ("UNKNOWN",))
+ return
+ if mode in {
+ "protocol-eof-before-terminal",
+ "protocol-zero-without-success",
+ }:
+ return
+ if mode == "protocol-duplicate-ok":
+ _worker_send(channel, ("OK",))
+ _worker_send(channel, ("OK",))
+ return
+ if mode == "protocol-success-crash":
+ _worker_send(channel, ("OK",))
+ raise SystemExit(71)
+ if mode == "success-dirty-origin":
+ dirty_module = types.ModuleType("ares.worker_dirty_probe")
+ dirty_origin = _REPO_ROOT.parent / "worker_dirty_probe.py"
+ dirty_module.__file__ = str(dirty_origin)
+ dirty_module.__spec__ = importlib.machinery.ModuleSpec(
+ "ares.worker_dirty_probe",
+ loader=None,
+ origin=str(dirty_origin),
+ )
+ sys.modules["ares.worker_dirty_probe"] = dirty_module
+ if mode == "success-dirty-origin-removed":
+ _worker_import_then_remove_external_probe()
+ if mode == "migrate":
+ action(config, revision)
+ emit_success = True
+ if emit_success:
+ _worker_send(channel, ("OK",))
+ except Exception as exc:
+ exit_code = 70
+ try:
+ _worker_send(channel, ("ERROR", _safe_exception_type(exc)))
+ except (BrokenPipeError, EOFError, OSError):
+ pass
+ finally:
+ channel.close()
+ if exit_code:
+ raise SystemExit(exit_code)
+
+
+async def _wait_for_process_exit(process: Any, timeout: float) -> bool:
+ deadline = time.monotonic() + timeout
+ while process.is_alive() and time.monotonic() < deadline:
+ process.join(timeout=0)
+ await asyncio.sleep(_WORKER_POLL_SECONDS)
+ process.join(timeout=0)
+ return not process.is_alive() and process.exitcode is not None
+
+
+def _add_fixed_cleanup_note(
+ primary: Exception,
+ action: str,
+ cleanup_error: Exception,
+) -> None:
+ primary.add_note(
+ f"Alembic worker cleanup failed [{action}: "
+ f"{type(cleanup_error).__name__}]"
+ )
+
+
+def _close_unowned_endpoint(
+ endpoint: Any,
+ action: str,
+ primary: Exception,
+) -> None:
+ if endpoint is None:
+ return
+ try:
+ endpoint.close()
+ except Exception as cleanup_error:
+ _add_fixed_cleanup_note(primary, action, cleanup_error)
+
+
+def _process_may_have_started(process: Any) -> bool:
+ try:
+ if process.pid is not None:
+ return True
+ except Exception:
+ return True
+ try:
+ return bool(process.is_alive())
+ except Exception:
+ return True
+
+
+def _close_settled_worker_resources(worker: _OwnedWorker) -> None:
+ failures: list[tuple[str, Exception]] = []
+ if not worker.parent_closed:
+ try:
+ worker.channel.close()
+ worker.parent_closed = True
+ except Exception as exc:
+ failures.append(("close-parent-endpoint", exc))
+ if worker.child_channel is not None and not worker.child_closed:
+ try:
+ worker.child_channel.close()
+ worker.child_closed = True
+ except Exception as exc:
+ failures.append(("close-child-endpoint", exc))
+ if not worker.process_closed:
+ try:
+ worker.process.close()
+ worker.process_closed = True
+ except Exception as exc:
+ failures.append(("close-process", exc))
+ if failures:
+ error = RuntimeError("Alembic worker resource closure failed")
+ for action, failure in failures:
+ _add_fixed_cleanup_note(error, action, failure)
+ raise error from None
+ worker.closed = True
+ _OWNED_WORKERS.discard(worker)
+
+
+async def _settle_worker(
+ worker: _OwnedWorker,
+ *,
+ terminate: bool,
+) -> int:
+ if worker.closed:
+ raise RuntimeError("Alembic worker ownership was already closed")
+ if worker.death_proven:
+ exit_code = (
+ -1
+ if worker.settled_exit_code is None
+ else worker.settled_exit_code
+ )
+ _close_settled_worker_resources(worker)
+ return exit_code
+ process = worker.process
+ try:
+ process_id = process.pid
+ except Exception:
+ process_id = None
+ worker.may_have_started = True
+ if process_id is None:
+ if worker.may_have_started:
+ raise RuntimeError("Alembic worker death was not proven")
+ worker.death_proven = True
+ worker.settled_exit_code = -1
+ _close_settled_worker_resources(worker)
+ return -1
+
+ if terminate and process.is_alive():
+ process.terminate()
+ settled = await _wait_for_process_exit(
+ process,
+ _WORKER_SETTLE_SECONDS,
+ )
+ if not settled and terminate:
+ process.kill()
+ settled = await _wait_for_process_exit(
+ process,
+ _WORKER_SETTLE_SECONDS,
+ )
+ if not settled:
+ raise RuntimeError("Alembic worker death was not proven")
+
+ exit_code = int(process.exitcode)
+ worker.death_proven = True
+ worker.settled_exit_code = exit_code
+ process.join(timeout=0)
+ _close_settled_worker_resources(worker)
+ return exit_code
+
+
+async def _receive_worker_frame(
+ worker: _OwnedWorker,
+ *,
+ deadline: float,
+) -> tuple[str, ...] | None:
+ while time.monotonic() < deadline:
+ try:
+ has_frame = worker.channel.poll()
+ except (BrokenPipeError, EOFError, OSError):
+ worker.eof = True
+ return None
+ if has_frame:
+ try:
+ frame = worker.channel.recv()
+ except (BrokenPipeError, EOFError, OSError):
+ worker.eof = True
+ return None
+ if not isinstance(frame, tuple) or not all(
+ isinstance(item, str) for item in frame
+ ):
+ raise RuntimeError("Alembic worker failed [ProtocolError]")
+ return frame
+ if not worker.process.is_alive():
+ await asyncio.sleep(0)
+ try:
+ has_frame = worker.channel.poll()
+ except (BrokenPipeError, EOFError, OSError):
+ worker.eof = True
+ return None
+ if has_frame:
+ continue
+ try:
+ worker.channel.recv()
+ except (BrokenPipeError, EOFError, OSError):
+ worker.eof = True
+ return None
+ raise RuntimeError("Alembic worker failed [ProtocolError]")
+ await asyncio.sleep(_WORKER_POLL_SECONDS)
+ raise TimeoutError
+
+
+async def _run_worker(
+ payload: dict[str, str],
+ *,
+ timeout: float,
+ started: asyncio.Event | None = None,
+) -> None:
+ parent_channel = None
+ child_channel = None
+ process = None
+ pipe_resources: tuple[Any, ...] = ()
+ try:
+ context = multiprocessing.get_context("spawn")
+ pipe_result = context.Pipe(duplex=True)
+ if isinstance(pipe_result, (tuple, list)):
+ pipe_resources = tuple(pipe_result)
+ if len(pipe_resources) != 2:
+ raise RuntimeError("worker-pipe-construction-error")
+ parent_channel, child_channel = pipe_resources
+ except Exception as exc:
+ primary = RuntimeError(
+ f"Alembic worker startup failed [{type(exc).__name__}]"
+ )
+ for index, endpoint in enumerate(pipe_resources):
+ _close_unowned_endpoint(
+ endpoint,
+ f"close-pipe-endpoint-{index}",
+ primary,
+ )
+ raise primary from None
+ try:
+ process = context.Process(
+ target=_alembic_worker_entry,
+ args=(child_channel,),
+ name="ares-alembic-worker",
+ )
+ except Exception as exc:
+ primary = RuntimeError(
+ f"Alembic worker startup failed [{type(exc).__name__}]"
+ )
+ _close_unowned_endpoint(
+ parent_channel,
+ "close-parent-endpoint",
+ primary,
+ )
+ _close_unowned_endpoint(
+ child_channel,
+ "close-child-endpoint",
+ primary,
+ )
+ raise primary from None
+
+ worker = _OwnedWorker(
+ process=process,
+ channel=parent_channel,
+ child_channel=child_channel,
+ )
+ _OWNED_WORKERS.add(worker)
+ try:
+ worker.start_attempted = True
+ process.start()
+ worker.may_have_started = True
+ child_channel.close()
+ worker.child_closed = True
+ parent_channel.send(("PAYLOAD", payload))
+ except Exception as exc:
+ worker.may_have_started = (
+ worker.may_have_started or _process_may_have_started(process)
+ )
+ primary = RuntimeError(
+ f"Alembic worker startup failed [{type(exc).__name__}]"
+ )
+ try:
+ await asyncio.shield(
+ _settle_worker(worker, terminate=True)
+ )
+ except Exception as cleanup_error:
+ _add_fixed_cleanup_note(
+ primary,
+ "settle-startup-worker",
+ cleanup_error,
+ )
+ raise primary from None
+
+ protocol_failure = False
+ terminal: tuple[str, ...] | None = None
+ try:
+ ready_deadline = time.monotonic() + _WORKER_SETTLE_SECONDS
+ ready = await _receive_worker_frame(
+ worker,
+ deadline=ready_deadline,
+ )
+ if ready != ("READY",):
+ setup_error = (
+ ready is not None
+ and len(ready) == 2
+ and ready[0] == "ERROR"
+ and _SAFE_EXCEPTION_TYPE.fullmatch(ready[1]) is not None
+ )
+ if setup_error:
+ after_setup_error = await _receive_worker_frame(
+ worker,
+ deadline=time.monotonic() + _WORKER_SETTLE_SECONDS,
+ )
+ exit_code = await _settle_worker(
+ worker,
+ terminate=False,
+ )
+ if after_setup_error is None and exit_code == 70:
+ raise RuntimeError(
+ f"Alembic worker failed [{ready[1]}]"
+ ) from None
+ raise RuntimeError("Alembic worker failed [ProtocolError]")
+ if started is not None:
+ started.set()
+ parent_channel.send(("GO",))
+
+ terminal_deadline = time.monotonic() + timeout
+ terminal = await _receive_worker_frame(
+ worker,
+ deadline=terminal_deadline,
+ )
+ if terminal is None or (
+ terminal != ("OK",)
+ and not (
+ len(terminal) == 2
+ and terminal[0] == "ERROR"
+ and _SAFE_EXCEPTION_TYPE.fullmatch(terminal[1]) is not None
+ )
+ ):
+ raise RuntimeError("Alembic worker failed [ProtocolError]")
+
+ after_terminal = await _receive_worker_frame(
+ worker,
+ deadline=time.monotonic() + _WORKER_SETTLE_SECONDS,
+ )
+ if after_terminal is not None:
+ raise RuntimeError("Alembic worker failed [ProtocolError]")
+ exit_code = await _settle_worker(worker, terminate=False)
+ if terminal == ("OK",) and exit_code == 0:
+ return
+ if terminal[0] == "ERROR" and exit_code == 70:
+ raise RuntimeError(
+ f"Alembic worker failed [{terminal[1]}]"
+ ) from None
+ raise RuntimeError("Alembic worker failed [ProtocolError]")
+ except TimeoutError:
+ protocol_failure = True
+ raise RuntimeError("Alembic worker timed out") from None
+ except asyncio.CancelledError:
+ protocol_failure = True
+ raise
+ except RuntimeError:
+ protocol_failure = True
+ raise
+ finally:
+ if worker in _OWNED_WORKERS:
+ try:
+ await asyncio.shield(
+ _settle_worker(worker, terminate=protocol_failure)
+ )
+ except RuntimeError:
+ raise RuntimeError(
+ "Alembic worker settlement failed"
+ ) from None
+
+
+async def _alembic(
+ harness: _MigrationHarness,
+ operation: str,
+ revision: str,
+ *,
+ fault: str | None = None,
+) -> None:
+ if operation not in {"upgrade", "downgrade"}:
+ raise AssertionError("unknown migration operation")
+ payload = {
+ "mode": "migrate",
+ "database_name": harness.database_name,
+ "operation": operation,
+ "revision": revision,
+ }
+ if fault is not None:
+ payload["fault"] = fault
+ await _run_worker(
+ payload,
+ timeout=_WORKER_TIMEOUT_SECONDS,
+ )
+
+
+def _sanitized_setup_failure(action: str, exc: Exception) -> RuntimeError:
+ return RuntimeError(
+ f"PostgreSQL migration setup failed [{action}: {type(exc).__name__}]"
+ )
+
+
+async def _attempt_cleanup(
+ action: str,
+ cleanup: Callable[[], Awaitable[object]],
+ failures: list[str],
+) -> None:
+ try:
+ await asyncio.wait_for(
+ cleanup(),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+ except Exception as exc:
+ failures.append(f"{action}: {type(exc).__name__}")
+
+
+async def _settle_owned_workers_for_cleanup(
+ failures: list[str],
+) -> bool:
+ for worker in tuple(_OWNED_WORKERS):
+ try:
+ await _settle_worker(worker, terminate=True)
+ except Exception as exc:
+ failures.append(
+ f"settle-alembic-worker: {type(exc).__name__}"
+ )
+ return not _OWNED_WORKERS
+
+
+@asynccontextmanager
+async def _postgres_harness(
+) -> AsyncIterator[_MigrationHarness]:
+ config = _postgres_config()
+ try:
+ import asyncpg
+ except ImportError:
+ pytest.fail(
+ "asyncpg is required for configured PostgreSQL tests",
+ pytrace=False,
+ )
+
+ database_name = f"ares_migration_{uuid4().hex}"
+ _require_fixed(
+ _SAFE_DATABASE_NAME.fullmatch(database_name) is not None,
+ "generated PostgreSQL database identifier was unsafe",
+ )
+ _require_fixed(
+ database_name != config.maintenance_database,
+ "generated PostgreSQL database identifier collided",
+ )
+
+ admin = None
+ creation_attempted = False
+ cleanup_failures: list[str] = []
+ try:
+ try:
+ admin = await asyncio.wait_for(
+ asyncpg.connect(
+ host=config.host,
+ port=config.port,
+ user=config.user,
+ database=config.maintenance_database,
+ ),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+ except Exception as exc:
+ raise _sanitized_setup_failure("admin-connect", exc) from None
+
+ creation_attempted = True
+ try:
+ await asyncio.wait_for(
+ admin.execute(f'CREATE DATABASE "{database_name}"'),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+ except Exception as exc:
+ raise _sanitized_setup_failure("database-create", exc) from None
+
+ yield _MigrationHarness(
+ config=config,
+ database_name=database_name,
+ )
+ finally:
+ primary_failure = sys.exception()
+ workers_settled = await _settle_owned_workers_for_cleanup(
+ cleanup_failures
+ )
+ if creation_attempted and admin is not None and workers_settled:
+
+ async def _drop_database() -> None:
+ await asyncio.wait_for(
+ admin.execute(
+ """
+ SELECT pg_terminate_backend(pid)
+ FROM pg_stat_activity
+ WHERE datname=$1 AND pid <> pg_backend_pid()
+ """,
+ database_name,
+ ),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+ await asyncio.wait_for(
+ admin.execute(
+ f'DROP DATABASE IF EXISTS "{database_name}" '
+ "WITH (FORCE)"
+ ),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ await _attempt_cleanup(
+ "drop-test-database",
+ _drop_database,
+ cleanup_failures,
+ )
+ elif creation_attempted and not workers_settled:
+ cleanup_failures.append("drop-test-database: WorkerOwnershipError")
+ if admin is not None:
+ await _attempt_cleanup(
+ "close-admin-connection",
+ admin.close,
+ cleanup_failures,
+ )
+ if cleanup_failures:
+ if primary_failure is not None:
+ for failure in cleanup_failures:
+ primary_failure.add_note(
+ f"PostgreSQL migration cleanup failure [{failure}]"
+ )
+ else:
+ raise RuntimeError(
+ "PostgreSQL migration cleanup failed: "
+ + "; ".join(cleanup_failures)
+ ) from None
+
+
+async def _connect(harness: _MigrationHarness) -> Any:
+ try:
+ import asyncpg
+ except ImportError:
+ pytest.fail(
+ "asyncpg is required for configured PostgreSQL tests",
+ pytrace=False,
+ )
+ try:
+ connection = await asyncio.wait_for(
+ asyncpg.connect(
+ host=harness.config.host,
+ port=harness.config.port,
+ user=harness.config.user,
+ database=harness.database_name,
+ ),
+ timeout=_POSTGRES_OPERATION_TIMEOUT_SECONDS,
+ )
+ return _BoundedConnection(connection)
+ except Exception as exc:
+ raise _sanitized_setup_failure("catalog-connect", exc) from None
+
+
+async def _postgres_integrity_failure(
+ connection: Any,
+ statement: str,
+ *parameters: object,
+ expected_type: str,
+) -> bool:
+ rejected = False
+ try:
+ await connection.execute(statement, *parameters)
+ except Exception as exc:
+ rejected = type(exc).__name__ == expected_type
+ reusable = await connection.fetchval("SELECT 1") == 1
+ return rejected and reusable
+
+
+async def _seed_postgres_contract(connection: Any) -> None:
+ await connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES($1, $2)",
+ "campaign-contract",
+ "Synthetic campaign",
+ )
+ await connection.execute(
+ """
+ INSERT INTO module_runs(id, campaign_id, module_id, outcome)
+ VALUES($1, $2, $3, $4)
+ """,
+ "run-contract",
+ "campaign-contract",
+ "module",
+ "complete",
+ )
+ await connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title, description, severity
+ ) VALUES($1, $2, $3, $4, $5, $6)
+ """,
+ "finding-contract",
+ "campaign-contract",
+ "module",
+ "Synthetic finding",
+ "Synthetic description",
+ "low",
+ )
+ await connection.execute(
+ """
+ INSERT INTO hosts(id, campaign_id, ip_address)
+ VALUES($1, $2, $3)
+ """,
+ "host-contract",
+ "campaign-contract",
+ "192.0.2.10",
+ )
+ await connection.execute(
+ """
+ INSERT INTO credentials(
+ id, campaign_id, host_id, username, cred_type
+ ) VALUES($1, $2, $3, $4, $5)
+ """,
+ "credential-contract",
+ "campaign-contract",
+ "host-contract",
+ "synthetic-user",
+ "password",
+ )
+ await connection.execute(
+ """
+ INSERT INTO loot(id, campaign_id, host_id, loot_type, name)
+ VALUES($1, $2, $3, $4, $5)
+ """,
+ "loot-contract",
+ "campaign-contract",
+ "host-contract",
+ "metadata",
+ "Synthetic loot",
+ )
+ await connection.execute(
+ "INSERT INTO audit_log(campaign_id, action) VALUES($1, $2)",
+ "campaign-contract",
+ "synthetic-action",
+ )
+ await connection.execute(
+ """
+ INSERT INTO users(id, username, hashed_password)
+ VALUES($1, $2, $3)
+ """,
+ "user-contract",
+ "synthetic-account",
+ "synthetic-hash",
+ )
+ await connection.execute(
+ """
+ INSERT INTO api_keys(id, user_id, name, key_hash, key_prefix)
+ VALUES($1, $2, $3, $4, $5)
+ """,
+ "api-key-contract",
+ "user-contract",
+ "Synthetic key",
+ "synthetic-hash",
+ "synthetic",
+ )
+ await connection.execute(
+ """
+ INSERT INTO refresh_tokens(id, user_id, expires_at)
+ VALUES($1, $2, $3)
+ """,
+ "refresh-contract",
+ "user-contract",
+ datetime(2099, 1, 1, tzinfo=timezone.utc),
+ )
+ await connection.execute(
+ """
+ INSERT INTO revoked_access_tokens(jti, user_id, expires_at)
+ VALUES($1, $2, $3)
+ """,
+ "revoked-contract",
+ "user-contract",
+ datetime(2099, 1, 1, tzinfo=timezone.utc),
+ )
+ await connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES($1, $2)
+ """,
+ "192.0.2.20",
+ "synthetic-bucket",
+ )
+
+
+async def _postgres_isolation_fingerprint(
+ connection: Any,
+) -> _PostgresIsolationFingerprint:
+ try:
+ schemas = tuple(
+ str(row["schema_name"])
+ for row in await connection.fetch(
+ """
+ SELECT nspname AS schema_name
+ FROM pg_namespace
+ WHERE nspname !~ '^pg_'
+ AND nspname <> 'information_schema'
+ ORDER BY nspname
+ """
+ )
+ )
+ relations = tuple(
+ tuple(row.values())
+ for row in await connection.fetch(
+ """
+ SELECT
+ namespace.nspname AS schema_name,
+ relation.relname AS relation_name,
+ relation.relkind AS relation_kind,
+ relation.relpersistence AS persistence
+ FROM pg_class AS relation
+ JOIN pg_namespace AS namespace
+ ON namespace.oid=relation.relnamespace
+ WHERE namespace.nspname !~ '^pg_'
+ AND namespace.nspname <> 'information_schema'
+ ORDER BY
+ namespace.nspname,
+ relation.relname,
+ relation.relkind
+ """
+ )
+ )
+ columns = tuple(
+ tuple(row.values())
+ for row in await connection.fetch(
+ """
+ SELECT
+ namespace.nspname AS schema_name,
+ relation.relname AS relation_name,
+ attribute.attnum AS ordinal_position,
+ attribute.attname AS column_name,
+ format_type(
+ attribute.atttypid,
+ attribute.atttypmod
+ ) AS formatted_type,
+ attribute.attnotnull AS not_null,
+ pg_get_expr(
+ default_value.adbin,
+ default_value.adrelid
+ ) AS default_expression,
+ attribute.attidentity AS identity_kind,
+ attribute.attgenerated AS generated_kind
+ FROM pg_attribute AS attribute
+ JOIN pg_class AS relation
+ ON relation.oid=attribute.attrelid
+ JOIN pg_namespace AS namespace
+ ON namespace.oid=relation.relnamespace
+ LEFT JOIN pg_attrdef AS default_value
+ ON default_value.adrelid=attribute.attrelid
+ AND default_value.adnum=attribute.attnum
+ WHERE namespace.nspname !~ '^pg_'
+ AND namespace.nspname <> 'information_schema'
+ AND attribute.attnum > 0
+ AND NOT attribute.attisdropped
+ ORDER BY
+ namespace.nspname,
+ relation.relname,
+ attribute.attnum
+ """
+ )
+ )
+ constraints = tuple(
+ tuple(row.values())
+ for row in await connection.fetch(
+ """
+ SELECT
+ namespace.nspname AS schema_name,
+ relation.relname AS relation_name,
+ constraint_value.conname AS constraint_name,
+ constraint_value.contype AS constraint_type,
+ pg_get_constraintdef(
+ constraint_value.oid,
+ true
+ ) AS definition
+ FROM pg_constraint AS constraint_value
+ JOIN pg_class AS relation
+ ON relation.oid=constraint_value.conrelid
+ JOIN pg_namespace AS namespace
+ ON namespace.oid=relation.relnamespace
+ WHERE namespace.nspname !~ '^pg_'
+ AND namespace.nspname <> 'information_schema'
+ ORDER BY
+ namespace.nspname,
+ relation.relname,
+ constraint_value.conname
+ """
+ )
+ )
+ indexes = tuple(
+ tuple(row.values())
+ for row in await connection.fetch(
+ """
+ SELECT
+ namespace.nspname AS schema_name,
+ table_relation.relname AS relation_name,
+ index_relation.relname AS index_name,
+ index_value.indisunique AS is_unique,
+ index_value.indisprimary AS is_primary,
+ pg_get_indexdef(index_relation.oid) AS definition
+ FROM pg_index AS index_value
+ JOIN pg_class AS table_relation
+ ON table_relation.oid=index_value.indrelid
+ JOIN pg_class AS index_relation
+ ON index_relation.oid=index_value.indexrelid
+ JOIN pg_namespace AS namespace
+ ON namespace.oid=table_relation.relnamespace
+ WHERE namespace.nspname !~ '^pg_'
+ AND namespace.nspname <> 'information_schema'
+ ORDER BY
+ namespace.nspname,
+ table_relation.relname,
+ index_relation.relname
+ """
+ )
+ )
+ sequences = tuple(
+ tuple(row.values())
+ for row in await connection.fetch(
+ """
+ SELECT
+ namespace.nspname AS schema_name,
+ relation.relname AS sequence_name,
+ format_type(
+ sequence_value.seqtypid,
+ NULL
+ ) AS data_type,
+ sequence_value.seqstart AS start_value,
+ sequence_value.seqmin AS minimum_value,
+ sequence_value.seqmax AS maximum_value,
+ sequence_value.seqincrement AS increment_value,
+ sequence_value.seqcycle AS cycles,
+ sequence_value.seqcache AS cache_size
+ FROM pg_sequence AS sequence_value
+ JOIN pg_class AS relation
+ ON relation.oid=sequence_value.seqrelid
+ JOIN pg_namespace AS namespace
+ ON namespace.oid=relation.relnamespace
+ WHERE namespace.nspname !~ '^pg_'
+ AND namespace.nspname <> 'information_schema'
+ ORDER BY namespace.nspname, relation.relname
+ """
+ )
+ )
+ version_rows = tuple(
+ (
+ str(row["schema_name"]),
+ str(row["version_state"]),
+ )
+ for row in await connection.fetch(
+ """
+ SELECT
+ namespace.nspname AS schema_name,
+ table_to_xml(
+ relation.oid::regclass,
+ true,
+ false,
+ ''
+ )::text AS version_state
+ FROM pg_class AS relation
+ JOIN pg_namespace AS namespace
+ ON namespace.oid=relation.relnamespace
+ WHERE namespace.nspname !~ '^pg_'
+ AND namespace.nspname <> 'information_schema'
+ AND relation.relkind IN ('r', 'p')
+ AND relation.relname='alembic_version'
+ ORDER BY namespace.nspname
+ """
+ )
+ )
+ return _PostgresIsolationFingerprint(
+ schemas=schemas,
+ relations=relations,
+ columns=columns,
+ constraints=constraints,
+ indexes=indexes,
+ sequences=sequences,
+ versions=version_rows,
+ )
+ except Exception as exc:
+ raise _sanitized_setup_failure(
+ "isolation-fingerprint",
+ exc,
+ ) from None
+
+
+def _isolation_fingerprint_has_no_ares_state(
+ fingerprint: _PostgresIsolationFingerprint,
+) -> bool:
+ forbidden_relations = _EXPECTED_TABLES | {"alembic_version"}
+ return (
+ not fingerprint.versions
+ and all(
+ str(relation[1]) not in forbidden_relations
+ for relation in fingerprint.relations
+ )
+ )
+
+
+async def _database_fingerprint(
+ config: _PostgresConfig,
+ database_name: str,
+) -> _PostgresIsolationFingerprint:
+ harness = _MigrationHarness(
+ config=config,
+ database_name=database_name,
+ )
+ connection = await _connect(harness)
+ try:
+ return await _postgres_isolation_fingerprint(connection)
+ finally:
+ primary = sys.exception()
+ try:
+ await connection.close()
+ except Exception as cleanup_error:
+ if primary is not None:
+ primary.add_note(
+ "PostgreSQL migration fingerprint cleanup failed "
+ f"[{type(cleanup_error).__name__}]"
+ )
+ else:
+ raise _sanitized_setup_failure(
+ "fingerprint-close",
+ cleanup_error,
+ ) from None
+
+
+async def _database_revision(
+ config: _PostgresConfig,
+ database_name: str,
+) -> str | None:
+ harness = _MigrationHarness(
+ config=config,
+ database_name=database_name,
+ )
+ connection = await _connect(harness)
+ try:
+ return await _version(connection)
+ finally:
+ primary = sys.exception()
+ try:
+ await connection.close()
+ except Exception as cleanup_error:
+ if primary is not None:
+ primary.add_note(
+ "PostgreSQL migration revision cleanup failed "
+ f"[{type(cleanup_error).__name__}]"
+ )
+ else:
+ raise _sanitized_setup_failure(
+ "revision-close",
+ cleanup_error,
+ ) from None
+
+
+async def _version(connection: Any) -> str | None:
+ exists = await connection.fetchval(
+ "SELECT to_regclass('alembic_version') IS NOT NULL"
+ )
+ if not exists:
+ return None
+ value = await connection.fetchval(
+ "SELECT version_num FROM alembic_version"
+ )
+ return None if value is None else str(value)
+
+
+def _normalize_postgres_expression(value: str) -> str:
+ normalized = value.lower().replace('"', "")
+ normalized = re.sub(r"\s+", "", normalized)
+ while normalized.startswith("(") and normalized.endswith(")"):
+ normalized = normalized[1:-1]
+ if normalized.startswith("check(") and normalized.endswith(")"):
+ normalized = normalized[6:-1]
+ return normalized.replace("(", "").replace(")", "")
+
+
+def _postgres_default_kind(value: object) -> str | None:
+ if value is None:
+ return None
+ normalized = str(value).strip()
+ lowered = normalized.lower()
+ if lowered.startswith("nextval("):
+ return "sequence"
+ if "now()" in lowered:
+ return "now"
+ while normalized.startswith("(") and normalized.endswith(")"):
+ normalized = normalized[1:-1].strip()
+ cast_position = normalized.rfind("::")
+ if cast_position >= 0:
+ normalized = normalized[:cast_position]
+ normalized = normalized.strip()
+ if len(normalized) >= 2 and normalized[0] == normalized[-1] == "'":
+ normalized = normalized[1:-1].replace("''", "'")
+ return f"literal:{normalized}"
+
+
+async def _postgres_catalog_contract(
+ connection: Any,
+) -> _PostgresCatalogContract:
+ tables = tuple(
+ str(row["table_name"])
+ for row in await connection.fetch(
+ """
+ SELECT table_name
+ FROM information_schema.tables
+ WHERE table_schema=current_schema()
+ AND table_type='BASE TABLE'
+ AND table_name <> 'alembic_version'
+ ORDER BY table_name
+ """
+ )
+ )
+ columns = tuple(
+ (
+ str(row["table_name"]),
+ str(row["column_name"]),
+ str(row["data_type"]),
+ str(row["is_nullable"]) == "YES",
+ _postgres_default_kind(row["column_default"]),
+ )
+ for row in await connection.fetch(
+ """
+ SELECT
+ table_name,
+ ordinal_position,
+ column_name,
+ data_type,
+ is_nullable,
+ column_default
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND table_name <> 'alembic_version'
+ ORDER BY table_name, ordinal_position
+ """
+ )
+ )
+ primary_keys = tuple(
+ (
+ str(row["table_name"]),
+ tuple(str(value) for value in row["columns"]),
+ )
+ for row in await connection.fetch(
+ """
+ SELECT
+ relation.relname AS table_name,
+ ARRAY(
+ SELECT attribute.attname
+ FROM unnest(constraint.conkey)
+ WITH ORDINALITY AS key(attnum, position)
+ JOIN pg_attribute AS attribute
+ ON attribute.attrelid=constraint.conrelid
+ AND attribute.attnum=key.attnum
+ ORDER BY key.position
+ ) AS columns
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS relation
+ ON relation.oid=constraint.conrelid
+ WHERE relation.relnamespace=current_schema()::regnamespace
+ AND constraint.contype='p'
+ AND relation.relname <> 'alembic_version'
+ ORDER BY relation.relname
+ """
+ )
+ )
+ unique_constraints = tuple(
+ (
+ str(row["table_name"]),
+ str(row["constraint_name"]),
+ tuple(str(value) for value in row["columns"]),
+ )
+ for row in await connection.fetch(
+ """
+ SELECT
+ relation.relname AS table_name,
+ constraint.conname AS constraint_name,
+ ARRAY(
+ SELECT attribute.attname
+ FROM unnest(constraint.conkey)
+ WITH ORDINALITY AS key(attnum, position)
+ JOIN pg_attribute AS attribute
+ ON attribute.attrelid=constraint.conrelid
+ AND attribute.attnum=key.attnum
+ ORDER BY key.position
+ ) AS columns
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS relation
+ ON relation.oid=constraint.conrelid
+ WHERE relation.relnamespace=current_schema()::regnamespace
+ AND constraint.contype='u'
+ ORDER BY relation.relname, constraint.conname
+ """
+ )
+ )
+ checks = tuple(
+ (
+ str(row["table_name"]),
+ str(row["constraint_name"]),
+ _normalize_postgres_expression(str(row["definition"])),
+ )
+ for row in await connection.fetch(
+ """
+ SELECT
+ relation.relname AS table_name,
+ constraint.conname AS constraint_name,
+ pg_get_constraintdef(constraint.oid) AS definition
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS relation
+ ON relation.oid=constraint.conrelid
+ WHERE relation.relnamespace=current_schema()::regnamespace
+ AND constraint.contype='c'
+ ORDER BY relation.relname, constraint.conname
+ """
+ )
+ )
+ foreign_keys = tuple(
+ (
+ str(row["table_name"]),
+ str(row["constraint_name"]),
+ tuple(str(value) for value in row["local_columns"]),
+ str(row["remote_table"]),
+ tuple(str(value) for value in row["remote_columns"]),
+ str(row["update_action"]),
+ str(row["delete_action"]),
+ )
+ for row in await connection.fetch(
+ """
+ SELECT
+ source.relname AS table_name,
+ constraint.conname AS constraint_name,
+ ARRAY(
+ SELECT attribute.attname
+ FROM unnest(constraint.conkey)
+ WITH ORDINALITY AS key(attnum, position)
+ JOIN pg_attribute AS attribute
+ ON attribute.attrelid=constraint.conrelid
+ AND attribute.attnum=key.attnum
+ ORDER BY key.position
+ ) AS local_columns,
+ target.relname AS remote_table,
+ ARRAY(
+ SELECT attribute.attname
+ FROM unnest(constraint.confkey)
+ WITH ORDINALITY AS key(attnum, position)
+ JOIN pg_attribute AS attribute
+ ON attribute.attrelid=constraint.confrelid
+ AND attribute.attnum=key.attnum
+ ORDER BY key.position
+ ) AS remote_columns,
+ CASE constraint.confupdtype
+ WHEN 'a' THEN 'NO ACTION'
+ WHEN 'r' THEN 'RESTRICT'
+ WHEN 'c' THEN 'CASCADE'
+ WHEN 'n' THEN 'SET NULL'
+ WHEN 'd' THEN 'SET DEFAULT'
+ END AS update_action,
+ CASE constraint.confdeltype
+ WHEN 'a' THEN 'NO ACTION'
+ WHEN 'r' THEN 'RESTRICT'
+ WHEN 'c' THEN 'CASCADE'
+ WHEN 'n' THEN 'SET NULL'
+ WHEN 'd' THEN 'SET DEFAULT'
+ END AS delete_action
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS source
+ ON source.oid=constraint.conrelid
+ JOIN pg_class AS target
+ ON target.oid=constraint.confrelid
+ WHERE source.relnamespace=current_schema()::regnamespace
+ AND constraint.contype='f'
+ ORDER BY source.relname, constraint.conname
+ """
+ )
+ )
+ indexes = tuple(
+ (
+ str(row["table_name"]),
+ str(row["index_name"]),
+ tuple(str(value) for value in row["columns"]),
+ bool(row["is_unique"]),
+ (
+ None
+ if row["predicate"] is None
+ else _normalize_postgres_expression(str(row["predicate"]))
+ ),
+ )
+ for row in await connection.fetch(
+ """
+ SELECT
+ table_relation.relname AS table_name,
+ index_relation.relname AS index_name,
+ ARRAY(
+ SELECT attribute.attname
+ FROM unnest(index_catalog.indkey)
+ WITH ORDINALITY AS key(attnum, position)
+ JOIN pg_attribute AS attribute
+ ON attribute.attrelid=table_relation.oid
+ AND attribute.attnum=key.attnum
+ WHERE key.position <= index_catalog.indnkeyatts
+ ORDER BY key.position
+ ) AS columns,
+ index_catalog.indisunique AS is_unique,
+ pg_get_expr(
+ index_catalog.indpred,
+ index_catalog.indrelid
+ ) AS predicate
+ FROM pg_index AS index_catalog
+ JOIN pg_class AS table_relation
+ ON table_relation.oid=index_catalog.indrelid
+ JOIN pg_class AS index_relation
+ ON index_relation.oid=index_catalog.indexrelid
+ WHERE table_relation.relnamespace=current_schema()::regnamespace
+ AND NOT EXISTS (
+ SELECT 1 FROM pg_constraint AS constraint
+ WHERE constraint.conindid=index_catalog.indexrelid
+ )
+ ORDER BY table_relation.relname, index_relation.relname
+ """
+ )
+ )
+ sequences = tuple(
+ str(row["sequence_name"])
+ for row in await connection.fetch(
+ """
+ SELECT sequence_name
+ FROM information_schema.sequences
+ WHERE sequence_schema=current_schema()
+ ORDER BY sequence_name
+ """
+ )
+ )
+ return _PostgresCatalogContract(
+ tables=tables,
+ columns=columns,
+ primary_keys=primary_keys,
+ unique_constraints=unique_constraints,
+ checks=checks,
+ foreign_keys=foreign_keys,
+ indexes=indexes,
+ sequences=sequences,
+ )
+
+
+def _fixed_postgres_contract(revision: str) -> _PostgresCatalogContract:
+ if revision == "base":
+ return _PostgresCatalogContract((), (), (), (), (), (), (), ())
+ tables = {
+ "campaigns",
+ "module_runs",
+ "findings",
+ "hosts",
+ "credentials",
+ "loot",
+ "audit_log",
+ "users",
+ "api_keys",
+ "refresh_tokens",
+ }
+ if revision >= "0003":
+ tables.add("rate_limit_events")
+ if revision >= "0004":
+ tables.add("revoked_access_tokens")
+ ordered_tables = tuple(sorted(tables))
+ order = {
+ table: tuple(columns)
+ for table, columns in _EXPECTED_COLUMN_ORDER.items()
+ if table in tables
+ }
+ if revision == "0001":
+ order["findings"] = tuple(
+ column for column in order["findings"] if column != "trace_id"
+ )
+ if revision < "0006":
+ order["credentials"] = tuple(
+ "cracked_value" if column == "cracked_value_enc" else column
+ for column in order["credentials"]
+ )
+ columns: list[tuple[str, str, str, bool, str | None]] = []
+ for table in ordered_tables:
+ for column in order[table]:
+ canonical_column = (
+ "cracked_value_enc"
+ if column == "cracked_value"
+ else column
+ )
+ key = (table, canonical_column)
+ if key in _POSTGRES_INTEGER_COLUMNS:
+ data_type = "integer"
+ elif key in _POSTGRES_FLOAT_COLUMNS:
+ data_type = "double precision"
+ elif key in _POSTGRES_TIMESTAMP_COLUMNS:
+ data_type = "timestamp with time zone"
+ else:
+ data_type = "text"
+ nullable = key in _POSTGRES_NULLABLE_COLUMNS
+ if table == "findings" and column == "trace_id":
+ nullable = revision < "0005"
+ columns.append(
+ (
+ table,
+ column,
+ data_type,
+ nullable,
+ _POSTGRES_DEFAULTS.get(key),
+ )
+ )
+ primary_keys = tuple(
+ (
+ table,
+ (
+ "jti"
+ if table == "revoked_access_tokens"
+ else "id",
+ ),
+ )
+ for table in ordered_tables
+ )
+ unique_constraints = tuple(
+ sorted(
+ (
+ ("hosts", "uq_hosts_campaign_ip", ("campaign_id", "ip_address")),
+ ("users", "uq_users_username", ("username",)),
+ )
+ )
+ )
+ foreign_key_names = {
+ ("module_runs", "campaign_id"): "fk_module_runs_campaign",
+ ("findings", "campaign_id"): "fk_findings_campaign",
+ ("hosts", "campaign_id"): "fk_hosts_campaign",
+ ("credentials", "campaign_id"): "fk_credentials_campaign",
+ ("credentials", "host_id"): "fk_credentials_host",
+ ("loot", "campaign_id"): "fk_loot_campaign",
+ ("loot", "host_id"): "fk_loot_host",
+ ("audit_log", "campaign_id"): "fk_audit_campaign",
+ ("api_keys", "user_id"): "fk_api_keys_user",
+ ("refresh_tokens", "user_id"): "fk_refresh_tokens_user",
+ }
+ foreign_keys = tuple(
+ sorted(
+ (
+ table,
+ foreign_key_names[(table, local)],
+ (local,),
+ remote,
+ ("id",),
+ "NO ACTION",
+ action,
+ )
+ for table, local, remote, action in _EXPECTED_FOREIGN_KEYS
+ if table in tables
+ )
+ )
+ index_names = set(_EXPECTED_INDEXES)
+ if revision == "0001":
+ index_names.discard("idx_findings_cvss")
+ if revision < "0003":
+ index_names.difference_update(
+ {"idx_rle_ip", "idx_rle_timestamp", "idx_rle_blocked"}
+ )
+ if revision < "0004":
+ index_names.discard("idx_rat_expires")
+ indexes = tuple(
+ sorted(
+ (
+ _POSTGRES_INDEX_TABLES[name],
+ name,
+ columns,
+ False,
+ None,
+ )
+ for name, columns in _EXPECTED_INDEXES.items()
+ if name in index_names
+ )
+ )
+ checks = [
+ (
+ table,
+ name,
+ (
+ f"{column}isnullorisfinite{column}"
+ if nullable
+ else f"isfinite{column}"
+ ),
+ )
+ for (table, column), (name, nullable) in (
+ _POSTGRES_FINITE_TIMESTAMP_CONSTRAINTS.items()
+ )
+ if table in tables
+ ]
+ if revision >= "0003":
+ checks.append(
+ (
+ "rate_limit_events",
+ "ck_rate_limit_events_blocked_bool",
+ "blocked=anyarray[0,1]",
+ )
+ )
+ sequences = ["audit_log_id_seq"]
+ if revision >= "0003":
+ sequences.append("rate_limit_events_id_seq")
+ return _PostgresCatalogContract(
+ tables=ordered_tables,
+ columns=tuple(columns),
+ primary_keys=primary_keys,
+ unique_constraints=unique_constraints,
+ checks=tuple(sorted(checks)),
+ foreign_keys=foreign_keys,
+ indexes=indexes,
+ sequences=tuple(sorted(sequences)),
+ )
+
+
+def _fixed_legacy_postgres_contract(
+ revision: str,
+) -> _PostgresCatalogContract:
+ repaired = _fixed_postgres_contract(revision)
+ tables = tuple(
+ table for table in repaired.tables if table != "module_runs"
+ )
+ columns = tuple(
+ (
+ table,
+ column,
+ data_type,
+ (
+ True
+ if table == "findings"
+ and column in {"cvss_score", "cvss_vector", "trace_id"}
+ else nullable
+ ),
+ default,
+ )
+ for table, column, data_type, nullable, default in repaired.columns
+ if table != "module_runs"
+ )
+ indexes = tuple(
+ index for index in repaired.indexes if index[0] != "module_runs"
+ ) + (
+ (
+ "findings",
+ "idx_findings_validated",
+ ("validated",),
+ False,
+ None,
+ ),
+ )
+ return replace(
+ repaired,
+ tables=tables,
+ columns=columns,
+ primary_keys=tuple(
+ item for item in repaired.primary_keys if item[0] != "module_runs"
+ ),
+ checks=(),
+ foreign_keys=(),
+ indexes=tuple(sorted(indexes)),
+ )
+
+
+_POSTGRES_RUNTIME_LEGACY_CONSTRAINT_RECIPE = (
+ ("0001", "module_runs", "fk_module_runs_campaign"),
+ ("0001", "findings", "fk_findings_campaign"),
+ ("0001", "hosts", "fk_hosts_campaign"),
+ ("0001", "credentials", "fk_credentials_campaign"),
+ ("0001", "credentials", "fk_credentials_host"),
+ ("0001", "loot", "fk_loot_campaign"),
+ ("0001", "loot", "fk_loot_host"),
+ ("0001", "audit_log", "fk_audit_campaign"),
+ ("0001", "api_keys", "fk_api_keys_user"),
+ ("0001", "refresh_tokens", "fk_refresh_tokens_user"),
+ ("0001", "campaigns", "ck_campaigns_created_at_finite"),
+ ("0001", "campaigns", "ck_campaigns_updated_at_finite"),
+ ("0001", "module_runs", "ck_module_runs_completed_at_finite"),
+ ("0001", "findings", "ck_findings_discovered_at_finite"),
+ ("0001", "hosts", "ck_hosts_first_seen_finite"),
+ ("0001", "hosts", "ck_hosts_last_seen_finite"),
+ ("0001", "credentials", "ck_credentials_captured_at_finite"),
+ ("0001", "loot", "ck_loot_captured_at_finite"),
+ ("0001", "audit_log", "ck_audit_log_timestamp_finite"),
+ ("0001", "users", "ck_users_created_at_finite"),
+ ("0001", "users", "ck_users_last_login_finite"),
+ ("0001", "api_keys", "ck_api_keys_last_used_finite"),
+ ("0001", "api_keys", "ck_api_keys_expires_at_finite"),
+ ("0001", "api_keys", "ck_api_keys_created_at_finite"),
+ ("0001", "refresh_tokens", "ck_refresh_tokens_expires_at_finite"),
+ ("0001", "refresh_tokens", "ck_refresh_tokens_created_at_finite"),
+ ("0001", "refresh_tokens", "ck_refresh_tokens_used_at_finite"),
+ (
+ "0003",
+ "rate_limit_events",
+ "ck_rate_limit_events_blocked_bool",
+ ),
+ (
+ "0003",
+ "rate_limit_events",
+ "ck_rate_limit_events_timestamp_finite",
+ ),
+ (
+ "0004",
+ "revoked_access_tokens",
+ "ck_revoked_access_tokens_revoked_at_finite",
+ ),
+ (
+ "0004",
+ "revoked_access_tokens",
+ "ck_revoked_access_tokens_expires_at_finite",
+ ),
+)
+
+
+def _postgres_runtime_legacy_recipe(
+ revision: str,
+) -> _PostgresLegacyRecipe:
+ if revision not in {"0001", "0002", "0003", "0004", "0005"}:
+ raise AssertionError("unsupported PostgreSQL legacy recipe revision")
+ nullable_columns = [
+ ("findings", "cvss_score"),
+ ("findings", "cvss_vector"),
+ ]
+ if revision >= "0002":
+ nullable_columns.append(("findings", "trace_id"))
+ return _PostgresLegacyRecipe(
+ constraints_to_drop=tuple(
+ (table, constraint)
+ for introduced, table, constraint in (
+ _POSTGRES_RUNTIME_LEGACY_CONSTRAINT_RECIPE
+ )
+ if introduced <= revision
+ ),
+ tables_to_drop=("module_runs",),
+ nullable_columns=tuple(nullable_columns),
+ indexes_to_create=(
+ (
+ "idx_findings_validated",
+ "findings",
+ ("validated",),
+ ),
+ ),
+ )
+
+
[email protected](autouse=True)
+def _forbid_runtime_bootstrap(monkeypatch: pytest.MonkeyPatch) -> None:
+ from ares.db.postgres import PostgresDatabase
+
+ async def _prohibited_connect(*_args: object, **_kwargs: object) -> None:
+ pytest.fail(
+ "runtime PostgreSQL bootstrap was invoked",
+ pytrace=False,
+ )
+
+ monkeypatch.setattr(PostgresDatabase, "connect", _prohibited_connect)
+
+
+def _clear_postgres_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+ for name in _POSTGRES_ENV:
+ monkeypatch.delenv(name, raising=False)
+
+
+def test_postgres_legacy_recipe_does_not_call_expected_oracle(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ expected_recipe = _postgres_runtime_legacy_recipe("0005")
+
+ def _poisoned_oracle(*_args: object, **_kwargs: object) -> object:
+ raise AssertionError("expected oracle was traversed by fixture recipe")
+
+ module = sys.modules[__name__]
+ monkeypatch.setattr(
+ module,
+ "_fixed_postgres_contract",
+ _poisoned_oracle,
+ )
+ monkeypatch.setattr(
+ module,
+ "_fixed_legacy_postgres_contract",
+ _poisoned_oracle,
+ )
+ constructed = _postgres_runtime_legacy_recipe("0005")
+ _require_fixed(
+ constructed == expected_recipe,
+ "PostgreSQL legacy recipe depended on an expected oracle",
+ )
+
+
+def test_postgres_legacy_recipe_and_oracle_have_no_mutable_alias() -> None:
+ def _deeply_immutable(value: object) -> bool:
+ if isinstance(value, tuple):
+ return all(_deeply_immutable(item) for item in value)
+ return isinstance(value, (str, int, bool, type(None)))
+
+ recipe = _postgres_runtime_legacy_recipe("0005")
+ oracle = _fixed_legacy_postgres_contract("0005")
+ recipe_constraints = list(recipe.constraints_to_drop)
+ oracle_tables = list(oracle.tables)
+ recipe_constraints.append(
+ ("synthetic_table", "synthetic_constraint")
+ )
+ oracle_tables.append("synthetic_table")
+ independent = (
+ tuple(recipe_constraints) != recipe.constraints_to_drop
+ and tuple(oracle_tables) != oracle.tables
+ and _postgres_runtime_legacy_recipe("0005") == recipe
+ and _fixed_legacy_postgres_contract("0005") == oracle
+ and all(
+ _deeply_immutable(value)
+ for value in (
+ recipe.constraints_to_drop,
+ recipe.tables_to_drop,
+ recipe.nullable_columns,
+ recipe.indexes_to_create,
+ oracle.tables,
+ oracle.columns,
+ oracle.checks,
+ oracle.foreign_keys,
+ )
+ )
+ )
+ _require_fixed(
+ independent,
+ "PostgreSQL legacy recipe and oracle share mutable state",
+ )
+
+
+def test_postgres_configuration_all_absent_skips(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ _clear_postgres_environment(monkeypatch)
+ skipped = False
+ try:
+ _postgres_config()
+ except pytest.skip.Exception:
+ skipped = True
+ _require_fixed(
+ skipped,
+ "absent PostgreSQL configuration did not intentionally skip",
+ )
+
+
+def test_noncanonical_database_names_do_not_configure_harness(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ _clear_postgres_environment(monkeypatch)
+ monkeypatch.setenv("ARES_TEST_POSTGRES_DATABASE", "ignored")
+ monkeypatch.setenv("ARES_DATABASE_URL", "ignored")
+ skipped = False
+ try:
+ _postgres_config()
+ except pytest.skip.Exception:
+ skipped = True
+ _require_fixed(
+ skipped,
+ "noncanonical database configuration activated the harness",
+ )
+
+
+ "values",
+ [
+ {"ARES_TEST_POSTGRES_HOST": "configured"},
+ {
+ "ARES_TEST_POSTGRES_HOST": "",
+ "ARES_TEST_POSTGRES_PORT": "5432",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ },
+ {
+ "ARES_TEST_POSTGRES_HOST": " ",
+ "ARES_TEST_POSTGRES_PORT": "5432",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ },
+ {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ },
+ {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "05432",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ },
+ {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "+5432",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ },
+ {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "65536",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ },
+ {
+ "ARES_TEST_POSTGRES_HOST": "",
+ "ARES_TEST_POSTGRES_PORT": "",
+ "ARES_TEST_POSTGRES_USER": "",
+ "ARES_TEST_POSTGRES_DB": "",
+ },
+ {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "not-a-port",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ },
+ {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "\u0665\u0664\u0663\u0662",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ },
+ ],
+ ids=(
+ "partial",
+ "empty",
+ "whitespace",
+ "empty-port",
+ "noncanonical-port",
+ "signed-port",
+ "out-of-range-port",
+ "all-empty",
+ "malformed-port",
+ "non-ascii-port",
+ ),
+)
+def test_postgres_configuration_invalid_states_fail(
+ monkeypatch: pytest.MonkeyPatch,
+ values: dict[str, str],
+) -> None:
+ _clear_postgres_environment(monkeypatch)
+ for name, value in values.items():
+ monkeypatch.setenv(name, value)
+ failed = False
+ try:
+ _postgres_config()
+ except pytest.fail.Exception:
+ failed = True
+ _require_fixed(
+ failed,
+ "invalid PostgreSQL configuration did not fail",
+ )
+
+
+def test_postgres_configuration_complete_shape_is_accepted(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ _clear_postgres_environment(monkeypatch)
+ values = {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "5432",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ }
+ for name, value in values.items():
+ monkeypatch.setenv(name, value)
+ config = _postgres_config()
+ accepted = (
+ config.port == 5432
+ and bool(config.host)
+ and bool(config.user)
+ and bool(config.maintenance_database)
+ )
+ _require_fixed(
+ accepted,
+ "complete PostgreSQL configuration was rejected",
+ )
+
+
+async def test_complete_configuration_without_driver_fails_safely(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ _clear_postgres_environment(monkeypatch)
+ values = {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "5432",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ }
+ for name, value in values.items():
+ monkeypatch.setenv(name, value)
+ real_import = builtins.__import__
+
+ def _without_asyncpg(
+ name: str,
+ *args: object,
+ **kwargs: object,
+ ) -> object:
+ if name == "asyncpg":
+ raise ImportError
+ return real_import(name, *args, **kwargs)
+
+ monkeypatch.setattr(builtins, "__import__", _without_asyncpg)
+ failed = False
+ try:
+ async with _postgres_harness():
+ pytest.fail(
+ "driver gate unexpectedly entered database setup",
+ pytrace=False,
+ )
+ except pytest.fail.Exception:
+ failed = True
+ _require_fixed(
+ failed,
+ "configured PostgreSQL harness accepted a missing driver",
+ )
+
+
+async def test_owned_worker_completion_and_error_are_settled() -> None:
+ await _run_worker({"mode": "success"}, timeout=2.0)
+ failed = False
+ try:
+ await _run_worker({"mode": "migration-error"}, timeout=2.0)
+ except RuntimeError:
+ failed = True
+ _require_fixed(failed, "worker exception did not propagate")
+ _require_fixed(
+ len(_OWNED_WORKERS) == 0,
+ "completed worker remained owned",
+ )
+
+
+async def test_owned_worker_timeout_is_terminated() -> None:
+ started = asyncio.Event()
+ failed = False
+ try:
+ await _run_worker(
+ {"mode": "block"},
+ timeout=0.1,
+ started=started,
+ )
+ except RuntimeError:
+ failed = True
+ _require_fixed(started.is_set(), "blocking worker never became ready")
+ _require_fixed(failed, "blocking worker did not time out")
+ _require_fixed(
+ len(_OWNED_WORKERS) == 0,
+ "timed-out worker remained owned",
+ )
+
+
+async def test_owned_worker_parent_cancellation_is_settled() -> None:
+ started = asyncio.Event()
+ task = asyncio.create_task(
+ _run_worker(
+ {"mode": "block"},
+ timeout=30.0,
+ started=started,
+ )
+ )
+ await asyncio.wait_for(started.wait(), timeout=5.0)
+ task.cancel()
+ cancelled = False
+ try:
+ await task
+ except asyncio.CancelledError:
+ cancelled = True
+ _require_fixed(cancelled, "worker parent cancellation was suppressed")
+ _require_fixed(
+ len(_OWNED_WORKERS) == 0,
+ "cancelled worker remained owned",
+ )
+
+
+ "mode",
+ [
+ "protocol-ok-before-ready",
+ "protocol-duplicate-ready",
+ "protocol-duplicate-ok",
+ "protocol-malformed",
+ "protocol-eof-before-terminal",
+ "protocol-success-crash",
+ "protocol-zero-without-success",
+ ],
+)
+async def test_worker_protocol_rejects_invalid_sequences(mode: str) -> None:
+ failed = False
+ try:
+ await _run_worker({"mode": mode}, timeout=2.0)
+ except RuntimeError:
+ failed = True
+ _require_fixed(failed, "invalid worker protocol sequence was accepted")
+ _require_fixed(
+ len(_OWNED_WORKERS) == 0,
+ "invalid worker protocol retained a settled worker",
+ )
+
+
+async def test_worker_setup_failure_occurs_before_ready() -> None:
+ started = asyncio.Event()
+ caught: Exception | None = None
+ try:
+ await _run_worker(
+ {"mode": "setup-error"},
+ timeout=2.0,
+ started=started,
+ )
+ except RuntimeError as error:
+ caught = error
+ fixed_failure = (
+ type(caught) is RuntimeError
+ and str(caught) == "Alembic worker failed [RuntimeError]"
+ and bool(getattr(caught, "__suppress_context__", False))
+ )
+ _require_fixed(
+ fixed_failure,
+ "worker setup failure was not sanitized",
+ )
+ _require_fixed(
+ not started.is_set(),
+ "worker setup failure was incorrectly reported as ready",
+ )
+
+
+ "mode",
+ ["success-dirty-origin", "success-dirty-origin-removed"],
+ ids=("present-at-final-guard", "removed-before-final-guard"),
+)
+async def test_worker_final_origin_guard_rejects_late_dirty_import(
+ mode: str,
+) -> None:
+ failed = False
+ try:
+ await _run_worker(
+ {"mode": mode},
+ timeout=2.0,
+ )
+ except RuntimeError:
+ failed = True
+ _require_fixed(
+ failed and not _OWNED_WORKERS,
+ "worker final origin guard accepted a late dirty import",
+ )
+
+
+class _IntegrationOriginProbeLoader:
+ def create_module(self, _spec: object) -> None:
+ return None
+
+ def exec_module(self, _module: object) -> None:
+ return None
+
+
+class _IntegrationOriginProbeFinder:
+ def __init__(self, name: str, spec: object) -> None:
+ self._name = name
+ self._spec = spec
+
+ def find_spec(
+ self,
+ fullname: str,
+ _path: object = None,
+ _target: object = None,
+ ) -> object:
+ return self._spec if fullname == self._name else None
+
+
+@contextmanager
+def _integration_origin_probe(
+ name: str,
+ spec: object,
+) -> Iterator[Callable[[], None]]:
+ finder = _IntegrationOriginProbeFinder(name, spec)
+ parent_name, _, child_name = name.rpartition(".")
+ parent = (
+ importlib.import_module(parent_name)
+ if parent_name
+ else None
+ )
+ missing = object()
+ previous_module = sys.modules.pop(name, missing)
+ previous_attribute = (
+ parent.__dict__.get(child_name, missing)
+ if parent is not None
+ else missing
+ )
+ sys.meta_path.insert(0, finder)
+
+ def _import_then_remove() -> None:
+ importlib.import_module(name)
+ sys.modules.pop(name, None)
+ if parent is not None and child_name in parent.__dict__:
+ delattr(parent, child_name)
+
+ try:
+ yield _import_then_remove
+ finally:
+ if finder in sys.meta_path:
+ sys.meta_path.remove(finder)
+ sys.modules.pop(name, None)
+ if previous_module is not missing:
+ sys.modules[name] = previous_module
+ if parent is not None:
+ if previous_attribute is missing:
+ if child_name in parent.__dict__:
+ delattr(parent, child_name)
+ else:
+ setattr(parent, child_name, previous_attribute)
+
+
+ ("name", "mixed"),
+ [
+ ("ares.integration_removed_probe", False),
+ ("migrations.versions.0007_add_websocket_tickets", False),
+ ("migrations.versions.integration_mixed_probe", True),
+ ],
+ ids=("dirty-ares", "dirty-0007", "mixed-namespace"),
+)
+def test_integration_origin_ledger_retains_removed_import(
+ tmp_path: Path,
+ name: str,
+ mixed: bool,
+) -> None:
+ if mixed:
+ spec = importlib.machinery.ModuleSpec(
+ name,
+ loader=None,
+ is_package=True,
+ )
+ spec.submodule_search_locations = [
+ str(_REPO_ROOT / "migrations" / "versions"),
+ str(tmp_path),
+ ]
+ else:
+ spec = importlib.machinery.ModuleSpec(
+ name,
+ _IntegrationOriginProbeLoader(),
+ origin=str(tmp_path / "probe.py"),
+ )
+ rejected = False
+ try:
+ with _integration_origin_probe(name, spec) as import_then_remove:
+ with _candidate_origin_boundary(isolated=True):
+ import_then_remove()
+ except RuntimeError:
+ rejected = True
+ _require_fixed(
+ rejected,
+ "integration origin ledger forgot a removed import",
+ )
+
+
+def test_integration_final_origin_guard_rejects_late_dirty_import(
+ monkeypatch: pytest.MonkeyPatch,
+ tmp_path: Path,
+) -> None:
+ dirty_module = types.ModuleType("migrations.versions.late_dirty_probe")
+ dirty_origin = tmp_path / "late_dirty_probe.py"
+ dirty_module.__file__ = str(dirty_origin)
+ dirty_module.__spec__ = importlib.machinery.ModuleSpec(
+ "migrations.versions.late_dirty_probe",
+ loader=None,
+ origin=str(dirty_origin),
+ )
+ monkeypatch.setitem(
+ sys.modules,
+ "migrations.versions.late_dirty_probe",
+ dirty_module,
+ )
+ rejected = not _loaded_first_party_origins_are_candidate_local(
+ sys.modules,
+ _REPO_ROOT,
+ )
+ _require_fixed(
+ rejected,
+ "integration final origin guard accepted a late dirty import",
+ )
+
+
+def _integration_reused_origin_probe_body() -> None:
+ return None
+
+
+def test_integration_origin_ledger_rechecks_reused_code(
+ tmp_path: Path,
+) -> None:
+ probe_code = _integration_reused_origin_probe_body.__code__
+ local_probe = types.FunctionType(
+ probe_code,
+ {
+ "__name__": "migrations.versions.integration_reused_probe",
+ "__package__": "migrations.versions",
+ "__file__": str(
+ _REPO_ROOT
+ / "migrations"
+ / "versions"
+ / "0006_integration_reused_probe.py"
+ ),
+ },
+ )
+ dirty_probe = types.FunctionType(
+ probe_code,
+ {
+ "__name__": "migrations.versions.integration_reused_probe",
+ "__package__": "migrations.versions",
+ "__file__": str(
+ tmp_path
+ / "migrations"
+ / "versions"
+ / "0007_integration_reused_probe.py"
+ ),
+ },
+ )
+ rejected = False
+ try:
+ with _candidate_origin_boundary(isolated=True):
+ local_probe()
+ dirty_probe()
+ except RuntimeError:
+ rejected = True
+ _require_fixed(
+ rejected,
+ "integration origin ledger cached a stale frame origin",
+ )
+
+
+def test_integration_origin_ledger_ignores_unrelated_migrations_directory(
+ tmp_path: Path,
+) -> None:
+ third_party_probe = types.FunctionType(
+ _integration_reused_origin_probe_body.__code__,
+ {
+ "__name__": "third_party.integration_origin_probe",
+ "__package__": "third_party",
+ "__file__": str(
+ tmp_path / "migrations" / "integration_origin_probe.py"
+ ),
+ },
+ )
+ with _candidate_origin_boundary(isolated=True):
+ third_party_probe()
+
+
+@dataclass(slots=True, repr=False)
+class _IpcConfidentialityAudit:
+ forbidden_values: tuple[str, ...] = field(repr=False)
+ process_args_safe: bool = False
+ process_closed: bool = False
+ parent_endpoint_closed: bool = False
+ sensitive_seen: bool = False
+ unsafe_object_seen: bool = False
+ sent_signatures: list[tuple[str, int]] = field(
+ default_factory=list,
+ repr=False,
+ )
+ received_signatures: list[tuple[str, int]] = field(
+ default_factory=list,
+ repr=False,
+ )
+
+ def _observe_value(self, value: object) -> None:
+ if isinstance(value, str):
+ if any(marker in value for marker in self.forbidden_values):
+ self.sensitive_seen = True
+ folded = value.casefold()
+ if folded in {
+ "postgresql",
+ "postgresql+asyncpg",
+ "asyncpg",
+ } or any(
+ marker in folded
+ for marker in (
+ "postgresql://",
+ "postgresql+asyncpg://",
+ "ares_test_postgres_",
+ )
+ ):
+ self.sensitive_seen = True
+ return
+ if isinstance(value, bytes):
+ lowered = value.lower()
+ if any(
+ marker.encode("utf-8") in value
+ for marker in self.forbidden_values
+ ) or b"postgresql" in lowered:
+ self.sensitive_seen = True
+ return
+ if isinstance(value, int) and any(
+ marker.isdecimal() and int(marker) == value
+ for marker in self.forbidden_values
+ ):
+ self.sensitive_seen = True
+ return
+ if isinstance(value, dict):
+ for key, item in value.items():
+ self._observe_value(key)
+ self._observe_value(item)
+ return
+ if isinstance(value, (tuple, list)):
+ for item in value:
+ self._observe_value(item)
+ return
+ module_name = type(value).__module__
+ if module_name.startswith(("alembic", "sqlalchemy")):
+ self.unsafe_object_seen = True
+
+ def observe_process(self, kwargs: dict[str, object]) -> None:
+ arguments = kwargs.get("args")
+ safe_shape = (
+ kwargs.get("target") is _alembic_worker_entry
+ and isinstance(arguments, tuple)
+ and len(arguments) == 1
+ )
+ if isinstance(arguments, tuple):
+ for argument in arguments:
+ self._observe_value(argument)
+ self.process_args_safe = safe_shape
+
+ def observe_frame(self, direction: str, frame: object) -> None:
+ self._observe_value(frame)
+ if not isinstance(frame, tuple) or not frame:
+ self.unsafe_object_seen = True
+ return
+ kind = frame[0] if isinstance(frame[0], str) else "INVALID"
+ signature = (kind, len(frame))
+ if direction == "sent":
+ self.sent_signatures.append(signature)
+ else:
+ self.received_signatures.append(signature)
+
+
+@dataclass(slots=True, repr=False)
+class _AuditedParentChannel:
+ raw: object = field(repr=False)
+ audit: _IpcConfidentialityAudit = field(repr=False)
+
+ def send(self, frame: object) -> None:
+ self.audit.observe_frame("sent", frame)
+ self.raw.send(frame)
+
+ def recv(self) -> object:
+ frame = self.raw.recv()
+ self.audit.observe_frame("received", frame)
+ return frame
+
+ def poll(self) -> bool:
+ return bool(self.raw.poll())
+
+ def close(self) -> None:
+ self.raw.close()
+ self.audit.parent_endpoint_closed = True
+
+
+@dataclass(slots=True, repr=False)
+class _AuditedProcess:
+ raw: object = field(repr=False)
+ audit: _IpcConfidentialityAudit = field(repr=False)
+
+ def __getattr__(self, name: str) -> object:
+ return getattr(self.raw, name)
+
+ def close(self) -> None:
+ self.raw.close()
+ self.audit.process_closed = True
+
+
+@dataclass(slots=True, repr=False)
+class _AuditedSpawnContext:
+ raw: object = field(repr=False)
+ audit: _IpcConfidentialityAudit = field(repr=False)
+ child_endpoint: object = field(default=None, init=False, repr=False)
+
+ def Pipe(self, *, duplex: bool) -> tuple[object, object]: # noqa: N802
+ parent, child = self.raw.Pipe(duplex=duplex)
+ self.child_endpoint = child
+ return _AuditedParentChannel(parent, self.audit), child
+
+ def Process(self, **kwargs: object) -> _AuditedProcess: # noqa: N802
+ self.audit.observe_process(kwargs)
+ return _AuditedProcess(self.raw.Process(**kwargs), self.audit)
+
+
+ ("mode", "should_succeed"),
+ [
+ ("ipc-prepare-success", True),
+ ("ipc-prepare-error", False),
+ ],
+ ids=("prepared-success", "prepared-sanitized-failure"),
+)
+async def test_migration_ipc_uses_only_fixed_control_data(
+ monkeypatch: pytest.MonkeyPatch,
+ mode: str,
+ should_succeed: bool,
+) -> None:
+ canonical_values = {
+ "ARES_TEST_POSTGRES_HOST": "ipc-host-canary",
+ "ARES_TEST_POSTGRES_PORT": "5432",
+ "ARES_TEST_POSTGRES_USER": "ipc-user-canary",
+ "ARES_TEST_POSTGRES_DB": "ipc-maintenance-canary",
+ }
+ for name, value in canonical_values.items():
+ monkeypatch.setenv(name, value)
+ real_context = multiprocessing.get_context("spawn")
+ audit = _IpcConfidentialityAudit(
+ tuple(canonical_values.values())
+ )
+ audited_context = _AuditedSpawnContext(real_context, audit)
+ monkeypatch.setattr(
+ multiprocessing,
+ "get_context",
+ lambda _method: audited_context,
+ )
+ caught: Exception | None = None
+ try:
+ await _run_worker(
+ {
+ "mode": mode,
+ "database_name": f"ares_migration_{'a' * 32}",
+ "operation": "upgrade",
+ "revision": "0001",
+ },
+ timeout=5.0,
+ )
+ except RuntimeError as error:
+ caught = error
+
+ child_endpoint_closed = bool(
+ audited_context.child_endpoint is not None
+ and getattr(audited_context.child_endpoint, "closed", False)
+ )
+ expected_received = (
+ [("READY", 1), ("OK", 1)]
+ if should_succeed
+ else [("READY", 1), ("ERROR", 2)]
+ )
+ result_safe = (
+ (caught is None if should_succeed else type(caught) is RuntimeError)
+ and (
+ should_succeed
+ or str(caught) == "Alembic worker failed [RuntimeError]"
+ )
+ and audit.process_args_safe
+ and audit.sent_signatures
+ == [("PAYLOAD", 2), ("GO", 1)]
+ and audit.received_signatures == expected_received
+ and not audit.sensitive_seen
+ and not audit.unsafe_object_seen
+ and audit.parent_endpoint_closed
+ and child_endpoint_closed
+ and audit.process_closed
+ and not _OWNED_WORKERS
+ )
+ _require_fixed(
+ result_safe,
+ "migration IPC confidentiality protocol diverged",
+ )
+
+
+def test_child_constructs_explicit_target_from_inherited_configuration(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ child_environment = {
+ "ARES_TEST_POSTGRES_HOST": "child-host-canary",
+ "ARES_TEST_POSTGRES_PORT": "5432",
+ "ARES_TEST_POSTGRES_USER": "child-user-canary",
+ "ARES_TEST_POSTGRES_DB": "child-maintenance-canary",
+ }
+ for name, value in child_environment.items():
+ monkeypatch.setenv(name, value)
+ target = f"ares_migration_{'b' * 32}"
+ target_url_was_child_local = False
+ config_sentinel = object()
+ upgrade_sentinel = object()
+
+ def _capture_config(url: str) -> object:
+ nonlocal target_url_was_child_local
+ target_url_was_child_local = (
+ target in url
+ and child_environment["ARES_TEST_POSTGRES_HOST"] in url
+ and child_environment["ARES_TEST_POSTGRES_USER"] in url
+ )
+ return config_sentinel
+
+ monkeypatch.setattr(
+ sys.modules[__name__],
+ "_alembic_config",
+ _capture_config,
+ )
+ config, action, revision, fault = _prepare_child_migration(
+ {
+ "mode": "migrate",
+ "database_name": target,
+ "operation": "upgrade",
+ "revision": "0001",
+ },
+ types.SimpleNamespace(
+ upgrade=upgrade_sentinel,
+ downgrade=object(),
+ ),
+ )
+ prepared = (
+ target_url_was_child_local
+ and config is config_sentinel
+ and action is upgrade_sentinel
+ and revision == "0001"
+ and fault is None
+ )
+ _require_fixed(
+ prepared,
+ "child-side explicit migration target construction failed",
+ )
+
+
+def test_malformed_child_target_is_rejected_before_url_construction(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ child_environment = {
+ "ARES_TEST_POSTGRES_HOST": "configured",
+ "ARES_TEST_POSTGRES_PORT": "5432",
+ "ARES_TEST_POSTGRES_USER": "configured",
+ "ARES_TEST_POSTGRES_DB": "configured",
+ }
+ for name, value in child_environment.items():
+ monkeypatch.setenv(name, value)
+ url_constructed = False
+
+ def _record_url(*_args: object, **_kwargs: object) -> str:
+ nonlocal url_constructed
+ url_constructed = True
+ return "unexpected"
+
+ monkeypatch.setattr(
+ sys.modules[__name__],
+ "_migration_url",
+ _record_url,
+ )
+ failed = False
+ try:
+ _prepare_child_migration(
+ {
+ "mode": "migrate",
+ "database_name": "invalid",
+ "operation": "upgrade",
+ "revision": "0001",
+ },
+ types.SimpleNamespace(
+ upgrade=object(),
+ downgrade=object(),
+ ),
+ )
+ except RuntimeError:
+ failed = True
+ _require_fixed(
+ failed and not url_constructed,
+ "malformed child target reached URL construction",
+ )
+
+
+async def test_child_configuration_failure_returns_fixed_protocol_result(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ _clear_postgres_environment(monkeypatch)
+ caught: Exception | None = None
+ try:
+ await _run_worker(
+ {
+ "mode": "migrate",
+ "database_name": f"ares_migration_{'c' * 32}",
+ "operation": "upgrade",
+ "revision": "0001",
+ },
+ timeout=2.0,
+ )
+ except RuntimeError as error:
+ caught = error
+ fixed_result = (
+ type(caught) is RuntimeError
+ and str(caught) == "Alembic worker failed [RuntimeError]"
+ and bool(getattr(caught, "__suppress_context__", False))
+ and not _OWNED_WORKERS
+ )
+ _require_fixed(
+ fixed_result,
+ "child configuration failure exposed non-protocol data",
+ )
+
+
+class _WorkerConstructionError(RuntimeError):
+ pass
+
+
+class _WorkerStartError(RuntimeError):
+ pass
+
+
+class _WorkerEndpointCloseError(RuntimeError):
+ pass
+
+
+class _ConstructionEndpoint:
+ def __init__(self, *, fail_close_once: bool = False) -> None:
+ self.closed = False
+ self.close_attempts = 0
+ self.fail_close_once = fail_close_once
+
+ def close(self) -> None:
+ self.close_attempts += 1
+ if self.fail_close_once and self.close_attempts == 1:
+ raise _WorkerEndpointCloseError
+ self.closed = True
+
+
+class _NeverStartedProcess:
+ def __init__(self) -> None:
+ self.pid = None
+ self.exitcode = None
+ self.closed = False
+ self.start_called = False
+
+ def start(self) -> None:
+ self.start_called = True
+ raise _WorkerStartError
+
+ def is_alive(self) -> bool:
+ return False
+
+ def close(self) -> None:
+ self.closed = True
+
+
+class _PipeFailureContext:
+ def Pipe(self, *, duplex: bool) -> object: # noqa: N802
+ del duplex
+ raise _WorkerConstructionError
+
+
+class _PartialPipeFailureContext:
+ def __init__(self) -> None:
+ self.endpoint = _ConstructionEndpoint()
+
+ def Pipe(self, *, duplex: bool) -> tuple[object]: # noqa: N802
+ del duplex
+ return (self.endpoint,)
+
+
+class _ProcessFailureContext:
+ def __init__(self) -> None:
+ self.parent = _ConstructionEndpoint()
+ self.child = _ConstructionEndpoint()
+ self.process_kwargs: dict[str, object] | None = None
+
+ def Pipe( # noqa: N802
+ self,
+ *,
+ duplex: bool,
+ ) -> tuple[object, object]:
+ del duplex
+ return self.parent, self.child
+
+ def Process(self, **kwargs: object) -> object: # noqa: N802
+ self.process_kwargs = dict(kwargs)
+ raise _WorkerConstructionError
+
+
+class _StartFailureContext:
+ def __init__(self, *, fail_parent_close_once: bool = False) -> None:
+ self.parent = _ConstructionEndpoint(
+ fail_close_once=fail_parent_close_once
+ )
+ self.child = _ConstructionEndpoint()
+ self.process = _NeverStartedProcess()
+
+ def Pipe( # noqa: N802
+ self,
+ *,
+ duplex: bool,
+ ) -> tuple[object, object]:
+ del duplex
+ return self.parent, self.child
+
+ def Process( # noqa: N802
+ self,
+ **_kwargs: object,
+ ) -> _NeverStartedProcess:
+ return self.process
+
+
+async def test_worker_pipe_construction_failure_leaves_no_owned_resource(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(
+ multiprocessing,
+ "get_context",
+ lambda _method: _PipeFailureContext(),
+ )
+ caught: Exception | None = None
+ try:
+ await _run_worker({"mode": "success"}, timeout=1.0)
+ except RuntimeError as error:
+ caught = error
+ failed_closed = (
+ type(caught) is RuntimeError
+ and str(caught)
+ == "Alembic worker startup failed [_WorkerConstructionError]"
+ and bool(getattr(caught, "__suppress_context__", False))
+ and not _OWNED_WORKERS
+ )
+ _require_fixed(
+ failed_closed,
+ "Pipe construction failure leaked worker ownership",
+ )
+
+
+async def test_worker_partial_pipe_result_closes_obtained_endpoint(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ context = _PartialPipeFailureContext()
+ monkeypatch.setattr(
+ multiprocessing,
+ "get_context",
+ lambda _method: context,
+ )
+ caught: Exception | None = None
+ try:
+ await _run_worker({"mode": "success"}, timeout=1.0)
+ except RuntimeError as error:
+ caught = error
+ failed_closed = (
+ type(caught) is RuntimeError
+ and context.endpoint.closed
+ and not _OWNED_WORKERS
+ )
+ _require_fixed(
+ failed_closed,
+ "partial Pipe construction leaked its obtained endpoint",
+ )
+
+
+async def test_worker_process_construction_failure_closes_both_endpoints(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ context = _ProcessFailureContext()
+ monkeypatch.setattr(
+ multiprocessing,
+ "get_context",
+ lambda _method: context,
+ )
+ caught: Exception | None = None
+ try:
+ await _run_worker({"mode": "success"}, timeout=1.0)
+ except RuntimeError as error:
+ caught = error
+ process_arguments_are_control_only = (
+ context.process_kwargs is not None
+ and context.process_kwargs.get("target") is _alembic_worker_entry
+ and context.process_kwargs.get("args") == (context.child,)
+ and context.process_kwargs.get("name") == "ares-alembic-worker"
+ and set(context.process_kwargs) == {"target", "args", "name"}
+ )
+ failed_closed = (
+ type(caught) is RuntimeError
+ and context.parent.closed
+ and context.child.closed
+ and process_arguments_are_control_only
+ and not _OWNED_WORKERS
+ )
+ _require_fixed(
+ failed_closed,
+ "Process construction failure did not close Pipe endpoints",
+ )
+
+
+async def test_worker_start_failure_before_child_creation_is_settled(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ context = _StartFailureContext()
+ monkeypatch.setattr(
+ multiprocessing,
+ "get_context",
+ lambda _method: context,
+ )
+ caught: Exception | None = None
+ try:
+ await _run_worker({"mode": "success"}, timeout=1.0)
+ except RuntimeError as error:
+ caught = error
+ settled = (
+ type(caught) is RuntimeError
+ and context.process.start_called
+ and context.process.closed
+ and context.parent.closed
+ and context.child.closed
+ and not _OWNED_WORKERS
+ )
+ _require_fixed(
+ settled,
+ "pre-child start failure did not settle all owned resources",
+ )
+
+
+async def test_worker_start_failure_preserves_fixed_primary_when_close_fails(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ context = _StartFailureContext(fail_parent_close_once=True)
+ monkeypatch.setattr(
+ multiprocessing,
+ "get_context",
+ lambda _method: context,
+ )
+ caught: Exception | None = None
+ try:
+ await _run_worker({"mode": "success"}, timeout=1.0)
+ except RuntimeError as error:
+ caught = error
+ retained = tuple(_OWNED_WORKERS)
+ primary_preserved = (
+ type(caught) is RuntimeError
+ and str(caught)
+ == "Alembic worker startup failed [_WorkerStartError]"
+ and tuple(getattr(caught, "__notes__", ()))
+ == (
+ "Alembic worker cleanup failed "
+ "[settle-startup-worker: RuntimeError]",
+ )
+ and len(retained) == 1
+ )
+ if retained:
+ await _settle_worker(retained[0], terminate=True)
+ _require_fixed(
+ primary_preserved and not _OWNED_WORKERS,
+ "startup cleanup failure replaced its fixed primary failure",
+ )
+
+
+class _AmbiguousStartProcess:
+ def __init__(self, process: Any) -> None:
+ self._process = process
+ self._closed = False
+ self._final_exitcode: int | None = None
+
+ def start(self) -> None:
+ self._process.start()
+ raise _WorkerStartError
+
+ @property
+ def exitcode(self) -> int | None:
+ if self._closed:
+ return self._final_exitcode
+ return self._process.exitcode
+
+ def is_alive(self) -> bool:
+ return False if self._closed else bool(self._process.is_alive())
+
+ def close(self) -> None:
+ self._final_exitcode = self._process.exitcode
+ self._process.close()
+ self._closed = True
+
+ def __getattr__(self, name: str) -> object:
+ return getattr(self._process, name)
+
+
+class _AmbiguousStartContext:
+ def __init__(self, context: Any) -> None:
+ self._context = context
+ self.endpoints: tuple[Any, Any] | None = None
+ self.process: _AmbiguousStartProcess | None = None
+
+ def Pipe(self, *, duplex: bool) -> tuple[Any, Any]: # noqa: N802
+ self.endpoints = self._context.Pipe(duplex=duplex)
+ return self.endpoints
+
+ def Process( # noqa: N802
+ self,
+ **kwargs: object,
+ ) -> _AmbiguousStartProcess:
+ self.process = _AmbiguousStartProcess(
+ self._context.Process(**kwargs)
+ )
+ return self.process
+
+
+async def test_worker_ambiguous_start_failure_settles_real_child(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ real_context = multiprocessing.get_context("spawn")
+ context = _AmbiguousStartContext(real_context)
+ monkeypatch.setattr(
+ multiprocessing,
+ "get_context",
+ lambda _method: context,
+ )
+ caught: Exception | None = None
+ try:
+ await _run_worker({"mode": "success"}, timeout=1.0)
+ except RuntimeError as error:
+ caught = error
+ endpoints_closed = (
+ context.endpoints is not None
+ and all(endpoint.closed for endpoint in context.endpoints)
+ )
+ child_settled = (
+ context.process is not None
+ and context.process.exitcode is not None
+ and not context.process.is_alive()
+ )
+ _require_fixed(
+ type(caught) is RuntimeError
+ and endpoints_closed
+ and child_settled
+ and not _OWNED_WORKERS,
+ "ambiguous Process.start failure left a live child or endpoint",
+ )
+
+
+class _FakeWorkerChannel:
+ def __init__(self) -> None:
+ self.closed = False
+
+ def close(self) -> None:
+ self.closed = True
+
+
+class _FakeWorkerProcess:
+ def __init__(self, *, kill_succeeds: bool) -> None:
+ self.pid = 1
+ self.exitcode: int | None = None
+ self._alive = True
+ self._kill_succeeds = kill_succeeds
+ self.terminate_called = False
+ self.kill_called = False
+ self.closed = False
+
+ def is_alive(self) -> bool:
+ return self._alive
+
+ def join(self, timeout: float = 0) -> None:
+ del timeout
+
+ def terminate(self) -> None:
+ self.terminate_called = True
+
+ def kill(self) -> None:
+ self.kill_called = True
+ if self._kill_succeeds:
+ self._alive = False
+ self.exitcode = -9
+
+ def close(self) -> None:
+ self.closed = True
+
+
+async def test_worker_settlement_escalates_from_terminate_to_kill(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(
+ sys.modules[__name__],
+ "_WORKER_SETTLE_SECONDS",
+ 0.02,
+ )
+ process = _FakeWorkerProcess(kill_succeeds=True)
+ worker = _OwnedWorker(process=process, channel=_FakeWorkerChannel())
+ _OWNED_WORKERS.add(worker)
+ exit_code = await _settle_worker(worker, terminate=True)
+ _require_fixed(
+ process.terminate_called
+ and process.kill_called
+ and process.closed
+ and exit_code == -9
+ and worker not in _OWNED_WORKERS,
+ "worker settlement did not escalate and release ownership",
+ )
+
+
+async def test_unproven_worker_death_retains_ownership_and_blocks_cleanup(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(
+ sys.modules[__name__],
+ "_WORKER_SETTLE_SECONDS",
+ 0.02,
+ )
+ process = _FakeWorkerProcess(kill_succeeds=False)
+ worker = _OwnedWorker(process=process, channel=_FakeWorkerChannel())
+ _OWNED_WORKERS.add(worker)
+ failed = False
+ try:
+ await _settle_worker(worker, terminate=True)
+ except RuntimeError:
+ failed = True
+ cleanup_failures: list[str] = []
+ cleanup_allowed = await _settle_owned_workers_for_cleanup(
+ cleanup_failures
+ )
+ retained = worker in _OWNED_WORKERS
+ process._alive = False
+ process.exitcode = -9
+ await _settle_worker(worker, terminate=True)
+ _require_fixed(
+ failed
+ and not cleanup_allowed
+ and retained
+ and bool(cleanup_failures)
+ and worker not in _OWNED_WORKERS,
+ "unproven worker death did not retain ownership and block cleanup",
+ )
+
+
+async def test_empty_postgres_base_to_0006_uses_only_alembic() -> None:
+ async with _postgres_harness() as harness:
+ connection = await _connect(harness)
+ try:
+ initial_tables = await connection.fetchval(
+ """
+ SELECT count(*)
+ FROM information_schema.tables
+ WHERE table_schema=current_schema()
+ AND table_type='BASE TABLE'
+ """
+ )
+ no_alembic_version = (
+ await connection.fetchval(
+ "SELECT to_regclass('alembic_version') IS NULL"
+ )
+ is True
+ )
+ finally:
+ await connection.close()
+
+ _require_fixed(
+ initial_tables == 0 and no_alembic_version,
+ "disposable PostgreSQL database was not genuinely empty",
+ )
+ await _alembic(harness, "upgrade", "0006")
+
+ connection = await _connect(harness)
+ try:
+ tables = {
+ str(row["table_name"])
+ for row in await connection.fetch(
+ """
+ SELECT table_name
+ FROM information_schema.tables
+ WHERE table_schema=current_schema()
+ AND table_type='BASE TABLE'
+ """
+ )
+ }
+ reached_revision = await _version(connection) == "0006"
+ migration_only_tables = (
+ tables == _EXPECTED_TABLES | {"alembic_version"}
+ )
+ finally:
+ await connection.close()
+
+ _require_fixed(
+ reached_revision,
+ "PostgreSQL did not reach revision 0006",
+ )
+ _require_fixed(
+ migration_only_tables,
+ "PostgreSQL migration-created table contract diverged",
+ )
+
+
+async def test_explicit_postgres_target_excludes_environment_decoy(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ async with _postgres_harness() as selected:
+ async with _postgres_harness() as decoy:
+ distinct_safe_targets = (
+ selected.database_name != decoy.database_name
+ and selected.database_name
+ != selected.config.maintenance_database
+ and decoy.database_name != decoy.config.maintenance_database
+ and _SAFE_DATABASE_NAME.fullmatch(selected.database_name)
+ is not None
+ and _SAFE_DATABASE_NAME.fullmatch(decoy.database_name)
+ is not None
+ )
+ _require_fixed(
+ distinct_safe_targets,
+ "PostgreSQL target isolation identifiers were unsafe",
+ )
+ maintenance_before = await _database_fingerprint(
+ selected.config,
+ selected.config.maintenance_database,
+ )
+ selected_before = await _database_fingerprint(
+ selected.config,
+ selected.database_name,
+ )
+ decoy_before = await _database_fingerprint(
+ decoy.config,
+ decoy.database_name,
+ )
+ empty_baselines = (
+ _isolation_fingerprint_has_no_ares_state(selected_before)
+ and _isolation_fingerprint_has_no_ares_state(decoy_before)
+ )
+ _require_fixed(
+ empty_baselines,
+ "PostgreSQL isolation baselines were not empty",
+ )
+ decoy_url = _migration_url(
+ decoy.config,
+ decoy.database_name,
+ ordinary_driver=True,
+ )
+ monkeypatch.setenv("ARES_DATABASE_URL", decoy_url)
+
+ await _alembic(selected, "upgrade", "0004")
+ selected_after_upgrade = await _database_fingerprint(
+ selected.config,
+ selected.database_name,
+ )
+ revision_after_upgrade = await _database_revision(
+ selected.config,
+ selected.database_name,
+ )
+ decoy_after_upgrade = await _database_fingerprint(
+ decoy.config,
+ decoy.database_name,
+ )
+ maintenance_after_upgrade = await _database_fingerprint(
+ selected.config,
+ selected.config.maintenance_database,
+ )
+
+ await _alembic(selected, "upgrade", "0004")
+ selected_after_repeat = await _database_fingerprint(
+ selected.config,
+ selected.database_name,
+ )
+ revision_after_repeat = await _database_revision(
+ selected.config,
+ selected.database_name,
+ )
+ decoy_after_repeat = await _database_fingerprint(
+ decoy.config,
+ decoy.database_name,
+ )
+ maintenance_after_repeat = await _database_fingerprint(
+ selected.config,
+ selected.config.maintenance_database,
+ )
+
+ await _alembic(selected, "downgrade", "0003")
+ selected_after_downgrade = await _database_fingerprint(
+ selected.config,
+ selected.database_name,
+ )
+ revision_after_downgrade = await _database_revision(
+ selected.config,
+ selected.database_name,
+ )
+ decoy_after_downgrade = await _database_fingerprint(
+ decoy.config,
+ decoy.database_name,
+ )
+ maintenance_after_downgrade = await _database_fingerprint(
+ selected.config,
+ selected.config.maintenance_database,
+ )
+
+ await _alembic(selected, "upgrade", "0004")
+ selected_after_reupgrade = await _database_fingerprint(
+ selected.config,
+ selected.database_name,
+ )
+ revision_after_reupgrade = await _database_revision(
+ selected.config,
+ selected.database_name,
+ )
+ decoy_after_reupgrade = await _database_fingerprint(
+ decoy.config,
+ decoy.database_name,
+ )
+ maintenance_after_reupgrade = await _database_fingerprint(
+ selected.config,
+ selected.config.maintenance_database,
+ )
+
+ target_transitions_are_exact = (
+ selected_after_upgrade != selected_before
+ and revision_after_upgrade == "0004"
+ and selected_after_repeat == selected_after_upgrade
+ and revision_after_repeat == "0004"
+ and selected_after_downgrade != selected_after_upgrade
+ and revision_after_downgrade == "0003"
+ and selected_after_reupgrade == selected_after_upgrade
+ and revision_after_reupgrade == "0004"
+ )
+ decoy_remained_exact = all(
+ fingerprint == decoy_before
+ and _isolation_fingerprint_has_no_ares_state(fingerprint)
+ for fingerprint in (
+ decoy_after_upgrade,
+ decoy_after_repeat,
+ decoy_after_downgrade,
+ decoy_after_reupgrade,
+ )
+ )
+ maintenance_remained_exact = all(
+ fingerprint == maintenance_before
+ for fingerprint in (
+ maintenance_after_upgrade,
+ maintenance_after_repeat,
+ maintenance_after_downgrade,
+ maintenance_after_reupgrade,
+ )
+ )
+ _require_fixed(
+ target_transitions_are_exact
+ and decoy_remained_exact
+ and maintenance_remained_exact,
+ "explicit PostgreSQL migration target isolation failed",
+ )
+
+
+async def test_postgres_revision_round_trip_preserves_rows() -> None:
+ async with _postgres_harness() as harness:
+ for revision in ("0001", "0002", "0003", "0004", "0005"):
+ await _alembic(harness, "upgrade", revision)
+ connection = await _connect(harness)
+ try:
+ reached_revision = await _version(connection) == revision
+ if revision == "0001":
+ await connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES($1, $2)",
+ "campaign-a",
+ "Migration campaign",
+ )
+ await connection.execute(
+ """
+ INSERT INTO credentials(
+ id, campaign_id, username, cred_type, cracked_value
+ ) VALUES($1, $2, $3, $4, $5)
+ """,
+ "credential-a",
+ "campaign-a",
+ "synthetic-user",
+ "password",
+ "synthetic-encrypted-marker",
+ )
+ finally:
+ await connection.close()
+ _require_fixed(
+ reached_revision,
+ "PostgreSQL revision sequence stopped unexpectedly",
+ )
+
+ await _alembic(harness, "upgrade", "0006")
+ connection = await _connect(harness)
+ try:
+ upgrade_preserved = (
+ await connection.fetchval(
+ """
+ SELECT cracked_value_enc IS NOT NULL
+ FROM credentials WHERE id=$1
+ """,
+ "credential-a",
+ )
+ is True
+ )
+ finally:
+ await connection.close()
+ _require_fixed(
+ upgrade_preserved,
+ "PostgreSQL revision 0006 did not preserve the credential value",
+ )
+
+ await _alembic(harness, "downgrade", "0005")
+ connection = await _connect(harness)
+ try:
+ downgrade_preserved = (
+ await connection.fetchval(
+ """
+ SELECT cracked_value IS NOT NULL
+ FROM credentials WHERE id=$1
+ """,
+ "credential-a",
+ )
+ is True
+ )
+ finally:
+ await connection.close()
+ _require_fixed(
+ downgrade_preserved,
+ "PostgreSQL revision 0006 downgrade lost a credential value",
+ )
+
+ for revision in ("0004", "0003", "0002", "0001"):
+ await _alembic(harness, "downgrade", revision)
+ connection = await _connect(harness)
+ try:
+ reached_revision = await _version(connection) == revision
+ finally:
+ await connection.close()
+ _require_fixed(
+ reached_revision,
+ "PostgreSQL downgrade sequence stopped unexpectedly",
+ )
+
+ connection = await _connect(harness)
+ try:
+ parent_columns = {
+ str(row["column_name"])
+ for row in await connection.fetch(
+ """
+ SELECT column_name
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND table_name='findings'
+ """
+ )
+ }
+ finally:
+ await connection.close()
+ parent_is_repaired = (
+ {"cvss_score", "cvss_vector"}.issubset(parent_columns)
+ and "trace_id" not in parent_columns
+ )
+ _require_fixed(
+ parent_is_repaired,
+ "PostgreSQL revision 0002 downgrade contradicted its parent",
+ )
+
+ await _alembic(harness, "downgrade", "base")
+ connection = await _connect(harness)
+ try:
+ remaining_application_tables = await connection.fetchval(
+ """
+ SELECT count(*)
+ FROM information_schema.tables
+ WHERE table_schema=current_schema()
+ AND table_name = ANY($1::text[])
+ """,
+ list(_EXPECTED_TABLES),
+ )
+ finally:
+ await connection.close()
+ _require_fixed(
+ remaining_application_tables == 0,
+ "PostgreSQL downgrade to base retained an application table",
+ )
+
+ await _alembic(harness, "upgrade", "0006")
+
+
+async def test_postgres_downgrades_restore_exact_repaired_parents() -> None:
+ async with _postgres_harness() as harness:
+ await _alembic(harness, "upgrade", "0006")
+
+ parent_by_revision = {
+ "0006": "0005",
+ "0005": "0004",
+ "0004": "0003",
+ "0003": "0002",
+ "0002": "0001",
+ "0001": "base",
+ }
+ for _revision, parent in parent_by_revision.items():
+ await _alembic(harness, "downgrade", parent)
+ connection = await _connect(harness)
+ try:
+ actual = await _postgres_catalog_contract(connection)
+ finally:
+ await connection.close()
+ expected = _fixed_postgres_contract(parent)
+ _require_fixed(
+ actual == expected,
+ "PostgreSQL downgrade did not restore its repaired parent",
+ )
+
+
+async def test_postgres_0006_catalog_types_defaults_fks_and_indexes() -> None:
+ async with _postgres_harness() as harness:
+ await _alembic(harness, "upgrade", "0006")
+ connection = await _connect(harness)
+ try:
+ all_column_rows = await connection.fetch(
+ """
+ SELECT
+ table_name,
+ ordinal_position,
+ column_name,
+ data_type,
+ is_nullable
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND table_name = ANY($1::text[])
+ ORDER BY table_name, ordinal_position
+ """,
+ list(_EXPECTED_COLUMN_ORDER),
+ )
+ actual_columns: dict[str, list[tuple[str, str, str]]] = {}
+ for row in all_column_rows:
+ actual_columns.setdefault(
+ str(row["table_name"]),
+ [],
+ ).append(
+ (
+ str(row["column_name"]),
+ str(row["data_type"]),
+ str(row["is_nullable"]),
+ )
+ )
+ columns_are_exact = True
+ for table, expected_order in _EXPECTED_COLUMN_ORDER.items():
+ rows = actual_columns.get(table, [])
+ if tuple(row[0] for row in rows) != expected_order:
+ columns_are_exact = False
+ break
+ for name, data_type, nullable in rows:
+ key = (table, name)
+ if key in _POSTGRES_INTEGER_COLUMNS:
+ expected_type = "integer"
+ elif key in _POSTGRES_FLOAT_COLUMNS:
+ expected_type = "double precision"
+ elif key in _POSTGRES_TIMESTAMP_COLUMNS:
+ expected_type = "timestamp with time zone"
+ else:
+ expected_type = "text"
+ expected_nullable = (
+ "YES"
+ if key in _POSTGRES_NULLABLE_COLUMNS
+ else "NO"
+ )
+ if (
+ data_type != expected_type
+ or nullable != expected_nullable
+ ):
+ columns_are_exact = False
+ break
+ if not columns_are_exact:
+ break
+
+ sequence_defaults = {
+ (str(row["table_name"]), str(row["column_name"]))
+ for row in await connection.fetch(
+ """
+ SELECT table_name, column_name
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND column_default LIKE 'nextval(%'
+ """
+ )
+ }
+ sequence_contract_matches = sequence_defaults == {
+ ("audit_log", "id"),
+ ("rate_limit_events", "id"),
+ }
+ timestamp_rows = await connection.fetch(
+ """
+ SELECT table_name, column_name, data_type, column_default
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND (
+ (table_name='campaigns' AND column_name='created_at')
+ OR
+ (table_name='module_runs' AND column_name='completed_at')
+ OR
+ (table_name='findings' AND column_name='discovered_at')
+ OR
+ (table_name='rate_limit_events' AND column_name='timestamp')
+ OR
+ (
+ table_name='revoked_access_tokens'
+ AND column_name='revoked_at'
+ )
+ )
+ """
+ )
+ timestamps_are_aware = len(timestamp_rows) == 5 and all(
+ row["data_type"] == "timestamp with time zone"
+ and "now()" in str(row["column_default"]).lower()
+ for row in timestamp_rows
+ )
+ hardened_columns = await connection.fetchval(
+ """
+ SELECT count(*)
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND table_name='findings'
+ AND column_name = ANY(
+ ARRAY['cvss_score', 'cvss_vector', 'trace_id']
+ )
+ AND is_nullable='NO'
+ """
+ )
+ nullability_matches = hardened_columns == 3
+
+ foreign_key_rows = await connection.fetch(
+ """
+ SELECT
+ source.relname AS source_table,
+ source_column.attname AS source_column,
+ target.relname AS target_table,
+ CASE constraint.confdeltype
+ WHEN 'c' THEN 'CASCADE'
+ WHEN 'n' THEN 'SET NULL'
+ ELSE 'OTHER'
+ END AS delete_action
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS source
+ ON source.oid=constraint.conrelid
+ JOIN pg_class AS target
+ ON target.oid=constraint.confrelid
+ JOIN pg_attribute AS source_column
+ ON source_column.attrelid=source.oid
+ AND source_column.attnum=constraint.conkey[1]
+ WHERE constraint.contype='f'
+ AND source.relnamespace=current_schema()::regnamespace
+ """
+ )
+ foreign_keys = {
+ (
+ str(row["source_table"]),
+ str(row["source_column"]),
+ str(row["target_table"]),
+ str(row["delete_action"]),
+ )
+ for row in foreign_key_rows
+ }
+
+ index_rows = await connection.fetch(
+ """
+ SELECT
+ index_class.relname AS index_name,
+ array_agg(attribute.attname ORDER BY key.ordinality) AS columns
+ FROM pg_index AS index_catalog
+ JOIN pg_class AS table_class
+ ON table_class.oid=index_catalog.indrelid
+ JOIN pg_class AS index_class
+ ON index_class.oid=index_catalog.indexrelid
+ JOIN unnest(index_catalog.indkey)
+ WITH ORDINALITY AS key(attnum, ordinality)
+ ON key.attnum > 0
+ JOIN pg_attribute AS attribute
+ ON attribute.attrelid=table_class.oid
+ AND attribute.attnum=key.attnum
+ WHERE table_class.relnamespace=current_schema()::regnamespace
+ AND NOT index_catalog.indisprimary
+ AND NOT index_catalog.indisunique
+ GROUP BY index_class.relname
+ """,
+ )
+ indexes = {
+ str(row["index_name"]): tuple(row["columns"])
+ for row in index_rows
+ }
+ primary_key_tables = {
+ str(row["table_name"])
+ for row in await connection.fetch(
+ """
+ SELECT table_class.relname AS table_name
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS table_class
+ ON table_class.oid=constraint.conrelid
+ WHERE constraint.contype='p'
+ AND table_class.relnamespace=
+ current_schema()::regnamespace
+ """
+ )
+ }
+ primary_keys_match = primary_key_tables == _EXPECTED_TABLES
+ unique_contracts = {
+ str(row["constraint_name"])
+ for row in await connection.fetch(
+ """
+ SELECT constraint_name
+ FROM information_schema.table_constraints
+ WHERE table_schema=current_schema()
+ AND constraint_type='UNIQUE'
+ """
+ )
+ }
+ uniqueness_matches = unique_contracts == {
+ "uq_hosts_campaign_ip",
+ "uq_users_username",
+ }
+
+ fk_rejected = False
+ try:
+ await connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title, description, severity
+ ) VALUES($1, $2, $3, $4, $5, $6)
+ """,
+ "finding-a",
+ "missing-campaign",
+ "module-a",
+ "title",
+ "description",
+ "high",
+ )
+ except Exception as exc:
+ fk_rejected = type(exc).__name__ == "ForeignKeyViolationError"
+ reusable = await connection.fetchval("SELECT 1") == 1
+ finally:
+ await connection.close()
+
+ _require_fixed(
+ columns_are_exact,
+ "PostgreSQL ordered column/type/nullability contract diverged",
+ )
+ _require_fixed(
+ sequence_contract_matches,
+ "PostgreSQL sequence-backed identity contract diverged",
+ )
+ _require_fixed(
+ timestamps_are_aware,
+ "PostgreSQL timestamp/default contract diverged",
+ )
+ _require_fixed(
+ nullability_matches,
+ "PostgreSQL finding nullability contract diverged",
+ )
+ _require_fixed(
+ primary_keys_match,
+ "PostgreSQL primary-key contract diverged",
+ )
+ _require_fixed(
+ uniqueness_matches,
+ "PostgreSQL uniqueness contract diverged",
+ )
+ _require_fixed(
+ foreign_keys == _EXPECTED_FOREIGN_KEYS,
+ "PostgreSQL foreign-key contract diverged",
+ )
+ _require_fixed(
+ indexes == _EXPECTED_INDEXES,
+ "PostgreSQL logical index contract diverged",
+ )
+ _require_fixed(
+ fk_rejected,
+ "PostgreSQL did not enforce a required foreign key",
+ )
+ _require_fixed(
+ reusable,
+ "PostgreSQL connection was not reusable after a constraint error",
+ )
+
+
+async def test_postgres_all_timestamp_columns_reject_infinity() -> None:
+ async with _postgres_harness() as harness:
+ await _alembic(harness, "upgrade", "0006")
+ connection = await _connect(harness)
+ try:
+ await _seed_postgres_contract(connection)
+ constraint_rows = await connection.fetch(
+ """
+ SELECT
+ relation.relname AS table_name,
+ constraint.conname AS constraint_name,
+ pg_get_constraintdef(constraint.oid) AS definition
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS relation
+ ON relation.oid=constraint.conrelid
+ WHERE relation.relnamespace=current_schema()::regnamespace
+ AND constraint.contype='c'
+ """
+ )
+ observed_constraints = {
+ (
+ str(row["table_name"]),
+ str(row["constraint_name"]),
+ ): " ".join(
+ str(row["definition"]).lower().replace('"', "").split()
+ )
+ for row in constraint_rows
+ }
+ semantic_constraints_match = True
+ for (
+ table,
+ column,
+ ), (name, nullable) in (
+ _POSTGRES_FINITE_TIMESTAMP_CONSTRAINTS.items()
+ ):
+ definition = observed_constraints.get((table, name), "")
+ compact = definition.replace(" ", "").replace("(", "").replace(
+ ")", ""
+ )
+ has_finite = f"isfinite{column}" in compact
+ has_nullable = f"{column}isnullor" in compact
+ if not has_finite or has_nullable != nullable:
+ semantic_constraints_match = False
+ break
+
+ key_by_table = {
+ "campaigns": ("id", "campaign-contract"),
+ "module_runs": ("id", "run-contract"),
+ "findings": ("id", "finding-contract"),
+ "hosts": ("id", "host-contract"),
+ "credentials": ("id", "credential-contract"),
+ "loot": ("id", "loot-contract"),
+ "audit_log": ("id", 1),
+ "users": ("id", "user-contract"),
+ "api_keys": ("id", "api-key-contract"),
+ "refresh_tokens": ("id", "refresh-contract"),
+ "revoked_access_tokens": ("jti", "revoked-contract"),
+ "rate_limit_events": ("id", 1),
+ }
+ finite_value = datetime(2030, 1, 1, tzinfo=timezone.utc)
+ enforced_for_every_column = True
+ for (table, column), (_name, nullable) in sorted(
+ _POSTGRES_FINITE_TIMESTAMP_CONSTRAINTS.items()
+ ):
+ key_name, key_value = key_by_table[table]
+ update_finite = (
+ f'UPDATE "{table}" SET "{column}"=$1 ' # noqa: S608
+ f'WHERE "{key_name}"=$2'
+ )
+ await connection.execute(
+ update_finite,
+ finite_value,
+ key_value,
+ )
+ finite_applied = await connection.fetchval(
+ (
+ f'SELECT isfinite("{column}") FROM "{table}" ' # noqa: S608
+ f'WHERE "{key_name}"=$1'
+ ),
+ key_value,
+ )
+ positive_rejected = await _postgres_integrity_failure(
+ connection,
+ (
+ f'UPDATE "{table}" ' # noqa: S608
+ f'SET "{column}"=\'infinity\'::timestamptz '
+ f'WHERE "{key_name}"=$1'
+ ),
+ key_value,
+ expected_type="CheckViolationError",
+ )
+ positive_unchanged = await connection.fetchval(
+ (
+ f'SELECT isfinite("{column}") FROM "{table}" ' # noqa: S608
+ f'WHERE "{key_name}"=$1'
+ ),
+ key_value,
+ )
+ negative_rejected = await _postgres_integrity_failure(
+ connection,
+ (
+ f'UPDATE "{table}" ' # noqa: S608
+ f'SET "{column}"=\'-infinity\'::timestamptz '
+ f'WHERE "{key_name}"=$1'
+ ),
+ key_value,
+ expected_type="CheckViolationError",
+ )
+ negative_unchanged = await connection.fetchval(
+ (
+ f'SELECT isfinite("{column}") FROM "{table}" ' # noqa: S608
+ f'WHERE "{key_name}"=$1'
+ ),
+ key_value,
+ )
+ if nullable:
+ await connection.execute(
+ (
+ f'UPDATE "{table}" SET "{column}"=NULL ' # noqa: S608
+ f'WHERE "{key_name}"=$1'
+ ),
+ key_value,
+ )
+ null_contract = await connection.fetchval(
+ (
+ f'SELECT "{column}" IS NULL FROM "{table}" ' # noqa: S608
+ f'WHERE "{key_name}"=$1'
+ ),
+ key_value,
+ )
+ await connection.execute(
+ update_finite,
+ finite_value,
+ key_value,
+ )
+ else:
+ null_contract = await _postgres_integrity_failure(
+ connection,
+ (
+ f'UPDATE "{table}" SET "{column}"=NULL ' # noqa: S608
+ f'WHERE "{key_name}"=$1'
+ ),
+ key_value,
+ expected_type="NotNullViolationError",
+ )
+ if not all(
+ (
+ finite_applied is True,
+ positive_rejected,
+ positive_unchanged is True,
+ negative_rejected,
+ negative_unchanged is True,
+ null_contract is True,
+ )
+ ):
+ enforced_for_every_column = False
+ break
+ reusable = await connection.fetchval("SELECT 1") == 1
+ finally:
+ await connection.close()
+
+ _require_fixed(
+ semantic_constraints_match,
+ "PostgreSQL finite timestamp catalog contract diverged",
+ )
+ _require_fixed(
+ enforced_for_every_column and reusable,
+ "PostgreSQL finite timestamp enforcement diverged",
+ )
+
+
+async def test_postgres_0006_enforces_complete_relational_contract() -> None:
+ async with _postgres_harness() as harness:
+ await _alembic(harness, "upgrade", "0006")
+ connection = await _connect(harness)
+ try:
+ await _seed_postgres_contract(connection)
+ key_by_table = {
+ "campaigns": ("id", "campaign-contract"),
+ "module_runs": ("id", "run-contract"),
+ "findings": ("id", "finding-contract"),
+ "hosts": ("id", "host-contract"),
+ "credentials": ("id", "credential-contract"),
+ "loot": ("id", "loot-contract"),
+ "audit_log": ("id", 1),
+ "users": ("id", "user-contract"),
+ "api_keys": ("id", "api-key-contract"),
+ "refresh_tokens": ("id", "refresh-contract"),
+ "revoked_access_tokens": ("jti", "revoked-contract"),
+ "rate_limit_events": ("id", 1),
+ }
+
+ required_columns_rejected = True
+ for table, order in _EXPECTED_COLUMN_ORDER.items():
+ key_name, key_value = key_by_table[table]
+ for name in order:
+ if (table, name) in _POSTGRES_NULLABLE_COLUMNS:
+ continue
+ statement = (
+ f'UPDATE "{table}" SET "{name}"=NULL ' # noqa: S608
+ f'WHERE "{key_name}"=$1'
+ )
+ if not await _postgres_integrity_failure(
+ connection,
+ statement,
+ key_value,
+ expected_type="NotNullViolationError",
+ ):
+ required_columns_rejected = False
+ break
+
+ foreign_keys_rejected = True
+ for table, local, _remote, _action in sorted(
+ _EXPECTED_FOREIGN_KEYS
+ ):
+ key_name, key_value = key_by_table[table]
+ statement = (
+ f'UPDATE "{table}" SET "{local}"=$1 ' # noqa: S608
+ f'WHERE "{key_name}"=$2'
+ )
+ if not await _postgres_integrity_failure(
+ connection,
+ statement,
+ "missing-parent",
+ key_value,
+ expected_type="ForeignKeyViolationError",
+ ):
+ foreign_keys_rejected = False
+ break
+
+ duplicate_host_rejected = await _postgres_integrity_failure(
+ connection,
+ """
+ INSERT INTO hosts(id, campaign_id, ip_address)
+ VALUES($1, $2, $3)
+ """,
+ "host-duplicate",
+ "campaign-contract",
+ "192.0.2.10",
+ expected_type="UniqueViolationError",
+ )
+ duplicate_user_rejected = await _postgres_integrity_failure(
+ connection,
+ """
+ INSERT INTO users(id, username, hashed_password)
+ VALUES($1, $2, $3)
+ """,
+ "user-duplicate",
+ "synthetic-account",
+ "synthetic-hash",
+ expected_type="UniqueViolationError",
+ )
+
+ transaction = connection.transaction()
+ await transaction.start()
+ try:
+ await connection.execute(
+ "DELETE FROM hosts WHERE id=$1",
+ "host-contract",
+ )
+ set_null_rows = await connection.fetchrow(
+ """
+ SELECT
+ (SELECT host_id IS NULL FROM credentials WHERE id=$1)
+ AS credential_cleared,
+ (SELECT host_id IS NULL FROM loot WHERE id=$2)
+ AS loot_cleared
+ """,
+ "credential-contract",
+ "loot-contract",
+ )
+ set_null_enforced = (
+ set_null_rows is not None
+ and set_null_rows["credential_cleared"] is True
+ and set_null_rows["loot_cleared"] is True
+ )
+ finally:
+ await transaction.rollback()
+
+ transaction = connection.transaction()
+ await transaction.start()
+ try:
+ await connection.execute(
+ "DELETE FROM campaigns WHERE id=$1",
+ "campaign-contract",
+ )
+ campaign_actions = await connection.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM module_runs) AS runs,
+ (SELECT count(*) FROM findings) AS findings,
+ (SELECT count(*) FROM hosts) AS hosts,
+ (SELECT count(*) FROM credentials) AS credentials,
+ (SELECT count(*) FROM loot) AS loot,
+ (
+ SELECT campaign_id IS NULL
+ FROM audit_log
+ WHERE id=1
+ ) AS audit_cleared
+ """
+ )
+ campaign_actions_enforced = (
+ campaign_actions is not None
+ and tuple(campaign_actions.values())
+ == (0, 0, 0, 0, 0, True)
+ )
+ finally:
+ await transaction.rollback()
+
+ transaction = connection.transaction()
+ await transaction.start()
+ try:
+ await connection.execute(
+ "DELETE FROM users WHERE id=$1",
+ "user-contract",
+ )
+ user_actions = await connection.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM api_keys) AS api_keys,
+ (SELECT count(*) FROM refresh_tokens)
+ AS refresh_tokens
+ """
+ )
+ user_cascade_enforced = (
+ user_actions is not None
+ and tuple(user_actions.values()) == (0, 0)
+ )
+ finally:
+ await transaction.rollback()
+
+ timestamp_values = await connection.fetchrow(
+ """
+ SELECT
+ (SELECT created_at FROM campaigns LIMIT 1) AS campaign,
+ (SELECT completed_at FROM module_runs LIMIT 1) AS run,
+ (SELECT discovered_at FROM findings LIMIT 1) AS finding,
+ (SELECT first_seen FROM hosts LIMIT 1) AS host,
+ (SELECT captured_at FROM credentials LIMIT 1)
+ AS credential,
+ (SELECT captured_at FROM loot LIMIT 1) AS loot,
+ (SELECT timestamp FROM audit_log LIMIT 1) AS audit,
+ (SELECT created_at FROM users LIMIT 1) AS account,
+ (SELECT created_at FROM api_keys LIMIT 1) AS api_key,
+ (SELECT created_at FROM refresh_tokens LIMIT 1)
+ AS refresh,
+ (SELECT revoked_at FROM revoked_access_tokens LIMIT 1)
+ AS revoked,
+ (SELECT timestamp FROM rate_limit_events LIMIT 1)
+ AS rate_limit
+ """
+ )
+ timestamp_defaults_execute = (
+ timestamp_values is not None
+ and all(
+ isinstance(value, datetime)
+ and value.utcoffset() is not None
+ for value in timestamp_values.values()
+ )
+ )
+ integer_defaults_execute = (
+ await connection.fetchrow(
+ """
+ SELECT
+ (SELECT success=0 FROM module_runs LIMIT 1) AS run,
+ (
+ SELECT validated=0 AND false_positive=0
+ FROM findings LIMIT 1
+ ) AS finding,
+ (SELECT is_dc=0 FROM hosts LIMIT 1) AS host,
+ (SELECT cracked=0 FROM credentials LIMIT 1)
+ AS credential,
+ (SELECT is_active=1 FROM users LIMIT 1) AS account,
+ (SELECT is_active=1 FROM api_keys LIMIT 1) AS api_key,
+ (SELECT is_revoked=0 FROM refresh_tokens LIMIT 1)
+ AS refresh,
+ (SELECT blocked=0 FROM rate_limit_events LIMIT 1)
+ AS rate_limit
+ """
+ )
+ )
+ integer_defaults_match = (
+ integer_defaults_execute is not None
+ and all(integer_defaults_execute.values())
+ )
+
+ audit_second = await connection.fetchval(
+ """
+ INSERT INTO audit_log(action) VALUES($1)
+ RETURNING id
+ """,
+ "second-action",
+ )
+ await connection.execute(
+ "DELETE FROM audit_log WHERE id=$1",
+ audit_second,
+ )
+ audit_third = await connection.fetchval(
+ """
+ INSERT INTO audit_log(action) VALUES($1)
+ RETURNING id
+ """,
+ "third-action",
+ )
+ rate_second = await connection.fetchval(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES($1, $2)
+ RETURNING id
+ """,
+ "192.0.2.21",
+ "synthetic-bucket",
+ )
+ await connection.execute(
+ "DELETE FROM rate_limit_events WHERE id=$1",
+ rate_second,
+ )
+ rate_third = await connection.fetchval(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES($1, $2)
+ RETURNING id
+ """,
+ "192.0.2.22",
+ "synthetic-bucket",
+ )
+ monotonic_sequences = (
+ int(audit_third) > int(audit_second)
+ and int(rate_third) > int(rate_second)
+ )
+ finally:
+ await connection.close()
+
+ _require_fixed(
+ required_columns_rejected,
+ "PostgreSQL accepted NULL in a required column",
+ )
+ _require_fixed(
+ foreign_keys_rejected,
+ "PostgreSQL accepted an invalid foreign-key parent",
+ )
+ _require_fixed(
+ duplicate_host_rejected and duplicate_user_rejected,
+ "PostgreSQL uniqueness enforcement diverged",
+ )
+ _require_fixed(
+ set_null_enforced,
+ "PostgreSQL SET NULL behavior diverged",
+ )
+ _require_fixed(
+ campaign_actions_enforced and user_cascade_enforced,
+ "PostgreSQL cascade behavior diverged",
+ )
+ _require_fixed(
+ timestamp_defaults_execute,
+ "PostgreSQL aware timestamp defaults diverged",
+ )
+ _require_fixed(
+ integer_defaults_match,
+ "PostgreSQL integer defaults diverged",
+ )
+ _require_fixed(
+ monotonic_sequences,
+ "PostgreSQL sequence behavior diverged",
+ )
+
+
+async def test_postgres_0003_blocked_integer_contract_is_enforced() -> None:
+ async with _postgres_harness() as harness:
+ await _alembic(harness, "upgrade", "0003")
+ connection = await _connect(harness)
+ try:
+ await connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES($1, $2)
+ """,
+ "synthetic-a",
+ "bucket",
+ )
+ await connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket, blocked)
+ VALUES($1, $2, $3)
+ """,
+ "synthetic-b",
+ "bucket",
+ 0,
+ )
+ await connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket, blocked)
+ VALUES($1, $2, $3)
+ """,
+ "synthetic-c",
+ "bucket",
+ 1,
+ )
+ valid_contract = await connection.fetchrow(
+ """
+ SELECT count(*) AS row_count,
+ min(blocked) AS minimum,
+ max(blocked) AS maximum,
+ bool_and(timestamp IS NOT NULL) AS timestamps_present
+ FROM rate_limit_events
+ """
+ )
+ rejected = 0
+ for index, value in enumerate((None, -1, 2, 17)):
+ try:
+ await connection.execute(
+ """
+ INSERT INTO rate_limit_events(
+ ip_address, bucket, blocked
+ ) VALUES($1, $2, $3)
+ """,
+ f"synthetic-invalid-{index}",
+ "bucket",
+ value,
+ )
+ except Exception as exc:
+ if type(exc).__name__ in {
+ "CheckViolationError",
+ "NotNullViolationError",
+ }:
+ rejected += 1
+ invalid_rows = await connection.fetchval(
+ """
+ SELECT count(*) FROM rate_limit_events
+ WHERE ip_address LIKE 'synthetic-invalid-%'
+ """
+ )
+ check_definition = await connection.fetchval(
+ """
+ SELECT pg_get_constraintdef(constraint.oid)
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS relation
+ ON relation.oid=constraint.conrelid
+ WHERE relation.relname='rate_limit_events'
+ AND constraint.conname='ck_rate_limit_events_blocked_bool'
+ """
+ )
+ check_is_semantic = (
+ isinstance(check_definition, str)
+ and "blocked" in check_definition
+ and "= ANY" in check_definition
+ and "0" in check_definition
+ and "1" in check_definition
+ )
+ reusable = await connection.fetchval("SELECT 1") == 1
+ finally:
+ await connection.close()
+
+ valid_values = (
+ valid_contract is not None
+ and valid_contract["row_count"] == 3
+ and valid_contract["minimum"] == 0
+ and valid_contract["maximum"] == 1
+ and valid_contract["timestamps_present"] is True
+ )
+ _require_fixed(
+ valid_values
+ and rejected == 4
+ and invalid_rows == 0
+ and check_is_semantic
+ and reusable,
+ "PostgreSQL blocked integer contract was not enforced",
+ )
+
+ await _alembic(harness, "downgrade", "0002")
+ connection = await _connect(harness)
+ try:
+ removed = (
+ await connection.fetchval(
+ "SELECT to_regclass('rate_limit_events') IS NULL"
+ )
+ is True
+ )
+ finally:
+ await connection.close()
+ await _alembic(harness, "upgrade", "0003")
+ connection = await _connect(harness)
+ try:
+ reupgrade_rejected = False
+ try:
+ await connection.execute(
+ """
+ INSERT INTO rate_limit_events(
+ ip_address, bucket, blocked
+ ) VALUES($1, $2, $3)
+ """,
+ "synthetic-reupgrade",
+ "bucket",
+ 2,
+ )
+ except Exception as exc:
+ reupgrade_rejected = (
+ type(exc).__name__ == "CheckViolationError"
+ )
+ finally:
+ await connection.close()
+ _require_fixed(
+ removed and reupgrade_rejected,
+ "PostgreSQL 0003 downgrade/re-upgrade lost enforcement",
+ )
+
+
+async def test_postgres_0005_trace_normalization_round_trip() -> None:
+ async with _postgres_harness() as harness:
+ await _alembic(harness, "upgrade", "0004")
+ connection = await _connect(harness)
+ try:
+ await connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES($1, $2)",
+ "campaign-trace",
+ "Migration campaign",
+ )
+ for index, trace_value in enumerate((None, "", "trace-marker")):
+ await connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, trace_id
+ ) VALUES($1, $2, $3, $4, $5, $6, $7)
+ """,
+ f"finding-{index}",
+ "campaign-trace",
+ "module",
+ f"title-{index}",
+ "description",
+ "low",
+ trace_value,
+ )
+ finally:
+ await connection.close()
+
+ await _alembic(harness, "upgrade", "0005")
+ connection = await _connect(harness)
+ try:
+ upgraded = await connection.fetchrow(
+ """
+ SELECT count(*) AS row_count,
+ count(*) FILTER (WHERE trace_id IS NULL) AS null_count,
+ count(*) FILTER (WHERE trace_id='') AS empty_count,
+ count(*) FILTER (
+ WHERE trace_id='trace-marker'
+ ) AS marker_count,
+ count(DISTINCT title) AS title_count
+ FROM findings
+ """
+ )
+ finally:
+ await connection.close()
+ upgraded_correctly = (
+ upgraded is not None
+ and tuple(upgraded.values()) == (3, 0, 2, 1, 3)
+ )
+ _require_fixed(
+ upgraded_correctly,
+ "PostgreSQL trace normalization changed protected state",
+ )
+
+ await _alembic(harness, "downgrade", "0004")
+ connection = await _connect(harness)
+ try:
+ await connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, trace_id
+ ) VALUES($1, $2, $3, $4, $5, $6, NULL)
+ """,
+ "finding-after-downgrade",
+ "campaign-trace",
+ "module",
+ "title-after-downgrade",
+ "description",
+ "low",
+ )
+ finally:
+ await connection.close()
+ await _alembic(harness, "upgrade", "0005")
+ connection = await _connect(harness)
+ try:
+ reupgraded = await connection.fetchrow(
+ """
+ SELECT count(*) AS row_count,
+ count(*) FILTER (WHERE trace_id IS NULL) AS null_count,
+ count(*) FILTER (WHERE trace_id='') AS empty_count,
+ count(*) FILTER (
+ WHERE trace_id='trace-marker'
+ ) AS marker_count
+ FROM findings
+ """
+ )
+ finally:
+ await connection.close()
+ reupgraded_correctly = (
+ reupgraded is not None
+ and tuple(reupgraded.values()) == (4, 0, 3, 1)
+ )
+ _require_fixed(
+ reupgraded_correctly,
+ "PostgreSQL trace re-upgrade diverged",
+ )
+
+
+async def _install_postgres_version_failure(connection: Any) -> None:
+ await connection.execute(
+ """
+ CREATE OR REPLACE FUNCTION migration_version_failure()
+ RETURNS trigger
+ LANGUAGE plpgsql
+ AS $body$
+ BEGIN
+ RAISE EXCEPTION 'migration version update denied';
+ END;
+ $body$
+ """
+ )
+ await connection.execute(
+ """
+ CREATE TRIGGER migration_version_failure
+ BEFORE UPDATE ON alembic_version
+ FOR EACH ROW EXECUTE FUNCTION migration_version_failure()
+ """
+ )
+
+
+async def _remove_postgres_version_failure(connection: Any) -> None:
+ await connection.execute(
+ "DROP TRIGGER IF EXISTS migration_version_failure "
+ "ON alembic_version"
+ )
+ await connection.execute(
+ "DROP FUNCTION IF EXISTS migration_version_failure()"
+ )
+
+
[email protected]("direction", ["upgrade", "downgrade"])
+ "boundary",
+ ["before-hardening", "after-hardening", "version-update"],
+)
+async def test_postgres_0005_failure_boundaries_roll_back_atomically(
+ direction: str,
+ boundary: str,
+) -> None:
+ async with _postgres_harness() as harness:
+ starting_revision = "0004" if direction == "upgrade" else "0005"
+ result_revision = "0005" if direction == "upgrade" else "0004"
+ await _alembic(harness, "upgrade", starting_revision)
+ connection = await _connect(harness)
+ try:
+ await connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES($1, $2)",
+ "campaign-failure",
+ "Synthetic campaign",
+ )
+ await connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, trace_id
+ ) VALUES($1, $2, $3, $4, $5, $6, $7)
+ """,
+ "finding-failure",
+ "campaign-failure",
+ "module",
+ "Synthetic title",
+ "Synthetic description",
+ "low",
+ None if direction == "upgrade" else "",
+ )
+ before_contract = await _postgres_catalog_contract(connection)
+ before_rows = await connection.fetchrow(
+ """
+ SELECT
+ count(*) AS rows,
+ count(*) FILTER (WHERE trace_id IS NULL) AS nulls,
+ count(*) FILTER (WHERE trace_id='') AS empty_values
+ FROM findings
+ """
+ )
+ if boundary == "version-update":
+ await _install_postgres_version_failure(connection)
+ finally:
+ await connection.close()
+
+ fault = {
+ "before-hardening": "0005-before-alter",
+ "after-hardening": "0005-after-alter",
+ "version-update": None,
+ }[boundary]
+ failed = False
+ try:
+ if direction == "upgrade":
+ await _alembic(
+ harness,
+ "upgrade",
+ "0005",
+ fault=fault,
+ )
+ else:
+ await _alembic(
+ harness,
+ "downgrade",
+ "0004",
+ fault=fault,
+ )
+ except RuntimeError:
+ failed = True
+
+ connection = await _connect(harness)
+ try:
+ if boundary == "version-update":
+ await _remove_postgres_version_failure(connection)
+ after_contract = await _postgres_catalog_contract(connection)
+ after_rows = await connection.fetchrow(
+ """
+ SELECT
+ count(*) AS rows,
+ count(*) FILTER (WHERE trace_id IS NULL) AS nulls,
+ count(*) FILTER (WHERE trace_id='') AS empty_values
+ FROM findings
+ """
+ )
+ current_revision = await _version(connection)
+ reusable = await connection.fetchval("SELECT 1") == 1
+ finally:
+ await connection.close()
+ rolled_back = (
+ failed
+ and before_contract == after_contract
+ and before_rows is not None
+ and after_rows is not None
+ and tuple(before_rows.values()) == tuple(after_rows.values())
+ and current_revision == starting_revision
+ and reusable
+ )
+ _require_fixed(
+ rolled_back,
+ "PostgreSQL revision 0005 failure was not atomic",
+ )
+
+ if direction == "upgrade":
+ await _alembic(harness, "upgrade", "0005")
+ else:
+ await _alembic(harness, "downgrade", "0004")
+ connection = await _connect(harness)
+ try:
+ recovered = (
+ await _version(connection) == result_revision
+ and await _postgres_catalog_contract(connection)
+ == _fixed_postgres_contract(result_revision)
+ )
+ finally:
+ await connection.close()
+ _require_fixed(
+ recovered,
+ "PostgreSQL revision 0005 did not recover after rollback",
+ )
+
+
[email protected]("direction", ["upgrade", "downgrade"])
[email protected]("boundary", ["rename", "version-update"])
+async def test_postgres_0006_failure_after_rename_rolls_back_atomically(
+ direction: str,
+ boundary: str,
+) -> None:
+ async with _postgres_harness() as harness:
+ starting_revision = "0005" if direction == "upgrade" else "0006"
+ result_revision = "0006" if direction == "upgrade" else "0005"
+ source_column = (
+ "cracked_value"
+ if direction == "upgrade"
+ else "cracked_value_enc"
+ )
+ result_column = (
+ "cracked_value_enc"
+ if direction == "upgrade"
+ else "cracked_value"
+ )
+ await _alembic(harness, "upgrade", starting_revision)
+ connection = await _connect(harness)
+ try:
+ await connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES($1, $2)",
+ "campaign-rename",
+ "Synthetic campaign",
+ )
+ await connection.execute(
+ f"""
+ INSERT INTO credentials(
+ id, campaign_id, username, cred_type, "{source_column}"
+ ) VALUES($1, $2, $3, $4, $5)
+ """,
+ "credential-rename",
+ "campaign-rename",
+ "synthetic-user",
+ "password",
+ "synthetic-marker",
+ )
+ before_contract = await _postgres_catalog_contract(connection)
+ if boundary == "version-update":
+ await _install_postgres_version_failure(connection)
+ finally:
+ await connection.close()
+
+ failed = False
+ try:
+ if direction == "upgrade":
+ await _alembic(
+ harness,
+ "upgrade",
+ "0006",
+ fault=(
+ "0006-after-rename"
+ if boundary == "rename"
+ else None
+ ),
+ )
+ else:
+ await _alembic(
+ harness,
+ "downgrade",
+ "0005",
+ fault=(
+ "0006-after-rename"
+ if boundary == "rename"
+ else None
+ ),
+ )
+ except RuntimeError:
+ failed = True
+
+ connection = await _connect(harness)
+ try:
+ if boundary == "version-update":
+ await _remove_postgres_version_failure(connection)
+ after_contract = await _postgres_catalog_contract(connection)
+ source_value_query = (
+ "SELECT count(*) FROM credentials "
+ "WHERE cracked_value IS NOT NULL"
+ if source_column == "cracked_value"
+ else "SELECT count(*) FROM credentials "
+ "WHERE cracked_value_enc IS NOT NULL"
+ )
+ unchanged_value = await connection.fetchval(
+ source_value_query
+ )
+ current_revision = await _version(connection)
+ reusable = await connection.fetchval("SELECT 1") == 1
+ finally:
+ await connection.close()
+ _require_fixed(
+ failed
+ and before_contract == after_contract
+ and unchanged_value == 1
+ and current_revision == starting_revision
+ and reusable,
+ "PostgreSQL revision 0006 failure was not atomic",
+ )
+
+ if direction == "upgrade":
+ await _alembic(harness, "upgrade", "0006")
+ else:
+ await _alembic(harness, "downgrade", "0005")
+ connection = await _connect(harness)
+ try:
+ result_value_query = (
+ "SELECT count(*) FROM credentials "
+ "WHERE cracked_value IS NOT NULL"
+ if result_column == "cracked_value"
+ else "SELECT count(*) FROM credentials "
+ "WHERE cracked_value_enc IS NOT NULL"
+ )
+ recovered_value = await connection.fetchval(
+ result_value_query
+ )
+ recovered = (
+ await _version(connection) == result_revision
+ and await _postgres_catalog_contract(connection)
+ == _fixed_postgres_contract(result_revision)
+ and recovered_value == 1
+ )
+ finally:
+ await connection.close()
+ _require_fixed(
+ recovered,
+ "PostgreSQL revision 0006 did not recover after rollback",
+ )
+
+
+async def _transform_postgres_runtime_legacy_catalog(
+ connection: Any,
+ revision: str,
+) -> None:
+ recipe = _postgres_runtime_legacy_recipe(revision)
+ for table, name in recipe.constraints_to_drop:
+ await connection.execute(
+ f'ALTER TABLE "{table}" DROP CONSTRAINT "{name}"'
+ )
+ for table in recipe.tables_to_drop:
+ await connection.execute(f'DROP TABLE "{table}"')
+ for table, column in recipe.nullable_columns:
+ await connection.execute(
+ f'ALTER TABLE "{table}" ALTER COLUMN "{column}" DROP NOT NULL'
+ )
+ for name, table, columns in recipe.indexes_to_create:
+ rendered_columns = ", ".join(
+ f'"{column}"' for column in columns
+ )
+ await connection.execute(
+ f'CREATE INDEX "{name}" ON "{table}" ({rendered_columns})'
+ )
+
+
+async def _seed_postgres_legacy_catalog(
+ connection: Any,
+ revision: str,
+) -> None:
+ await connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES($1, $2)",
+ "legacy-campaign",
+ "Synthetic legacy campaign",
+ )
+ if revision >= "0002":
+ await connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, cvss_score, cvss_vector, trace_id
+ ) VALUES($1, $2, $3, $4, $5, $6, NULL, NULL, NULL)
+ """,
+ "legacy-finding",
+ "legacy-campaign",
+ "module",
+ "Synthetic finding",
+ "Synthetic description",
+ "low",
+ )
+ else:
+ await connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, cvss_score, cvss_vector
+ ) VALUES($1, $2, $3, $4, $5, $6, NULL, NULL)
+ """,
+ "legacy-finding",
+ "legacy-campaign",
+ "module",
+ "Synthetic finding",
+ "Synthetic description",
+ "low",
+ )
+ await connection.execute(
+ """
+ INSERT INTO hosts(id, campaign_id, ip_address)
+ VALUES($1, $2, $3)
+ """,
+ "legacy-host",
+ "legacy-campaign",
+ "192.0.2.70",
+ )
+ await connection.execute(
+ """
+ INSERT INTO credentials(
+ id, campaign_id, host_id, username, cred_type, cracked_value
+ ) VALUES($1, $2, $3, $4, $5, $6)
+ """,
+ "legacy-credential",
+ "legacy-campaign",
+ "legacy-host",
+ "synthetic-user",
+ "password",
+ "synthetic-marker",
+ )
+ await connection.execute(
+ """
+ INSERT INTO loot(id, campaign_id, host_id, loot_type, name)
+ VALUES($1, $2, $3, $4, $5)
+ """,
+ "legacy-loot",
+ "legacy-campaign",
+ "legacy-host",
+ "metadata",
+ "Synthetic loot",
+ )
+ await connection.execute(
+ "INSERT INTO audit_log(campaign_id, action) VALUES($1, $2)",
+ "legacy-campaign",
+ "synthetic-action",
+ )
+ await connection.execute(
+ """
+ INSERT INTO users(id, username, hashed_password)
+ VALUES($1, $2, $3)
+ """,
+ "legacy-user",
+ "synthetic-account",
+ "synthetic-hash",
+ )
+ await connection.execute(
+ """
+ INSERT INTO api_keys(id, user_id, name, key_hash, key_prefix)
+ VALUES($1, $2, $3, $4, $5)
+ """,
+ "legacy-api-key",
+ "legacy-user",
+ "Synthetic key",
+ "synthetic-hash",
+ "synthetic",
+ )
+ await connection.execute(
+ """
+ INSERT INTO refresh_tokens(id, user_id, expires_at)
+ VALUES($1, $2, $3)
+ """,
+ "legacy-refresh",
+ "legacy-user",
+ datetime(2099, 1, 1, tzinfo=timezone.utc),
+ )
+ if revision >= "0003":
+ await connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES($1, $2)
+ """,
+ "192.0.2.71",
+ "synthetic-bucket",
+ )
+ if revision >= "0004":
+ await connection.execute(
+ """
+ INSERT INTO revoked_access_tokens(jti, user_id, expires_at)
+ VALUES($1, $2, $3)
+ """,
+ "legacy-revoked",
+ "legacy-user",
+ datetime(2099, 1, 1, tzinfo=timezone.utc),
+ )
+
+
+ "legacy_revision",
+ ["0001", "0002", "0003", "0004", "0005"],
+)
+async def test_complete_postgres_runtime_legacy_catalogs_are_preserved(
+ legacy_revision: str,
+) -> None:
+ async with _postgres_harness() as harness:
+ await _alembic(harness, "upgrade", legacy_revision)
+ connection = await _connect(harness)
+ try:
+ await _transform_postgres_runtime_legacy_catalog(
+ connection,
+ legacy_revision,
+ )
+ await _seed_postgres_legacy_catalog(
+ connection,
+ legacy_revision,
+ )
+ initial_contract = await _postgres_catalog_contract(connection)
+ finally:
+ await connection.close()
+ _require_fixed(
+ initial_contract
+ == _fixed_legacy_postgres_contract(legacy_revision),
+ "constructed PostgreSQL legacy catalog diverged",
+ )
+
+ await _alembic(harness, "upgrade", "0006")
+ connection = await _connect(harness)
+ try:
+ row_counts = await connection.fetchrow(
+ """
+ SELECT
+ (SELECT count(*) FROM campaigns) AS campaigns,
+ (SELECT count(*) FROM findings) AS findings,
+ (SELECT count(*) FROM hosts) AS hosts,
+ (SELECT count(*) FROM credentials) AS credentials,
+ (SELECT count(*) FROM loot) AS loot,
+ (SELECT count(*) FROM audit_log) AS audit,
+ (SELECT count(*) FROM users) AS users,
+ (SELECT count(*) FROM api_keys) AS api_keys,
+ (SELECT count(*) FROM refresh_tokens) AS refresh_tokens
+ """
+ )
+ protected_value_present = await connection.fetchval(
+ """
+ SELECT count(*) FROM credentials
+ WHERE cracked_value_enc IS NOT NULL
+ """
+ )
+ structural_drift_deferred = (
+ await connection.fetchval(
+ "SELECT to_regclass('module_runs') IS NULL"
+ )
+ is True
+ and not (
+ await _postgres_catalog_contract(connection)
+ ).foreign_keys
+ )
+ current_revision = await _version(connection)
+ reusable = await connection.fetchval("SELECT 1") == 1
+ finally:
+ await connection.close()
+ preserved = (
+ row_counts is not None
+ and tuple(row_counts.values())
+ == (1, 1, 1, 1, 1, 1, 1, 1, 1)
+ and protected_value_present == 1
+ and structural_drift_deferred
+ and current_revision == "0006"
+ and reusable
+ )
+ _require_fixed(
+ preserved,
+ "PostgreSQL legacy catalog upgrade lost protected state",
+ )
+
+
+ ("revision", "column"),
+ [("0002", "cvss_score"), ("0005", "trace_id")],
+)
+async def test_postgres_legacy_missing_column_variants(
+ revision: str,
+ column: str,
+) -> None:
+ async with _postgres_harness() as harness:
+ parent = "0001" if revision == "0002" else "0004"
+ await _alembic(harness, "upgrade", parent)
+ connection = await _connect(harness)
+ try:
+ if revision == "0002":
+ await connection.execute(
+ "ALTER TABLE findings DROP COLUMN cvss_score"
+ )
+ await connection.execute(
+ "ALTER TABLE findings DROP COLUMN cvss_vector"
+ )
+ else:
+ await connection.execute(
+ "ALTER TABLE findings DROP COLUMN trace_id"
+ )
+ finally:
+ await connection.close()
+
+ await _alembic(harness, "upgrade", revision)
+ connection = await _connect(harness)
+ try:
+ repaired = (
+ await connection.fetchval(
+ """
+ SELECT count(*)
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND table_name='findings'
+ AND column_name=$1
+ AND is_nullable='NO'
+ """,
+ column,
+ )
+ == 1
+ )
+ finally:
+ await connection.close()
+ _require_fixed(
+ repaired,
+ "PostgreSQL legacy finding catalog was not reconciled",
+ )
+
+
+ "variant",
+ ["target-only", "both", "neither"],
+)
+async def test_postgres_0006_catalog_variants(variant: str) -> None:
+ async with _postgres_harness() as harness:
+ await _alembic(harness, "upgrade", "0005")
+ connection = await _connect(harness)
+ try:
+ if variant == "target-only":
+ await connection.execute(
+ "ALTER TABLE credentials "
+ "RENAME COLUMN cracked_value TO cracked_value_enc"
+ )
+ elif variant == "both":
+ await connection.execute(
+ "ALTER TABLE credentials ADD COLUMN cracked_value_enc TEXT"
+ )
+ else:
+ await connection.execute(
+ "ALTER TABLE credentials DROP COLUMN cracked_value"
+ )
+ finally:
+ await connection.close()
+
+ if variant == "target-only":
+ await _alembic(harness, "upgrade", "0006")
+ connection = await _connect(harness)
+ try:
+ accepted = await _version(connection) == "0006"
+ finally:
+ await connection.close()
+ _require_fixed(
+ accepted,
+ "PostgreSQL target-only catalog was not accepted",
+ )
+ return
+
+ with pytest.raises(
+ RuntimeError,
+ match="^Alembic worker failed \\[RuntimeError\\]$",
+ ):
+ await _alembic(harness, "upgrade", "0006")
+ connection = await _connect(harness)
+ try:
+ remained_at_parent = await _version(connection) == "0005"
+ reusable = await connection.fetchval("SELECT 1") == 1
+ finally:
+ await connection.close()
+ _require_fixed(
+ remained_at_parent,
+ "failed PostgreSQL revision advanced the Alembic version",
+ )
+ _require_fixed(
+ reusable,
+ "PostgreSQL connection was not reusable after migration failure",
+ )
+
+
+async def _postgres_credential_catalog_fingerprint(
+ connection: Any,
+) -> tuple[object, ...]:
+ columns = tuple(
+ tuple(row.values())
+ for row in await connection.fetch(
+ """
+ SELECT
+ column_name,
+ ordinal_position,
+ data_type,
+ udt_name,
+ is_nullable,
+ column_default,
+ is_identity
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND table_name='credentials'
+ ORDER BY ordinal_position
+ """
+ )
+ )
+ constraints = tuple(
+ tuple(row.values())
+ for row in await connection.fetch(
+ """
+ SELECT
+ constraint.conname,
+ constraint.contype,
+ pg_get_constraintdef(constraint.oid)
+ FROM pg_constraint AS constraint
+ JOIN pg_class AS relation
+ ON relation.oid=constraint.conrelid
+ WHERE relation.relnamespace=current_schema()::regnamespace
+ AND relation.relname='credentials'
+ ORDER BY constraint.conname
+ """
+ )
+ )
+ indexes = tuple(
+ tuple(row.values())
+ for row in await connection.fetch(
+ """
+ SELECT indexname, indexdef
+ FROM pg_indexes
+ WHERE schemaname=current_schema()
+ AND tablename='credentials'
+ ORDER BY indexname
+ """
+ )
+ )
+ return columns, constraints, indexes
+
+
+async def _prepare_postgres_0006_variant(
+ connection: Any,
+ *,
+ source: str,
+ target: str,
+ variant: str,
+) -> None:
+ if variant == "source-only":
+ return
+ if variant == "target-only":
+ await connection.execute(
+ f'ALTER TABLE credentials RENAME COLUMN "{source}" TO "{target}"'
+ )
+ return
+ if variant == "both":
+ await connection.execute(
+ f'ALTER TABLE credentials ADD COLUMN "{target}" TEXT'
+ )
+ return
+ if variant == "neither":
+ await connection.execute(
+ f'ALTER TABLE credentials DROP COLUMN "{source}"'
+ )
+ return
+ if variant.startswith("wrong-target-"):
+ await connection.execute(
+ f'ALTER TABLE credentials DROP COLUMN "{source}"'
+ )
+ inspected = target
+ if variant.endswith("-type"):
+ definition = "VARCHAR(64)"
+ elif variant.endswith("-nullability"):
+ definition = "TEXT NOT NULL"
+ elif variant.endswith("-default-null"):
+ definition = "TEXT DEFAULT NULL"
+ elif variant.endswith("-default"):
+ definition = "TEXT DEFAULT ''::text"
+ else:
+ raise AssertionError("unknown PostgreSQL target variant")
+ await connection.execute(
+ f'ALTER TABLE credentials ADD COLUMN "{inspected}" {definition}'
+ )
+ return
+ if variant.startswith("wrong-source-"):
+ if variant.endswith("-type"):
+ await connection.execute(
+ f'ALTER TABLE credentials ALTER COLUMN "{source}" '
+ "TYPE VARCHAR(64)"
+ )
+ elif variant.endswith("-nullability"):
+ await connection.execute(
+ f'ALTER TABLE credentials ALTER COLUMN "{source}" SET NOT NULL'
+ )
+ elif variant.endswith("-default-null"):
+ await connection.execute(
+ f'ALTER TABLE credentials ALTER COLUMN "{source}" '
+ "SET DEFAULT NULL"
+ )
+ elif variant.endswith("-default"):
+ await connection.execute(
+ f'ALTER TABLE credentials ALTER COLUMN "{source}" '
+ "SET DEFAULT ''::text"
+ )
+ else:
+ raise AssertionError("unknown PostgreSQL source variant")
+ return
+ raise AssertionError("unknown PostgreSQL revision 0006 variant")
+
+
[email protected]("direction", ["upgrade", "downgrade"])
+ "variant",
+ [
+ "source-only",
+ "target-only",
+ "both",
+ "neither",
+ "wrong-source-type",
+ "wrong-source-nullability",
+ "wrong-source-default",
+ "wrong-source-default-null",
+ "wrong-target-type",
+ "wrong-target-nullability",
+ "wrong-target-default",
+ "wrong-target-default-null",
+ ],
+)
+async def test_postgres_0006_exact_column_state_machine(
+ direction: str,
+ variant: str,
+) -> None:
+ async with _postgres_harness() as harness:
+ if direction == "upgrade":
+ await _alembic(harness, "upgrade", "0005")
+ source = "cracked_value"
+ target = "cracked_value_enc"
+ parent_revision = "0005"
+ result_revision = "0006"
+ else:
+ await _alembic(harness, "upgrade", "0006")
+ source = "cracked_value_enc"
+ target = "cracked_value"
+ parent_revision = "0006"
+ result_revision = "0005"
+
+ connection = await _connect(harness)
+ try:
+ await _prepare_postgres_0006_variant(
+ connection,
+ source=source,
+ target=target,
+ variant=variant,
+ )
+ present_columns = {
+ str(row["column_name"])
+ for row in await connection.fetch(
+ """
+ SELECT column_name
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND table_name='credentials'
+ """
+ )
+ }
+ value_column = (
+ source
+ if source in present_columns
+ else target if target in present_columns else None
+ )
+ await connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES($1, $2)",
+ "campaign-0006",
+ "Migration campaign",
+ )
+ if value_column == "cracked_value":
+ await connection.execute(
+ """
+ INSERT INTO credentials(
+ id, campaign_id, username, cred_type, cracked_value
+ ) VALUES($1, $2, $3, $4, $5)
+ """,
+ "credential-0006",
+ "campaign-0006",
+ "synthetic-user",
+ "password",
+ "synthetic-marker",
+ )
+ elif value_column == "cracked_value_enc":
+ await connection.execute(
+ """
+ INSERT INTO credentials(
+ id, campaign_id, username, cred_type, cracked_value_enc
+ ) VALUES($1, $2, $3, $4, $5)
+ """,
+ "credential-0006",
+ "campaign-0006",
+ "synthetic-user",
+ "password",
+ "synthetic-marker",
+ )
+ before_catalog = await _postgres_credential_catalog_fingerprint(
+ connection
+ )
+ before_rows = await connection.fetchval(
+ "SELECT count(*) FROM credentials"
+ )
+ finally:
+ await connection.close()
+
+ failed = False
+ try:
+ if direction == "upgrade":
+ await _alembic(harness, "upgrade", "0006")
+ else:
+ await _alembic(harness, "downgrade", "0005")
+ except RuntimeError:
+ failed = True
+
+ connection = await _connect(harness)
+ try:
+ after_catalog = await _postgres_credential_catalog_fingerprint(
+ connection
+ )
+ after_rows = await connection.fetchval(
+ "SELECT count(*) FROM credentials"
+ )
+ target_definition = await connection.fetchrow(
+ """
+ SELECT data_type, udt_name, is_nullable, column_default
+ FROM information_schema.columns
+ WHERE table_schema=current_schema()
+ AND table_name='credentials'
+ AND column_name=$1
+ """,
+ target,
+ )
+ target_is_exact = (
+ target_definition is not None
+ and target_definition["data_type"] == "text"
+ and target_definition["udt_name"] == "text"
+ and target_definition["is_nullable"] == "YES"
+ and target_definition["column_default"] is None
+ )
+ if target == "cracked_value_enc":
+ preserved = (
+ await connection.fetchval(
+ """
+ SELECT count(*) FROM credentials
+ WHERE cracked_value_enc IS NOT NULL
+ """
+ )
+ == 1
+ )
+ else:
+ preserved = (
+ await connection.fetchval(
+ """
+ SELECT count(*) FROM credentials
+ WHERE cracked_value IS NOT NULL
+ """
+ )
+ == 1
+ )
+ current_revision = await _version(connection)
+ reusable = await connection.fetchval("SELECT 1") == 1
+ finally:
+ await connection.close()
+
+ allowed = variant in {"source-only", "target-only"}
+ if allowed:
+ _require_fixed(
+ not failed
+ and current_revision == result_revision
+ and target_is_exact
+ and preserved
+ and reusable,
+ "PostgreSQL revision 0006 rejected an exact catalog",
+ )
+ else:
+ _require_fixed(
+ failed
+ and current_revision == parent_revision
+ and before_catalog == after_catalog
+ and before_rows == after_rows
+ and reusable,
+ "PostgreSQL revision 0006 changed an incompatible catalog",
+ )
diff --git a/tests/unit/test_migration_portability.py b/tests/unit/test_migration_portability.py
new file mode 100644
index 0000000..ff6f364
--- /dev/null
+++ b/tests/unit/test_migration_portability.py
@@ -0,0 +1,5905 @@
+"""SQLite execution tests for the portable historical Alembic chain."""
+from __future__ import annotations
+
+import argparse
+import importlib
+import importlib.machinery
+import os
+import re
+import sqlite3
+import sys
+import types
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import pytest
+from alembic import command
+from alembic.config import Config
+from sqlalchemy.engine import URL
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_EXPECTED_APP_TABLES = {
+ "campaigns",
+ "module_runs",
+ "findings",
+ "hosts",
+ "credentials",
+ "loot",
+ "audit_log",
+ "users",
+ "api_keys",
+ "refresh_tokens",
+ "revoked_access_tokens",
+ "rate_limit_events",
+}
+_EXPECTED_COLUMNS = {
+ "campaigns": {
+ "id",
+ "name",
+ "client",
+ "operator",
+ "noise_profile",
+ "status",
+ "scope_json",
+ "targets_json",
+ "notes",
+ "created_at",
+ "updated_at",
+ },
+ "module_runs": {
+ "id",
+ "campaign_id",
+ "module_id",
+ "outcome",
+ "success",
+ "duration_ms",
+ "completed_at",
+ },
+ "findings": {
+ "id",
+ "campaign_id",
+ "module_id",
+ "title",
+ "description",
+ "severity",
+ "confidence",
+ "mitre_technique",
+ "mitre_tactic",
+ "cvss_score",
+ "cvss_vector",
+ "trace_id",
+ "evidence_json",
+ "remediation",
+ "host",
+ "validated",
+ "false_positive",
+ "discovered_at",
+ },
+ "hosts": {
+ "id",
+ "campaign_id",
+ "ip_address",
+ "hostname",
+ "fqdn",
+ "os",
+ "os_version",
+ "domain",
+ "is_dc",
+ "open_ports_json",
+ "tags_json",
+ "first_seen",
+ "last_seen",
+ },
+ "credentials": {
+ "id",
+ "campaign_id",
+ "host_id",
+ "username",
+ "secret_enc",
+ "cred_type",
+ "domain",
+ "source_module",
+ "notes",
+ "cracked",
+ "cracked_value_enc",
+ "captured_at",
+ },
+ "loot": {
+ "id",
+ "campaign_id",
+ "host_id",
+ "loot_type",
+ "name",
+ "description",
+ "content_enc",
+ "size_bytes",
+ "path_on_target",
+ "source_module",
+ "tags_json",
+ "captured_at",
+ },
+ "audit_log": {
+ "id",
+ "campaign_id",
+ "actor",
+ "action",
+ "detail",
+ "module_id",
+ "timestamp",
+ },
+ "users": {
+ "id",
+ "username",
+ "hashed_password",
+ "role",
+ "is_active",
+ "created_by",
+ "created_at",
+ "last_login",
+ },
+ "api_keys": {
+ "id",
+ "user_id",
+ "name",
+ "key_hash",
+ "key_prefix",
+ "scopes",
+ "is_active",
+ "last_used",
+ "expires_at",
+ "created_at",
+ },
+ "refresh_tokens": {
+ "id",
+ "user_id",
+ "is_revoked",
+ "expires_at",
+ "created_at",
+ "used_at",
+ },
+ "revoked_access_tokens": {
+ "jti",
+ "user_id",
+ "revoked_at",
+ "expires_at",
+ },
+ "rate_limit_events": {
+ "id",
+ "ip_address",
+ "bucket",
+ "username",
+ "blocked",
+ "timestamp",
+ },
+}
+_EXPECTED_COLUMN_ORDER = {
+ "campaigns": (
+ "id",
+ "name",
+ "client",
+ "operator",
+ "noise_profile",
+ "status",
+ "scope_json",
+ "targets_json",
+ "notes",
+ "created_at",
+ "updated_at",
+ ),
+ "module_runs": (
+ "id",
+ "campaign_id",
+ "module_id",
+ "outcome",
+ "success",
+ "duration_ms",
+ "completed_at",
+ ),
+ "findings": (
+ "id",
+ "campaign_id",
+ "module_id",
+ "title",
+ "description",
+ "severity",
+ "confidence",
+ "mitre_technique",
+ "mitre_tactic",
+ "cvss_score",
+ "cvss_vector",
+ "evidence_json",
+ "remediation",
+ "host",
+ "validated",
+ "false_positive",
+ "discovered_at",
+ "trace_id",
+ ),
+ "hosts": (
+ "id",
+ "campaign_id",
+ "ip_address",
+ "hostname",
+ "fqdn",
+ "os",
+ "os_version",
+ "domain",
+ "is_dc",
+ "open_ports_json",
+ "tags_json",
+ "first_seen",
+ "last_seen",
+ ),
+ "credentials": (
+ "id",
+ "campaign_id",
+ "host_id",
+ "username",
+ "secret_enc",
+ "cred_type",
+ "domain",
+ "source_module",
+ "notes",
+ "cracked",
+ "cracked_value_enc",
+ "captured_at",
+ ),
+ "loot": (
+ "id",
+ "campaign_id",
+ "host_id",
+ "loot_type",
+ "name",
+ "description",
+ "content_enc",
+ "size_bytes",
+ "path_on_target",
+ "source_module",
+ "tags_json",
+ "captured_at",
+ ),
+ "audit_log": (
+ "id",
+ "campaign_id",
+ "actor",
+ "action",
+ "detail",
+ "module_id",
+ "timestamp",
+ ),
+ "users": (
+ "id",
+ "username",
+ "hashed_password",
+ "role",
+ "is_active",
+ "created_by",
+ "created_at",
+ "last_login",
+ ),
+ "api_keys": (
+ "id",
+ "user_id",
+ "name",
+ "key_hash",
+ "key_prefix",
+ "scopes",
+ "is_active",
+ "last_used",
+ "expires_at",
+ "created_at",
+ ),
+ "refresh_tokens": (
+ "id",
+ "user_id",
+ "is_revoked",
+ "expires_at",
+ "created_at",
+ "used_at",
+ ),
+ "revoked_access_tokens": (
+ "jti",
+ "user_id",
+ "revoked_at",
+ "expires_at",
+ ),
+ "rate_limit_events": (
+ "id",
+ "ip_address",
+ "bucket",
+ "username",
+ "blocked",
+ "timestamp",
+ ),
+}
+_EXPECTED_SQLITE_COLUMN_FINGERPRINTS = {
+ "campaigns": (
+ ("id", "TEXT", 1, None, 1),
+ ("name", "TEXT", 1, None, 0),
+ ("client", "TEXT", 1, "'Internal'", 0),
+ ("operator", "TEXT", 1, "'unknown'", 0),
+ ("noise_profile", "TEXT", 1, "'stealth'", 0),
+ ("status", "TEXT", 1, "'created'", 0),
+ ("scope_json", "TEXT", 1, "'[]'", 0),
+ ("targets_json", "TEXT", 1, "'[]'", 0),
+ ("notes", "TEXT", 0, "''", 0),
+ ("created_at", "TEXT", 1, "datetime('now')", 0),
+ ("updated_at", "TEXT", 1, "datetime('now')", 0),
+ ),
+ "module_runs": (
+ ("id", "TEXT", 1, None, 1),
+ ("campaign_id", "TEXT", 1, None, 0),
+ ("module_id", "TEXT", 1, None, 0),
+ ("outcome", "TEXT", 1, None, 0),
+ ("success", "INTEGER", 1, "'0'", 0),
+ ("duration_ms", "FLOAT", 1, "'0.0'", 0),
+ ("completed_at", "TEXT", 1, "datetime('now')", 0),
+ ),
+ "findings": (
+ ("id", "TEXT", 1, None, 1),
+ ("campaign_id", "TEXT", 1, None, 0),
+ ("module_id", "TEXT", 1, None, 0),
+ ("title", "TEXT", 1, None, 0),
+ ("description", "TEXT", 1, None, 0),
+ ("severity", "TEXT", 1, None, 0),
+ ("confidence", "FLOAT", 1, "'1.0'", 0),
+ ("mitre_technique", "TEXT", 0, None, 0),
+ ("mitre_tactic", "TEXT", 0, None, 0),
+ ("cvss_score", "FLOAT", 1, "'0.0'", 0),
+ ("cvss_vector", "TEXT", 1, "''", 0),
+ ("evidence_json", "TEXT", 1, "'{}'", 0),
+ ("remediation", "TEXT", 0, "''", 0),
+ ("host", "TEXT", 0, None, 0),
+ ("validated", "INTEGER", 1, "'0'", 0),
+ ("false_positive", "INTEGER", 1, "'0'", 0),
+ ("discovered_at", "TEXT", 1, "datetime('now')", 0),
+ ("trace_id", "TEXT", 1, "''", 0),
+ ),
+ "hosts": (
+ ("id", "TEXT", 1, None, 1),
+ ("campaign_id", "TEXT", 1, None, 0),
+ ("ip_address", "TEXT", 1, None, 0),
+ ("hostname", "TEXT", 0, None, 0),
+ ("fqdn", "TEXT", 0, None, 0),
+ ("os", "TEXT", 0, None, 0),
+ ("os_version", "TEXT", 0, None, 0),
+ ("domain", "TEXT", 0, None, 0),
+ ("is_dc", "INTEGER", 1, "'0'", 0),
+ ("open_ports_json", "TEXT", 1, "'[]'", 0),
+ ("tags_json", "TEXT", 1, "'[]'", 0),
+ ("first_seen", "TEXT", 1, "datetime('now')", 0),
+ ("last_seen", "TEXT", 1, "datetime('now')", 0),
+ ),
+ "credentials": (
+ ("id", "TEXT", 1, None, 1),
+ ("campaign_id", "TEXT", 1, None, 0),
+ ("host_id", "TEXT", 0, None, 0),
+ ("username", "TEXT", 1, None, 0),
+ ("secret_enc", "TEXT", 0, None, 0),
+ ("cred_type", "TEXT", 1, None, 0),
+ ("domain", "TEXT", 0, None, 0),
+ ("source_module", "TEXT", 0, None, 0),
+ ("notes", "TEXT", 0, "''", 0),
+ ("cracked", "INTEGER", 1, "'0'", 0),
+ ("cracked_value_enc", "TEXT", 0, None, 0),
+ ("captured_at", "TEXT", 1, "datetime('now')", 0),
+ ),
+ "loot": (
+ ("id", "TEXT", 1, None, 1),
+ ("campaign_id", "TEXT", 1, None, 0),
+ ("host_id", "TEXT", 0, None, 0),
+ ("loot_type", "TEXT", 1, None, 0),
+ ("name", "TEXT", 1, None, 0),
+ ("description", "TEXT", 0, "''", 0),
+ ("content_enc", "TEXT", 0, None, 0),
+ ("size_bytes", "INTEGER", 0, "'0'", 0),
+ ("path_on_target", "TEXT", 0, None, 0),
+ ("source_module", "TEXT", 0, None, 0),
+ ("tags_json", "TEXT", 1, "'[]'", 0),
+ ("captured_at", "TEXT", 1, "datetime('now')", 0),
+ ),
+ "audit_log": (
+ ("id", "INTEGER", 1, None, 1),
+ ("campaign_id", "TEXT", 0, None, 0),
+ ("actor", "TEXT", 1, "'system'", 0),
+ ("action", "TEXT", 1, None, 0),
+ ("detail", "TEXT", 0, "''", 0),
+ ("module_id", "TEXT", 0, None, 0),
+ ("timestamp", "TEXT", 1, "datetime('now')", 0),
+ ),
+ "users": (
+ ("id", "TEXT", 1, None, 1),
+ ("username", "TEXT", 1, None, 0),
+ ("hashed_password", "TEXT", 1, None, 0),
+ ("role", "TEXT", 1, "'reporter'", 0),
+ ("is_active", "INTEGER", 1, "'1'", 0),
+ ("created_by", "TEXT", 1, "'system'", 0),
+ ("created_at", "TEXT", 1, "datetime('now')", 0),
+ ("last_login", "TEXT", 0, None, 0),
+ ),
+ "api_keys": (
+ ("id", "TEXT", 1, None, 1),
+ ("user_id", "TEXT", 1, None, 0),
+ ("name", "TEXT", 1, None, 0),
+ ("key_hash", "TEXT", 1, None, 0),
+ ("key_prefix", "TEXT", 1, None, 0),
+ ("scopes", "TEXT", 1, "'read'", 0),
+ ("is_active", "INTEGER", 1, "'1'", 0),
+ ("last_used", "TEXT", 0, None, 0),
+ ("expires_at", "TEXT", 0, None, 0),
+ ("created_at", "TEXT", 1, "datetime('now')", 0),
+ ),
+ "refresh_tokens": (
+ ("id", "TEXT", 1, None, 1),
+ ("user_id", "TEXT", 1, None, 0),
+ ("is_revoked", "INTEGER", 1, "'0'", 0),
+ ("expires_at", "TEXT", 1, None, 0),
+ ("created_at", "TEXT", 1, "datetime('now')", 0),
+ ("used_at", "TEXT", 0, None, 0),
+ ),
+ "revoked_access_tokens": (
+ ("jti", "TEXT", 1, None, 1),
+ ("user_id", "TEXT", 1, None, 0),
+ ("revoked_at", "TEXT", 1, "datetime('now')", 0),
+ ("expires_at", "TEXT", 1, None, 0),
+ ),
+ "rate_limit_events": (
+ ("id", "INTEGER", 1, None, 1),
+ ("ip_address", "TEXT", 1, None, 0),
+ ("bucket", "TEXT", 1, None, 0),
+ ("username", "TEXT", 0, None, 0),
+ ("blocked", "INTEGER", 1, "'0'", 0),
+ ("timestamp", "TEXT", 1, "datetime('now')", 0),
+ ),
+}
+_EXPECTED_UNIQUE_CONSTRAINTS = {
+ ("hosts", ("campaign_id", "ip_address")),
+ ("users", ("username",)),
+}
+_EXPECTED_INDEXES = {
+ "idx_module_runs_campaign": ("module_runs", ("campaign_id",)),
+ "idx_module_runs_completed": ("module_runs", ("completed_at",)),
+ "idx_findings_campaign": ("findings", ("campaign_id",)),
+ "idx_findings_severity": ("findings", ("severity",)),
+ "idx_findings_fp": ("findings", ("false_positive",)),
+ "idx_findings_mitre": ("findings", ("mitre_technique",)),
+ "idx_findings_cvss": ("findings", ("cvss_score",)),
+ "idx_hosts_campaign": ("hosts", ("campaign_id",)),
+ "idx_hosts_ip": ("hosts", ("ip_address",)),
+ "idx_hosts_domain": ("hosts", ("domain",)),
+ "idx_creds_campaign": ("credentials", ("campaign_id",)),
+ "idx_creds_username": ("credentials", ("username",)),
+ "idx_creds_type": ("credentials", ("cred_type",)),
+ "idx_loot_campaign": ("loot", ("campaign_id",)),
+ "idx_loot_type": ("loot", ("loot_type",)),
+ "idx_audit_campaign": ("audit_log", ("campaign_id",)),
+ "idx_audit_actor": ("audit_log", ("actor",)),
+ "idx_audit_action": ("audit_log", ("action",)),
+ "idx_users_username": ("users", ("username",)),
+ "idx_users_role": ("users", ("role",)),
+ "idx_apikeys_user": ("api_keys", ("user_id",)),
+ "idx_apikeys_prefix": ("api_keys", ("key_prefix",)),
+ "idx_refresh_user": ("refresh_tokens", ("user_id",)),
+ "idx_refresh_exp": ("refresh_tokens", ("expires_at",)),
+ "idx_rat_expires": ("revoked_access_tokens", ("expires_at",)),
+ "idx_rle_ip": ("rate_limit_events", ("ip_address",)),
+ "idx_rle_timestamp": ("rate_limit_events", ("timestamp",)),
+ "idx_rle_blocked": ("rate_limit_events", ("blocked",)),
+}
+_EXPECTED_FOREIGN_KEYS = {
+ ("module_runs", "campaign_id", "campaigns", "id", "CASCADE"),
+ ("findings", "campaign_id", "campaigns", "id", "CASCADE"),
+ ("hosts", "campaign_id", "campaigns", "id", "CASCADE"),
+ ("credentials", "campaign_id", "campaigns", "id", "CASCADE"),
+ ("credentials", "host_id", "hosts", "id", "SET NULL"),
+ ("loot", "campaign_id", "campaigns", "id", "CASCADE"),
+ ("loot", "host_id", "hosts", "id", "SET NULL"),
+ ("audit_log", "campaign_id", "campaigns", "id", "SET NULL"),
+ ("api_keys", "user_id", "users", "id", "CASCADE"),
+ ("refresh_tokens", "user_id", "users", "id", "CASCADE"),
+}
+
+
+@dataclass(frozen=True)
+class _CatalogContract:
+ tables: tuple[str, ...]
+ columns: tuple[
+ tuple[str, tuple[tuple[str, str, int, object, int], ...]], ...
+ ]
+ primary_keys: tuple[tuple[str, tuple[str, ...]], ...]
+ unique_constraints: tuple[tuple[str, tuple[str, ...]], ...]
+ checks: tuple[tuple[str, str, str], ...]
+ foreign_keys: tuple[
+ tuple[str, str, str, str, str, str], ...
+ ]
+ indexes: tuple[
+ tuple[str, str, tuple[str, ...], bool, str | None], ...
+ ]
+ autoincrement_tables: tuple[str, ...]
+
+
+def _require_fixed(condition: bool, message: str) -> None:
+ if not condition:
+ pytest.fail(message, pytrace=False)
+
+
+def _requires_candidate_origin(name: str) -> bool:
+ return (
+ name in {"ares", "migrations", "tests.unit", "tests.integration"}
+ or name.startswith(("ares.", "migrations."))
+ or name.startswith(("tests.unit.", "tests.integration."))
+ )
+
+
+def _path_is_within_candidate(path: object, candidate_root: Path) -> bool:
+ try:
+ resolved_path = os.path.normcase(
+ str(Path(path).resolve(strict=False))
+ )
+ resolved_root = os.path.normcase(
+ str(candidate_root.resolve(strict=True))
+ )
+ return os.path.commonpath((resolved_path, resolved_root)) == (
+ resolved_root
+ )
+ except (OSError, RuntimeError, TypeError, ValueError):
+ return False
+
+
+def _module_origin_is_candidate_local(
+ module: object,
+ candidate_root: Path,
+) -> bool:
+ spec = getattr(module, "__spec__", None)
+ concrete_origins: list[object] = []
+ module_file = getattr(module, "__file__", None)
+ if module_file is not None:
+ concrete_origins.append(module_file)
+ spec_origin = getattr(spec, "origin", None)
+ if spec_origin not in {None, "built-in", "frozen"}:
+ concrete_origins.append(spec_origin)
+ concrete_is_local = not concrete_origins or all(
+ _path_is_within_candidate(origin, candidate_root)
+ for origin in concrete_origins
+ )
+
+ search_locations = getattr(spec, "submodule_search_locations", None)
+ if search_locations is None:
+ search_locations = getattr(module, "__path__", None)
+ if search_locations is None:
+ locations_are_local = True
+ has_locations = False
+ else:
+ locations = tuple(search_locations)
+ has_locations = bool(locations)
+ locations_are_local = has_locations and all(
+ _path_is_within_candidate(location, candidate_root)
+ for location in locations
+ )
+ return (
+ concrete_is_local
+ and locations_are_local
+ and (bool(concrete_origins) or has_locations)
+ )
+
+
+def _spec_origin_is_candidate_local(
+ spec: object,
+ candidate_root: Path,
+) -> bool:
+ concrete_origins: list[object] = []
+ spec_origin = getattr(spec, "origin", None)
+ if spec_origin not in {None, "built-in", "frozen"}:
+ concrete_origins.append(spec_origin)
+ concrete_is_local = not concrete_origins or all(
+ _path_is_within_candidate(origin, candidate_root)
+ for origin in concrete_origins
+ )
+ search_locations = getattr(spec, "submodule_search_locations", None)
+ if search_locations is None:
+ locations_are_local = True
+ has_locations = False
+ else:
+ locations = tuple(search_locations)
+ has_locations = bool(locations)
+ locations_are_local = has_locations and all(
+ _path_is_within_candidate(location, candidate_root)
+ for location in locations
+ )
+ return (
+ concrete_is_local
+ and locations_are_local
+ and (bool(concrete_origins) or has_locations)
+ )
+
+
+def _relative_path_is_first_party(relative_path: Path) -> bool:
+ folded_parts = tuple(part.casefold() for part in relative_path.parts)
+ if not folded_parts:
+ return False
+ if folded_parts[0] in {"ares", "migrations"}:
+ return True
+ return (
+ len(folded_parts) >= 2
+ and folded_parts[:2] in {("tests", "unit"), ("tests", "integration")}
+ )
+
+
+def _frame_file_is_first_party(
+ module_file: object,
+ candidate_root: Path,
+) -> bool:
+ if not isinstance(module_file, (str, os.PathLike)):
+ return False
+ try:
+ resolved_file = Path(module_file).resolve()
+ except (OSError, RuntimeError, TypeError, ValueError):
+ return False
+ for root in (candidate_root, _REPO_ROOT):
+ try:
+ relative_path = resolved_file.relative_to(root.resolve())
+ except ValueError:
+ continue
+ if _relative_path_is_first_party(relative_path):
+ return True
+ folded_parts = tuple(part.casefold() for part in resolved_file.parts)
+ if len(folded_parts) >= 2 and folded_parts[-2:] == (
+ "migrations",
+ "env.py",
+ ):
+ return True
+ return (
+ len(folded_parts) >= 3
+ and folded_parts[-3:-1] == ("migrations", "versions")
+ and re.fullmatch(r"[0-9]{4}_[a-z0-9_]+\.py", folded_parts[-1])
+ is not None
+ )
+
+
+def _frame_is_first_party(
+ frame: types.FrameType,
+ candidate_root: Path,
+) -> bool:
+ globals_map = frame.f_globals
+ name = globals_map.get("__name__")
+ package = globals_map.get("__package__")
+ if isinstance(name, str) and _requires_candidate_origin(name):
+ return True
+ if isinstance(package, str) and _requires_candidate_origin(package):
+ return True
+ return _frame_file_is_first_party(
+ globals_map.get("__file__"),
+ candidate_root,
+ )
+
+
+class _CandidateOriginFinder:
+ def __init__(
+ self,
+ ledger: _CandidateOriginLedger,
+ delegates: tuple[object, ...],
+ ) -> None:
+ self._ledger = ledger
+ self._delegates = delegates
+
+ def find_spec(
+ self,
+ fullname: str,
+ path: object = None,
+ target: object = None,
+ ) -> object:
+ for finder in self._delegates:
+ find_spec = getattr(finder, "find_spec", None)
+ if find_spec is None:
+ continue
+ spec = find_spec(fullname, path, target)
+ if spec is not None:
+ self._ledger.observe_spec(fullname, spec)
+ return spec
+ return None
+
+
+@dataclass(slots=True, repr=False)
+class _CandidateOriginLedger:
+ candidate_root: Path
+ isolated: bool = False
+ violated: bool = False
+ _finder: _CandidateOriginFinder | None = field(
+ default=None,
+ init=False,
+ repr=False,
+ )
+ _previous_profile: object = field(default=None, init=False, repr=False)
+ _profile_callback: object = field(default=None, init=False, repr=False)
+ _previous_meta_path: tuple[object, ...] | None = field(
+ default=None,
+ init=False,
+ repr=False,
+ )
+ _observed_frame_origins: set[
+ tuple[
+ types.CodeType,
+ int,
+ str | None,
+ str | None,
+ str | None,
+ ]
+ ] = field(
+ default_factory=set,
+ init=False,
+ repr=False,
+ )
+
+ def observe_spec(self, name: str, spec: object) -> None:
+ if _requires_candidate_origin(name) and not (
+ _spec_origin_is_candidate_local(spec, self.candidate_root)
+ ):
+ self.violated = True
+
+ def observe_modules(self, modules: object) -> None:
+ if not _loaded_first_party_origins_are_candidate_local(
+ modules,
+ self.candidate_root,
+ ):
+ self.violated = True
+
+ def _profile(
+ self,
+ frame: types.FrameType,
+ event: str,
+ arg: object,
+ ) -> None:
+ if event == "call":
+ globals_map = frame.f_globals
+ raw_file = globals_map.get("__file__")
+ try:
+ normalized_file = (
+ os.fspath(raw_file)
+ if isinstance(raw_file, (str, os.PathLike))
+ else None
+ )
+ except TypeError:
+ normalized_file = None
+ raw_name = globals_map.get("__name__")
+ raw_package = globals_map.get("__package__")
+ observation = (
+ frame.f_code,
+ id(globals_map),
+ raw_name if isinstance(raw_name, str) else None,
+ raw_package if isinstance(raw_package, str) else None,
+ normalized_file,
+ )
+ if observation not in self._observed_frame_origins:
+ self._observed_frame_origins.add(observation)
+ if _frame_is_first_party(frame, self.candidate_root):
+ module_file = frame.f_globals.get("__file__")
+ if module_file is None or not _path_is_within_candidate(
+ module_file,
+ self.candidate_root,
+ ):
+ self.violated = True
+ previous = self._previous_profile
+ if not self.isolated and callable(previous):
+ previous(frame, event, arg)
+
+ def install(self) -> None:
+ self._previous_meta_path = tuple(sys.meta_path)
+ delegates = tuple(
+ finder
+ for finder in self._previous_meta_path
+ if not isinstance(finder, _CandidateOriginFinder)
+ )
+ self._finder = _CandidateOriginFinder(self, delegates)
+ sys.meta_path.insert(0, self._finder)
+ self._previous_profile = sys.getprofile()
+ self._profile_callback = self._profile
+ sys.setprofile(self._profile_callback)
+
+ def installed_exactly(self) -> bool:
+ return (
+ self._finder is not None
+ and bool(sys.meta_path)
+ and sys.meta_path[0] is self._finder
+ and sys.getprofile() is self._profile_callback
+ )
+
+ def close(self) -> None:
+ previous_meta_path = self._previous_meta_path
+ if previous_meta_path is not None:
+ sys.meta_path[:] = previous_meta_path
+ sys.setprofile(self._previous_profile)
+ self._finder = None
+ self._profile_callback = None
+ self._previous_profile = None
+ self._previous_meta_path = None
+ self._observed_frame_origins.clear()
+
+
+_ACTIVE_ORIGIN_LEDGERS: list[_CandidateOriginLedger] = []
+
+
+def _loaded_first_party_origins_are_candidate_local(
+ modules: object,
+ candidate_root: Path,
+) -> bool:
+ try:
+ loaded = tuple(modules.items())
+ except AttributeError:
+ return False
+ for name, module in loaded:
+ if not isinstance(name, str) or not _requires_candidate_origin(name):
+ continue
+ if module is None or not _module_origin_is_candidate_local(
+ module,
+ candidate_root,
+ ):
+ return False
+ return True
+
+
+def _assert_candidate_origin_boundary(
+ ledger: _CandidateOriginLedger | None = None,
+) -> None:
+ ledgers = (
+ (ledger,)
+ if ledger is not None
+ else tuple(_ACTIVE_ORIGIN_LEDGERS)
+ )
+ for active_ledger in ledgers:
+ active_ledger.observe_modules(sys.modules)
+ resolved_locally = (
+ _path_is_within_candidate(__file__, _REPO_ROOT)
+ and all(
+ not active_ledger.violated
+ and active_ledger.installed_exactly()
+ for active_ledger in ledgers
+ )
+ and _loaded_first_party_origins_are_candidate_local(
+ sys.modules,
+ _REPO_ROOT,
+ )
+ )
+ _require_fixed(
+ resolved_locally,
+ "first-party migration test import escaped the source candidate",
+ )
+
+
+@contextmanager
+def _candidate_origin_boundary(
+ *,
+ isolated: bool = False,
+) -> Iterator[_CandidateOriginLedger]:
+ ledger = _CandidateOriginLedger(_REPO_ROOT, isolated=isolated)
+ ledger.install()
+ _ACTIVE_ORIGIN_LEDGERS.append(ledger)
+ try:
+ _assert_candidate_origin_boundary(ledger)
+ yield ledger
+ finally:
+ try:
+ _assert_candidate_origin_boundary(ledger)
+ finally:
+ for index in range(len(_ACTIVE_ORIGIN_LEDGERS) - 1, -1, -1):
+ if _ACTIVE_ORIGIN_LEDGERS[index] is ledger:
+ del _ACTIVE_ORIGIN_LEDGERS[index]
+ break
+ ledger.close()
+
+
[email protected](scope="module", autouse=True)
+def _final_candidate_origin_boundary() -> Iterator[None]:
+ with _candidate_origin_boundary():
+ yield
+
+
+def test_migration_test_process_resolves_first_party_code_locally() -> None:
+ _assert_candidate_origin_boundary()
+
+
+def _synthetic_module(
+ name: str,
+ *,
+ origin: Path | None = None,
+ search_locations: tuple[Path, ...] | None = None,
+) -> types.ModuleType:
+ module = types.ModuleType(name)
+ if search_locations is None:
+ spec = importlib.machinery.ModuleSpec(
+ name,
+ loader=None,
+ origin=None if origin is None else str(origin),
+ )
+ if origin is not None:
+ module.__file__ = str(origin)
+ else:
+ spec = importlib.machinery.ModuleSpec(
+ name,
+ loader=None,
+ is_package=True,
+ )
+ spec.submodule_search_locations = [
+ str(location) for location in search_locations
+ ]
+ module.__path__ = list(spec.submodule_search_locations)
+ module.__spec__ = spec
+ return module
+
+
+def test_candidate_origin_guard_rejects_dirty_only_first_party_modules(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ with TemporaryDirectory(prefix="ares-origin-tripwire-") as directory:
+ dirty_root = Path(directory)
+ dirty_ares_file = dirty_root / "ares" / "dirty_only_probe.py"
+ dirty_ares_file.parent.mkdir(parents=True)
+ dirty_ares_file.write_text("", encoding="utf-8")
+ dirty_migration_root = (
+ dirty_root / "migrations" / "versions" / "dirty_only_probe"
+ )
+ dirty_migration_root.mkdir(parents=True)
+ dirty_modules = {
+ "ares.dirty_only_probe": _synthetic_module(
+ "ares.dirty_only_probe",
+ origin=dirty_ares_file,
+ ),
+ "migrations.versions.dirty_only_probe": _synthetic_module(
+ "migrations.versions.dirty_only_probe",
+ search_locations=(dirty_migration_root,),
+ ),
+ }
+ for name, module in dirty_modules.items():
+ monkeypatch.setitem(sys.modules, name, module)
+ dirty_counterparts_absent = all(
+ not _REPO_ROOT.joinpath(*name.split(".")).with_suffix(
+ ".py"
+ ).exists()
+ and not _REPO_ROOT.joinpath(
+ *name.split("."),
+ "__init__.py",
+ ).exists()
+ for name in dirty_modules
+ )
+ guard_rejected = not (
+ _loaded_first_party_origins_are_candidate_local(
+ sys.modules,
+ _REPO_ROOT,
+ )
+ )
+ _require_fixed(
+ dirty_counterparts_absent and guard_rejected,
+ "candidate origin guard accepted a dirty-only first-party module",
+ )
+
+
+def test_candidate_origin_guard_handles_namespace_policy_without_false_positives(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ with TemporaryDirectory(prefix="ares-origin-third-party-") as directory:
+ external_root = Path(directory)
+ local_namespace = _synthetic_module(
+ "tests.unit.candidate_namespace_probe",
+ search_locations=(_REPO_ROOT / "tests" / "unit",),
+ )
+ third_party_namespace = _synthetic_module(
+ "third_party_namespace.probe",
+ search_locations=(external_root,),
+ )
+ monkeypatch.setitem(
+ sys.modules,
+ "tests.unit.candidate_namespace_probe",
+ local_namespace,
+ )
+ monkeypatch.setitem(
+ sys.modules,
+ "third_party_namespace.probe",
+ third_party_namespace,
+ )
+ accepted = _loaded_first_party_origins_are_candidate_local(
+ sys.modules,
+ _REPO_ROOT,
+ )
+ _require_fixed(
+ accepted,
+ "candidate origin guard rejected an allowed namespace module",
+ )
+
+
+ ("name", "namespace"),
+ [
+ ("ares.late_dirty_probe", False),
+ ("migrations.versions.late_dirty_probe", True),
+ ("ares.db.websocket_tickets", False),
+ ("migrations.versions.0007_add_websocket_tickets", False),
+ ],
+ ids=(
+ "late-ares-module",
+ "late-migration-namespace",
+ "late-ticket-module",
+ "late-0007-module",
+ ),
+)
+def test_final_candidate_origin_boundary_rejects_late_dirty_imports(
+ monkeypatch: pytest.MonkeyPatch,
+ name: str,
+ namespace: bool,
+) -> None:
+ _assert_candidate_origin_boundary()
+ with TemporaryDirectory(prefix="ares-final-origin-") as directory:
+ external_root = Path(directory)
+ if namespace:
+ module = _synthetic_module(
+ name,
+ search_locations=(external_root,),
+ )
+ else:
+ module_path = external_root / "late_dirty_probe.py"
+ module_path.write_text("", encoding="utf-8")
+ module = _synthetic_module(name, origin=module_path)
+ monkeypatch.setitem(sys.modules, name, module)
+ rejected = not _loaded_first_party_origins_are_candidate_local(
+ sys.modules,
+ _REPO_ROOT,
+ )
+ _require_fixed(
+ rejected,
+ "final candidate origin boundary accepted a late dirty import",
+ )
+
+
+def test_final_candidate_origin_boundary_accepts_late_local_imports(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setitem(
+ sys.modules,
+ "ares.late_candidate_probe",
+ _synthetic_module(
+ "ares.late_candidate_probe",
+ origin=_REPO_ROOT / "ares" / "late_candidate_probe.py",
+ ),
+ )
+ monkeypatch.setitem(
+ sys.modules,
+ "migrations.versions.late_candidate_probe",
+ _synthetic_module(
+ "migrations.versions.late_candidate_probe",
+ search_locations=(_REPO_ROOT / "migrations" / "versions",),
+ ),
+ )
+ _assert_candidate_origin_boundary()
+
+
+def test_final_candidate_origin_boundary_rejects_mixed_namespace(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ with TemporaryDirectory(prefix="ares-mixed-origin-") as directory:
+ monkeypatch.setitem(
+ sys.modules,
+ "tests.integration.mixed_candidate_probe",
+ _synthetic_module(
+ "tests.integration.mixed_candidate_probe",
+ search_locations=(
+ _REPO_ROOT / "tests" / "integration",
+ Path(directory),
+ ),
+ ),
+ )
+ rejected = not _loaded_first_party_origins_are_candidate_local(
+ sys.modules,
+ _REPO_ROOT,
+ )
+ _require_fixed(
+ rejected,
+ "final candidate origin boundary accepted a mixed namespace",
+ )
+
+
+def test_final_candidate_origin_boundary_runs_after_ordinary_failure(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ calls = 0
+
+ def _record_boundary(
+ _ledger: _CandidateOriginLedger | None = None,
+ ) -> None:
+ nonlocal calls
+ calls += 1
+
+ monkeypatch.setattr(
+ sys.modules[__name__],
+ "_assert_candidate_origin_boundary",
+ _record_boundary,
+ )
+ ordinary_failure_survived = False
+ try:
+ with _candidate_origin_boundary():
+ raise RuntimeError
+ except RuntimeError:
+ ordinary_failure_survived = True
+ _require_fixed(
+ ordinary_failure_survived and calls == 2,
+ "candidate origin finalizer did not run after an ordinary failure",
+ )
+
+
+class _OriginProbeLoader:
+ def create_module(self, _spec: object) -> None:
+ return None
+
+ def exec_module(self, _module: object) -> None:
+ return None
+
+
+class _OriginProbeFinder:
+ def __init__(self, name: str, spec: object) -> None:
+ self._name = name
+ self._spec = spec
+
+ def find_spec(
+ self,
+ fullname: str,
+ _path: object = None,
+ _target: object = None,
+ ) -> object:
+ return self._spec if fullname == self._name else None
+
+
+@contextmanager
+def _origin_probe(
+ name: str,
+ spec: object,
+) -> Iterator[Callable[[], None]]:
+ finder = _OriginProbeFinder(name, spec)
+ parent_name, _, child_name = name.rpartition(".")
+ parent = (
+ importlib.import_module(parent_name)
+ if parent_name
+ else None
+ )
+ missing = object()
+ previous_module = sys.modules.pop(name, missing)
+ previous_attribute = (
+ parent.__dict__.get(child_name, missing)
+ if parent is not None
+ else missing
+ )
+ sys.meta_path.insert(0, finder)
+
+ def _import_then_remove() -> None:
+ importlib.import_module(name)
+ sys.modules.pop(name, None)
+ if parent is not None and child_name in parent.__dict__:
+ delattr(parent, child_name)
+
+ try:
+ yield _import_then_remove
+ finally:
+ if finder in sys.meta_path:
+ sys.meta_path.remove(finder)
+ sys.modules.pop(name, None)
+ if previous_module is not missing:
+ sys.modules[name] = previous_module
+ if parent is not None:
+ if previous_attribute is missing:
+ if child_name in parent.__dict__:
+ delattr(parent, child_name)
+ else:
+ setattr(parent, child_name, previous_attribute)
+
+
+def _concrete_probe_spec(name: str, origin: Path) -> object:
+ return importlib.machinery.ModuleSpec(
+ name,
+ _OriginProbeLoader(),
+ origin=str(origin),
+ )
+
+
+def _namespace_probe_spec(
+ name: str,
+ locations: tuple[Path, ...],
+) -> object:
+ spec = importlib.machinery.ModuleSpec(name, loader=None, is_package=True)
+ spec.submodule_search_locations = [
+ str(location)
+ for location in locations
+ ]
+ return spec
+
+
+ ("name", "probe_kind"),
+ [
+ ("ares.ledger_dirty_probe", "concrete"),
+ ("migrations.versions.ledger_dirty_probe", "concrete"),
+ ("migrations.versions.0007_add_websocket_tickets", "concrete"),
+ ("ares.db.websocket_tickets", "concrete"),
+ ("migrations.versions.ledger_mixed_probe", "mixed"),
+ ],
+ ids=(
+ "dirty-ares-removed",
+ "dirty-migration-removed",
+ "dirty-0007-removed",
+ "dirty-ticket-removed",
+ "mixed-namespace-removed",
+ ),
+)
+def test_origin_ledger_retains_removed_first_party_violation(
+ name: str,
+ probe_kind: str,
+) -> None:
+ rejected = False
+ with TemporaryDirectory(prefix="ares-origin-ledger-") as directory:
+ external_root = Path(directory)
+ if probe_kind == "mixed":
+ spec = _namespace_probe_spec(
+ name,
+ (
+ _REPO_ROOT / "migrations" / "versions",
+ external_root,
+ ),
+ )
+ else:
+ spec = _concrete_probe_spec(
+ name,
+ external_root / "probe.py",
+ )
+ try:
+ with _origin_probe(name, spec) as import_then_remove:
+ with _candidate_origin_boundary(isolated=True):
+ import_then_remove()
+ except pytest.fail.Exception:
+ rejected = True
+ _require_fixed(
+ rejected,
+ "candidate origin ledger forgot a removed first-party import",
+ )
+
+
+ ("name", "spec_kind"),
+ [
+ ("migrations.versions.ledger_local_probe", "local"),
+ ("third_party_ledger_probe", "third-party"),
+ ],
+ ids=("candidate-local-removed", "unrelated-namespace-removed"),
+)
+def test_origin_ledger_accepts_removed_safe_import(
+ name: str,
+ spec_kind: str,
+) -> None:
+ if spec_kind == "local":
+ spec = _concrete_probe_spec(
+ name,
+ _REPO_ROOT / "migrations" / "versions" / "probe.py",
+ )
+ else:
+ with TemporaryDirectory(
+ prefix="ares-origin-third-party-"
+ ) as directory:
+ spec = _namespace_probe_spec(name, (Path(directory),))
+ with _origin_probe(name, spec) as import_then_remove:
+ with _candidate_origin_boundary(isolated=True):
+ import_then_remove()
+ return
+ with _origin_probe(name, spec) as import_then_remove:
+ with _candidate_origin_boundary(isolated=True):
+ import_then_remove()
+
+
+def test_origin_ledger_final_guard_runs_after_ordinary_failure() -> None:
+ rejected_by_final_guard = False
+ with TemporaryDirectory(prefix="ares-origin-finally-") as directory:
+ name = "ares.removed_before_final_guard"
+ spec = _concrete_probe_spec(name, Path(directory) / "probe.py")
+ try:
+ with _origin_probe(name, spec) as import_then_remove:
+ with _candidate_origin_boundary(isolated=True):
+ import_then_remove()
+ raise RuntimeError
+ except pytest.fail.Exception:
+ rejected_by_final_guard = True
+ _require_fixed(
+ rejected_by_final_guard,
+ "candidate origin ledger final guard was skipped after failure",
+ )
+
+
+def _reused_origin_probe_body() -> None:
+ return None
+
+
+def test_origin_ledger_rechecks_reused_code_with_changed_origin() -> None:
+ rejected = False
+ with TemporaryDirectory(prefix="ares-origin-reused-code-") as directory:
+ external_file = Path(directory) / "migrations" / "versions" / (
+ "0007_external_probe.py"
+ )
+ probe_code = _reused_origin_probe_body.__code__
+ local_probe = types.FunctionType(
+ probe_code,
+ {
+ "__name__": "migrations.versions.reused_code_probe",
+ "__package__": "migrations.versions",
+ "__file__": str(
+ _REPO_ROOT
+ / "migrations"
+ / "versions"
+ / "0006_reused_code_probe.py"
+ ),
+ },
+ )
+ dirty_probe = types.FunctionType(
+ probe_code,
+ {
+ "__name__": "migrations.versions.reused_code_probe",
+ "__package__": "migrations.versions",
+ "__file__": str(external_file),
+ },
+ )
+ try:
+ with _candidate_origin_boundary(isolated=True):
+ local_probe()
+ dirty_probe()
+ except pytest.fail.Exception:
+ rejected = True
+ _require_fixed(
+ rejected,
+ "candidate origin ledger cached a stale frame origin",
+ )
+
+
+def test_origin_ledger_ignores_unrelated_migrations_directory() -> None:
+ with TemporaryDirectory(prefix="ares-origin-unrelated-") as directory:
+ third_party_probe = types.FunctionType(
+ _reused_origin_probe_body.__code__,
+ {
+ "__name__": "third_party.origin_probe",
+ "__package__": "third_party",
+ "__file__": str(
+ Path(directory) / "migrations" / "origin_probe.py"
+ ),
+ },
+ )
+ with _candidate_origin_boundary(isolated=True):
+ third_party_probe()
+
+
+def test_origin_ledger_requires_first_meta_path_position() -> None:
+ displaced_was_rejected = False
+ finder = _OriginProbeFinder("unrelated_displacement_probe", object())
+ with _candidate_origin_boundary(isolated=True) as ledger:
+ sys.meta_path.insert(0, finder)
+ try:
+ try:
+ _assert_candidate_origin_boundary(ledger)
+ except pytest.fail.Exception:
+ displaced_was_rejected = True
+ finally:
+ if finder in sys.meta_path:
+ sys.meta_path.remove(finder)
+ _require_fixed(
+ displaced_was_rejected,
+ "candidate origin finder accepted displaced ownership",
+ )
+
+
+def test_origin_ledger_restores_exact_observer_state() -> None:
+ previous_meta_path = tuple(sys.meta_path)
+ previous_profile = sys.getprofile()
+ ledger = _CandidateOriginLedger(_REPO_ROOT, isolated=True)
+
+ def _replacement_profile(
+ _frame: types.FrameType,
+ _event: str,
+ _arg: object,
+ ) -> None:
+ return None
+
+ ledger.install()
+ sys.meta_path.insert(0, _OriginProbeFinder("observer_tamper", object()))
+ sys.setprofile(_replacement_profile)
+ ledger.close()
+ restored = (
+ tuple(sys.meta_path) == previous_meta_path
+ and sys.getprofile() is previous_profile
+ and not ledger._observed_frame_origins
+ )
+ _require_fixed(
+ restored,
+ "candidate origin ledger did not restore observer state",
+ )
+
+
+@contextmanager
+def _temporary_database(label: str) -> Iterator[Path]:
+ with TemporaryDirectory(prefix=f"ares-migration-{label}-") as directory:
+ path = Path(directory) / "catalog.db"
+ outside_repository = _REPO_ROOT not in path.resolve().parents
+ _require_fixed(
+ outside_repository,
+ "migration database was created inside the repository",
+ )
+ yield path
+
+
+def _sqlite_url(path: Path, *, async_driver: bool = False) -> str:
+ driver = "sqlite+aiosqlite" if async_driver else "sqlite"
+ return f"{driver}:///{path.resolve().as_posix()}"
+
+
+def _config(
+ *,
+ configured_url: str,
+ x_url: str | None = None,
+ x_arguments: list[str] | None = None,
+) -> Config:
+ if x_url is not None and x_arguments is not None:
+ raise AssertionError("conflicting test configuration")
+ config = Config(str(_REPO_ROOT / "alembic.ini"))
+ config.set_main_option(
+ "script_location",
+ str(_REPO_ROOT / "migrations"),
+ )
+ config.set_main_option("sqlalchemy.url", configured_url)
+ config.cmd_opts = argparse.Namespace(
+ x=(
+ x_arguments
+ if x_arguments is not None
+ else ([] if x_url is None else [f"db_url={x_url}"])
+ )
+ )
+ return config
+
+
+def _upgrade(path: Path, revision: str, *, async_driver: bool = False) -> None:
+ url = _sqlite_url(path, async_driver=async_driver)
+ command.upgrade(_config(configured_url=url, x_url=url), revision)
+
+
+def _downgrade(path: Path, revision: str) -> None:
+ url = _sqlite_url(path)
+ command.downgrade(_config(configured_url=url, x_url=url), revision)
+
+
+def _connect(path: Path) -> sqlite3.Connection:
+ connection = sqlite3.connect(path)
+ connection.execute("PRAGMA foreign_keys=ON")
+ return connection
+
+
+def _version(path: Path) -> str | None:
+ connection = _connect(path)
+ try:
+ exists = connection.execute(
+ "SELECT 1 FROM sqlite_master "
+ "WHERE type='table' AND name='alembic_version'"
+ ).fetchone()
+ if exists is None:
+ return None
+ row = connection.execute(
+ "SELECT version_num FROM alembic_version"
+ ).fetchone()
+ return None if row is None else str(row[0])
+ finally:
+ connection.close()
+
+
+def _database_is_empty_and_unstamped(path: Path) -> bool:
+ if not path.exists():
+ return True
+ connection = sqlite3.connect(path)
+ try:
+ application_objects = connection.execute(
+ """
+ SELECT count(*) FROM sqlite_master
+ WHERE type IN ('table', 'index')
+ AND name NOT LIKE 'sqlite_%'
+ """
+ ).fetchone()
+ return application_objects == (0,)
+ finally:
+ connection.close()
+
+
+def _statement_class(statement: object) -> str:
+ normalized = " ".join(str(statement).strip().upper().split())
+ if normalized == "PRAGMA JOURNAL_MODE = WAL":
+ return "sqlite-journal-policy"
+ if normalized == "PRAGMA FOREIGN_KEYS = ON":
+ return "sqlite-foreign-key-policy"
+ if normalized.startswith(("CREATE ", "ALTER ", "DROP ")):
+ return "migration-ddl"
+ return "other"
+
+
+class _RecordingCursor:
+ def __init__(self, cursor: object, statements: list[str]) -> None:
+ self._cursor = cursor
+ self._statements = statements
+
+ def execute(self, statement: object, *args: object, **kwargs: object) -> object:
+ self._statements.append(_statement_class(statement))
+ return self._cursor.execute(statement, *args, **kwargs)
+
+ def __getattr__(self, name: str) -> object:
+ return getattr(self._cursor, name)
+
+
+class _RecordingConnection:
+ def __init__(self, connection: object, statements: list[str]) -> None:
+ self._connection = connection
+ self._statements = statements
+
+ def cursor(self, *args: object, **kwargs: object) -> _RecordingCursor:
+ cursor = self._connection.cursor(*args, **kwargs)
+ return _RecordingCursor(cursor, self._statements)
+
+ def __getattr__(self, name: str) -> object:
+ return getattr(self._connection, name)
+
+
+def _column_map(
+ connection: sqlite3.Connection,
+ table: str,
+) -> dict[str, tuple[str, int, object, int]]:
+ return {
+ str(row[1]): (str(row[2]), int(row[3]), row[4], int(row[5]))
+ for row in connection.execute(f'PRAGMA table_info("{table}")')
+ }
+
+
+def _index_map(
+ connection: sqlite3.Connection,
+) -> dict[str, tuple[str, tuple[str, ...]]]:
+ result: dict[str, tuple[str, tuple[str, ...]]] = {}
+ tables = tuple(_EXPECTED_APP_TABLES)
+ for table in tables:
+ for row in connection.execute(f'PRAGMA index_list("{table}")'):
+ name = str(row[1])
+ if name.startswith("sqlite_autoindex_"):
+ continue
+ columns = tuple(
+ str(item[2])
+ for item in connection.execute(f'PRAGMA index_info("{name}")')
+ )
+ result[name] = (table, columns)
+ return result
+
+
+def _foreign_keys(
+ connection: sqlite3.Connection,
+) -> set[tuple[str, str, str, str, str]]:
+ result: set[tuple[str, str, str, str, str]] = set()
+ for table in _EXPECTED_APP_TABLES:
+ for row in connection.execute(f'PRAGMA foreign_key_list("{table}")'):
+ result.add(
+ (
+ table,
+ str(row[3]),
+ str(row[2]),
+ str(row[4]),
+ str(row[6]).upper(),
+ )
+ )
+ return result
+
+
+def _ordered_column_fingerprint(
+ connection: sqlite3.Connection,
+ table: str,
+) -> tuple[tuple[str, str, int, object, int], ...]:
+ return tuple(
+ (str(row[1]), str(row[2]), int(row[3]), row[4], int(row[5]))
+ for row in connection.execute(f'PRAGMA table_info("{table}")')
+ )
+
+
+def _unique_constraints(
+ connection: sqlite3.Connection,
+) -> set[tuple[str, tuple[str, ...]]]:
+ result: set[tuple[str, tuple[str, ...]]] = set()
+ for table in _EXPECTED_APP_TABLES:
+ for row in connection.execute(f'PRAGMA index_list("{table}")'):
+ if str(row[3]) != "u":
+ continue
+ name = str(row[1])
+ columns = tuple(
+ str(item[2])
+ for item in connection.execute(f'PRAGMA index_info("{name}")')
+ )
+ result.add((table, columns))
+ return result
+
+
+def _normalize_sql_expression(value: str) -> str:
+ normalized = value.lower().replace('"', "").replace("`", "")
+ return re.sub(r"[\s()]+", "", normalized)
+
+
+def _named_checks(create_sql: str) -> tuple[tuple[str, str], ...]:
+ checks: list[tuple[str, str]] = []
+ pattern = re.compile(
+ r"\bCONSTRAINT\s+[\"`]?([A-Za-z_][A-Za-z0-9_]*)[\"`]?"
+ r"\s+CHECK\s*\(",
+ re.IGNORECASE,
+ )
+ for match in pattern.finditer(create_sql):
+ start = match.end()
+ depth = 1
+ position = start
+ quote: str | None = None
+ while position < len(create_sql) and depth:
+ character = create_sql[position]
+ if quote is not None:
+ if character == quote:
+ quote = None
+ elif character in {"'", '"'}:
+ quote = character
+ elif character == "(":
+ depth += 1
+ elif character == ")":
+ depth -= 1
+ position += 1
+ if depth:
+ raise AssertionError("unterminated SQLite CHECK expression")
+ checks.append(
+ (
+ match.group(1),
+ _normalize_sql_expression(
+ create_sql[start : position - 1]
+ ),
+ )
+ )
+ return tuple(sorted(checks))
+
+
+def _sqlite_catalog_contract(
+ connection: sqlite3.Connection,
+) -> _CatalogContract:
+ tables = tuple(
+ str(row[0])
+ for row in connection.execute(
+ """
+ SELECT name FROM sqlite_master
+ WHERE type='table'
+ AND name NOT LIKE 'sqlite_%'
+ AND name != 'alembic_version'
+ ORDER BY name
+ """
+ )
+ )
+ columns = tuple(
+ (table, _ordered_column_fingerprint(connection, table))
+ for table in tables
+ )
+ primary_keys = tuple(
+ (
+ table,
+ tuple(
+ name
+ for _position, name in sorted(
+ (
+ int(row[5]),
+ str(row[1]),
+ )
+ for row in connection.execute(
+ f'PRAGMA table_info("{table}")'
+ )
+ if int(row[5]) > 0
+ )
+ ),
+ )
+ for table in tables
+ )
+ unique_constraints: list[tuple[str, tuple[str, ...]]] = []
+ indexes: list[
+ tuple[str, str, tuple[str, ...], bool, str | None]
+ ] = []
+ foreign_keys: list[
+ tuple[str, str, str, str, str, str]
+ ] = []
+ checks: list[tuple[str, str, str]] = []
+ autoincrement_tables: list[str] = []
+ for table in tables:
+ table_sql_row = connection.execute(
+ "SELECT sql FROM sqlite_master WHERE type='table' AND name=?",
+ (table,),
+ ).fetchone()
+ table_sql = "" if table_sql_row is None else str(table_sql_row[0])
+ if "AUTOINCREMENT" in table_sql.upper():
+ autoincrement_tables.append(table)
+ checks.extend(
+ (table, name, expression)
+ for name, expression in _named_checks(table_sql)
+ )
+ for row in connection.execute(f'PRAGMA foreign_key_list("{table}")'):
+ foreign_keys.append(
+ (
+ table,
+ str(row[3]),
+ str(row[2]),
+ str(row[4]),
+ str(row[5]).upper(),
+ str(row[6]).upper(),
+ )
+ )
+ for row in connection.execute(f'PRAGMA index_list("{table}")'):
+ name = str(row[1])
+ index_columns = tuple(
+ str(item[2])
+ for item in connection.execute(
+ f'PRAGMA index_info("{name}")'
+ )
+ )
+ origin = str(row[3])
+ if origin == "u":
+ unique_constraints.append((table, index_columns))
+ continue
+ if origin != "c":
+ continue
+ index_sql_row = connection.execute(
+ "SELECT sql FROM sqlite_master "
+ "WHERE type='index' AND name=?",
+ (name,),
+ ).fetchone()
+ index_sql = (
+ ""
+ if index_sql_row is None or index_sql_row[0] is None
+ else str(index_sql_row[0])
+ )
+ predicate_match = re.search(
+ r"\bWHERE\b(.+)$",
+ index_sql,
+ flags=re.IGNORECASE,
+ )
+ predicate = (
+ None
+ if predicate_match is None
+ else _normalize_sql_expression(predicate_match.group(1))
+ )
+ indexes.append(
+ (
+ table,
+ name,
+ index_columns,
+ bool(row[2]),
+ predicate,
+ )
+ )
+ return _CatalogContract(
+ tables=tables,
+ columns=columns,
+ primary_keys=tuple(primary_keys),
+ unique_constraints=tuple(sorted(unique_constraints)),
+ checks=tuple(sorted(checks)),
+ foreign_keys=tuple(sorted(foreign_keys)),
+ indexes=tuple(sorted(indexes)),
+ autoincrement_tables=tuple(sorted(autoincrement_tables)),
+ )
+
+
+def _fixed_sqlite_contract(revision: str) -> _CatalogContract:
+ if revision == "base":
+ return _CatalogContract((), (), (), (), (), (), (), ())
+ tables = {
+ "schema_version",
+ "campaigns",
+ "module_runs",
+ "findings",
+ "hosts",
+ "credentials",
+ "loot",
+ "audit_log",
+ "users",
+ "api_keys",
+ "refresh_tokens",
+ }
+ if revision >= "0003":
+ tables.add("rate_limit_events")
+ if revision >= "0004":
+ tables.add("revoked_access_tokens")
+ ordered_tables = tuple(sorted(tables))
+
+ expected_columns = {
+ table: tuple(columns)
+ for table, columns in _EXPECTED_SQLITE_COLUMN_FINGERPRINTS.items()
+ if table in tables
+ }
+ expected_columns["schema_version"] = (
+ ("version", "INTEGER", 1, None, 1),
+ ("applied_at", "TEXT", 1, "datetime('now')", 0),
+ )
+ findings = list(expected_columns["findings"])
+ if revision == "0001":
+ findings = [column for column in findings if column[0] != "trace_id"]
+ elif revision < "0005":
+ findings = [
+ (
+ column[0],
+ column[1],
+ 0 if column[0] == "trace_id" else column[2],
+ column[3],
+ column[4],
+ )
+ for column in findings
+ ]
+ expected_columns["findings"] = tuple(findings)
+ if revision < "0006":
+ expected_columns["credentials"] = tuple(
+ (
+ "cracked_value" if column[0] == "cracked_value_enc" else column[0],
+ column[1],
+ column[2],
+ column[3],
+ column[4],
+ )
+ for column in expected_columns["credentials"]
+ )
+
+ primary_keys = tuple(
+ (
+ table,
+ tuple(
+ column[0]
+ for column in expected_columns[table]
+ if column[4] > 0
+ ),
+ )
+ for table in ordered_tables
+ )
+ unique_constraints = tuple(
+ sorted(
+ constraint
+ for constraint in _EXPECTED_UNIQUE_CONSTRAINTS
+ if constraint[0] in tables
+ )
+ )
+ foreign_keys = tuple(
+ sorted(
+ (
+ table,
+ local,
+ remote,
+ remote_column,
+ "NO ACTION",
+ on_delete,
+ )
+ for (
+ table,
+ local,
+ remote,
+ remote_column,
+ on_delete,
+ ) in _EXPECTED_FOREIGN_KEYS
+ if table in tables
+ )
+ )
+ index_names = set(_EXPECTED_INDEXES)
+ if revision == "0001":
+ index_names.discard("idx_findings_cvss")
+ if revision < "0003":
+ index_names.difference_update(
+ {"idx_rle_ip", "idx_rle_timestamp", "idx_rle_blocked"}
+ )
+ if revision < "0004":
+ index_names.discard("idx_rat_expires")
+ indexes = tuple(
+ sorted(
+ (
+ table,
+ name,
+ columns,
+ False,
+ None,
+ )
+ for name, (table, columns) in _EXPECTED_INDEXES.items()
+ if name in index_names
+ )
+ )
+ checks = (
+ (
+ "rate_limit_events",
+ "ck_rate_limit_events_blocked_bool",
+ "blockedin0,1",
+ ),
+ ) if revision >= "0003" else ()
+ autoincrement_tables = (
+ ("audit_log", "rate_limit_events")
+ if revision >= "0003"
+ else ("audit_log",)
+ )
+ return _CatalogContract(
+ tables=ordered_tables,
+ columns=tuple(
+ (table, expected_columns[table]) for table in ordered_tables
+ ),
+ primary_keys=primary_keys,
+ unique_constraints=unique_constraints,
+ checks=checks,
+ foreign_keys=foreign_keys,
+ indexes=indexes,
+ autoincrement_tables=autoincrement_tables,
+ )
+
+
+def _seed_campaign_and_credential(path: Path) -> None:
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES(?, ?)",
+ ("campaign-a", "Migration campaign"),
+ )
+ connection.execute(
+ """
+ INSERT INTO credentials(
+ id, campaign_id, username, cred_type, cracked_value
+ ) VALUES(?, ?, ?, ?, ?)
+ """,
+ (
+ "credential-a",
+ "campaign-a",
+ "synthetic-user",
+ "password",
+ "synthetic-encrypted-marker",
+ ),
+ )
+ connection.commit()
+ finally:
+ connection.close()
+
+
+def _credential_marker_survived(path: Path, column: str) -> bool:
+ connection = _connect(path)
+ try:
+ if column == "cracked_value_enc":
+ row = connection.execute(
+ "SELECT cracked_value_enc IS NOT NULL FROM credentials "
+ "WHERE id='credential-a'"
+ ).fetchone()
+ elif column == "cracked_value":
+ row = connection.execute(
+ "SELECT cracked_value IS NOT NULL FROM credentials "
+ "WHERE id='credential-a'"
+ ).fetchone()
+ else:
+ raise AssertionError("unknown credential column")
+ return row == (1,)
+ finally:
+ connection.close()
+
+
+def _expected_integrity_failure(
+ connection: sqlite3.Connection,
+ statement: str,
+ parameters: tuple[object, ...],
+) -> bool:
+ rejected = False
+ try:
+ connection.execute(statement, parameters)
+ connection.commit()
+ except sqlite3.IntegrityError:
+ rejected = True
+ connection.rollback()
+ reusable = connection.execute("SELECT 1").fetchone() == (1,)
+ return rejected and reusable
+
+
+def _seed_complete_contract(connection: sqlite3.Connection) -> None:
+ connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES(?, ?)",
+ ("campaign-contract", "Synthetic campaign"),
+ )
+ connection.execute(
+ """
+ INSERT INTO module_runs(
+ id, campaign_id, module_id, outcome
+ ) VALUES(?, ?, ?, ?)
+ """,
+ ("run-contract", "campaign-contract", "module", "complete"),
+ )
+ connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title, description, severity
+ ) VALUES(?, ?, ?, ?, ?, ?)
+ """,
+ (
+ "finding-contract",
+ "campaign-contract",
+ "module",
+ "Synthetic finding",
+ "Synthetic description",
+ "low",
+ ),
+ )
+ connection.execute(
+ """
+ INSERT INTO hosts(id, campaign_id, ip_address)
+ VALUES(?, ?, ?)
+ """,
+ ("host-contract", "campaign-contract", "192.0.2.10"),
+ )
+ connection.execute(
+ """
+ INSERT INTO credentials(
+ id, campaign_id, host_id, username, cred_type
+ ) VALUES(?, ?, ?, ?, ?)
+ """,
+ (
+ "credential-contract",
+ "campaign-contract",
+ "host-contract",
+ "synthetic-user",
+ "password",
+ ),
+ )
+ connection.execute(
+ """
+ INSERT INTO loot(
+ id, campaign_id, host_id, loot_type, name
+ ) VALUES(?, ?, ?, ?, ?)
+ """,
+ (
+ "loot-contract",
+ "campaign-contract",
+ "host-contract",
+ "metadata",
+ "Synthetic loot",
+ ),
+ )
+ connection.execute(
+ """
+ INSERT INTO audit_log(campaign_id, action)
+ VALUES(?, ?)
+ """,
+ ("campaign-contract", "synthetic-action"),
+ )
+ connection.execute(
+ """
+ INSERT INTO users(id, username, hashed_password)
+ VALUES(?, ?, ?)
+ """,
+ ("user-contract", "synthetic-account", "synthetic-hash"),
+ )
+ connection.execute(
+ """
+ INSERT INTO api_keys(
+ id, user_id, name, key_hash, key_prefix
+ ) VALUES(?, ?, ?, ?, ?)
+ """,
+ (
+ "api-key-contract",
+ "user-contract",
+ "Synthetic key",
+ "synthetic-hash",
+ "synthetic",
+ ),
+ )
+ connection.execute(
+ """
+ INSERT INTO refresh_tokens(id, user_id, expires_at)
+ VALUES(?, ?, ?)
+ """,
+ ("refresh-contract", "user-contract", "2099-01-01 00:00:00"),
+ )
+ connection.execute(
+ """
+ INSERT INTO revoked_access_tokens(jti, user_id, expires_at)
+ VALUES(?, ?, ?)
+ """,
+ ("revoked-contract", "user-contract", "2099-01-01 00:00:00"),
+ )
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES(?, ?)
+ """,
+ ("192.0.2.20", "synthetic-bucket"),
+ )
+ connection.commit()
+
+
+def _split_sqlite_table_clauses(create_sql: str) -> list[str]:
+ start = create_sql.find("(")
+ end = create_sql.rfind(")")
+ if start < 0 or end <= start:
+ raise AssertionError("invalid SQLite table definition")
+ body = create_sql[start + 1 : end]
+ clauses: list[str] = []
+ depth = 0
+ quote: str | None = None
+ clause_start = 0
+ for position, character in enumerate(body):
+ if quote is not None:
+ if character == quote:
+ quote = None
+ continue
+ if character in {"'", '"', "`"}:
+ quote = character
+ elif character == "(":
+ depth += 1
+ elif character == ")":
+ depth -= 1
+ elif character == "," and depth == 0:
+ clauses.append(body[clause_start:position].strip())
+ clause_start = position + 1
+ clauses.append(body[clause_start:].strip())
+ return clauses
+
+
+def _sqlite_clause_column(clause: str) -> str | None:
+ stripped = clause.lstrip()
+ if re.match(
+ r"^(CONSTRAINT|PRIMARY|UNIQUE|CHECK|FOREIGN)\b",
+ stripped,
+ flags=re.IGNORECASE,
+ ):
+ return None
+ match = re.match(
+ r'^(?:"([^"]+)"|`([^`]+)`|\[([^\]]+)\]|([^\s]+))',
+ stripped,
+ )
+ if match is None:
+ raise AssertionError("invalid SQLite column clause")
+ return next(value for value in match.groups() if value is not None)
+
+
+def _rebuild_legacy_table(
+ connection: sqlite3.Connection,
+ table: str,
+ revision: str,
+) -> None:
+ row = connection.execute(
+ "SELECT sql FROM sqlite_master WHERE type='table' AND name=?",
+ (table,),
+ ).fetchone()
+ if row is None:
+ raise AssertionError("missing source table for legacy transformation")
+ index_sql = tuple(
+ str(index[0])
+ for index in connection.execute(
+ "SELECT sql FROM sqlite_master "
+ "WHERE type='index' AND tbl_name=? AND sql IS NOT NULL "
+ "ORDER BY name",
+ (table,),
+ )
+ )
+ clauses = _split_sqlite_table_clauses(str(row[0]))
+ clauses = [
+ clause
+ for clause in clauses
+ if "FOREIGN KEY" not in clause.upper()
+ ]
+ if table == "rate_limit_events":
+ clauses = [
+ clause
+ for clause in clauses
+ if "CHECK" not in clause.upper()
+ ]
+ if table == "findings":
+ rewritten: list[str] = []
+ deferred: list[str] = []
+ for clause in clauses:
+ column = _sqlite_clause_column(clause)
+ if column in {"cvss_score", "cvss_vector", "trace_id"}:
+ clause = re.sub(
+ r"\s+NOT\s+NULL\b",
+ "",
+ clause,
+ flags=re.IGNORECASE,
+ )
+ if column in {"cvss_score", "cvss_vector"}:
+ deferred.append(clause)
+ else:
+ rewritten.append(clause)
+ confidence_position = next(
+ index
+ for index, clause in enumerate(rewritten)
+ if _sqlite_clause_column(clause) == "confidence"
+ )
+ clauses = (
+ rewritten[:confidence_position]
+ + deferred
+ + rewritten[confidence_position:]
+ )
+ temporary = f"migration_legacy_{table}"
+ create_sql = (
+ f'CREATE TABLE "{temporary}" (\n'
+ + ",\n".join(clauses)
+ + "\n)"
+ )
+ if table in {"audit_log", "rate_limit_events"}:
+ create_sql = re.sub(
+ r"\s+AUTOINCREMENT\b",
+ "",
+ create_sql,
+ flags=re.IGNORECASE,
+ )
+ columns = tuple(
+ str(column[1])
+ for column in connection.execute(f'PRAGMA table_info("{table}")')
+ )
+ quoted_columns = ", ".join(f'"{name}"' for name in columns)
+ connection.execute(create_sql)
+ connection.execute(
+ f'INSERT INTO "{temporary}" ({quoted_columns}) ' # noqa: S608
+ f'SELECT {quoted_columns} FROM "{table}"'
+ )
+ connection.execute(f'DROP TABLE "{table}"')
+ connection.execute(
+ f'ALTER TABLE "{temporary}" RENAME TO "{table}"'
+ )
+ for statement in index_sql:
+ connection.execute(statement)
+
+
+def _fixed_legacy_sqlite_contract(revision: str) -> _CatalogContract:
+ repaired = _fixed_sqlite_contract(revision)
+ tables = tuple(
+ table
+ for table in repaired.tables
+ if table not in {"module_runs", "schema_version"}
+ )
+ columns = dict(repaired.columns)
+ findings_by_name = {
+ column[0]: column for column in columns["findings"]
+ }
+ historical_finding_order = (
+ "id",
+ "campaign_id",
+ "module_id",
+ "title",
+ "description",
+ "severity",
+ "cvss_score",
+ "cvss_vector",
+ "confidence",
+ "mitre_technique",
+ "mitre_tactic",
+ "evidence_json",
+ "remediation",
+ "host",
+ "validated",
+ "false_positive",
+ "discovered_at",
+ ) + (("trace_id",) if revision >= "0002" else ())
+ columns["findings"] = tuple(
+ (
+ name,
+ findings_by_name[name][1],
+ (
+ 0
+ if name in {"cvss_score", "cvss_vector", "trace_id"}
+ else findings_by_name[name][2]
+ ),
+ findings_by_name[name][3],
+ findings_by_name[name][4],
+ )
+ for name in historical_finding_order
+ )
+ indexes = [
+ index
+ for index in repaired.indexes
+ if index[0] != "module_runs"
+ ]
+ indexes.append(
+ (
+ "findings",
+ "idx_findings_validated",
+ ("validated",),
+ False,
+ None,
+ )
+ )
+ return replace(
+ repaired,
+ tables=tables,
+ columns=tuple((table, columns[table]) for table in tables),
+ primary_keys=tuple(
+ item for item in repaired.primary_keys if item[0] in tables
+ ),
+ foreign_keys=(),
+ indexes=tuple(sorted(indexes)),
+ checks=(),
+ autoincrement_tables=(),
+ )
+
+
+def _create_transformed_legacy_catalog(path: Path, revision: str) -> None:
+ _upgrade(path, revision)
+ connection = _connect(path)
+ foreign_keys_enabled = True
+ try:
+ connection.commit()
+ connection.execute("PRAGMA foreign_keys=OFF")
+ foreign_keys_enabled = False
+ connection.execute("DROP TABLE module_runs")
+ connection.execute("DROP TABLE schema_version")
+ for table in (
+ "findings",
+ "hosts",
+ "credentials",
+ "loot",
+ "audit_log",
+ "api_keys",
+ "refresh_tokens",
+ ):
+ _rebuild_legacy_table(connection, table, revision)
+ if revision >= "0003":
+ _rebuild_legacy_table(
+ connection,
+ "rate_limit_events",
+ revision,
+ )
+ connection.execute(
+ "CREATE INDEX idx_findings_validated "
+ "ON findings(validated)"
+ )
+ connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES(?, ?)",
+ ("legacy-campaign", "Synthetic legacy campaign"),
+ )
+ trace_column_exists = revision >= "0002"
+ finding_count = 3 if trace_column_exists else 1
+ for index in range(finding_count):
+ base_values = (
+ f"legacy-finding-{index}",
+ "legacy-campaign",
+ "module",
+ f"Synthetic finding {index}",
+ "Synthetic legacy description",
+ "low",
+ None if index == 0 else float(index),
+ None if index == 0 else f"VECTOR-{index}",
+ )
+ if trace_column_exists:
+ trace_value = (None, "", "synthetic-trace")[index]
+ connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title, description,
+ severity, cvss_score, cvss_vector, trace_id
+ ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+ """,
+ (*base_values, trace_value),
+ )
+ else:
+ connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title, description,
+ severity, cvss_score, cvss_vector
+ ) VALUES(?, ?, ?, ?, ?, ?, ?, ?)
+ """,
+ base_values,
+ )
+ connection.execute(
+ """
+ INSERT INTO hosts(id, campaign_id, ip_address, hostname)
+ VALUES(?, ?, ?, ?)
+ """,
+ (
+ "legacy-host",
+ "legacy-campaign",
+ "192.0.2.40",
+ "synthetic-host",
+ ),
+ )
+ connection.execute(
+ """
+ INSERT INTO credentials(
+ id, campaign_id, host_id, username, cred_type, cracked_value
+ ) VALUES(?, ?, ?, ?, ?, ?)
+ """,
+ (
+ "legacy-credential",
+ "legacy-campaign",
+ "legacy-host",
+ "synthetic-user",
+ "password",
+ "synthetic-encrypted-marker",
+ ),
+ )
+ connection.execute(
+ """
+ INSERT INTO loot(id, campaign_id, host_id, loot_type, name)
+ VALUES(?, ?, ?, ?, ?)
+ """,
+ (
+ "legacy-loot",
+ "legacy-campaign",
+ "legacy-host",
+ "metadata",
+ "Synthetic loot",
+ ),
+ )
+ connection.execute(
+ "INSERT INTO audit_log(campaign_id, action) VALUES(?, ?)",
+ ("legacy-campaign", "synthetic-action"),
+ )
+ connection.execute(
+ """
+ INSERT INTO users(id, username, hashed_password)
+ VALUES(?, ?, ?)
+ """,
+ ("legacy-user", "synthetic-account", "synthetic-hash"),
+ )
+ connection.execute(
+ """
+ INSERT INTO api_keys(id, user_id, name, key_hash, key_prefix)
+ VALUES(?, ?, ?, ?, ?)
+ """,
+ (
+ "legacy-api-key",
+ "legacy-user",
+ "Synthetic key",
+ "synthetic-hash",
+ "synthetic",
+ ),
+ )
+ connection.execute(
+ """
+ INSERT INTO refresh_tokens(id, user_id, expires_at)
+ VALUES(?, ?, ?)
+ """,
+ ("legacy-refresh", "legacy-user", "2099-01-01 00:00:00"),
+ )
+ if revision >= "0003":
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES(?, ?)
+ """,
+ ("192.0.2.41", "synthetic-bucket"),
+ )
+ if revision >= "0004":
+ connection.execute(
+ """
+ INSERT INTO revoked_access_tokens(jti, user_id, expires_at)
+ VALUES(?, ?, ?)
+ """,
+ ("legacy-revoked", "legacy-user", "2099-01-01 00:00:00"),
+ )
+ connection.commit()
+ finally:
+ if not foreign_keys_enabled:
+ connection.execute("PRAGMA foreign_keys=ON")
+ connection.close()
+ current = _connect(path)
+ try:
+ complete_contract = (
+ _sqlite_catalog_contract(current)
+ == _fixed_legacy_sqlite_contract(revision)
+ )
+ finally:
+ current.close()
+ _require_fixed(
+ complete_contract,
+ "constructed legacy SQLite catalog diverged",
+ )
+
+
+ "async_driver",
+ [False, True],
+ ids=("ordinary-sqlite-url", "aiosqlite-factory-url"),
+)
+def test_sqlite_url_driver_forms_execute_real_migrations(
+ monkeypatch: pytest.MonkeyPatch,
+ async_driver: bool,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("driver") as path:
+ _upgrade(path, "0001", async_driver=async_driver)
+ reached_revision = _version(path) == "0001"
+ _require_fixed(
+ reached_revision,
+ "SQLite URL form did not execute revision 0001",
+ )
+
+
+def test_x_url_precedes_configured_url(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("x-priority") as selected:
+ other = selected.parent / "configured.db"
+ selected_url = _sqlite_url(selected)
+ command.upgrade(
+ _config(
+ configured_url=_sqlite_url(other),
+ x_url=selected_url,
+ ),
+ "0001",
+ )
+ selected_exists = selected.exists()
+ other_absent = not other.exists()
+ _require_fixed(
+ selected_exists and other_absent,
+ "the documented x-argument did not select the migration target",
+ )
+
+
+def test_explicit_target_excludes_environment_and_ini_decoys(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ with _temporary_database("target-precedence") as selected:
+ environment_decoy = selected.parent / "environment.db"
+ configured_decoy = selected.parent / "configured.db"
+ monkeypatch.setenv(
+ "ARES_DATABASE_URL",
+ _sqlite_url(environment_decoy),
+ )
+ command.upgrade(
+ _config(
+ configured_url=_sqlite_url(configured_decoy),
+ x_url=_sqlite_url(selected),
+ ),
+ "0001",
+ )
+ selected_reached_revision = _version(selected) == "0001"
+ decoys_untouched = all(
+ _database_is_empty_and_unstamped(path)
+ for path in (environment_decoy, configured_decoy)
+ )
+ _require_fixed(
+ selected_reached_revision and decoys_untouched,
+ "explicit migration target isolation failed",
+ )
+
+
+ "x_arguments",
+ [
+ ["db_url"],
+ ["db_url="],
+ ["db_url= "],
+ ["db_url= sqlite:///invalid"],
+ ["db_url=sqlite:///invalid "],
+ ],
+ ids=(
+ "bare",
+ "empty",
+ "whitespace",
+ "leading-whitespace",
+ "trailing-whitespace",
+ ),
+)
+def test_invalid_explicit_target_cannot_fall_through(
+ monkeypatch: pytest.MonkeyPatch,
+ x_arguments: list[str],
+) -> None:
+ with _temporary_database("invalid-explicit") as root:
+ environment_decoy = root.parent / "environment.db"
+ configured_decoy = root.parent / "configured.db"
+ monkeypatch.setenv(
+ "ARES_DATABASE_URL",
+ _sqlite_url(environment_decoy),
+ )
+ failed = False
+ try:
+ command.upgrade(
+ _config(
+ configured_url=_sqlite_url(configured_decoy),
+ x_arguments=x_arguments,
+ ),
+ "0001",
+ )
+ except RuntimeError:
+ failed = True
+ decoys_untouched = all(
+ _database_is_empty_and_unstamped(path)
+ for path in (environment_decoy, configured_decoy)
+ )
+ _require_fixed(
+ failed and decoys_untouched,
+ "invalid explicit target reached a fallback database",
+ )
+
+
[email protected]("identical", [False, True], ids=("conflicting", "identical"))
+def test_duplicate_explicit_targets_fail_before_mutation(
+ monkeypatch: pytest.MonkeyPatch,
+ identical: bool,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("duplicate-target") as first:
+ second = first if identical else first.parent / "second.db"
+ configured_decoy = first.parent / "configured.db"
+ failed = False
+ try:
+ command.upgrade(
+ _config(
+ configured_url=_sqlite_url(configured_decoy),
+ x_arguments=[
+ f"db_url={_sqlite_url(first)}",
+ f"db_url={_sqlite_url(second)}",
+ ],
+ ),
+ "0001",
+ )
+ except RuntimeError:
+ failed = True
+ candidates_untouched = all(
+ _database_is_empty_and_unstamped(path)
+ for path in {first, second, configured_decoy}
+ )
+ _require_fixed(
+ failed and candidates_untouched,
+ "duplicate explicit targets were not rejected atomically",
+ )
+
+
[email protected]("environment_value", ["", " ", " value", "value "])
+def test_present_invalid_environment_target_cannot_use_ini(
+ monkeypatch: pytest.MonkeyPatch,
+ environment_value: str,
+) -> None:
+ with _temporary_database("invalid-environment") as configured_decoy:
+ monkeypatch.setenv("ARES_DATABASE_URL", environment_value)
+ failed = False
+ try:
+ command.upgrade(
+ _config(configured_url=_sqlite_url(configured_decoy)),
+ "0001",
+ )
+ except RuntimeError:
+ failed = True
+ decoy_untouched = _database_is_empty_and_unstamped(configured_decoy)
+ _require_fixed(
+ failed and decoy_untouched,
+ "invalid environment target fell through to ini",
+ )
+
+
+def test_empty_configured_target_fails_before_mutation(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ failed = False
+ try:
+ command.upgrade(
+ _config(configured_url=""),
+ "0001",
+ )
+ except RuntimeError:
+ failed = True
+ _require_fixed(failed, "empty configured migration target was accepted")
+
+
+def test_unicode_percent_and_query_sqlite_target_round_trip(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with TemporaryDirectory(prefix="ares-migration-url-") as directory:
+ path = Path(directory) / "catalog-%-unicode-\u03bb.db"
+ outside_repository = _REPO_ROOT not in path.resolve().parents
+ url = URL.create(
+ "sqlite",
+ database=path.resolve().as_posix(),
+ query={"timeout": "5"},
+ ).render_as_string(hide_password=False)
+ command.upgrade(
+ _config(configured_url="sqlite:///unused.db", x_url=url),
+ "0001",
+ )
+ reached_revision = _version(path) == "0001"
+ _require_fixed(
+ outside_repository and reached_revision,
+ "structured SQLite URL components were not preserved",
+ )
+
+
+ "driver",
+ ["postgresql", "postgresql+asyncpg"],
+ ids=("ordinary-postgresql", "asyncpg-postgresql"),
+)
+def test_postgresql_url_components_and_repeated_query_are_preserved(
+ monkeypatch: pytest.MonkeyPatch,
+ driver: str,
+) -> None:
+ import sqlalchemy.ext.asyncio as sqlalchemy_asyncio
+ from sqlalchemy.engine import make_url
+
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ captured: dict[str, str] = {}
+
+ class _CaptureConnection:
+ async def __aenter__(self) -> _CaptureConnection:
+ return self
+
+ async def __aexit__(
+ self,
+ _exc_type: object,
+ _exc: object,
+ _traceback: object,
+ ) -> None:
+ return None
+
+ async def run_sync(self, _callable: object) -> None:
+ raise RuntimeError("capture-complete")
+
+ class _CaptureEngine:
+ def connect(self) -> _CaptureConnection:
+ return _CaptureConnection()
+
+ async def dispose(self) -> None:
+ return None
+
+ def _capture_engine(
+ section: dict[str, str],
+ **_kwargs: object,
+ ) -> _CaptureEngine:
+ captured["url"] = section["sqlalchemy.url"]
+ return _CaptureEngine()
+
+ monkeypatch.setattr(
+ sqlalchemy_asyncio,
+ "async_engine_from_config",
+ _capture_engine,
+ )
+ authority_component = "synthetic%component/\u03bb"
+ original = URL.create(
+ driver,
+ username="synthetic:user",
+ password=authority_component,
+ host="db.example.invalid",
+ port=5432,
+ database="synthetic%database-\u03bb",
+ query={
+ "application_name": ("first", "second"),
+ "sslmode": "require",
+ },
+ )
+ failed_safely = False
+ try:
+ command.upgrade(
+ _config(
+ configured_url="sqlite:///unused.db",
+ x_url=original.render_as_string(hide_password=False),
+ ),
+ "0001",
+ )
+ except RuntimeError:
+ failed_safely = True
+
+ captured_url = make_url(captured.get("url", "invalid://"))
+ components_preserved = (
+ captured_url.drivername == "postgresql+asyncpg"
+ and captured_url.username == original.username
+ and captured_url.password == original.password
+ and captured_url.host == original.host
+ and captured_url.port == original.port
+ and captured_url.database == original.database
+ and captured_url.query == original.query
+ )
+ _require_fixed(
+ failed_safely and components_preserved,
+ "structured PostgreSQL URL normalization diverged",
+ )
+
+
+def test_sqlite_connection_policy_precedes_migration_ddl(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ real_connect = sqlite3.connect
+ statement_classes: list[str] = []
+
+ def _recording_connect(*args: object, **kwargs: object) -> object:
+ connection = real_connect(*args, **kwargs)
+ return _RecordingConnection(connection, statement_classes)
+
+ monkeypatch.setattr(sqlite3, "connect", _recording_connect)
+ with _temporary_database("pragma-order") as path:
+ _upgrade(path, "0001")
+
+ journal_positions = [
+ index
+ for index, value in enumerate(statement_classes)
+ if value == "sqlite-journal-policy"
+ ]
+ foreign_positions = [
+ index
+ for index, value in enumerate(statement_classes)
+ if value == "sqlite-foreign-key-policy"
+ ]
+ ddl_positions = [
+ index
+ for index, value in enumerate(statement_classes)
+ if value == "migration-ddl"
+ ]
+ ordered = (
+ len(journal_positions) == 1
+ and len(foreign_positions) == 1
+ and bool(ddl_positions)
+ and journal_positions[0] < ddl_positions[0]
+ and foreign_positions[0] < ddl_positions[0]
+ )
+ _require_fixed(
+ ordered,
+ "SQLite connection policy did not precede migration DDL",
+ )
+
+
+def test_configured_url_is_the_fallback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("fallback") as path:
+ command.upgrade(
+ _config(configured_url=_sqlite_url(path)),
+ "0001",
+ )
+ reached_revision = _version(path) == "0001"
+ _require_fixed(
+ reached_revision,
+ "configured Alembic URL fallback did not run",
+ )
+
+
+def test_environment_url_is_a_sanitized_legacy_fallback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ with _temporary_database("environment-fallback") as selected:
+ other = selected.parent / "configured.db"
+ monkeypatch.setenv("ARES_DATABASE_URL", _sqlite_url(selected))
+ command.upgrade(
+ _config(configured_url=_sqlite_url(other)),
+ "0001",
+ )
+ selected_exists = selected.exists()
+ other_absent = not other.exists()
+ _require_fixed(
+ selected_exists and other_absent,
+ "environment URL fallback did not select the migration target",
+ )
+
+
+ ("failure_type", "expected_message"),
+ [
+ (
+ ImportError,
+ "Alembic logging configuration failed [ImportError]",
+ ),
+ (
+ RuntimeError,
+ "Alembic logging configuration failed [RuntimeError]",
+ ),
+ ],
+ ids=("logging-import", "logging-runtime"),
+)
+def test_logging_configuration_failures_are_sanitized(
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ failure_type: type[Exception],
+ expected_message: str,
+) -> None:
+ import logging.config
+ import traceback
+
+ marker = "synthetic-logging-detail"
+
+ def _fail_logging_configuration(*_args: object, **_kwargs: object) -> None:
+ raise failure_type(marker)
+
+ caught: Exception | None = None
+ with _temporary_database("logging-sanitization") as path:
+ with monkeypatch.context() as context:
+ context.delenv("ARES_DATABASE_URL", raising=False)
+ context.setattr(
+ logging.config,
+ "fileConfig",
+ _fail_logging_configuration,
+ )
+ try:
+ _upgrade(path, "0001")
+ except Exception as error:
+ caught = error
+
+ captured = capsys.readouterr()
+ rendered = (
+ ""
+ if caught is None
+ else "".join(
+ traceback.format_exception(
+ type(caught),
+ caught,
+ caught.__traceback__,
+ )
+ )
+ )
+ sanitized = (
+ caught is not None
+ and type(caught).__name__ == "_AlembicSanitizedError"
+ and str(caught) == expected_message
+ and bool(getattr(caught, "__suppress_context__", False))
+ and marker not in captured.out
+ and marker not in captured.err
+ and marker not in rendered
+ )
+ _require_fixed(
+ sanitized,
+ "Alembic logging failure diagnostics were not sanitized",
+ )
+
+
+def test_offline_and_unsupported_execution_fail_safely(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("failure-contract") as path:
+ url = _sqlite_url(path)
+ with pytest.raises(
+ RuntimeError,
+ match=(
+ "^Offline migration is not supported for the "
+ "ARES historical chain$"
+ ),
+ ):
+ command.upgrade(
+ _config(configured_url=url, x_url=url),
+ "0001",
+ sql=True,
+ )
+ with pytest.raises(
+ RuntimeError,
+ match="^Unsupported Alembic database dialect$",
+ ):
+ command.upgrade(
+ _config(
+ configured_url="mysql+asyncmy://invalid",
+ x_url="mysql+asyncmy://invalid",
+ ),
+ "0001",
+ )
+ with pytest.raises(
+ RuntimeError,
+ match="^Invalid Alembic database URL$",
+ ):
+ command.upgrade(
+ _config(configured_url="://", x_url="://"),
+ "0001",
+ )
+
+
+def test_revision_by_revision_round_trip_preserves_owned_state(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("round-trip") as path:
+ for revision in ("0001", "0002", "0003", "0004", "0005"):
+ _upgrade(path, revision)
+ reached_revision = _version(path) == revision
+ _require_fixed(
+ reached_revision,
+ "revision-by-revision upgrade stopped at the wrong revision",
+ )
+ if revision == "0001":
+ _seed_campaign_and_credential(path)
+
+ _upgrade(path, "0006")
+ renamed_value_survived = _credential_marker_survived(
+ path, "cracked_value_enc"
+ )
+ _require_fixed(
+ renamed_value_survived,
+ "revision 0006 did not preserve the credential value",
+ )
+
+ _downgrade(path, "0005")
+ restored_value_survived = _credential_marker_survived(
+ path, "cracked_value"
+ )
+ _require_fixed(
+ restored_value_survived,
+ "revision 0006 downgrade did not preserve the credential value",
+ )
+
+ _downgrade(path, "0004")
+ connection = _connect(path)
+ try:
+ trace_after_0005 = _column_map(connection, "findings").get(
+ "trace_id"
+ )
+ finally:
+ connection.close()
+ trace_retained = (
+ trace_after_0005 is not None and trace_after_0005[1] == 0
+ )
+ _require_fixed(
+ trace_retained,
+ "revision 0005 downgrade removed earlier trace metadata",
+ )
+
+ _downgrade(path, "0003")
+ _downgrade(path, "0002")
+ _downgrade(path, "0001")
+ connection = _connect(path)
+ try:
+ parent_columns = _column_map(connection, "findings")
+ finally:
+ connection.close()
+ parent_is_repaired = (
+ {"cvss_score", "cvss_vector"}.issubset(parent_columns)
+ and "trace_id" not in parent_columns
+ )
+ _require_fixed(
+ parent_is_repaired,
+ "revision 0002 downgrade contradicted the repaired parent",
+ )
+
+ _downgrade(path, "base")
+ connection = _connect(path)
+ try:
+ remaining_tables = {
+ str(row[0])
+ for row in connection.execute(
+ """
+ SELECT name FROM sqlite_master
+ WHERE type='table' AND name NOT LIKE 'sqlite_%'
+ """
+ )
+ }
+ finally:
+ connection.close()
+ base_is_empty = not remaining_tables.intersection(
+ _EXPECTED_APP_TABLES
+ )
+ _require_fixed(
+ base_is_empty,
+ "downgrade to base retained an application table",
+ )
+
+ _upgrade(path, "0006")
+ _upgrade(path, "0006")
+ final_revision = _version(path) == "0006"
+ _require_fixed(
+ final_revision,
+ "re-upgrade did not return to revision 0006",
+ )
+
+
+def test_every_downgrade_restores_exact_repaired_parent_fingerprint(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("exact-parent-fingerprints") as path:
+ _upgrade(path, "0006")
+
+ parent_by_revision = {
+ "0006": "0005",
+ "0005": "0004",
+ "0004": "0003",
+ "0003": "0002",
+ "0002": "0001",
+ "0001": "base",
+ }
+ for _revision, parent in parent_by_revision.items():
+ _downgrade(path, parent)
+ connection = _connect(path)
+ try:
+ actual = _sqlite_catalog_contract(connection)
+ finally:
+ connection.close()
+ expected = _fixed_sqlite_contract(parent)
+ exact_parent_restored = actual == expected
+ _require_fixed(
+ exact_parent_restored,
+ "downgrade did not restore the exact repaired parent catalog",
+ )
+
+
+def _replace_contract_table_columns(
+ contract: _CatalogContract,
+ table: str,
+ columns: tuple[tuple[str, str, int, object, int], ...],
+) -> _CatalogContract:
+ return replace(
+ contract,
+ columns=tuple(
+ (name, columns if name == table else current)
+ for name, current in contract.columns
+ ),
+ )
+
+
+ "mutation",
+ [
+ "missing-table",
+ "extra-table",
+ "missing-column",
+ "extra-column",
+ "column-order",
+ "column-type",
+ "column-nullability",
+ "column-default",
+ "primary-key-order",
+ "foreign-key-target",
+ "foreign-key-delete",
+ "foreign-key-update",
+ "check-always-true",
+ "check-expanded-values",
+ "index-columns",
+ "index-order",
+ "index-uniqueness",
+ "duplicate-equivalent-index",
+ "autoincrement",
+ ],
+)
+def test_fixed_catalog_oracle_rejects_semantic_mutations(
+ mutation: str,
+) -> None:
+ expected = _fixed_sqlite_contract("0006")
+ mutated = expected
+ campaign_columns = dict(expected.columns)["campaigns"]
+ if mutation == "missing-table":
+ mutated = replace(expected, tables=expected.tables[1:])
+ elif mutation == "extra-table":
+ mutated = replace(expected, tables=(*expected.tables, "unexpected"))
+ elif mutation == "missing-column":
+ mutated = _replace_contract_table_columns(
+ expected,
+ "campaigns",
+ campaign_columns[:-1],
+ )
+ elif mutation == "extra-column":
+ mutated = _replace_contract_table_columns(
+ expected,
+ "campaigns",
+ (*campaign_columns, ("unexpected", "TEXT", 0, None, 0)),
+ )
+ elif mutation == "column-order":
+ reordered = list(campaign_columns)
+ reordered[0], reordered[1] = reordered[1], reordered[0]
+ mutated = _replace_contract_table_columns(
+ expected,
+ "campaigns",
+ tuple(reordered),
+ )
+ elif mutation in {
+ "column-type",
+ "column-nullability",
+ "column-default",
+ }:
+ changed = list(campaign_columns)
+ name, data_type, required, default, primary = changed[1]
+ if mutation == "column-type":
+ data_type = "INTEGER"
+ elif mutation == "column-nullability":
+ required = 0
+ else:
+ default = "'unexpected'"
+ changed[1] = (name, data_type, required, default, primary)
+ mutated = _replace_contract_table_columns(
+ expected,
+ "campaigns",
+ tuple(changed),
+ )
+ elif mutation == "primary-key-order":
+ mutated = replace(
+ expected,
+ primary_keys=(
+ ("campaigns", ("name", "id")),
+ *expected.primary_keys[1:],
+ ),
+ )
+ elif mutation.startswith("foreign-key-"):
+ changed_foreign_keys = list(expected.foreign_keys)
+ table, local, remote, remote_column, update, delete = (
+ changed_foreign_keys[0]
+ )
+ if mutation == "foreign-key-target":
+ remote = "unexpected_parent"
+ elif mutation == "foreign-key-delete":
+ delete = "RESTRICT"
+ else:
+ update = "CASCADE"
+ changed_foreign_keys[0] = (
+ table,
+ local,
+ remote,
+ remote_column,
+ update,
+ delete,
+ )
+ mutated = replace(
+ expected,
+ foreign_keys=tuple(changed_foreign_keys),
+ )
+ elif mutation == "check-always-true":
+ mutated = replace(
+ expected,
+ checks=(
+ (
+ "rate_limit_events",
+ "ck_rate_limit_events_blocked_bool",
+ "1",
+ ),
+ ),
+ )
+ elif mutation == "check-expanded-values":
+ mutated = replace(
+ expected,
+ checks=(
+ (
+ "rate_limit_events",
+ "ck_rate_limit_events_blocked_bool",
+ "blockedin0,1,2",
+ ),
+ ),
+ )
+ elif mutation.startswith("index-"):
+ changed_indexes = list(expected.indexes)
+ table, name, columns, unique, predicate = changed_indexes[0]
+ if mutation == "index-columns":
+ columns = ("name",)
+ elif mutation == "index-order":
+ columns = tuple(reversed((*columns, "name")))
+ else:
+ unique = True
+ changed_indexes[0] = (
+ table,
+ name,
+ columns,
+ unique,
+ predicate,
+ )
+ mutated = replace(expected, indexes=tuple(changed_indexes))
+ elif mutation == "duplicate-equivalent-index":
+ table, _name, columns, unique, predicate = expected.indexes[0]
+ mutated = replace(
+ expected,
+ indexes=(
+ *expected.indexes,
+ (
+ table,
+ "idx_unexpected_duplicate",
+ columns,
+ unique,
+ predicate,
+ ),
+ ),
+ )
+ elif mutation == "autoincrement":
+ mutated = replace(
+ expected,
+ autoincrement_tables=("rate_limit_events",),
+ )
+ else:
+ raise AssertionError("unknown catalog mutation")
+ _require_fixed(
+ mutated != expected,
+ "fixed catalog oracle accepted a semantic mutation",
+ )
+
+
+def _sqlite_table_clauses(
+ connection: sqlite3.Connection,
+ table: str,
+) -> list[str]:
+ row = connection.execute(
+ "SELECT sql FROM sqlite_master WHERE type='table' AND name=?",
+ (table,),
+ ).fetchone()
+ if row is None or row[0] is None:
+ raise AssertionError("missing SQLite mutation source table")
+ return _split_sqlite_table_clauses(str(row[0]))
+
+
+def _rebuild_sqlite_mutation_table(
+ connection: sqlite3.Connection,
+ table: str,
+ clauses: list[str],
+) -> None:
+ index_statements = tuple(
+ str(row[0])
+ for row in connection.execute(
+ "SELECT sql FROM sqlite_master "
+ "WHERE type='index' AND tbl_name=? AND sql IS NOT NULL "
+ "ORDER BY name",
+ (table,),
+ )
+ )
+ source_columns = tuple(
+ str(row[1])
+ for row in connection.execute(f'PRAGMA table_info("{table}")')
+ )
+ target_columns = tuple(
+ column
+ for clause in clauses
+ for column in [_sqlite_clause_column(clause)]
+ if column is not None
+ )
+ copied_columns = tuple(
+ column for column in source_columns if column in target_columns
+ )
+ temporary = "migration_oracle_mutation"
+ connection.commit()
+ connection.execute("PRAGMA foreign_keys=OFF")
+ try:
+ connection.execute(
+ f'CREATE TABLE "{temporary}" (\n'
+ + ",\n".join(clauses)
+ + "\n)"
+ )
+ if copied_columns:
+ quoted = ", ".join(f'"{column}"' for column in copied_columns)
+ connection.execute(
+ f'INSERT INTO "{temporary}" ({quoted}) ' # noqa: S608
+ f'SELECT {quoted} FROM "{table}"'
+ )
+ connection.execute(f'DROP TABLE "{table}"')
+ connection.execute(
+ f'ALTER TABLE "{temporary}" RENAME TO "{table}"'
+ )
+ for statement in index_statements:
+ connection.execute(statement)
+ connection.commit()
+ except Exception:
+ connection.rollback()
+ raise
+ finally:
+ connection.execute("PRAGMA foreign_keys=ON")
+
+
+def _replace_sqlite_column_clause(
+ clauses: list[str],
+ column: str,
+ replacement: str,
+) -> list[str]:
+ replaced = False
+ result: list[str] = []
+ for clause in clauses:
+ if _sqlite_clause_column(clause) == column:
+ if replaced:
+ raise AssertionError("duplicate SQLite mutation column")
+ result.append(replacement)
+ replaced = True
+ else:
+ result.append(clause)
+ if not replaced:
+ raise AssertionError("missing SQLite mutation column")
+ return result
+
+
+def _replace_sqlite_constraint_clause(
+ clauses: list[str],
+ marker: str,
+ transform: Callable[[str], str],
+) -> list[str]:
+ replaced = False
+ result: list[str] = []
+ for clause in clauses:
+ if marker.lower() in clause.lower():
+ if replaced:
+ raise AssertionError("ambiguous SQLite mutation constraint")
+ result.append(transform(clause))
+ replaced = True
+ else:
+ result.append(clause)
+ if not replaced:
+ raise AssertionError("missing SQLite mutation constraint")
+ return result
+
+
+def _apply_real_sqlite_catalog_mutation(
+ connection: sqlite3.Connection,
+ mutation: str,
+) -> None:
+ if mutation == "missing-table":
+ connection.execute("DROP TABLE schema_version")
+ connection.commit()
+ return
+ if mutation == "extra-table":
+ connection.execute(
+ "CREATE TABLE unexpected_catalog_probe(marker TEXT)"
+ )
+ connection.commit()
+ return
+ if mutation in {
+ "missing-column",
+ "extra-column",
+ "column-order",
+ "column-type",
+ "column-nullability",
+ "column-default",
+ "primary-key-order",
+ }:
+ clauses = _sqlite_table_clauses(connection, "schema_version")
+ if mutation == "missing-column":
+ clauses = [
+ clause
+ for clause in clauses
+ if _sqlite_clause_column(clause) != "applied_at"
+ ]
+ elif mutation == "extra-column":
+ constraint_position = next(
+ (
+ index
+ for index, clause in enumerate(clauses)
+ if _sqlite_clause_column(clause) is None
+ ),
+ len(clauses),
+ )
+ clauses.insert(constraint_position, '"unexpected" TEXT')
+ elif mutation == "column-order":
+ column_positions = [
+ index
+ for index, clause in enumerate(clauses)
+ if _sqlite_clause_column(clause) is not None
+ ]
+ first, second = column_positions[:2]
+ clauses[first], clauses[second] = clauses[second], clauses[first]
+ elif mutation == "column-type":
+ clauses = _replace_sqlite_column_clause(
+ clauses,
+ "applied_at",
+ '"applied_at" INTEGER NOT NULL '
+ "DEFAULT (datetime('now'))",
+ )
+ elif mutation == "column-nullability":
+ clauses = _replace_sqlite_column_clause(
+ clauses,
+ "applied_at",
+ '"applied_at" TEXT DEFAULT (datetime(\'now\'))',
+ )
+ elif mutation == "column-default":
+ clauses = _replace_sqlite_column_clause(
+ clauses,
+ "applied_at",
+ '"applied_at" TEXT NOT NULL DEFAULT \'unexpected\'',
+ )
+ else:
+ clauses = _replace_sqlite_constraint_clause(
+ clauses,
+ "primary key",
+ lambda clause: re.sub(
+ r"PRIMARY\s+KEY\s*\([^)]*\)",
+ "PRIMARY KEY (version, applied_at)",
+ clause,
+ count=1,
+ flags=re.IGNORECASE,
+ ),
+ )
+ _rebuild_sqlite_mutation_table(
+ connection,
+ "schema_version",
+ clauses,
+ )
+ return
+ if mutation in {
+ "foreign-key-target",
+ "foreign-key-delete",
+ "foreign-key-update",
+ }:
+ clauses = _sqlite_table_clauses(connection, "module_runs")
+
+ def _mutate_foreign_key(clause: str) -> str:
+ if mutation == "foreign-key-target":
+ return re.sub(
+ r'REFERENCES\s+["`]?campaigns["`]?\s*'
+ r'\(\s*["`]?id["`]?\s*\)',
+ "REFERENCES users (id)",
+ clause,
+ count=1,
+ flags=re.IGNORECASE,
+ )
+ if mutation == "foreign-key-delete":
+ return re.sub(
+ r"ON\s+DELETE\s+CASCADE",
+ "ON DELETE RESTRICT",
+ clause,
+ count=1,
+ flags=re.IGNORECASE,
+ )
+ return f"{clause} ON UPDATE CASCADE"
+
+ clauses = _replace_sqlite_constraint_clause(
+ clauses,
+ "foreign key",
+ _mutate_foreign_key,
+ )
+ _rebuild_sqlite_mutation_table(
+ connection,
+ "module_runs",
+ clauses,
+ )
+ return
+ if mutation in {"check-always-true", "check-expanded-values"}:
+ clauses = _sqlite_table_clauses(connection, "rate_limit_events")
+ expression = (
+ "1"
+ if mutation == "check-always-true"
+ else "blocked IN (0, 1, 2)"
+ )
+ clauses = _replace_sqlite_constraint_clause(
+ clauses,
+ "ck_rate_limit_events_blocked_bool",
+ lambda _clause: (
+ "CONSTRAINT ck_rate_limit_events_blocked_bool "
+ f"CHECK ({expression})"
+ ),
+ )
+ _rebuild_sqlite_mutation_table(
+ connection,
+ "rate_limit_events",
+ clauses,
+ )
+ return
+ if mutation == "index-columns":
+ connection.execute("DROP INDEX idx_findings_campaign")
+ connection.execute(
+ "CREATE INDEX idx_findings_campaign ON findings(severity)"
+ )
+ connection.commit()
+ return
+ if mutation == "index-order":
+ clauses = _sqlite_table_clauses(connection, "hosts")
+ clauses = _replace_sqlite_constraint_clause(
+ clauses,
+ "uq_hosts_campaign_ip",
+ lambda clause: re.sub(
+ r"UNIQUE\s*\(\s*[\"`]?campaign_id[\"`]?\s*,\s*"
+ r"[\"`]?ip_address[\"`]?\s*\)",
+ "UNIQUE (ip_address, campaign_id)",
+ clause,
+ count=1,
+ flags=re.IGNORECASE,
+ ),
+ )
+ _rebuild_sqlite_mutation_table(connection, "hosts", clauses)
+ return
+ if mutation == "index-uniqueness":
+ connection.execute("DROP INDEX idx_findings_campaign")
+ connection.execute(
+ "CREATE UNIQUE INDEX idx_findings_campaign "
+ "ON findings(campaign_id)"
+ )
+ connection.commit()
+ return
+ if mutation == "duplicate-equivalent-index":
+ connection.execute(
+ "CREATE INDEX idx_unexpected_duplicate "
+ "ON findings(campaign_id)"
+ )
+ connection.commit()
+ return
+ if mutation == "autoincrement":
+ clauses = _sqlite_table_clauses(connection, "audit_log")
+ clauses = [
+ re.sub(
+ r"\s+AUTOINCREMENT\b",
+ "",
+ clause,
+ count=1,
+ flags=re.IGNORECASE,
+ )
+ for clause in clauses
+ ]
+ _rebuild_sqlite_mutation_table(connection, "audit_log", clauses)
+ return
+ raise AssertionError("unknown real SQLite catalog mutation")
+
+
+def _catalog_contract_changed_fields(
+ actual: _CatalogContract,
+ expected: _CatalogContract,
+) -> set[str]:
+ return {
+ name
+ for name in (
+ "tables",
+ "columns",
+ "primary_keys",
+ "unique_constraints",
+ "checks",
+ "foreign_keys",
+ "indexes",
+ "autoincrement_tables",
+ )
+ if getattr(actual, name) != getattr(expected, name)
+ }
+
+
+ ("mutation", "intended_fields"),
+ [
+ ("missing-table", {"tables", "columns", "primary_keys"}),
+ ("extra-table", {"tables", "columns", "primary_keys"}),
+ ("missing-column", {"columns"}),
+ ("extra-column", {"columns"}),
+ ("column-order", {"columns"}),
+ ("column-type", {"columns"}),
+ ("column-nullability", {"columns"}),
+ ("column-default", {"columns"}),
+ ("primary-key-order", {"columns", "primary_keys"}),
+ ("foreign-key-target", {"foreign_keys"}),
+ ("foreign-key-delete", {"foreign_keys"}),
+ ("foreign-key-update", {"foreign_keys"}),
+ ("check-always-true", {"checks"}),
+ ("check-expanded-values", {"checks"}),
+ ("index-columns", {"indexes"}),
+ ("index-order", {"unique_constraints"}),
+ ("index-uniqueness", {"indexes"}),
+ ("duplicate-equivalent-index", {"indexes"}),
+ ("autoincrement", {"autoincrement_tables"}),
+ ],
+)
+def test_real_sqlite_catalog_mutations_are_rejected_by_fixed_oracle(
+ monkeypatch: pytest.MonkeyPatch,
+ mutation: str,
+ intended_fields: set[str],
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database(f"real-oracle-{mutation}") as path:
+ _upgrade(path, "0006")
+ connection = _connect(path)
+ try:
+ expected = _fixed_sqlite_contract("0006")
+ pristine = _sqlite_catalog_contract(connection)
+ _apply_real_sqlite_catalog_mutation(connection, mutation)
+ actual = _sqlite_catalog_contract(connection)
+ changed_fields = _catalog_contract_changed_fields(
+ actual,
+ expected,
+ )
+ integrity_ok = (
+ connection.execute("PRAGMA integrity_check").fetchone()
+ == ("ok",)
+ )
+ finally:
+ connection.close()
+ rejected_for_intended_property = (
+ pristine == expected
+ and actual != expected
+ and changed_fields == intended_fields
+ and integrity_ok
+ and _version(path) == "0006"
+ )
+ _require_fixed(
+ rejected_for_intended_property,
+ "real SQLite mutation did not isolate the intended contract",
+ )
+
+
+def test_fresh_revision_0006_catalog_and_constraints(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("catalog") as path:
+ _upgrade(path, "0006")
+ connection = _connect(path)
+ try:
+ tables = {
+ str(row[0])
+ for row in connection.execute(
+ """
+ SELECT name FROM sqlite_master
+ WHERE type='table' AND name NOT LIKE 'sqlite_%'
+ """
+ )
+ }
+ application_tables_match = (
+ tables
+ == _EXPECTED_APP_TABLES
+ | {"alembic_version", "schema_version"}
+ and {"alembic_version", "schema_version"}.issubset(tables)
+ and "websocket_tickets" not in tables
+ )
+ columns_match = all(
+ _ordered_column_fingerprint(connection, table)
+ == _EXPECTED_SQLITE_COLUMN_FINGERPRINTS[table]
+ and tuple(_column_map(connection, table)) == expected
+ for table, expected in _EXPECTED_COLUMN_ORDER.items()
+ )
+ primary_keys_match = all(
+ sum(item[3] for item in _column_map(connection, table).values())
+ == 1
+ for table in _EXPECTED_APP_TABLES
+ )
+ indexes_match = _index_map(connection) == _EXPECTED_INDEXES
+ foreign_keys_match = (
+ _foreign_keys(connection) == _EXPECTED_FOREIGN_KEYS
+ )
+ unique_constraints_match = (
+ _unique_constraints(connection)
+ == _EXPECTED_UNIQUE_CONSTRAINTS
+ )
+ autoincrement_tables = {
+ str(row[0])
+ for row in connection.execute(
+ """
+ SELECT name FROM sqlite_master
+ WHERE type='table' AND upper(sql) LIKE '%AUTOINCREMENT%'
+ """
+ )
+ }
+ autoincrement_match = autoincrement_tables == {
+ "audit_log",
+ "rate_limit_events",
+ }
+ blocked_table_sql = connection.execute(
+ """
+ SELECT sql FROM sqlite_master
+ WHERE type='table' AND name='rate_limit_events'
+ """
+ ).fetchone()
+ blocked_check_match = (
+ blocked_table_sql is not None
+ and "blocked in (0, 1)"
+ in " ".join(str(blocked_table_sql[0]).lower().split())
+ )
+
+ finding_columns = _column_map(connection, "findings")
+ critical_nullability = (
+ finding_columns["cvss_score"][1] == 1
+ and finding_columns["cvss_vector"][1] == 1
+ and finding_columns["trace_id"][1] == 1
+ )
+ timestamp_defaults = all(
+ "datetime" in str(default).lower()
+ for table, column in (
+ ("campaigns", "created_at"),
+ ("module_runs", "completed_at"),
+ ("findings", "discovered_at"),
+ ("rate_limit_events", "timestamp"),
+ ("revoked_access_tokens", "revoked_at"),
+ )
+ for default in [_column_map(connection, table)[column][2]]
+ )
+
+ bad_fk_rejected = False
+ try:
+ connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title, description, severity
+ ) VALUES(?, ?, ?, ?, ?, ?)
+ """,
+ (
+ "finding-a",
+ "missing-campaign",
+ "module-a",
+ "title",
+ "description",
+ "high",
+ ),
+ )
+ except sqlite3.IntegrityError:
+ bad_fk_rejected = True
+ finally:
+ connection.rollback()
+ finally:
+ connection.close()
+
+ _require_fixed(
+ application_tables_match,
+ "revision 0006 table contract is incomplete",
+ )
+ _require_fixed(
+ columns_match,
+ "revision 0006 column contract is incomplete",
+ )
+ _require_fixed(
+ primary_keys_match,
+ "revision 0006 primary-key contract is incomplete",
+ )
+ _require_fixed(
+ indexes_match,
+ "revision 0006 logical index contract diverged",
+ )
+ _require_fixed(
+ foreign_keys_match,
+ "revision 0006 foreign-key contract diverged",
+ )
+ _require_fixed(
+ unique_constraints_match,
+ "revision 0006 uniqueness contract diverged",
+ )
+ _require_fixed(
+ autoincrement_match,
+ "revision 0006 SQLite autoincrement contract diverged",
+ )
+ _require_fixed(
+ blocked_check_match,
+ "revision 0006 blocked check contract diverged",
+ )
+ _require_fixed(
+ critical_nullability,
+ "finding hardening contract diverged",
+ )
+ _require_fixed(
+ timestamp_defaults,
+ "SQLite database-time defaults diverged",
+ )
+ _require_fixed(
+ bad_fk_rejected,
+ "SQLite did not enforce a required foreign key",
+ )
+
+
+def test_sqlite_revision_0006_enforces_relational_contract(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("enforcement") as path:
+ _upgrade(path, "0006")
+ connection = _connect(path)
+ try:
+ _seed_complete_contract(connection)
+ key_by_table = {
+ "campaigns": ("id", "campaign-contract"),
+ "module_runs": ("id", "run-contract"),
+ "findings": ("id", "finding-contract"),
+ "hosts": ("id", "host-contract"),
+ "credentials": ("id", "credential-contract"),
+ "loot": ("id", "loot-contract"),
+ "audit_log": ("id", 1),
+ "users": ("id", "user-contract"),
+ "api_keys": ("id", "api-key-contract"),
+ "refresh_tokens": ("id", "refresh-contract"),
+ "revoked_access_tokens": ("jti", "revoked-contract"),
+ "rate_limit_events": ("id", 1),
+ }
+
+ required_columns_rejected = True
+ for table, columns in _EXPECTED_SQLITE_COLUMN_FINGERPRINTS.items():
+ key_name, key_value = key_by_table[table]
+ for name, _kind, required, _default, primary in columns:
+ if not required or primary:
+ continue
+ statement = (
+ f'UPDATE "{table}" SET "{name}"=NULL ' # noqa: S608
+ f'WHERE "{key_name}"=?'
+ )
+ if not _expected_integrity_failure(
+ connection,
+ statement,
+ (key_value,),
+ ):
+ required_columns_rejected = False
+ break
+
+ foreign_keys_rejected = True
+ for table, local, _remote, _remote_column, _action in sorted(
+ _EXPECTED_FOREIGN_KEYS
+ ):
+ key_name, key_value = key_by_table[table]
+ statement = (
+ f'UPDATE "{table}" SET "{local}"=? ' # noqa: S608
+ f'WHERE "{key_name}"=?'
+ )
+ if not _expected_integrity_failure(
+ connection,
+ statement,
+ ("missing-parent", key_value),
+ ):
+ foreign_keys_rejected = False
+ break
+
+ duplicate_host_rejected = _expected_integrity_failure(
+ connection,
+ """
+ INSERT INTO hosts(id, campaign_id, ip_address)
+ VALUES(?, ?, ?)
+ """,
+ ("host-duplicate", "campaign-contract", "192.0.2.10"),
+ )
+ duplicate_username_rejected = _expected_integrity_failure(
+ connection,
+ """
+ INSERT INTO users(id, username, hashed_password)
+ VALUES(?, ?, ?)
+ """,
+ ("user-duplicate", "synthetic-account", "synthetic-hash"),
+ )
+
+ connection.execute("SAVEPOINT set_null_probe")
+ connection.execute(
+ "DELETE FROM hosts WHERE id=?",
+ ("host-contract",),
+ )
+ host_dependents = connection.execute(
+ """
+ SELECT
+ (SELECT host_id IS NULL FROM credentials WHERE id=?),
+ (SELECT host_id IS NULL FROM loot WHERE id=?)
+ """,
+ ("credential-contract", "loot-contract"),
+ ).fetchone()
+ set_null_enforced = host_dependents == (1, 1)
+ connection.execute("ROLLBACK TO set_null_probe")
+ connection.execute("RELEASE set_null_probe")
+
+ connection.execute("SAVEPOINT campaign_cascade_probe")
+ connection.execute(
+ "DELETE FROM campaigns WHERE id=?",
+ ("campaign-contract",),
+ )
+ campaign_dependents = connection.execute(
+ """
+ SELECT
+ (SELECT count(*) FROM module_runs),
+ (SELECT count(*) FROM findings),
+ (SELECT count(*) FROM hosts),
+ (SELECT count(*) FROM credentials),
+ (SELECT count(*) FROM loot),
+ (SELECT campaign_id IS NULL FROM audit_log WHERE id=1)
+ """
+ ).fetchone()
+ campaign_actions_enforced = campaign_dependents == (
+ 0,
+ 0,
+ 0,
+ 0,
+ 0,
+ 1,
+ )
+ connection.execute("ROLLBACK TO campaign_cascade_probe")
+ connection.execute("RELEASE campaign_cascade_probe")
+
+ connection.execute("SAVEPOINT user_cascade_probe")
+ connection.execute(
+ "DELETE FROM users WHERE id=?",
+ ("user-contract",),
+ )
+ user_dependents = connection.execute(
+ """
+ SELECT
+ (SELECT count(*) FROM api_keys),
+ (SELECT count(*) FROM refresh_tokens)
+ """
+ ).fetchone()
+ user_cascade_enforced = user_dependents == (0, 0)
+ connection.execute("ROLLBACK TO user_cascade_probe")
+ connection.execute("RELEASE user_cascade_probe")
+
+ timestamp_defaults_execute = all(
+ connection.execute(
+ f'SELECT "{column}" IS NOT NULL ' # noqa: S608
+ f'AND typeof("{column}")="text" FROM "{table}" LIMIT 1'
+ ).fetchone()
+ == (1,)
+ for table, column in (
+ ("campaigns", "created_at"),
+ ("module_runs", "completed_at"),
+ ("findings", "discovered_at"),
+ ("hosts", "first_seen"),
+ ("credentials", "captured_at"),
+ ("loot", "captured_at"),
+ ("audit_log", "timestamp"),
+ ("users", "created_at"),
+ ("api_keys", "created_at"),
+ ("refresh_tokens", "created_at"),
+ ("revoked_access_tokens", "revoked_at"),
+ ("rate_limit_events", "timestamp"),
+ )
+ )
+ integer_defaults_execute = (
+ connection.execute(
+ """
+ SELECT
+ (SELECT success=0 FROM module_runs LIMIT 1),
+ (SELECT validated=0 AND false_positive=0
+ FROM findings LIMIT 1),
+ (SELECT is_dc=0 FROM hosts LIMIT 1),
+ (SELECT cracked=0 FROM credentials LIMIT 1),
+ (SELECT is_active=1 FROM users LIMIT 1),
+ (SELECT is_active=1 FROM api_keys LIMIT 1),
+ (SELECT is_revoked=0 FROM refresh_tokens LIMIT 1),
+ (SELECT blocked=0 FROM rate_limit_events LIMIT 1)
+ """
+ ).fetchone()
+ == (1, 1, 1, 1, 1, 1, 1, 1)
+ )
+
+ connection.execute(
+ "INSERT INTO audit_log(action) VALUES(?)",
+ ("second-action",),
+ )
+ audit_second = int(connection.execute(
+ "SELECT max(id) FROM audit_log"
+ ).fetchone()[0])
+ connection.execute(
+ "DELETE FROM audit_log WHERE id=?",
+ (audit_second,),
+ )
+ connection.execute(
+ "INSERT INTO audit_log(action) VALUES(?)",
+ ("third-action",),
+ )
+ audit_third = int(connection.execute(
+ "SELECT max(id) FROM audit_log"
+ ).fetchone()[0])
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES(?, ?)
+ """,
+ ("192.0.2.21", "synthetic-bucket"),
+ )
+ rate_second = int(connection.execute(
+ "SELECT max(id) FROM rate_limit_events"
+ ).fetchone()[0])
+ connection.execute(
+ "DELETE FROM rate_limit_events WHERE id=?",
+ (rate_second,),
+ )
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES(?, ?)
+ """,
+ ("192.0.2.22", "synthetic-bucket"),
+ )
+ rate_third = int(connection.execute(
+ "SELECT max(id) FROM rate_limit_events"
+ ).fetchone()[0])
+ connection.commit()
+ monotonic_ids = (
+ audit_third > audit_second and rate_third > rate_second
+ )
+ finally:
+ connection.close()
+
+ _require_fixed(
+ required_columns_rejected,
+ "SQLite accepted NULL in a required non-primary column",
+ )
+ _require_fixed(
+ foreign_keys_rejected,
+ "SQLite accepted an invalid foreign-key parent",
+ )
+ _require_fixed(
+ duplicate_host_rejected and duplicate_username_rejected,
+ "SQLite uniqueness enforcement diverged",
+ )
+ _require_fixed(
+ set_null_enforced,
+ "SQLite SET NULL behavior diverged",
+ )
+ _require_fixed(
+ campaign_actions_enforced and user_cascade_enforced,
+ "SQLite cascade behavior diverged",
+ )
+ _require_fixed(
+ timestamp_defaults_execute,
+ "SQLite timestamp default behavior diverged",
+ )
+ _require_fixed(
+ integer_defaults_execute,
+ "SQLite integer default behavior diverged",
+ )
+ _require_fixed(
+ monotonic_ids,
+ "SQLite autoincrement behavior diverged",
+ )
+
+
+def test_revision_0003_blocked_integer_contract_is_enforced(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("blocked-contract") as path:
+ _upgrade(path, "0003")
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "INSERT INTO rate_limit_events(ip_address, bucket) VALUES(?, ?)",
+ ("synthetic-a", "bucket"),
+ )
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket, blocked)
+ VALUES(?, ?, ?)
+ """,
+ ("synthetic-b", "bucket", 0),
+ )
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket, blocked)
+ VALUES(?, ?, ?)
+ """,
+ ("synthetic-c", "bucket", 1),
+ )
+ connection.commit()
+ valid_rows = connection.execute(
+ """
+ SELECT count(*), min(blocked), max(blocked)
+ FROM rate_limit_events
+ """
+ ).fetchone()
+
+ rejected = 0
+ for index, value in enumerate((None, -1, 2, 17)):
+ try:
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(
+ ip_address, bucket, blocked
+ ) VALUES(?, ?, ?)
+ """,
+ (f"synthetic-invalid-{index}", "bucket", value),
+ )
+ connection.commit()
+ except sqlite3.IntegrityError:
+ rejected += 1
+ connection.rollback()
+ invalid_rows = connection.execute(
+ """
+ SELECT count(*) FROM rate_limit_events
+ WHERE ip_address LIKE 'synthetic-invalid-%'
+ """
+ ).fetchone()
+ reusable = connection.execute("SELECT 1").fetchone() == (1,)
+ table_sql = connection.execute(
+ """
+ SELECT sql FROM sqlite_master
+ WHERE type='table' AND name='rate_limit_events'
+ """
+ ).fetchone()
+ normalized_check = (
+ table_sql is not None
+ and "blocked IN (0, 1)"
+ in " ".join(str(table_sql[0]).split())
+ )
+ finally:
+ connection.close()
+
+ contract_enforced = (
+ valid_rows == (3, 0, 1)
+ and rejected == 4
+ and invalid_rows == (0,)
+ and reusable
+ and normalized_check
+ )
+ _require_fixed(
+ contract_enforced,
+ "revision 0003 blocked contract was not enforced",
+ )
+
+ _downgrade(path, "0002")
+ connection = _connect(path)
+ try:
+ removed = connection.execute(
+ """
+ SELECT 1 FROM sqlite_master
+ WHERE type='table' AND name='rate_limit_events'
+ """
+ ).fetchone() is None
+ finally:
+ connection.close()
+ _upgrade(path, "0003")
+ connection = _connect(path)
+ try:
+ reupgrade_rejected = False
+ try:
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(
+ ip_address, bucket, blocked
+ ) VALUES(?, ?, ?)
+ """,
+ ("synthetic-reupgrade", "bucket", 2),
+ )
+ connection.commit()
+ except sqlite3.IntegrityError:
+ reupgrade_rejected = True
+ connection.rollback()
+ finally:
+ connection.close()
+ _require_fixed(
+ removed and reupgrade_rejected,
+ "revision 0003 downgrade/re-upgrade lost enforcement",
+ )
+
+
+def test_sqlite_autoincrement_sequence_lifecycle_is_monotonic(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("autoincrement-sequence") as path:
+ _upgrade(path, "0003")
+ connection = _connect(path)
+ try:
+ connection.execute(
+ """
+ CREATE TABLE unrelated_sequence_probe(
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ marker TEXT NOT NULL
+ )
+ """
+ )
+ connection.execute(
+ "INSERT INTO unrelated_sequence_probe(marker) VALUES(?)",
+ ("synthetic",),
+ )
+ for action in ("first", "second"):
+ connection.execute(
+ "INSERT INTO audit_log(action) VALUES(?)",
+ (action,),
+ )
+ for address in ("192.0.2.50", "192.0.2.51"):
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES(?, ?)
+ """,
+ (address, "bucket"),
+ )
+ connection.execute("DELETE FROM audit_log WHERE id=2")
+ connection.execute(
+ "INSERT INTO audit_log(action) VALUES(?)",
+ ("third",),
+ )
+ connection.execute(
+ "INSERT INTO audit_log(id, action) VALUES(?, ?)",
+ (100, "explicit-high"),
+ )
+ connection.execute(
+ "INSERT INTO audit_log(action) VALUES(?)",
+ ("after-high",),
+ )
+ connection.execute(
+ "DELETE FROM rate_limit_events WHERE id=2"
+ )
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES(?, ?)
+ """,
+ ("192.0.2.52", "bucket"),
+ )
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(id, ip_address, bucket)
+ VALUES(?, ?, ?)
+ """,
+ (200, "192.0.2.53", "bucket"),
+ )
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES(?, ?)
+ """,
+ ("192.0.2.54", "bucket"),
+ )
+ connection.commit()
+ allocated = (
+ connection.execute(
+ "SELECT max(id) FROM audit_log"
+ ).fetchone()
+ == (101,)
+ and connection.execute(
+ "SELECT max(id) FROM rate_limit_events"
+ ).fetchone()
+ == (201,)
+ )
+ sequence_rows = dict(
+ connection.execute(
+ """
+ SELECT name, seq FROM sqlite_sequence
+ WHERE name IN (
+ 'audit_log',
+ 'rate_limit_events',
+ 'unrelated_sequence_probe'
+ )
+ """
+ )
+ )
+ sequence_state_matches = sequence_rows == {
+ "audit_log": 101,
+ "rate_limit_events": 201,
+ "unrelated_sequence_probe": 1,
+ }
+ finally:
+ connection.close()
+
+ _downgrade(path, "0002")
+ connection = _connect(path)
+ try:
+ after_rate_drop = dict(
+ connection.execute(
+ "SELECT name, seq FROM sqlite_sequence"
+ )
+ )
+ finally:
+ connection.close()
+ rate_sequence_removed = (
+ "rate_limit_events" not in after_rate_drop
+ and after_rate_drop.get("audit_log") == 101
+ and after_rate_drop.get("unrelated_sequence_probe") == 1
+ )
+
+ _downgrade(path, "base")
+ connection = _connect(path)
+ try:
+ after_base = dict(
+ connection.execute(
+ "SELECT name, seq FROM sqlite_sequence"
+ )
+ )
+ finally:
+ connection.close()
+ audit_sequence_removed = (
+ "audit_log" not in after_base
+ and after_base.get("unrelated_sequence_probe") == 1
+ )
+
+ _upgrade(path, "0003")
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "INSERT INTO audit_log(action) VALUES(?)",
+ ("fresh",),
+ )
+ connection.execute(
+ """
+ INSERT INTO rate_limit_events(ip_address, bucket)
+ VALUES(?, ?)
+ """,
+ ("192.0.2.55", "bucket"),
+ )
+ connection.commit()
+ clean_reinitialization = (
+ connection.execute(
+ "SELECT max(id) FROM audit_log"
+ ).fetchone()
+ == (1,)
+ and connection.execute(
+ "SELECT max(id) FROM rate_limit_events"
+ ).fetchone()
+ == (1,)
+ and connection.execute(
+ """
+ SELECT seq FROM sqlite_sequence
+ WHERE name='unrelated_sequence_probe'
+ """
+ ).fetchone()
+ == (1,)
+ )
+ finally:
+ connection.close()
+
+ _require_fixed(
+ allocated
+ and sequence_state_matches
+ and rate_sequence_removed
+ and audit_sequence_removed
+ and clean_reinitialization,
+ "SQLite AUTOINCREMENT sequence lifecycle diverged",
+ )
+
+
+ "legacy_revision",
+ ["0001", "0002", "0003", "0004", "0005"],
+)
+def test_complete_head_era_catalogs_preserve_data_and_defer_known_drift(
+ monkeypatch: pytest.MonkeyPatch,
+ legacy_revision: str,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database(f"complete-legacy-{legacy_revision}") as path:
+ _create_transformed_legacy_catalog(path, legacy_revision)
+ connection = _connect(path)
+ try:
+ initial_fingerprint_matches = (
+ _sqlite_catalog_contract(connection)
+ == _fixed_legacy_sqlite_contract(legacy_revision)
+ and _version(path) == legacy_revision
+ )
+ finally:
+ connection.close()
+ _require_fixed(
+ initial_fingerprint_matches,
+ "frozen HEAD-era catalog fingerprint diverged",
+ )
+
+ _upgrade(path, "0006")
+ connection = _connect(path)
+ try:
+ row_counts = connection.execute(
+ """
+ SELECT
+ (SELECT count(*) FROM campaigns),
+ (SELECT count(*) FROM findings),
+ (SELECT count(*) FROM hosts),
+ (SELECT count(*) FROM credentials),
+ (SELECT count(*) FROM loot),
+ (SELECT count(*) FROM audit_log),
+ (SELECT count(*) FROM users),
+ (SELECT count(*) FROM api_keys),
+ (SELECT count(*) FROM refresh_tokens)
+ """
+ ).fetchone()
+ expected_finding_count = 3 if legacy_revision >= "0002" else 1
+ unrelated_rows_survived = row_counts == (
+ 1,
+ expected_finding_count,
+ 1,
+ 1,
+ 1,
+ 1,
+ 1,
+ 1,
+ 1,
+ )
+ credential_value_survived = (
+ connection.execute(
+ """
+ SELECT count(*) FROM credentials
+ WHERE cracked_value_enc IS NOT NULL
+ """
+ ).fetchone()
+ == (1,)
+ )
+ final_finding_columns = _column_map(connection, "findings")
+ cvss_drift_deferred = (
+ final_finding_columns["cvss_score"][1]
+ == (1 if legacy_revision == "0001" else 0)
+ and final_finding_columns["cvss_vector"][1]
+ == (1 if legacy_revision == "0001" else 0)
+ )
+ trace_drift_deferred = (
+ final_finding_columns["trace_id"][1]
+ == (0 if legacy_revision == "0005" else 1)
+ )
+ table_names = {
+ str(row[0])
+ for row in connection.execute(
+ """
+ SELECT name FROM sqlite_master
+ WHERE type='table' AND name NOT LIKE 'sqlite_%'
+ """
+ )
+ }
+ structural_drift_remains = (
+ "module_runs" not in table_names
+ and "schema_version" not in table_names
+ and not _foreign_keys(connection)
+ and "idx_findings_validated"
+ in {
+ str(row[0])
+ for row in connection.execute(
+ """
+ SELECT name FROM sqlite_master
+ WHERE type='index' AND sql IS NOT NULL
+ """
+ )
+ }
+ )
+ rate_check_state_is_historical = True
+ if legacy_revision >= "0003":
+ rate_sql = connection.execute(
+ """
+ SELECT sql FROM sqlite_master
+ WHERE type='table' AND name='rate_limit_events'
+ """
+ ).fetchone()
+ rate_check_state_is_historical = (
+ rate_sql is not None
+ and "blocked in (0,1)"
+ not in str(rate_sql[0]).lower().replace(" ", "")
+ )
+ final_revision = _version(path) == "0006"
+ finally:
+ connection.close()
+
+ _require_fixed(
+ unrelated_rows_survived and credential_value_survived,
+ "legacy upgrade lost protected or unrelated rows",
+ )
+ _require_fixed(
+ cvss_drift_deferred
+ and trace_drift_deferred
+ and structural_drift_remains
+ and rate_check_state_is_historical,
+ "legacy drift was silently misclassified as repaired",
+ )
+ _require_fixed(
+ final_revision,
+ "legacy catalog did not advance to revision 0006",
+ )
+
+
+def test_revision_0002_reconciles_legacy_missing_columns(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("legacy-0002") as path:
+ _upgrade(path, "0001")
+ connection = _connect(path)
+ try:
+ connection.execute("ALTER TABLE findings DROP COLUMN cvss_score")
+ connection.execute("ALTER TABLE findings DROP COLUMN cvss_vector")
+ connection.commit()
+ finally:
+ connection.close()
+ _upgrade(path, "0002")
+ connection = _connect(path)
+ try:
+ columns = _column_map(connection, "findings")
+ finally:
+ connection.close()
+ repaired = (
+ {"cvss_score", "cvss_vector", "trace_id"}.issubset(columns)
+ and columns["cvss_score"][1] == 1
+ and columns["cvss_vector"][1] == 1
+ )
+ _require_fixed(
+ repaired,
+ "revision 0002 did not reconcile the legacy catalog",
+ )
+
+
+def test_revision_0005_reconciles_missing_trace_column(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("legacy-0005") as path:
+ _upgrade(path, "0004")
+ connection = _connect(path)
+ try:
+ connection.execute("ALTER TABLE findings DROP COLUMN trace_id")
+ connection.commit()
+ finally:
+ connection.close()
+ _upgrade(path, "0005")
+ connection = _connect(path)
+ try:
+ trace = _column_map(connection, "findings").get("trace_id")
+ finally:
+ connection.close()
+ hardened = trace is not None and trace[1] == 1
+ _require_fixed(
+ hardened,
+ "revision 0005 did not reconcile missing trace metadata",
+ )
+
+
+def test_revision_0005_normalizes_only_null_trace_values(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("trace-normalization") as path:
+ _upgrade(path, "0004")
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES(?, ?)",
+ ("campaign-trace", "Migration campaign"),
+ )
+ for index, trace_value in enumerate((None, "", "trace-marker")):
+ connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, trace_id
+ ) VALUES(?, ?, ?, ?, ?, ?, ?)
+ """,
+ (
+ f"finding-{index}",
+ "campaign-trace",
+ "module",
+ f"title-{index}",
+ "description",
+ "low",
+ trace_value,
+ ),
+ )
+ connection.commit()
+ finally:
+ connection.close()
+
+ _upgrade(path, "0005")
+ connection = _connect(path)
+ try:
+ upgraded = connection.execute(
+ """
+ SELECT
+ count(*),
+ sum(trace_id IS NULL),
+ sum(trace_id=''),
+ sum(trace_id='trace-marker'),
+ count(DISTINCT title)
+ FROM findings
+ """
+ ).fetchone()
+ finally:
+ connection.close()
+ _require_fixed(
+ upgraded == (3, 0, 2, 1, 3),
+ "revision 0005 trace normalization changed protected state",
+ )
+
+ _downgrade(path, "0004")
+ connection = _connect(path)
+ try:
+ downgraded = connection.execute(
+ """
+ SELECT count(*), sum(trace_id=''), sum(trace_id='trace-marker')
+ FROM findings
+ """
+ ).fetchone()
+ connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, trace_id
+ ) VALUES(?, ?, ?, ?, ?, ?, NULL)
+ """,
+ (
+ "finding-after-downgrade",
+ "campaign-trace",
+ "module",
+ "title-after-downgrade",
+ "description",
+ "low",
+ ),
+ )
+ connection.commit()
+ finally:
+ connection.close()
+ _require_fixed(
+ downgraded == (3, 2, 1),
+ "revision 0005 downgrade reconstructed legacy NULL state",
+ )
+
+ _upgrade(path, "0005")
+ connection = _connect(path)
+ try:
+ reupgraded = connection.execute(
+ """
+ SELECT
+ count(*),
+ sum(trace_id IS NULL),
+ sum(trace_id=''),
+ sum(trace_id='trace-marker')
+ FROM findings
+ """
+ ).fetchone()
+ finally:
+ connection.close()
+ _require_fixed(
+ reupgraded == (4, 0, 3, 1),
+ "revision 0005 re-upgrade normalization diverged",
+ )
+
+
+def _install_sqlite_version_failure(path: Path) -> None:
+ connection = _connect(path)
+ try:
+ connection.execute(
+ """
+ CREATE TRIGGER migration_version_failure
+ BEFORE UPDATE ON alembic_version
+ BEGIN
+ SELECT RAISE(ABORT, 'migration version update denied');
+ END
+ """
+ )
+ connection.commit()
+ finally:
+ connection.close()
+
+
+def _remove_sqlite_version_failure(path: Path) -> None:
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "DROP TRIGGER IF EXISTS migration_version_failure"
+ )
+ connection.commit()
+ finally:
+ connection.close()
+
+
+class _PrimaryTraceMigrationError(RuntimeError):
+ pass
+
+
+class _RollbackSavepointError(RuntimeError):
+ pass
+
+
+class _ReleaseSavepointError(RuntimeError):
+ pass
+
+
+class _SavepointCreationError(RuntimeError):
+ pass
+
+
+class _ConnectionInvalidationError(RuntimeError):
+ pass
+
+
+class _TraceSavepointBind:
+ def __init__(
+ self,
+ *,
+ fail_savepoint: bool = False,
+ fail_rollback: bool = False,
+ fail_release: bool = False,
+ fail_invalidate: bool = False,
+ ) -> None:
+ self.fail_savepoint = fail_savepoint
+ self.fail_rollback = fail_rollback
+ self.fail_release = fail_release
+ self.fail_invalidate = fail_invalidate
+ self.actions: list[str] = []
+ self.invalidation_attempted = False
+ self.commit_called = False
+
+ def exec_driver_sql(self, statement: str) -> None:
+ normalized = " ".join(statement.upper().split())
+ if normalized.startswith("SAVEPOINT "):
+ action = "savepoint"
+ elif normalized.startswith("ROLLBACK TO SAVEPOINT "):
+ action = "rollback"
+ elif normalized.startswith("RELEASE SAVEPOINT "):
+ action = "release"
+ else:
+ action = "unexpected"
+ self.actions.append(action)
+ if action == "savepoint" and self.fail_savepoint:
+ raise _SavepointCreationError
+ if action == "rollback" and self.fail_rollback:
+ raise _RollbackSavepointError
+ if action == "release" and self.fail_release:
+ raise _ReleaseSavepointError
+
+ def invalidate(self) -> None:
+ self.invalidation_attempted = True
+ if self.fail_invalidate:
+ raise _ConnectionInvalidationError
+
+ def commit(self) -> None:
+ self.commit_called = True
+
+
+def _traceback_retains(
+ traceback: object,
+ expected: object,
+) -> bool:
+ current = traceback
+ while current is not None:
+ if current is expected:
+ return True
+ current = current.tb_next
+ return False
+
+
+ (
+ "fail_rollback",
+ "fail_release",
+ "fail_invalidate",
+ "expected_actions",
+ "expected_invalidation",
+ "expected_notes",
+ ),
+ [
+ (
+ False,
+ False,
+ False,
+ ("savepoint", "rollback", "release"),
+ False,
+ (),
+ ),
+ (
+ True,
+ False,
+ False,
+ ("savepoint", "rollback"),
+ True,
+ (
+ "Migration 0005 savepoint cleanup failed "
+ "[rollback-savepoint: _RollbackSavepointError]",
+ ),
+ ),
+ (
+ False,
+ True,
+ False,
+ ("savepoint", "rollback", "release"),
+ True,
+ (
+ "Migration 0005 savepoint cleanup failed "
+ "[release-savepoint: _ReleaseSavepointError]",
+ ),
+ ),
+ (
+ True,
+ False,
+ True,
+ ("savepoint", "rollback"),
+ True,
+ (
+ "Migration 0005 savepoint cleanup failed "
+ "[rollback-savepoint: _RollbackSavepointError]",
+ "Migration 0005 savepoint cleanup failed "
+ "[invalidate-connection: _ConnectionInvalidationError]",
+ ),
+ ),
+ ],
+ ids=(
+ "cleanup-succeeds",
+ "rollback-fails",
+ "release-fails",
+ "rollback-and-invalidation-fail",
+ ),
+)
+def test_revision_0005_savepoint_cleanup_preserves_primary_exception(
+ monkeypatch: pytest.MonkeyPatch,
+ fail_rollback: bool,
+ fail_release: bool,
+ fail_invalidate: bool,
+ expected_actions: tuple[str, ...],
+ expected_invalidation: bool,
+ expected_notes: tuple[str, ...],
+) -> None:
+ revision = importlib.import_module(
+ "migrations.versions.0005_add_trace_id_to_findings"
+ )
+ bind = _TraceSavepointBind(
+ fail_rollback=fail_rollback,
+ fail_release=fail_release,
+ fail_invalidate=fail_invalidate,
+ )
+ primary = _PrimaryTraceMigrationError()
+ original_traceback: list[object] = []
+
+ @contextmanager
+ def _failing_batch(*_args: object, **_kwargs: object) -> Iterator[object]:
+ try:
+ raise primary
+ except _PrimaryTraceMigrationError as error:
+ original_traceback.append(error.__traceback__)
+ raise
+ yield object()
+
+ monkeypatch.setattr(
+ revision,
+ "op",
+ types.SimpleNamespace(
+ get_bind=lambda: bind,
+ batch_alter_table=_failing_batch,
+ ),
+ )
+ caught: Exception | None = None
+ try:
+ revision._alter_trace("sqlite", nullable=False)
+ except _PrimaryTraceMigrationError as error:
+ caught = error
+ notes = tuple(getattr(caught, "__notes__", ()))
+ preserved = (
+ caught is primary
+ and len(original_traceback) == 1
+ and _traceback_retains(
+ getattr(caught, "__traceback__", None),
+ original_traceback[0],
+ )
+ and tuple(bind.actions) == expected_actions
+ and bind.invalidation_attempted is expected_invalidation
+ and notes == expected_notes
+ and not bind.commit_called
+ )
+ _require_fixed(
+ preserved,
+ "revision 0005 cleanup replaced or exposed the primary failure",
+ )
+
+
+def test_revision_0005_savepoint_creation_failure_does_not_run_cleanup(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ revision = importlib.import_module(
+ "migrations.versions.0005_add_trace_id_to_findings"
+ )
+ bind = _TraceSavepointBind(fail_savepoint=True)
+ batch_entered = False
+
+ @contextmanager
+ def _unexpected_batch(
+ *_args: object,
+ **_kwargs: object,
+ ) -> Iterator[object]:
+ nonlocal batch_entered
+ batch_entered = True
+ yield object()
+
+ monkeypatch.setattr(
+ revision,
+ "op",
+ types.SimpleNamespace(
+ get_bind=lambda: bind,
+ batch_alter_table=_unexpected_batch,
+ ),
+ )
+ caught: Exception | None = None
+ try:
+ revision._alter_trace("sqlite", nullable=False)
+ except _SavepointCreationError as error:
+ caught = error
+ failed_closed = (
+ isinstance(caught, _SavepointCreationError)
+ and bind.actions == ["savepoint"]
+ and not batch_entered
+ and not bind.commit_called
+ and not getattr(caught, "__notes__", ())
+ )
+ _require_fixed(
+ failed_closed,
+ "revision 0005 savepoint creation failure ran unsafe cleanup",
+ )
+
+
+class _MigrationCleanupProbeError(RuntimeError):
+ pass
+
+
+def test_alembic_command_preserves_revision_primary_and_traceback(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from alembic.operations import Operations
+ from sqlalchemy.ext.asyncio import AsyncEngine
+
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("0005-command-primary") as path:
+ _upgrade(path, "0004")
+ primary = _PrimaryTraceMigrationError()
+ original_traceback: list[object] = []
+ original_dispose = AsyncEngine.dispose
+
+ @contextmanager
+ def _raise_primary(
+ *_args: object,
+ **_kwargs: object,
+ ) -> Iterator[object]:
+ try:
+ raise primary
+ except _PrimaryTraceMigrationError as error:
+ original_traceback.append(error.__traceback__)
+ raise
+ yield object()
+
+ async def _dispose_then_fail(
+ engine: AsyncEngine,
+ *_args: object,
+ **_kwargs: object,
+ ) -> None:
+ await original_dispose(engine)
+ raise _MigrationCleanupProbeError
+
+ caught: Exception | None = None
+ with monkeypatch.context() as context:
+ context.setattr(
+ Operations,
+ "batch_alter_table",
+ _raise_primary,
+ )
+ context.setattr(
+ AsyncEngine,
+ "dispose",
+ _dispose_then_fail,
+ )
+ try:
+ _upgrade(path, "0005")
+ except Exception as error:
+ caught = error
+
+ notes = tuple(getattr(caught, "__notes__", ()))
+ preserved = (
+ caught is primary
+ and len(original_traceback) == 1
+ and _traceback_retains(
+ getattr(caught, "__traceback__", None),
+ original_traceback[0],
+ )
+ and notes
+ == (
+ "Alembic engine cleanup failed "
+ "[_MigrationCleanupProbeError]",
+ )
+ and _version(path) == "0004"
+ )
+ _require_fixed(
+ preserved,
+ "Alembic command replaced a revision-owned primary failure",
+ )
+
+
+def test_alembic_operational_failure_remains_sanitized(
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+) -> None:
+ import traceback
+
+ from alembic.operations import Operations
+ from sqlalchemy.exc import OperationalError
+ from sqlalchemy.ext.asyncio import AsyncEngine
+
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("0005-command-operational") as path:
+ _upgrade(path, "0004")
+ sensitive_marker = "operational-detail-canary"
+ cleanup_marker = "cleanup-detail-canary"
+ operational = OperationalError(
+ sensitive_marker,
+ {},
+ RuntimeError(sensitive_marker),
+ )
+ original_dispose = AsyncEngine.dispose
+
+ @contextmanager
+ def _raise_operational(
+ *_args: object,
+ **_kwargs: object,
+ ) -> Iterator[object]:
+ raise operational
+ yield object()
+
+ async def _dispose_then_fail(
+ engine: AsyncEngine,
+ *_args: object,
+ **_kwargs: object,
+ ) -> None:
+ await original_dispose(engine)
+ raise _MigrationCleanupProbeError(cleanup_marker)
+
+ caught: Exception | None = None
+ with monkeypatch.context() as context:
+ context.setattr(
+ Operations,
+ "batch_alter_table",
+ _raise_operational,
+ )
+ context.setattr(
+ AsyncEngine,
+ "dispose",
+ _dispose_then_fail,
+ )
+ try:
+ _upgrade(path, "0005")
+ except Exception as error:
+ caught = error
+
+ captured = capsys.readouterr()
+ rendered = (
+ ""
+ if caught is None
+ else "".join(
+ traceback.format_exception(
+ type(caught),
+ caught,
+ caught.__traceback__,
+ )
+ )
+ )
+ confidential = (
+ sensitive_marker
+ not in captured.out
+ and sensitive_marker not in captured.err
+ and sensitive_marker not in rendered
+ and cleanup_marker not in captured.out
+ and cleanup_marker not in captured.err
+ and cleanup_marker not in rendered
+ )
+ sanitized = (
+ type(caught) is RuntimeError
+ and str(caught)
+ == "Alembic online migration failed [OperationalError]"
+ and bool(getattr(caught, "__suppress_context__", False))
+ and _version(path) == "0004"
+ )
+ _require_fixed(
+ sanitized and confidential,
+ "Alembic operational failure diagnostics were not sanitized",
+ )
+
+
+def test_revision_0005_rollback_failure_invalidates_real_connection(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from alembic.operations import Operations
+ from sqlalchemy.engine import Connection
+
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("0005-rollback-invalidation") as path:
+ _upgrade(path, "0004")
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES(?, ?)",
+ ("campaign-invalidation", "Synthetic campaign"),
+ )
+ connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, trace_id
+ ) VALUES(?, ?, ?, ?, ?, ?, NULL)
+ """,
+ (
+ "finding-invalidation",
+ "campaign-invalidation",
+ "module",
+ "Synthetic title",
+ "Synthetic description",
+ "low",
+ ),
+ )
+ connection.commit()
+ finally:
+ connection.close()
+
+ original_batch = Operations.batch_alter_table
+ original_execute = Connection.execute
+ original_exec_driver_sql = Connection.exec_driver_sql
+ original_invalidate = Connection.invalidate
+ normalization_seen = False
+ rollback_failed = False
+ invalidation_seen = False
+ savepoint_actions: list[str] = []
+
+ @contextmanager
+ def _fail_after_normalization(
+ operations: Operations,
+ table_name: str,
+ *args: object,
+ **kwargs: object,
+ ) -> Iterator[object]:
+ if table_name == "findings":
+ raise _PrimaryTraceMigrationError
+ with original_batch(
+ operations,
+ table_name,
+ *args,
+ **kwargs,
+ ) as batch:
+ yield batch
+
+ def _record_normalization(
+ connection: Connection,
+ statement: object,
+ *args: object,
+ **kwargs: object,
+ ) -> object:
+ nonlocal normalization_seen
+ normalized = " ".join(str(statement).upper().split())
+ if normalized.startswith("UPDATE FINDINGS SET TRACE_ID="):
+ normalization_seen = True
+ return original_execute(connection, statement, *args, **kwargs)
+
+ def _fail_rollback_to_savepoint(
+ connection: Connection,
+ statement: str,
+ *args: object,
+ **kwargs: object,
+ ) -> object:
+ nonlocal rollback_failed
+ normalized = " ".join(statement.upper().split())
+ if normalized.startswith("SAVEPOINT "):
+ savepoint_actions.append("savepoint")
+ if normalized.startswith("ROLLBACK TO SAVEPOINT "):
+ savepoint_actions.append("rollback")
+ rollback_failed = True
+ raise _RollbackSavepointError
+ if normalized.startswith("RELEASE SAVEPOINT "):
+ savepoint_actions.append("release")
+ return original_exec_driver_sql(
+ connection,
+ statement,
+ *args,
+ **kwargs,
+ )
+
+ def _record_invalidation(
+ connection: Connection,
+ *args: object,
+ **kwargs: object,
+ ) -> None:
+ nonlocal invalidation_seen
+ invalidation_seen = True
+ original_invalidate(connection, *args, **kwargs)
+
+ caught_failure = False
+ with monkeypatch.context() as context:
+ context.setattr(
+ Operations,
+ "batch_alter_table",
+ _fail_after_normalization,
+ )
+ context.setattr(Connection, "execute", _record_normalization)
+ context.setattr(
+ Connection,
+ "exec_driver_sql",
+ _fail_rollback_to_savepoint,
+ )
+ context.setattr(Connection, "invalidate", _record_invalidation)
+ try:
+ _upgrade(path, "0005")
+ except _PrimaryTraceMigrationError:
+ caught_failure = True
+
+ connection = _connect(path)
+ try:
+ remained_exact_parent = (
+ _sqlite_catalog_contract(connection)
+ == _fixed_sqlite_contract("0004")
+ )
+ row_unchanged = (
+ connection.execute(
+ """
+ SELECT count(*), count(*) FILTER (WHERE trace_id IS NULL)
+ FROM findings
+ """
+ ).fetchone()
+ == (1, 1)
+ )
+ no_temporary_table = (
+ connection.execute(
+ """
+ SELECT count(*) FROM sqlite_master
+ WHERE type='table' AND name LIKE '_alembic_tmp_%'
+ """
+ ).fetchone()
+ == (0,)
+ )
+ foreign_keys_enabled = (
+ connection.execute("PRAGMA foreign_keys").fetchone() == (1,)
+ )
+ finally:
+ connection.close()
+ remained_at_parent = _version(path) == "0004"
+
+ _upgrade(path, "0005")
+ connection = _connect(path)
+ try:
+ retry_converged = (
+ _sqlite_catalog_contract(connection)
+ == _fixed_sqlite_contract("0005")
+ and connection.execute(
+ """
+ SELECT count(*), count(*) FILTER (WHERE trace_id='')
+ FROM findings
+ """
+ ).fetchone()
+ == (1, 1)
+ )
+ finally:
+ connection.close()
+ _require_fixed(
+ caught_failure
+ and normalization_seen
+ and rollback_failed
+ and invalidation_seen
+ and savepoint_actions == ["savepoint", "rollback"]
+ and remained_exact_parent
+ and row_unchanged
+ and remained_at_parent
+ and no_temporary_table
+ and foreign_keys_enabled
+ and _version(path) == "0005"
+ and retry_converged,
+ "revision 0005 rollback failure was not safely recoverable",
+ )
+
+
[email protected]("direction", ["upgrade", "downgrade"])
+ "boundary",
+ ["before-hardening", "after-hardening", "version-update"],
+)
+def test_revision_0005_failure_boundaries_are_recoverable(
+ monkeypatch: pytest.MonkeyPatch,
+ direction: str,
+ boundary: str,
+) -> None:
+ from alembic.operations import Operations
+
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database(f"0005-failure-{direction}-{boundary}") as path:
+ starting_revision = "0004" if direction == "upgrade" else "0005"
+ result_revision = "0005" if direction == "upgrade" else "0004"
+ _upgrade(path, starting_revision)
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES(?, ?)",
+ ("campaign-failure", "Synthetic campaign"),
+ )
+ trace_value = None if direction == "upgrade" else ""
+ connection.execute(
+ """
+ INSERT INTO findings(
+ id, campaign_id, module_id, title,
+ description, severity, trace_id
+ ) VALUES(?, ?, ?, ?, ?, ?, ?)
+ """,
+ (
+ "finding-failure",
+ "campaign-failure",
+ "module",
+ "Synthetic title",
+ "Synthetic description",
+ "low",
+ trace_value,
+ ),
+ )
+ connection.commit()
+ before_rows = connection.execute(
+ "SELECT count(*), count(DISTINCT title) FROM findings"
+ ).fetchone()
+ finally:
+ connection.close()
+
+ original_batch = Operations.batch_alter_table
+ if boundary != "version-update":
+
+ @contextmanager
+ def _failing_batch(
+ operations: Operations,
+ table_name: str,
+ *args: object,
+ **kwargs: object,
+ ) -> Iterator[object]:
+ if (
+ table_name == "findings"
+ and boundary == "before-hardening"
+ ):
+ raise RuntimeError("migration fault injection")
+ with original_batch(
+ operations,
+ table_name,
+ *args,
+ **kwargs,
+ ) as batch:
+ yield batch
+ if (
+ table_name == "findings"
+ and boundary == "after-hardening"
+ ):
+ raise RuntimeError("migration fault injection")
+
+ monkeypatch.setattr(
+ Operations,
+ "batch_alter_table",
+ _failing_batch,
+ )
+ else:
+ _install_sqlite_version_failure(path)
+
+ failed = False
+ try:
+ if direction == "upgrade":
+ _upgrade(path, "0005")
+ else:
+ _downgrade(path, "0004")
+ except RuntimeError:
+ failed = True
+
+ monkeypatch.setattr(
+ Operations,
+ "batch_alter_table",
+ original_batch,
+ )
+ _remove_sqlite_version_failure(path)
+ connection = _connect(path)
+ try:
+ after_failure_rows = connection.execute(
+ """
+ SELECT
+ count(*),
+ count(DISTINCT title),
+ count(*) FILTER (WHERE trace_id IS NULL),
+ count(*) FILTER (WHERE trace_id='')
+ FROM findings
+ """
+ ).fetchone()
+ temporary_tables = connection.execute(
+ """
+ SELECT count(*) FROM sqlite_master
+ WHERE type='table' AND name LIKE '_alembic_tmp_%'
+ """
+ ).fetchone()
+ foreign_keys_enabled = (
+ connection.execute("PRAGMA foreign_keys").fetchone() == (1,)
+ )
+ finally:
+ connection.close()
+ remained_at_start = _version(path) == starting_revision
+ no_data_loss = (
+ before_rows is not None
+ and after_failure_rows is not None
+ and after_failure_rows[:2] == before_rows
+ and sum(after_failure_rows[2:]) == before_rows[0]
+ )
+
+ if direction == "upgrade":
+ _upgrade(path, "0005")
+ else:
+ _downgrade(path, "0004")
+ connection = _connect(path)
+ try:
+ recovered_contract = (
+ _sqlite_catalog_contract(connection)
+ == _fixed_sqlite_contract(result_revision)
+ )
+ sentinel_preserved = (
+ connection.execute(
+ """
+ SELECT count(*), count(*) FILTER (WHERE trace_id='')
+ FROM findings
+ """
+ ).fetchone()
+ == (1, 1)
+ )
+ finally:
+ connection.close()
+ _require_fixed(
+ failed
+ and remained_at_start
+ and no_data_loss
+ and temporary_tables == (0,)
+ and foreign_keys_enabled
+ and _version(path) == result_revision
+ and recovered_contract
+ and sentinel_preserved,
+ "revision 0005 failure boundary was not safely recoverable",
+ )
+
+
[email protected]("direction", ["upgrade", "downgrade"])
+def test_revision_0006_failure_after_rename_is_recoverable(
+ monkeypatch: pytest.MonkeyPatch,
+ direction: str,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database(f"0006-version-failure-{direction}") as path:
+ starting_revision = "0005" if direction == "upgrade" else "0006"
+ result_revision = "0006" if direction == "upgrade" else "0005"
+ expected_column = (
+ "cracked_value_enc" if direction == "upgrade" else "cracked_value"
+ )
+ _upgrade(path, starting_revision)
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES(?, ?)",
+ ("campaign-rename", "Synthetic campaign"),
+ )
+ source_column = (
+ "cracked_value"
+ if direction == "upgrade"
+ else "cracked_value_enc"
+ )
+ connection.execute(
+ f"""
+ INSERT INTO credentials(
+ id, campaign_id, username, cred_type, "{source_column}"
+ ) VALUES(?, ?, ?, ?, ?)
+ """,
+ (
+ "credential-rename",
+ "campaign-rename",
+ "synthetic-user",
+ "password",
+ "synthetic-marker",
+ ),
+ )
+ connection.commit()
+ before_rows = connection.execute(
+ "SELECT count(*) FROM credentials"
+ ).fetchone()
+ finally:
+ connection.close()
+
+ _install_sqlite_version_failure(path)
+ failed = False
+ try:
+ if direction == "upgrade":
+ _upgrade(path, "0006")
+ else:
+ _downgrade(path, "0005")
+ except RuntimeError:
+ failed = True
+ _remove_sqlite_version_failure(path)
+
+ connection = _connect(path)
+ try:
+ intermediate_columns = _column_map(
+ connection,
+ "credentials",
+ )
+ exactly_one_name = (
+ ("cracked_value" in intermediate_columns)
+ != ("cracked_value_enc" in intermediate_columns)
+ )
+ intermediate_rows = connection.execute(
+ "SELECT count(*) FROM credentials"
+ ).fetchone()
+ temporary_tables = connection.execute(
+ """
+ SELECT count(*) FROM sqlite_master
+ WHERE type='table' AND name LIKE '_alembic_tmp_%'
+ """
+ ).fetchone()
+ foreign_keys_enabled = (
+ connection.execute("PRAGMA foreign_keys").fetchone() == (1,)
+ )
+ finally:
+ connection.close()
+
+ if direction == "upgrade":
+ _upgrade(path, "0006")
+ else:
+ _downgrade(path, "0005")
+ connection = _connect(path)
+ try:
+ final_contract = (
+ _sqlite_catalog_contract(connection)
+ == _fixed_sqlite_contract(result_revision)
+ )
+ value_query = (
+ "SELECT count(*) FROM credentials "
+ "WHERE cracked_value IS NOT NULL"
+ if expected_column == "cracked_value"
+ else "SELECT count(*) FROM credentials "
+ "WHERE cracked_value_enc IS NOT NULL"
+ )
+ value_preserved = (
+ connection.execute(value_query).fetchone()
+ == (1,)
+ )
+ reusable = connection.execute("SELECT 1").fetchone() == (1,)
+ finally:
+ connection.close()
+ _require_fixed(
+ failed
+ and _version(path) == result_revision
+ and exactly_one_name
+ and before_rows == intermediate_rows
+ and temporary_tables == (0,)
+ and foreign_keys_enabled
+ and final_contract
+ and value_preserved
+ and reusable,
+ "revision 0006 rename failure was not safely recoverable",
+ )
+
+
+def test_revision_0006_accepts_already_renamed_catalog(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database("renamed-0006") as path:
+ _upgrade(path, "0005")
+ connection = _connect(path)
+ try:
+ connection.execute(
+ "ALTER TABLE credentials "
+ "RENAME COLUMN cracked_value TO cracked_value_enc"
+ )
+ connection.commit()
+ finally:
+ connection.close()
+ _upgrade(path, "0006")
+ reached_revision = _version(path) == "0006"
+ _require_fixed(
+ reached_revision,
+ "revision 0006 rejected the verified target-only catalog",
+ )
+
+
+ "variant",
+ ["both", "neither"],
+)
+def test_revision_0006_rejects_ambiguous_or_missing_catalog(
+ monkeypatch: pytest.MonkeyPatch,
+ variant: str,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database(f"invalid-0006-{variant}") as path:
+ _upgrade(path, "0005")
+ connection = _connect(path)
+ try:
+ if variant == "both":
+ connection.execute(
+ "ALTER TABLE credentials "
+ "ADD COLUMN cracked_value_enc TEXT"
+ )
+ else:
+ connection.execute(
+ "ALTER TABLE credentials DROP COLUMN cracked_value"
+ )
+ connection.commit()
+ finally:
+ connection.close()
+ caught: Exception | None = None
+ try:
+ _upgrade(path, "0006")
+ except RuntimeError as error:
+ caught = error
+ remained_at_parent = _version(path) == "0005"
+ expected_message = (
+ "Ambiguous credentials catalog for migration 0006"
+ if variant == "both"
+ else "Incompatible credentials catalog for migration 0006"
+ )
+ rejected_with_fixed_revision_error = (
+ type(caught) is RuntimeError
+ and str(caught) == expected_message
+ )
+ _require_fixed(
+ remained_at_parent and rejected_with_fixed_revision_error,
+ "failed revision 0006 advanced the Alembic version",
+ )
+
+
+def _credential_catalog_fingerprint(
+ connection: sqlite3.Connection,
+) -> tuple[object, ...]:
+ table_sql = connection.execute(
+ """
+ SELECT sql FROM sqlite_master
+ WHERE type='table' AND name='credentials'
+ """
+ ).fetchone()
+ columns = tuple(
+ (row[1], row[2], row[3], row[4], row[5])
+ for row in connection.execute('PRAGMA table_info("credentials")')
+ )
+ foreign_keys = tuple(
+ tuple(row[2:8])
+ for row in connection.execute(
+ 'PRAGMA foreign_key_list("credentials")'
+ )
+ )
+ indexes = tuple(
+ sorted(
+ (
+ row[1],
+ row[2],
+ row[3],
+ row[4],
+ tuple(
+ item[2]
+ for item in connection.execute(
+ f'PRAGMA index_info("{row[1]}")'
+ )
+ ),
+ )
+ for row in connection.execute(
+ 'PRAGMA index_list("credentials")'
+ )
+ )
+ )
+ return table_sql is not None, columns, foreign_keys, indexes
+
+
+def _prepare_0006_variant(
+ connection: sqlite3.Connection,
+ *,
+ source: str,
+ target: str,
+ variant: str,
+) -> None:
+ if variant == "source-only":
+ return
+ if variant == "target-only":
+ connection.execute(
+ f'ALTER TABLE credentials RENAME COLUMN "{source}" TO "{target}"'
+ )
+ return
+ if variant == "both":
+ connection.execute(
+ f'ALTER TABLE credentials ADD COLUMN "{target}" TEXT'
+ )
+ return
+ if variant == "neither":
+ connection.execute(
+ f'ALTER TABLE credentials DROP COLUMN "{source}"'
+ )
+ return
+
+ if variant.startswith("wrong-source-"):
+ inspected = source
+ scratch = "migration_0006_scratch"
+ connection.execute(
+ f'ALTER TABLE credentials RENAME COLUMN "{source}" TO "{scratch}"'
+ )
+ elif variant.startswith("wrong-target-"):
+ inspected = target
+ connection.execute(
+ f'ALTER TABLE credentials DROP COLUMN "{source}"'
+ )
+ else:
+ raise AssertionError("unknown revision 0006 test variant")
+
+ if variant.endswith("-type"):
+ definition = "VARCHAR(64)"
+ elif variant.endswith("-nullability"):
+ definition = "TEXT NOT NULL"
+ elif variant.endswith("-default-empty"):
+ definition = "TEXT DEFAULT ''"
+ elif variant.endswith("-default"):
+ definition = "TEXT DEFAULT NULL"
+ else:
+ raise AssertionError("unknown revision 0006 definition variant")
+ connection.execute(
+ f'ALTER TABLE credentials ADD COLUMN "{inspected}" {definition}'
+ )
+ if variant.startswith("wrong-source-"):
+ connection.execute(
+ 'ALTER TABLE credentials DROP COLUMN "migration_0006_scratch"'
+ )
+
+
[email protected]("direction", ["upgrade", "downgrade"])
+ "variant",
+ [
+ "source-only",
+ "target-only",
+ "both",
+ "neither",
+ "wrong-source-type",
+ "wrong-source-nullability",
+ "wrong-source-default",
+ "wrong-source-default-empty",
+ "wrong-target-type",
+ "wrong-target-nullability",
+ "wrong-target-default",
+ "wrong-target-default-empty",
+ ],
+)
+def test_revision_0006_exact_column_state_machine(
+ monkeypatch: pytest.MonkeyPatch,
+ direction: str,
+ variant: str,
+) -> None:
+ monkeypatch.delenv("ARES_DATABASE_URL", raising=False)
+ with _temporary_database(f"0006-{direction}-{variant}") as path:
+ if direction == "upgrade":
+ _upgrade(path, "0005")
+ source = "cracked_value"
+ target = "cracked_value_enc"
+ parent_revision = "0005"
+ result_revision = "0006"
+ else:
+ _upgrade(path, "0006")
+ source = "cracked_value_enc"
+ target = "cracked_value"
+ parent_revision = "0006"
+ result_revision = "0005"
+
+ connection = _connect(path)
+ try:
+ _prepare_0006_variant(
+ connection,
+ source=source,
+ target=target,
+ variant=variant,
+ )
+ present_columns = set(_column_map(connection, "credentials"))
+ value_column = (
+ source
+ if source in present_columns
+ else target if target in present_columns else None
+ )
+ connection.execute(
+ "INSERT INTO campaigns(id, name) VALUES(?, ?)",
+ ("campaign-0006", "Migration campaign"),
+ )
+ if value_column is not None:
+ connection.execute(
+ f"""
+ INSERT INTO credentials(
+ id, campaign_id, username, cred_type, "{value_column}"
+ ) VALUES(?, ?, ?, ?, ?)
+ """,
+ (
+ "credential-0006",
+ "campaign-0006",
+ "synthetic-user",
+ "password",
+ "synthetic-marker",
+ ),
+ )
+ connection.commit()
+ before_catalog = _credential_catalog_fingerprint(connection)
+ before_rows = connection.execute(
+ "SELECT count(*) FROM credentials"
+ ).fetchone()
+ finally:
+ connection.close()
+
+ allowed = variant in {"source-only", "target-only"}
+ failed = False
+ try:
+ if direction == "upgrade":
+ _upgrade(path, "0006")
+ else:
+ _downgrade(path, "0005")
+ except RuntimeError:
+ failed = True
+
+ connection = _connect(path)
+ try:
+ after_catalog = _credential_catalog_fingerprint(connection)
+ after_rows = connection.execute(
+ "SELECT count(*) FROM credentials"
+ ).fetchone()
+ columns = _column_map(connection, "credentials")
+ target_definition = columns.get(target)
+ target_is_exact = (
+ target_definition is not None
+ and target_definition[0].upper() == "TEXT"
+ and target_definition[1] == 0
+ and target_definition[2] is None
+ )
+ if target not in columns:
+ preserved = False
+ elif target == "cracked_value_enc":
+ preserved = (
+ connection.execute(
+ """
+ SELECT count(*) FROM credentials
+ WHERE cracked_value_enc IS NOT NULL
+ """
+ ).fetchone()
+ == (1,)
+ )
+ else:
+ preserved = (
+ connection.execute(
+ """
+ SELECT count(*) FROM credentials
+ WHERE cracked_value IS NOT NULL
+ """
+ ).fetchone()
+ == (1,)
+ )
+ reusable = connection.execute("SELECT 1").fetchone() == (1,)
+ finally:
+ connection.close()
+
+ if allowed:
+ accepted = (
+ not failed
+ and _version(path) == result_revision
+ and source not in columns
+ and target_is_exact
+ and preserved
+ and reusable
+ )
+ _require_fixed(
+ accepted,
+ "revision 0006 rejected a valid exact catalog",
+ )
+ else:
+ rejected_atomically = (
+ failed
+ and _version(path) == parent_revision
+ and before_catalog == after_catalog
+ and before_rows == after_rows
+ and reusable
+ )
+ _require_fixed(
+ rejected_atomically,
+ "revision 0006 changed an incompatible catalog",
+ )