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.

40.8 KB
Raw Blame
"""
ARES Security Critical Path Tests
==================================
Test suite for security-critical paths that must pass before every release.

Coverage:
    1. Token revocation  - logout → blacklist → reuse rejected
    2. Dashboard auth    - every API endpoint requires valid token
    3. RBAC enforcement  - per-role, per-endpoint access control
    4. Refresh rate limit - 429 after N rapid refresh attempts
    5. Vault persistence  - save/restore credential cycle
    6. validate() enforcement - engine calls validate() before execute()

Pattern: httpx.ASGITransport + dependency_overrides (no lifespan needed).
All tests are self-contained - no shared mutable state between classes.
"""

from __future__ import annotations

import asyncio
import os
from unittest.mock import AsyncMock, MagicMock

import pytest

# ── env bootstrap (before any ares import) ────────────────────────────────────
os.environ.setdefault("ARES_SECRET_KEY", "test-sec-critical-min32-chars!!!!")
os.environ.setdefault("ARES_ENCRYPTION_KEY", "test-enc-critical-min32-chars!!!!")
os.environ.setdefault("ARES_DEFAULT_ADMIN_PASSWORD", "TestCriticalPass1!")
os.environ.setdefault("ARES_DEBUG", "true")
os.environ.setdefault("ARES_BROWSER_ORIGIN", "http://localhost:5173")


# ── helpers ───────────────────────────────────────────────────────────────────

_MOCK_PRINCIPAL_ROLES: dict[str, str] = {}


@pytest.fixture(autouse=True)
def _isolate_server_dependencies():
    yield
    from ares.api.server import app

    app.dependency_overrides.clear()
    _MOCK_PRINCIPAL_ROLES.clear()


def _settings():
    from ares.core.config import get_settings

    get_settings.cache_clear()
    return get_settings()


def _make_token(username: str, role: str, expires_minutes: int = 60) -> str:
    from ares.core.security import create_access_token
    from ares.core.token_sessions import generate_family_id

    _MOCK_PRINCIPAL_ROLES[username] = role
    s = _settings()
    return create_access_token(
        data={"sub": username, "sid": generate_family_id(), "ver": 1},
        secret_key=s.secret_key_value,
        expires_minutes=expires_minutes,
    )


def _auth(username: str, role: str) -> dict:
    return {"Authorization": f"Bearer {_make_token(username, role)}"}


def _make_mock_db():
    db = MagicMock()
    db.verify_user = AsyncMock(return_value=None)
    db.get_user = AsyncMock(return_value=None)
    db.user_exists = AsyncMock(return_value=False)
    db.create_user = AsyncMock()
    db.create_refresh_token = AsyncMock(return_value="raw-mock-refresh-token")
    db.rotate_refresh_token = AsyncMock(return_value=(None, None))
    db.revoke_all_refresh_tokens = AsyncMock()
    from ares.core.token_sessions import (
        SessionRevocationResult,
        SessionRevocationStatus,
    )

    db.revoke_current_session = AsyncMock(
        return_value=SessionRevocationResult(SessionRevocationStatus.REVOKED)
    )
    db.revoke_refresh_cookie_session = AsyncMock(
        return_value=SessionRevocationResult(SessionRevocationStatus.REVOKED)
    )
    db.revoke_all_sessions = AsyncMock(
        return_value=SessionRevocationResult(SessionRevocationStatus.REVOKED)
    )
    db.revoke_access_token = AsyncMock()
    db.is_access_token_revoked = AsyncMock(return_value=False)

    async def resolve_access_token_principal(
        subject: str,
        _jti: str,
        _family_id: str,
        auth_epoch: int,
    ) -> dict[str, str] | None:
        if db.is_access_token_revoked.return_value is True:
            return None
        role = _MOCK_PRINCIPAL_ROLES.get(subject)
        if role is None:
            return None
        return {
            "id": f"mock-user-{subject}",
            "username": subject,
            "role": role,
            "auth_epoch": auth_epoch,
        }

    db.resolve_access_token_principal = AsyncMock(side_effect=resolve_access_token_principal)
    db.audit = AsyncMock()
    db.purge_expired_tokens = AsyncMock(return_value=0)
    db.list_campaigns = AsyncMock(return_value=([], 0))
    db.get_campaign = AsyncMock(return_value=None)
    db.verify_api_key = AsyncMock(return_value=None)
    db.load_credentials_raw = AsyncMock(return_value=[])
    return db


def _reset_limiter() -> None:
    from ares.api.rbac import _limiter

    _limiter._windows.clear()


def _browser_client(app):
    import httpx

    client: httpx.AsyncClient

    async def _headers(request: httpx.Request) -> None:
        if request.url.path in {
            "/auth/token",
            "/auth/refresh",
            "/auth/logout",
            "/auth/logout-all",
        }:
            request.headers["Origin"] = "http://localhost:5173"
            request.headers["Sec-Fetch-Site"] = "same-origin"
            try:
                csrf = client.cookies.get("ares-dev-csrf")
            except httpx.CookieConflict:
                csrf = None
            csrf = csrf or ("A" * 43)
            request.headers["X-ARES-CSRF"] = csrf
            cookie = request.headers.get("Cookie", "")
            if "ares-dev-csrf=" not in cookie:
                request.headers["Cookie"] = (
                    f"{cookie}; ares-dev-csrf={csrf}" if cookie else f"ares-dev-csrf={csrf}"
                )

    client = httpx.AsyncClient(
        transport=httpx.ASGITransport(app=app),
        base_url="http://localhost:5173",
        event_hooks={"request": [_headers]},
    )
    client.cookies.set("ares-dev-csrf", "A" * 43, domain="localhost.local", path="/")
    client.cookies.set("ares-dev-refresh", "r" * 64, domain="localhost.local", path="/")
    return client


def _run(coro):
    return asyncio.run(coro)


class _ReducedUvicornLogProbe:
    def __init__(self, marker: str) -> None:
        self._marker = marker
        self.calls = 0
        self.marker_absent = True

    def info(self, template: str, *args: object) -> None:
        self.calls += 1
        rendered = template % args
        self.marker_absent = self.marker_absent and self._marker not in rendered


def _uvicorn_protocol_probe(scope: dict, marker: str):
    from uvicorn.protocols.websockets.websockets_impl import WebSocketProtocol

    protocol = object.__new__(WebSocketProtocol)
    protocol.scope = scope
    protocol.logger = _ReducedUvicornLogProbe(marker)
    protocol.handshake_started_event = asyncio.Event()
    protocol.handshake_completed_event = asyncio.Event()
    protocol.closed_event = asyncio.Event()
    protocol.initial_response = None
    protocol.accepted_subprotocol = None
    protocol.extra_headers = []
    return protocol


def test_main_websocket_scrubs_query_before_actual_uvicorn_logging():
    import ast
    import inspect
    import textwrap
    import warnings

    from uvicorn.config import UvicornDeprecationWarning

    from ares.api.server import _take_campaign_websocket_ticket, campaign_events

    with warnings.catch_warnings():
        warnings.simplefilter("ignore", DeprecationWarning)
        warnings.simplefilter("ignore", UvicornDeprecationWarning)
        from uvicorn.protocols.websockets.websockets_impl import WebSocketProtocol

    marker = "A" * 43
    scope = {
        "type": "websocket",
        "path": "/ws/campaigns/synthetic/events",
        "query_string": f"ticket={marker}".encode("ascii"),
        "client": ("127.0.0.1", 1),
    }
    websocket = MagicMock()
    websocket.scope = scope
    parsed = _take_campaign_websocket_ticket(websocket)
    parsed_canonical = isinstance(parsed, str) and len(parsed) == 43
    query_scrubbed = scope["query_string"] == b""

    async def exercise() -> tuple[int, bool]:
        accepted = _uvicorn_protocol_probe(scope, marker)
        await WebSocketProtocol.asgi_send(
            accepted,
            {"type": "websocket.accept"},
        )
        denied = _uvicorn_protocol_probe(scope, marker)
        await WebSocketProtocol.asgi_send(
            denied,
            {"type": "websocket.close", "code": 4001},
        )
        return (
            accepted.logger.calls + denied.logger.calls,
            accepted.logger.marker_absent and denied.logger.marker_absent,
        )

    call_count, marker_absent = _run(exercise())
    route_body = ast.parse(textwrap.dedent(inspect.getsource(campaign_events))).body[0].body
    helper_body = (
        ast.parse(textwrap.dedent(inspect.getsource(_take_campaign_websocket_ticket))).body[0].body
    )
    route_first_operation_is_scrub = (
        isinstance(route_body[1], ast.Assign)
        and isinstance(route_body[1].value, ast.Call)
        and isinstance(route_body[1].value.func, ast.Name)
        and route_body[1].value.func.id == "_take_campaign_websocket_ticket"
    )
    helper_scrubs_before_validation = (
        isinstance(helper_body[1], ast.Assign)
        and isinstance(helper_body[2], ast.Assign)
        and isinstance(helper_body[3], ast.AnnAssign)
        and isinstance(helper_body[4], ast.Try)
    )
    if not (
        parsed_canonical
        and query_scrubbed
        and call_count == 2
        and marker_absent
        and route_first_operation_is_scrub
        and helper_scrubs_before_validation
    ):
        pytest.fail(
            "WebSocket query must be scrubbed before Uvicorn handshake logging.",
            pytrace=False,
        )


# ══════════════════════════════════════════════════════════════════════
# TEST CLASS 1 - TOKEN REVOCATION
# ══════════════════════════════════════════════════════════════════════


class TestTokenRevocation:
    """
    After logout, a still-valid (not-expired) access token must be rejected.
    The JTI blacklist is the mechanism - these tests verify it is enforced.
    """

    def setup_method(self):
        _reset_limiter()

    def _client(self, mock_db):
        from ares.api.server import app, get_db, get_settings

        app.state.db = mock_db
        app.dependency_overrides[get_db] = lambda: mock_db
        app.dependency_overrides[get_settings] = lambda: _settings()
        return _browser_client(app)

    def test_revoked_token_rejected(self):
        """Token whose JTI is in the blacklist must return 401."""
        db = _make_mock_db()
        db.is_access_token_revoked = AsyncMock(return_value=True)  # blacklisted

        async def _run_test():
            async with self._client(db) as c:
                r = await c.get("/auth/me", headers=_auth("alice", "operator"))
            assert r.status_code == 401, (
                f"Revoked token must return 401, got {r.status_code}. "
                "Logout is ineffective - token still works after revocation!"
            )

        _run(_run_test())

    def test_valid_token_accepted(self):
        """Token not in blacklist must work normally."""
        db = _make_mock_db()
        db.is_access_token_revoked = AsyncMock(return_value=False)
        db.get_user = AsyncMock(return_value={"id": "u1", "username": "alice", "role": "operator"})

        async def _run_test():
            async with self._client(db) as c:
                r = await c.get("/auth/me", headers=_auth("alice", "operator"))
            assert r.status_code == 200, f"Valid token must return 200, got {r.status_code}"

        _run(_run_test())

    def test_expired_token_rejected(self):
        """JWT past its exp claim must return 401."""
        db = _make_mock_db()
        token = _make_token("alice", "operator", expires_minutes=-1)

        async def _run_test():
            async with self._client(db) as c:
                r = await c.get("/auth/me", headers={"Authorization": f"Bearer {token}"})
            assert r.status_code == 401, f"Expired token must return 401, got {r.status_code}"

        _run(_run_test())

    def test_logout_triggers_cookie_family_revocation(self):
        """POST /auth/logout must use refresh-cookie family authority."""
        db = _make_mock_db()
        db.is_access_token_revoked = AsyncMock(return_value=False)
        db.get_user = AsyncMock(return_value={"id": "u1", "username": "alice", "role": "operator"})

        async def _run_test():
            async with self._client(db) as c:
                r = await c.post("/auth/logout", headers=_auth("alice", "operator"))
            assert r.status_code == 204
            db.revoke_refresh_cookie_session.assert_awaited_once()
            db.revoke_current_session.assert_not_awaited()

        _run(_run_test())


# ══════════════════════════════════════════════════════════════════════
# TEST CLASS 2 - DASHBOARD AUTHENTICATION
# ══════════════════════════════════════════════════════════════════════


class TestDashboardAuthentication:
    """
    Every dashboard /api/* endpoint must return 401 without a valid token.
    GET / (HTML shell) is deliberately public - SPA pattern, no sensitive data.
    """

    PROTECTED = [
        ("GET", "/api/status"),
        ("GET", "/api/campaigns"),
        ("GET", "/api/campaigns/test-id/findings"),
        ("GET", "/api/campaigns/test-id/hosts"),
        ("GET", "/api/campaigns/test-id/summary"),
        ("GET", "/api/workers"),
    ]

    def _client(self):
        import httpx

        from ares.api.dashboard.app import dashboard_app

        dashboard_app.state.db = _make_mock_db()
        return httpx.AsyncClient(
            transport=httpx.ASGITransport(app=dashboard_app),
            base_url="http://localhost",
        )

    @pytest.mark.parametrize("method,path", PROTECTED)
    def test_endpoint_requires_auth(self, method, path):
        """Each protected endpoint must return 401 with no token."""

        async def _run_test():
            async with self._client() as c:
                r = await c.request(method, path)
            assert r.status_code == 401, (
                f"Dashboard [{method}] {path} returned {r.status_code} without auth. "
                "This endpoint exposes campaign data without authentication!"
            )

        _run(_run_test())

    def test_root_accessible_without_auth(self):
        """GET / (HTML shell) is intentionally public."""

        async def _run_test():
            async with self._client() as c:
                r = await c.get("/")
            assert r.status_code == 200

        _run(_run_test())

    def test_valid_token_grants_access(self):
        """A valid JWT must give access to /api/campaigns."""
        db = _make_mock_db()
        db.list_campaigns = AsyncMock(return_value=([], 0))

        async def _run_test():
            import httpx

            from ares.api.dashboard.app import dashboard_app

            db.is_access_token_revoked = AsyncMock(return_value=False)
            dashboard_app.state.db = db
            async with httpx.AsyncClient(
                transport=httpx.ASGITransport(app=dashboard_app),
                base_url="http://localhost",
            ) as c:
                r = await c.get("/api/campaigns", headers=_auth("alice", "operator"))
            assert r.status_code == 200

        _run(_run_test())

    def test_dashboard_auth_fails_closed_when_db_error(self, monkeypatch):
        """When revocation check database fails, request must return 503 (fail closed), not 200."""
        from ares.db.database import AresDatabase

        async def mock_create(*a, **kw):
            raise ConnectionError("Database cluster unreachable")

        monkeypatch.setattr(AresDatabase, "create", mock_create)

        async def _run_test():
            import httpx

            from ares.api.dashboard.app import dashboard_app

            # Dashboard auth now prefers dashboard_app.state.db when present;
            # clear leftover state from earlier tests so the auth code has to
            # fall through to AresDatabase.create and observe our stub raise.
            if hasattr(dashboard_app.state, "db"):
                delattr(dashboard_app.state, "db")

            async with httpx.AsyncClient(
                transport=httpx.ASGITransport(app=dashboard_app),
                base_url="http://localhost",
            ) as c:
                r = await c.get("/api/campaigns", headers=_auth("alice", "operator"))
            assert r.status_code == 503

        _run(_run_test())

    def test_dashboard_rejects_revoked_family(self):
        """Regression: after /auth/logout revokes the refresh-token family,
        an access token issued from that family must stop working on the
        dashboard immediately — not keep working until expiry.

        This failed before the fix because the dashboard only checked
        is_access_token_revoked(jti); logout revokes the family (and the
        main-API's resolve_access_token_principal JOIN rejects on
        f.state='active'), but the plain-jti blocklist was never populated
        for /auth/logout, so the dashboard's old auth path accepted the
        stale token.
        """
        db = _make_mock_db()
        # Simulate "family revoked / user deactivated / epoch bumped":
        # resolve_access_token_principal returns None, same signal main-API
        # uses when the family is no longer active.
        db.resolve_access_token_principal = AsyncMock(return_value=None)

        async def _run_test():
            import httpx

            from ares.api.dashboard.app import dashboard_app

            dashboard_app.state.db = db
            async with httpx.AsyncClient(
                transport=httpx.ASGITransport(app=dashboard_app),
                base_url="http://localhost",
            ) as c:
                r = await c.get(
                    "/api/campaigns", headers=_auth("alice", "operator")
                )
            assert r.status_code == 401, (
                "Dashboard accepted a JWT whose refresh family was revoked / "
                "whose user was deactivated / whose auth_epoch was bumped. "
                "This defeats /auth/logout, /auth/logout-all, and admin "
                "deactivation on the dashboard surface."
            )

        _run(_run_test())


# ══════════════════════════════════════════════════════════════════════
# TEST CLASS 3 - RBAC ENFORCEMENT PER ROLE
# ══════════════════════════════════════════════════════════════════════


def test_legacy_dashboard_escapes_api_fields_before_innerhtml():
    """API-derived strings must be escaped before legacy dashboard innerHTML use."""
    from ares.api.dashboard.app import _DASHBOARD_HTML

    escaped_fragments = [
        "${escHtml(c.id)}",
        "${escHtml(c.name)}",
        "${escHtml(c.client)}",
        "${escHtml(c.noise_profile)}",
        "${escHtml(c.status)}",
        "${escHtml(String(f.severity || 'info').toUpperCase())}",
        "${escHtml(f.mitre_technique)}",
        "${escHtml(h.ip_address)}",
        "${escHtml(h.hostname)}",
        "${escHtml(h.os || 'Unknown OS')}",
        "escHtml(h.os_version)",
        "escHtml(h.domain)",
        "JSON.parse(h.open_ports_json).map(escHtml).join(', ')",
        "${escHtml(w.hostname)}",
        "${escHtml(String(w.id || '').slice(0,8))}",
        "(w.capabilities || []).map(escHtml).join(', ')",
        "${escHtml(w.last_beat)}",
        "${escHtml(w.active_tasks)}",
        "${escHtml(w.completed)}",
        "${escHtml(w.failed)}",
    ]
    for fragment in escaped_fragments:
        assert fragment in _DASHBOARD_HTML

    vulnerable_fragments = [
        "onclick=\"selectCampaign('${c.id}', this)\"",
        "${c.name}</div>",
        "${c.client}",
        "${f.mitre_technique}</span>",
        '<span class="ip">${h.ip_address}</span>',
        ">(${h.hostname})</span>",
        "${h.os || 'Unknown OS'}",
        "' ' + h.os_version",
        "JSON.parse(h.open_ports_json).join(', ')",
        "${w.hostname}</strong>",
        "${w.id.slice(0,8)}",
        "${w.capabilities.join(', ')||'all'}",
        "${w.last_beat}s ago",
        "${w.active_tasks}</strong>",
        "Done: ${w.completed}",
        "Failed: ${w.failed}",
    ]
    for fragment in vulnerable_fragments:
        assert fragment not in _DASHBOARD_HTML

    assert ".replace(/\"/g,'&quot;')" in _DASHBOARD_HTML
    assert ".replace(/'/g,'&#39;')" in _DASHBOARD_HTML


class TestRBACEnforcement:
    """
    Every role must be restricted to its allowed operations.
    """

    def setup_method(self):
        _reset_limiter()

    def _client(self, mock_db=None):
        from ares.api.server import app, get_db, get_settings

        db = mock_db or _make_mock_db()
        app.state.db = db
        app.dependency_overrides[get_db] = lambda: db
        app.dependency_overrides[get_settings] = lambda: _settings()
        return _browser_client(app)

    def test_no_token_returns_401(self):
        """Unauthenticated request must return 401, not 403."""

        async def _run_test():
            async with self._client() as c:
                r = await c.get("/campaigns")
            assert r.status_code == 401, f"No token must return 401, not {r.status_code}"

        _run(_run_test())

    def test_reporter_blocked_from_creating_campaign(self):
        """Reporter (read-only) must be blocked from POST /campaigns."""
        db = _make_mock_db()

        async def _run_test():
            async with self._client(db) as c:
                r = await c.post(
                    "/campaigns",
                    json={"name": "test", "targets": [], "scope_cidrs": []},
                    headers=_auth("reporter1", "reporter"),
                )
            assert r.status_code == 403, (
                f"Reporter must get 403 on POST /campaigns, got {r.status_code}"
            )

        _run(_run_test())

    def test_reporter_can_read_campaigns(self):
        """Reporter must be able to GET /campaigns."""
        db = _make_mock_db()

        async def _run_test():
            async with self._client(db) as c:
                r = await c.get("/campaigns", headers=_auth("reporter1", "reporter"))
            assert r.status_code == 200, (
                f"Reporter must be able to read campaigns, got {r.status_code}"
            )

        _run(_run_test())

    def test_operator_blocked_from_registering_users(self):
        """Only team_lead may call POST /auth/register."""
        db = _make_mock_db()

        async def _run_test():
            async with self._client(db) as c:
                r = await c.post(
                    "/auth/register",
                    json={"username": "newuser", "password": "Password1!", "role": "operator"},
                    headers=_auth("op1", "operator"),
                )
            assert r.status_code == 403, (
                f"Operator must be blocked from /auth/register, got {r.status_code}"
            )

        _run(_run_test())

    def test_team_lead_can_register_users(self):
        """team_lead must be able to reach POST /auth/register."""
        db = _make_mock_db()
        db.user_exists = AsyncMock(return_value=False)
        db.create_user = AsyncMock(return_value="new-user-id")

        async def _run_test():
            async with self._client(db) as c:
                r = await c.post(
                    "/auth/register",
                    json={"username": "newuser", "password": "StrongPass1!", "role": "operator"},
                    headers=_auth("lead1", "team_lead"),
                )
            assert r.status_code in (200, 201, 422), (
                f"team_lead must reach /auth/register (200/201), got {r.status_code}"
            )

        _run(_run_test())

    def test_can_run_module_rbac_operator(self):
        """operator may run ad.* and lateral.* modules."""
        from ares.api.rbac import AuthenticatedUser

        user = AuthenticatedUser(username="op1", role="operator")
        assert user.can_run_module("ad.kerberoast")
        assert user.can_run_module("lateral.psexec")
        assert user.can_run_module("windows.lsa_secrets")

    def test_can_run_module_rbac_recon(self):
        """recon may only run enumeration modules."""
        from ares.api.rbac import AuthenticatedUser

        user = AuthenticatedUser(username="recon1", role="recon")
        assert user.can_run_module("ad.enum_users")
        assert user.can_run_module("network.port_scan")
        # Must NOT run lateral or credential modules
        assert not user.can_run_module("lateral.psexec")
        assert not user.can_run_module("credential.reuse")

    def test_can_run_module_rbac_reporter(self):
        """reporter may not run any module."""
        from ares.api.rbac import AuthenticatedUser

        user = AuthenticatedUser(username="rep1", role="reporter")
        assert not user.can_run_module("ad.enum_users")
        assert not user.can_run_module("reporting.report_gen")

    def test_unknown_role_defaults_to_reporter(self):
        """Unknown role string must default to most restrictive (reporter)."""
        from ares.api.rbac import AuthenticatedUser
        from ares.collab.manager import OperatorRole

        user = AuthenticatedUser(username="mystery", role="god_mode")
        assert user.operator_role == OperatorRole.REPORTER
        assert not user.can_run_module("ad.kerberoast")


# ══════════════════════════════════════════════════════════════════════
# TEST CLASS 4 - REFRESH TOKEN RATE LIMITING
# ══════════════════════════════════════════════════════════════════════


class TestRefreshTokenRateLimit:
    """POST /auth/refresh must be rate-limited to prevent token flooding."""

    def setup_method(self):
        _reset_limiter()

    def _client(self, mock_db=None):
        from ares.api.server import app, get_db, get_settings

        db = mock_db or _make_mock_db()
        app.state.db = db
        app.dependency_overrides[get_db] = lambda: db
        app.dependency_overrides[get_settings] = lambda: _settings()
        return _browser_client(app)

    def test_rate_limited_after_many_attempts(self):
        """After N refresh calls from same IP, 429 must be returned."""
        from ares.api.rbac import RATE_LIMITS

        limit = RATE_LIMITS["auth"]

        async def _run_test():
            async with self._client() as c:
                statuses = []
                for _ in range(limit + 2):
                    r = await c.post("/auth/refresh")
                    statuses.append(r.status_code)
            assert 429 in statuses, f"Expected 429 after {limit} attempts, got statuses: {statuses}"

        _run(_run_test())

    def test_429_has_retry_after_header(self):
        """Rate-limit 429 response must include Retry-After header."""
        from ares.api.rbac import RATE_LIMITS

        limit = RATE_LIMITS["auth"]

        async def _run_test():
            async with self._client() as c:
                for _ in range(limit + 1):
                    r = await c.post("/auth/refresh")
                    if r.status_code == 429:
                        headers_lower = {k.lower(): v for k, v in r.headers.items()}
                        assert "retry-after" in headers_lower, (
                            "429 response must include Retry-After header"
                        )
                        return
            pytest.fail("Never received 429 - rate limiting not working")

        _run(_run_test())


# ══════════════════════════════════════════════════════════════════════
# TEST CLASS 5 - CREDENTIAL VAULT PERSISTENCE
# ══════════════════════════════════════════════════════════════════════


class TestCredentialVaultPersistence:
    """Credentials found during a module run must persist to DB and be restorable."""

    def test_persist_vault_saves_to_db(self):
        """Engine _persist_vault_credentials() must call save_credential_preencrypted."""
        from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
        from ares.core.engine import AresEngine
        from ares.credential.vault import Credential, CredentialType, CredentialVault

        db = MagicMock()
        db.save_credential_preencrypted = AsyncMock()

        campaign = Campaign(
            name="persist-test",
            client="test",
            scope=[ScopeEntry(cidr="10.0.0.0/8")],
            noise_profile=NoiseProfile.NORMAL,
        )
        vault = CredentialVault(encryption_key="test-vault-key-32-chars-ok!!!!")
        cred = Credential(
            campaign_id=campaign.id,
            username="administrator",
            domain="CORP",
            cred_type=CredentialType.NTLM,
            source_module="ad.dcsync",
        )
        vault.store(cred, "aad3b435b51404eeaad3b435b51404ee:8846f7eaee8fb117ad06bdd830b7586c")
        campaign._vault = vault  # type: ignore[attr-defined]

        engine = AresEngine(db=db)

        async def _run_test():
            saved = await engine._persist_vault_credentials(campaign)
            assert saved == 1, f"Must save 1 credential, got {saved}"
            db.save_credential_preencrypted.assert_called_once()
            call = db.save_credential_preencrypted.call_args[0][0]
            assert call.username == "administrator"
            assert call.domain == "CORP"
            assert "ntlm" in call.cred_type.lower()

        _run(_run_test())

    def test_restore_from_db_records(self):
        """Credentials loaded from DB must be re-hydrated into vault correctly."""
        from ares.credential.vault import Credential, CredentialType, CredentialVault

        enc_key = "test-restore-vault-key-32chars!!"

        # Vault A: store a credential
        vault_a = CredentialVault(encryption_key=enc_key)
        cred = Credential(
            id="cred-restore-001",
            campaign_id="camp-001",
            username="svc_sql",
            domain="CORP",
            cred_type=CredentialType.CLEARTEXT,
            source_module="test",
        )
        vault_a.store(cred, "SuperSecret99!")

        stored = vault_a._store["cred-restore-001"]
        secret_enc = stored.secret_enc
        secret_str = secret_enc.decode() if isinstance(secret_enc, bytes) else secret_enc

        # Simulate what DB returns
        db_records = [
            {
                "id": "cred-restore-001",
                "campaign_id": "camp-001",
                "username": "svc_sql",
                "domain": "CORP",
                "cred_type": "cleartext",
                "secret_enc": secret_str,
                "source_module": "test",
                "host_id": None,
                "notes": "",
            }
        ]

        # Vault B: restore from DB - share salt/ciphers for compatibility
        vault_b = CredentialVault(encryption_key=enc_key)
        vault_b._salt = vault_a._salt
        vault_b._salt_hex = vault_a._salt_hex
        vault_b._fernet = vault_a._fernet
        vault_b._aesgcm = vault_a._aesgcm

        count = vault_b.restore_from_db_records(db_records)

        assert count == 1, f"Must restore 1 credential, got {count}"
        assert "cred-restore-001" in vault_b._store

        revealed = vault_b.reveal("cred-restore-001")
        assert revealed == "SuperSecret99!", (
            f"Revealed secret after restore must be 'SuperSecret99!', got {revealed!r}"
        )

    def test_empty_vault_persist_returns_zero(self):
        """_persist_vault_credentials on empty vault must return 0."""
        from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
        from ares.core.engine import AresEngine
        from ares.credential.vault import CredentialVault

        db = MagicMock()
        db.save_credential_preencrypted = AsyncMock()

        campaign = Campaign(
            name="empty-vault-test",
            client="test",
            scope=[ScopeEntry(cidr="10.0.0.0/8")],
            noise_profile=NoiseProfile.NORMAL,
        )
        campaign._vault = CredentialVault(encryption_key=None)  # type: ignore

        engine = AresEngine(db=db)

        async def _run_test():
            saved = await engine._persist_vault_credentials(campaign)
            assert saved == 0
            db.save_credential_preencrypted.assert_not_called()

        _run(_run_test())

    def test_no_vault_on_campaign_is_safe(self):
        """Campaign without _vault attr must not crash _persist_vault_credentials."""
        from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
        from ares.core.engine import AresEngine

        db = MagicMock()
        db.save_credential_preencrypted = AsyncMock()
        campaign = Campaign(
            name="no-vault",
            client="test",
            scope=[ScopeEntry(cidr="10.0.0.0/8")],
            noise_profile=NoiseProfile.NORMAL,
        )
        # No _vault attr at all
        engine = AresEngine(db=db)

        async def _run_test():
            saved = await engine._persist_vault_credentials(campaign)
            assert saved == 0

        _run(_run_test())


# ══════════════════════════════════════════════════════════════════════
# TEST CLASS 6 - validate() ENFORCEMENT
# ══════════════════════════════════════════════════════════════════════


class TestValidateEnforcement:
    """Engine must call validate() before execute() on every module run."""

    def test_validate_called_before_execute(self):
        """validate() must be called; execute() must NOT run if validate fails."""
        from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
        from ares.core.engine import AresEngine
        from ares.core.errors import ModuleValidationError
        from ares.core.execution_admission import _mint_test_dispatch_context
        from ares.modules.base import BaseModule, ModuleResult, OpsecLevel

        validate_calls: list[bool] = []
        execute_calls: list[bool] = []

        class _StrictModule(BaseModule):
            MODULE_ID = "test.strict_validate"
            MODULE_NAME = "Strict Test"
            MODULE_CATEGORY = "test"
            MODULE_DESCRIPTION = "Validation test module"
            OPSEC_LEVEL = OpsecLevel.SILENT
            MITRE_TECHNIQUES = []
            REQUIRES = ["target"]
            OUTPUTS = []

            async def validate(self, ctx):
                validate_calls.append(True)
                if not ctx.params.get("required_param"):
                    raise ModuleValidationError(
                        "required_param is missing",
                        module_id=self.MODULE_ID,
                        field="required_param",
                    )

            async def execute(self, ctx):
                execute_calls.append(True)
                return ModuleResult(status="success", findings=[], raw={}, module_id=self.MODULE_ID)

        campaign = Campaign(
            name="validate-test",
            client="test",
            scope=[ScopeEntry(cidr="10.0.0.0/8")],
            noise_profile=NoiseProfile.NORMAL,
        )

        from ares.core.engine import ModuleRegistry as _Reg

        registry = _Reg()
        registry._registry = {"test.strict_validate": _StrictModule}

        engine = AresEngine()
        engine._registry = registry

        async def _run_test():
            from ares.core.config import get_settings

            get_settings.cache_clear()
            result = await engine.run_module(
                "test.strict_validate",
                campaign,
                params={"target": "10.0.0.1"},
                actor_role="team_lead",
                dispatch_context=_mint_test_dispatch_context(
                    engine, campaign.id, "test.strict_validate"
                ),
                # No required_param - validate() must fail
            )
            assert len(validate_calls) == 1, "validate() must be called exactly once"
            assert len(execute_calls) == 0, "execute() must NOT run when validate() raises"
            from ares.core.engine import ModuleStatus

            assert result.status == ModuleStatus.FAILED
            assert "required_param" in (result.error or "")

        _run(_run_test())

    def test_skip_validation_bypasses_validate(self):
        """skip_validation=True must bypass validate() and proceed to execute()."""
        from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
        from ares.core.engine import AresEngine
        from ares.core.errors import ModuleValidationError
        from ares.core.execution_admission import _mint_test_dispatch_context
        from ares.modules.base import BaseModule, ModuleResult, OpsecLevel

        validate_calls: list[bool] = []
        execute_calls: list[bool] = []

        class _AlwaysFailValidate(BaseModule):
            MODULE_ID = "test.always_fail_validate"
            MODULE_NAME = "Always Fail Validate"
            MODULE_CATEGORY = "test"
            MODULE_DESCRIPTION = "Skip validation test"
            OPSEC_LEVEL = OpsecLevel.SILENT
            MITRE_TECHNIQUES = []
            REQUIRES = []
            OUTPUTS = []

            async def validate(self, ctx):
                validate_calls.append(True)
                raise ModuleValidationError("always fails", module_id=self.MODULE_ID)

            async def execute(self, ctx):
                execute_calls.append(True)
                return ModuleResult(status="success", findings=[], raw={}, module_id=self.MODULE_ID)

        campaign = Campaign(
            name="skip-validate-test",
            client="test",
            scope=[ScopeEntry(cidr="10.0.0.0/8")],
            noise_profile=NoiseProfile.NORMAL,
        )

        from ares.core.engine import ModuleRegistry as _Reg

        registry = _Reg()
        registry._registry = {"test.always_fail_validate": _AlwaysFailValidate}

        engine = AresEngine()
        engine._registry = registry

        async def _run_test():
            from ares.core.config import get_settings

            get_settings.cache_clear()
            result = await engine.run_module(
                "test.always_fail_validate",
                campaign,
                params={"target": "10.0.0.1"},
                skip_validation=True,
                actor_role="team_lead",
                dispatch_context=_mint_test_dispatch_context(
                    engine, campaign.id, "test.always_fail_validate"
                ),
            )
            assert len(validate_calls) == 0, (
                "validate() must NOT be called when skip_validation=True"
            )
            assert len(execute_calls) == 1, "execute() must run when validation is skipped"
            from ares.core.engine import ModuleStatus

            assert result.status == ModuleStatus.DONE

        _run(_run_test())

    def test_targets_validation_rejects_path_traversal(self):
        """CampaignCreate must reject path traversal in targets."""
        from pydantic import ValidationError

        from ares.api.server import CampaignCreate

        with pytest.raises((ValidationError, ValueError)):
            CampaignCreate(
                name="test",
                targets=["../../../etc/passwd"],
            )

    def test_targets_validation_rejects_null(self):
        """CampaignCreate must reject None values in targets list."""
        from pydantic import ValidationError

        from ares.api.server import CampaignCreate

        with pytest.raises((ValidationError, ValueError)):
            CampaignCreate(
                name="test",
                targets=[None, "10.0.0.1"],  # type: ignore[list-item]
            )

    def test_targets_validation_accepts_valid(self):
        """CampaignCreate must accept valid IPs, CIDRs, and hostnames."""
        from ares.api.server import CampaignCreate

        c = CampaignCreate(
            name="test",
            targets=["10.0.0.1", "192.168.1.0/24", "dc01.corp.local"],
        )
        assert len(c.targets) == 3
        assert "10.0.0.1" in c.targets

    def test_targets_validation_filters_empty_strings(self):
        """CampaignCreate must silently drop empty/whitespace-only targets."""
        from ares.api.server import CampaignCreate

        c = CampaignCreate(
            name="test",
            targets=["", "  ", "10.0.0.1"],
        )
        assert c.targets == ["10.0.0.1"]