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.

74.6 KB
Raw Blame
"""
ARES Async Engine
Full async orchestration with parallel module execution.
"""

from __future__ import annotations

import asyncio
import inspect
import re
import time
import urllib.parse
import uuid
from collections.abc import Callable, Coroutine
from dataclasses import dataclass, field
from enum import Enum
from typing import TYPE_CHECKING, Any

from pydantic import BaseModel, Field

from ares.core.campaign import Campaign, Finding
from ares.core.config import AresSettings, get_settings
from ares.core.context import ExecutionContext
from ares.core.errors import AresError, NetworkError, ScopeFirewallBlockError
from ares.core.execution_admission import (
    AdmittedDispatchContextV1,
    AdmittedPlanContextV1,
    consume_dispatch_context,
    consume_plan_context,
    consume_terminal_commit_context,
    mark_effect_started,
)
from ares.core.logger import audit, get_logger, setup_logger
from ares.core.noise import NoiseController
from ares.core.notifier import build_notifier_from_settings
from ares.core.plugin.loader import ModuleRegistry, PluginLoader
from ares.core.runtime_state import CampaignRuntimeState, CampaignRuntimeStateStore
from ares.core.scope_firewall import scope_firewall_guard
from ares.core.validator import FindingValidator, ValidationResult, build_default_validator

if TYPE_CHECKING:
    pass
logger = get_logger("ares.engine")


class ModuleStatus(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    DONE = "done"
    FAILED = "failed"
    SKIPPED = "skipped"
    TIMEOUT = "timeout"
    CANCELLED = "cancelled"
    REJECTED = "failed"


MODULE_OUTCOMES = (
    "confirmed_findings",
    "completed_no_findings",
    "operator_error",
    "dependency_error",
    "network_error",
    "unsupported",
    "module_error",
    "scope_firewall_blocked",
)
_SUCCESSFUL_MODULE_OUTCOMES = {
    "modulestatus.done",
    "done",
    "success",
    "partial",
    "confirmed_findings",
    "completed_no_findings",
    "dry_run_ok",
}
_SECRET_ERROR_PATTERN = re.compile(
    r"(?i)\b(password|passwd|secret|token|api[_-]?key|nt_hash|lm_hash|krbtgt_hash)\b\s*([:=])\s*([^\s,;]+)"
)

_TARGET_KEYS = frozenset(
    {
        "target",
        "targets",
        "dc",
        "host",
        "hosts",
        "rhost",
        "rhosts",
        "ip",
        "ips",
        "server",
        "servers",
        "destination",
        "destinations",
        "url",
        "urls",
    }
)


def _extract_all_targets(params: dict[str, Any]) -> list[str]:
    """Recursively extract all target IPs, hostnames, and URLs from module parameters."""
    extracted: set[str] = set()

    def _inspect(obj: Any, parent_key: str = "") -> None:
        if not obj:
            return
        if isinstance(obj, str):
            if parent_key.lower() in _TARGET_KEYS:
                for part in re.split(r"[,\s]+", obj.strip()):
                    part = part.strip()
                    if not part:
                        continue
                    if "://" in part:
                        try:
                            parsed = urllib.parse.urlparse(part)
                            if parsed.hostname:
                                extracted.add(parsed.hostname)
                        except Exception:
                            pass
                    elif ":" in part and not part.startswith("[") and part.count(":") == 1:
                        host = part.split(":", 1)[0].strip()
                        if host:
                            extracted.add(host)
                    else:
                        extracted.add(part)
        elif isinstance(obj, (list, tuple, set)):
            for item in obj:
                _inspect(item, parent_key)
        elif isinstance(obj, dict):
            for k, v in obj.items():
                _inspect(v, str(k))

    _inspect(params, "")
    return sorted(extracted)


def module_outcome_value(value: Any) -> str:
    """Normalize enum/string result values for durable outcome handling."""
    enum_value = getattr(value, "value", None)
    if enum_value is not None:
        value = enum_value
    return str(value or "").strip().lower()


def is_successful_module_outcome(value: Any) -> bool:
    """Return whether an engine outcome represents a completed execution."""
    return module_outcome_value(value) in _SUCCESSFUL_MODULE_OUTCOMES


def redact_error_message(error: str | None) -> str | None:
    """Bound and redact common secret key/value forms in engine errors."""
    if not error:
        return error
    text = str(error)[:300]
    return _SECRET_ERROR_PATTERN.sub(
        lambda match: f"{match.group(1)}{match.group(2)}[redacted]", text
    )


def normalize_module_outcome(
    status: ModuleStatus | str,
    findings: list[Any] | None = None,
    error: str | None = None,
    raw_output: dict[str, Any] | None = None,
) -> tuple[str, str]:
    """Map engine results to a stable operator-facing outcome contract."""
    findings = findings or []
    raw = raw_output or {}
    raw_outcome = str(raw.get("outcome_category", ""))
    raw_message = str(raw.get("outcome_message", "")).strip()

    if findings:
        return "confirmed_findings", f"{len(findings)} confirmed finding(s) returned."
    if (
        "krb_ap_err_skew" in str(error or "").lower()
        or "clock skew too great" in str(error or "").lower()
    ):
        return (
            "operator_error",
            "Kerberos clock skew too great; sync the operator host and domain controller time, then rerun.",
        )
    error_text = str(error or "").strip()
    if (
        "kdc_err_wrong_realm" in error_text.lower()
        or "kerberos realm mismatch" in error_text.lower()
    ):
        return (
            "operator_error",
            "Kerberos realm mismatch; use the AD DNS domain/realm such as lab.local or LAB.LOCAL, not the DC IP address.",
        )
    if (
        "ldap/spn enumeration succeeded and found" in error_text.lower()
        and "before a hash was confirmed" in error_text.lower()
    ):
        return "network_error", error_text
    if raw_outcome in MODULE_OUTCOMES:
        if raw_message:
            return raw_outcome, raw_message
        return raw_outcome, raw_outcome.replace("_", " ").capitalize() + "."

    status_value = status.value if isinstance(status, ModuleStatus) else str(status)
    lowered = error_text.lower()
    if status_value == ModuleStatus.TIMEOUT.value or any(
        marker in lowered
        for marker in ("timed out", "timeout", "unreachable", "connection refused", "network")
    ):
        outcome = "network_error"
        default_message = (
            "The module could not complete because the target or network was unavailable."
        )
    elif any(
        marker in lowered
        for marker in (
            "dependency",
            "not installed",
            "no module named",
            "impacket",
            "pyasn1",
            "ldap3",
        )
    ):
        outcome = "dependency_error"
        default_message = "The module dependency check failed."
    elif status_value == ModuleStatus.SKIPPED.value or any(
        marker in lowered for marker in ("unsupported", "blocked", "not permitted")
    ):
        outcome = "unsupported"
        default_message = "The module is unsupported or blocked for this run."
    elif status_value in (ModuleStatus.FAILED.value, ModuleStatus.REJECTED.value) and any(
        marker in lowered
        for marker in ("validation", "required", "scope", "credential", "auth", "role")
    ):
        outcome = "operator_error"
        default_message = "Review the module inputs, authorization, and campaign scope."
    elif status_value == ModuleStatus.DONE.value:
        outcome = "completed_no_findings"
        default_message = (
            "Module completed; no confirmed findings or exploitable condition was observed."
        )
    else:
        outcome = "module_error"
        default_message = "The module failed before producing a confirmed result."

    if error_text:
        return outcome, f"{default_message} Details: {error_text[:300]}"
    return outcome, default_message


def redact_module_params(module_id: str, params: dict[str, Any]) -> dict[str, Any]:
    """Return a JSON-safe parameter summary with credential material redacted."""
    secret_fields: set[str] = set()
    try:
        from ares.modules.params import MODULE_PARAMS

        model = MODULE_PARAMS.get(module_id)
        if model:
            secret_fields = {
                name for name, field in model.schema_for_api().items() if field.get("secret")
            }
    except (ImportError, AttributeError):
        pass

    secret_names = secret_fields | {
        "password",
        "secret",
        "token",
        "api_key",
        "private_key",
        "nt_hash",
        "lm_hash",
        "krbtgt_hash",
        "ssh_pass",
        "access_key",
        "secret_key",
    }

    def _copy(name: str, value: Any) -> Any:
        if name in secret_names:
            return "[redacted]"
        if isinstance(value, dict):
            return {str(key): _copy(str(key), item) for key, item in value.items()}
        if isinstance(value, (list, tuple)):
            return [_copy(name, item) for item in value]
        if value is None or isinstance(value, (str, int, float, bool)):
            return value
        return str(value)

    return {str(key): _copy(str(key), value) for key, value in params.items()}


class EngineModuleResult(BaseModel):
    module_id: str
    status: ModuleStatus = ModuleStatus.DONE
    findings: list[Finding] = []
    validation_results: list[ValidationResult] = []
    raw_output: dict[str, Any] = {}
    error: str | None = None
    duration_ms: float = 0.0
    outcome: str = ""
    outcome_message: str = ""
    operator_next_steps: list[str] = []
    filtered_findings: dict[str, Any] = Field(default_factory=lambda: {"count": 0, "reasons": {}})

    def model_post_init(self, __context: Any) -> None:
        self.error = redact_error_message(self.error)
        if not self.outcome or not self.outcome_message:
            outcome, message = normalize_module_outcome(
                self.status,
                self.findings,
                self.error,
                self.raw_output,
            )
            self.outcome = self.outcome or outcome
            self.outcome_message = self.outcome_message or message
        if self.outcome == "operator_error" and "clock skew" in self.outcome_message.lower():
            self.operator_next_steps = [
                "Synchronize the operator host and domain controller clocks, then rerun the module."
            ]
        elif (
            self.outcome == "network_error"
            and "before a hash was confirmed" in self.outcome_message.lower()
        ):
            self.operator_next_steps = [
                "Verify DC/KDC reachability on port 88, clock synchronization, Kerberos service health, and account/SPN validity, then rerun."
            ]

    @property
    def confirmed_findings(self) -> list[Finding]:
        return [f for f in self.findings if f.validated and not f.false_positive]


@dataclass
class ExecutionPlan:
    """
    Stages run sequentially.
    Modules WITHIN each stage run in PARALLEL.

    Example:
        plan = (ExecutionPlan()
            .add_stage("recon",  ["ad.enum_users", "ad.enum_spn", "ad.enum_computers"])
            .add_stage("attack", ["ad.kerberoast", "ad.asreproast"])
            .add_stage("cloud",  ["cloud.aws", "cloud.azure", "cloud.gcp"])
        )
    """

    stages: list[dict[str, Any]] = field(default_factory=list)

    def add_stage(
        self,
        name: str,
        module_ids: list[str],
        params: dict[str, dict[str, Any]] | None = None,
    ) -> "ExecutionPlan":
        self.stages.append({"name": name, "modules": module_ids, "params": params or {}})
        return self

    def all_module_ids(self) -> list[str]:
        return [mid for s in self.stages for mid in s["modules"]]

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> "ExecutionPlan":
        plan = cls()
        for s in data.get("stages", []):
            plan.add_stage(s["name"], s["modules"], s.get("params", {}))
        return plan


@dataclass
class ProgressEvent:
    stage: str
    module_id: str
    status: ModuleStatus
    finding_count: int = 0
    error: str | None = None
    duration_ms: float = 0.0


ProgressCallback = Callable[[ProgressEvent], Coroutine[Any, Any, None]]


def _estimate_stage_duration(module_count: int) -> str:
    """Rough wall-clock estimate for a stage in dry-run preview.

    Modules run in parallel so the floor is ~30s (avg slowest module).
    Each additional module adds ~5s to account for scheduling overhead
    and the increasing likelihood of a slower outlier.
    """
    if module_count == 0:
        return "0s"
    secs = max(30, 30 + 5 * (module_count - 1))
    return f"~{secs // 60}m {secs % 60}s" if secs >= 60 else f"~{secs}s"


def _fire_and_log(coro, label: str = "background_task") -> None:
    """Schedule a fire-and-forget coroutine that logs exceptions instead of silently dropping them."""
    import asyncio as _aio

    async def _wrapper() -> None:
        try:
            await coro
        except Exception as _exc:
            logger.warning("background_task_error", task=label, error=str(_exc)[:120])

    _aio.create_task(_wrapper())


def _categorize_rejection_reason(v_res: Any, finding: Finding) -> str:
    """Categorize why a finding was rejected by the validator."""
    explicit_reason = getattr(v_res, "reason", None)
    if explicit_reason and isinstance(explicit_reason, str):
        return explicit_reason
    if hasattr(v_res, "notes") and v_res.notes:
        for n in v_res.notes:
            if n in ("no_evidence", "below_confidence_threshold", "validator_rejected"):
                return n
    ev = finding.evidence or {}
    if not ev or not any(bool(v) for v in ev.values()):
        return "no_evidence"
    if hasattr(v_res, "stage_results") and isinstance(v_res.stage_results, dict):
        for _, _, note in v_res.stage_results.values():
            note_lower = (note or "").lower()
            if (
                "no captured hash" in note_lower
                or "no evidence" in note_lower
                or "missing" in note_lower
            ):
                return "no_evidence"
    if getattr(v_res, "confidence", 0.0) < 0.4:
        return "below_confidence_threshold"
    return "validator_rejected"


class AresEngine:
    """
    ARES Async Engine.

    Single module:  await engine.run_module(module_id, campaign, params)
    Full plan:      await engine.run_plan(plan, campaign)
                    → modules in same stage run CONCURRENTLY
    """

    def __init__(
        self,
        settings: AresSettings | None = None,
        validator: FindingValidator | None = None,
        db: Any | None = None,
        max_parallel: int = 5,
    ) -> None:
        self.settings = settings or get_settings()
        self.validator = validator or build_default_validator()
        self.db = db
        self.max_parallel = max_parallel
        self._registry: ModuleRegistry | None = None
        self._semaphore: asyncio.Semaphore | None = None
        self._admitted_dispatch_contexts: dict[str, tuple[str, ...]] = {}
        self._admission_store_id: int | None = None
        self.notifier = build_notifier_from_settings(self.settings)
        from ares.telemetry.collector import get_collector

        self.telemetry = get_collector()
        self._runtime_states = CampaignRuntimeStateStore(
            self.settings.encryption_key_value,
            telemetry=self.telemetry,
        )
        setup_logger(self.settings.ares_log_level, self.settings.ares_log_file)

    def _bind_admission_store(self, store: object) -> None:
        """Bind this engine to exactly one lifecycle store for its process lifetime."""
        store_id = id(store)
        if self._admission_store_id is None:
            self._admission_store_id = store_id
            return
        if self._admission_store_id != store_id:
            raise PermissionError("engine is already bound to a different admission store")

    def _register_admitted_dispatch_context(self, context: AdmittedDispatchContextV1) -> None:
        """Register one coordinator nonce and all of its sealed work bindings."""
        self._bind_admission_store_id(context._store_id)
        self._admitted_dispatch_contexts[context._dispatch_nonce] = (
            context.campaign_id,
            context.submission_id,
            context.logical_execution_id,
            context.attempt_id,
            context.module_id,
            str(context.attempt_revision),
            str(context._store_id),
            context._signature,
        )

    def _bind_admission_store_id(self, store_id: int) -> None:
        if self._admission_store_id is None:
            self._admission_store_id = store_id
            return
        if self._admission_store_id != store_id:
            raise PermissionError("dispatch context belongs to a different admission store")

    def _consume_registered_dispatch_context(self, context: AdmittedDispatchContextV1) -> bool:
        """Atomically consume the coordinator-scoped work registration."""
        expected = self._admitted_dispatch_contexts.pop(context._dispatch_nonce, None)
        return expected == (
            context.campaign_id,
            context.submission_id,
            context.logical_execution_id,
            context.attempt_id,
            context.module_id,
            str(context.attempt_revision),
            str(context._store_id),
            context._signature,
        )

    # ── Loading ────────────────────────────────────────────────────────────

    def load_modules(self, external_dir: str | None = None) -> int:
        loader = PluginLoader()
        self._registry = loader.load_all(external_dir=external_dir)
        if loader.errors:
            logger.warning("engine_modules_failed_to_load")
        logger.info("engine_loaded_modules")
        return len(self._registry)

    @property
    def registry(self) -> ModuleRegistry:
        if self._registry is None:
            self.load_modules()
        if self._registry is None:
            raise RuntimeError(
                "ModuleRegistry not initialised - call load_modules() before accessing registry"
            )
        return self._registry

    def list_modules(self) -> list[dict[str, Any]]:
        return self.registry.list_metadata()

    async def ensure_campaign_runtime(
        self,
        campaign: Campaign,
        db: Any | None = None,
    ) -> CampaignRuntimeState:
        """Attach the campaign's shared state and rehydrate safe durable state."""
        return await self._runtime_states.ensure(campaign, self.db if db is None else db)

    def bind_database(self, db: Any) -> None:
        """Bind the active API database once, rejecting accidental split persistence."""
        if self.db is None:
            self.db = db
            return
        if self.db is not db:
            raise RuntimeError("AresEngine is already bound to a different database")

    async def restore_campaign_vault(self, campaign: Campaign) -> int:
        """Restore encrypted credential records into the shared campaign state."""
        if self.db is None:
            raise RuntimeError("Credential restore requires an active database")
        return await self._runtime_states.restore_vault(campaign, self.db)

    def campaign_runtime_state(self, campaign_id: str) -> CampaignRuntimeState | None:
        return self._runtime_states.get(campaign_id)

    def discard_campaign_runtime(self, campaign_id: str) -> None:
        self._runtime_states.discard(campaign_id)

    # ── Single module ──────────────────────────────────────────────────────

    async def run_module(
        self,
        module_id: str,
        campaign: Campaign,
        params: dict[str, Any],
        skip_validation: bool = False,
        timeout_seconds: int = 120,
        actor_role: str = "operator",
        dispatch_context: AdmittedDispatchContextV1 | None = None,
    ) -> EngineModuleResult:
        try:
            admitted_context = consume_dispatch_context(
                dispatch_context,
                consumer=self,
                campaign_id=campaign.id,
                module_id=module_id,
            )
        except PermissionError as exc:
            return EngineModuleResult(
                module_id=module_id,
                status=ModuleStatus.FAILED,
                error=str(exc),
            )
        runtime_state = await self.ensure_campaign_runtime(campaign)

        is_disabled = getattr(self.registry, "is_disabled", None)
        if callable(is_disabled) and is_disabled(module_id) is True:
            reason = getattr(self.registry, "get_disabled_reason", lambda _: None)(module_id) or "module disabled: implementation incomplete, see MOD-005"
            return EngineModuleResult(
                module_id=module_id,
                status=ModuleStatus.FAILED,
                error=reason,
            )

        if module_id not in self.registry:
            return EngineModuleResult(
                module_id=module_id,
                status=ModuleStatus.FAILED,
                error=f"Module '{module_id}' not found. Run: ares module list",
            )

        # ── RBAC check - role must be allowed to run this module ──────────
        from ares.collab.manager import can_role_run_module

        if not can_role_run_module(actor_role, module_id, self.registry):
            audit(
                "module_rbac_denied",
                actor=campaign.operator,
                detail=f"role={actor_role} module={module_id}",
            )
            return EngineModuleResult(
                module_id=module_id,
                status=ModuleStatus.FAILED,
                error=(
                    f"Role '{actor_role}' is not permitted to run "
                    f"'{module_id}'. Check ROLE_PERMISSIONS in collab/manager.py."
                ),
            )

        # ── Scope pre-check - enforce before any module code runs ────────
        # Cloud/reporting modules use API credentials, not host IPs - skip host pre-check
        _NO_SCOPE_CATEGORIES = {"cloud", "reporting"}
        _module_cls = self.registry.get(module_id)
        _module_category = str(getattr(_module_cls, "MODULE_CATEGORY", "") or "").lower().strip()
        if _module_category not in _NO_SCOPE_CATEGORIES:
            candidate_targets = _extract_all_targets(params)
            fallback_target = params.get("target", "") or params.get("dc", "") or params.get("host", "")
            if fallback_target and str(fallback_target) not in candidate_targets:
                candidate_targets.append(str(fallback_target))

            for cand in candidate_targets:
                if not campaign.is_in_scope(cand):
                    audit(
                        "module_scope_violation",
                        actor=campaign.operator,
                        detail=f"module={module_id} target={cand!r} not in scope",
                    )
                    return EngineModuleResult(
                        module_id=module_id,
                        status=ModuleStatus.FAILED,
                        error=f"Target {cand!r} is not in campaign scope {[s.cidr for s in campaign.scope]}. "
                        "Add the target CIDR to scope or use a different target.",
                    )

        cls = self.registry.get(module_id)
        noise = NoiseController(campaign)
        instance = cls(settings=self.settings, campaign=campaign, noise=noise)  # type: ignore[misc]
        # Respect per-module timeout if declared (MODULE_TIMEOUT_SECONDS)
        module_timeout = getattr(instance.__class__, "MODULE_TIMEOUT_SECONDS", None)
        effective_timeout = module_timeout if module_timeout is not None else timeout_seconds
        if effective_timeout != timeout_seconds:
            logger.debug(
                "engine_using_module_timeout", module_id=module_id, timeout=effective_timeout
            )

        audit(
            "module_run_start",
            actor=campaign.operator,
            detail=f"module={module_id} campaign={campaign.id[:8]}",
        )
        t0 = time.monotonic()

        try:
            # Build ExecutionContext - new v0.9.0+ interface
            ctx = ExecutionContext.build(
                campaign=campaign,
                target=params.get("dc") or params.get("host") or params.get("target", ""),
                module_id=module_id,
                domain=params.get("domain", ""),
                params=params,
                operator=campaign.operator,
                credentials=runtime_state.safe_credentials(),
                session=runtime_state.session,
                vault=runtime_state.vault,
                artifact_store=runtime_state.artifact_store,
                runtime_state=runtime_state,
                settings=self.settings,
                noise=noise,
                telemetry=runtime_state.telemetry,
            )

            async with scope_firewall_guard(
                campaign=campaign,
                module_id=module_id,
                module_category=_module_category,
            ):
                # ── validate() before execute() ───────────────────────────
                # Always call validate() first - lets modules fail fast with
                # informative errors before any network activity happens.
                # skip_validation=True is an escape hatch for tests / retries.
                if not skip_validation:
                    try:
                        await asyncio.wait_for(
                            instance.validate(ctx),
                            timeout=10,
                        )
                    except TimeoutError:
                        duration_ms = round((time.monotonic() - t0) * 1000, 2)
                        audit(
                            "module_validation_failed",
                            actor=campaign.operator,
                            detail=f"module={module_id} reason=timeout",
                        )
                        return EngineModuleResult(
                            module_id=module_id,
                            status=ModuleStatus.FAILED,
                            error=f"Module '{module_id}' validate() timed out (>10s)",
                            duration_ms=duration_ms,
                        )
                    except ScopeFirewallBlockError:
                        raise
                    except Exception as val_exc:
                        duration_ms = round((time.monotonic() - t0) * 1000, 2)
                        err_msg = str(val_exc)
                        logger.warning(
                            "engine_module_validation_failed", module_id=module_id, error=err_msg[:200]
                        )
                        audit(
                            "module_validation_failed",
                            actor=campaign.operator,
                            detail=f"module={module_id} error={err_msg[:100]}",
                        )
                        return EngineModuleResult(
                            module_id=module_id,
                            status=ModuleStatus.REJECTED,
                            error=f"Validation failed: {err_msg[:300]}",
                            duration_ms=duration_ms,
                        )
                # ── end validate ───────────────────────────────────────────

                # Call execute(ctx) - preferred interface.
                # Falls back to run(**ctx.params) via BaseModule.execute() default
                # for modules that haven't migrated yet.
                mark_effect_started(admitted_context)
                execute_coro = instance.execute(ctx)
                module_result = await asyncio.wait_for(execute_coro, timeout=effective_timeout)
                findings = module_result.findings
                raw = module_result.raw
        except TimeoutError:
            logger.error(
                "engine_timed_out_s",
                module_id=module_id,
                timeout_seconds=effective_timeout,
            )
            _last_exc: Exception = TimeoutError(f"Timed out after {effective_timeout}s")
            _action = AresError.RETRY
        except ScopeFirewallBlockError as exc:
            audit(
                "scope_firewall_egress_blocked",
                actor=campaign.operator,
                detail=f"module={module_id} target={exc.target_host} port={exc.target_port}",
            )
            logger.error(
                "scope_firewall_egress_blocked",
                module_id=module_id,
                target=exc.target_host,
                port=exc.target_port,
                scope=exc.scope_cidrs,
            )
            _last_exc = exc
            _action = AresError.SKIP
        except AresError as exc:
            logger.warning("engine_areserror", module_id=module_id, action=exc.action, exc=exc)
            _last_exc = exc
            _action = exc.action
        except Exception as exc:
            logger.error("engine_crashed", module_id=module_id, exc=exc, exc_info=True)
            _last_exc = exc
            _action = AresError.SKIP
        else:
            _last_exc = None
            _action = None

        # Automatic engine retries are forbidden.  A retry is a fresh durable
        # child attempt and is owned exclusively by the admission coordinator.
        _was_timeout = isinstance(_last_exc, asyncio.TimeoutError)

        if _last_exc is not None:
            status = ModuleStatus.TIMEOUT if _was_timeout else ModuleStatus.FAILED
            typed_outcome = (
                "scope_firewall_blocked"
                if isinstance(_last_exc, ScopeFirewallBlockError)
                else ("network_error" if isinstance(_last_exc, NetworkError) else "")
            )
            typed_message = (
                redact_error_message(str(_last_exc)[:300]) or "" if typed_outcome else ""
            )
            return EngineModuleResult(
                module_id=module_id,
                status=status,
                error=str(_last_exc)[:300],
                duration_ms=round((time.monotonic() - t0) * 1000, 2),
                outcome=typed_outcome,
                outcome_message=typed_message,
            )

        duration_ms = round((time.monotonic() - t0) * 1000, 2)

        # Validate
        validation_results: list[ValidationResult] = []
        if not skip_validation:
            for f in findings:
                f.module_id = f.module_id or module_id
            # Run all validations in parallel too
            validation_results = list(
                await asyncio.gather(*[self.validator.validate(f, raw) for f in findings])
            )

        # Prepare confirmed findings without persistence, publication, campaign
        # mutation, or artifact normalization.  Those effects are released only
        # after the coordinator durably commits the terminal attempt.
        confirmed: list[Finding] = []
        filtered_count = 0
        filtered_reasons: dict[str, int] = {}
        from ares.core.cvss import enrich_finding_with_cvss
        from ares.core.tracing import get_current_trace_id

        trace_id = get_current_trace_id() or ""
        for i, f in enumerate(findings):
            if not skip_validation and i < len(validation_results):
                v_res = validation_results[i]
                if v_res.should_report and v_res.confidence >= 0.4:
                    f.confidence = v_res.confidence
                    f.validated = True
                    f.module_id = f.module_id or module_id
                    enrich_finding_with_cvss(f)
                    if trace_id:
                        f.trace_id = trace_id
                    confirmed.append(f)
                else:
                    f.false_positive = True
                    f.validated = False
                    reason = _categorize_rejection_reason(v_res, f)
                    filtered_count += 1
                    filtered_reasons[reason] = filtered_reasons.get(reason, 0) + 1
                    logger.warning(
                        "finding_rejected_by_validator",
                        finding_id=f.id,
                        title=f.title,
                        severity=str(f.severity),
                        confidence=v_res.confidence,
                        reason=reason,
                    )
            else:
                if not f.false_positive:
                    f.validated = True
                    f.module_id = f.module_id or module_id
                    enrich_finding_with_cvss(f)
                    if trace_id:
                        f.trace_id = trace_id
                    confirmed.append(f)

        fp_count = len(findings) - len(confirmed)
        audit(
            "module_run_complete",
            actor=campaign.operator,
            detail=(
                f"module={module_id} ms={duration_ms} confirmed={len(confirmed)} fp={fp_count}"
            ),
        )

        return EngineModuleResult(
            module_id=module_id,
            status=ModuleStatus.DONE,
            findings=confirmed,
            validation_results=validation_results,
            raw_output=raw,
            duration_ms=duration_ms,
            filtered_findings={"count": filtered_count, "reasons": filtered_reasons},
        )

    # ── Parallel plan ──────────────────────────────────────────────────────

    async def run_plan(
        self,
        plan: ExecutionPlan,
        campaign: Campaign,
        global_params: dict[str, Any] | None = None,
        skip_validation: bool = False,
        timeout_per_module: int = 120,
        on_progress: ProgressCallback | None = None,
        actor_role: str = "operator",
        dispatch_context: AdmittedPlanContextV1 | None = None,
    ) -> dict[str, EngineModuleResult]:
        """
        Run all stages.
        Within each stage: modules execute CONCURRENTLY (bounded by max_parallel semaphore).
        Between stages: sequential (later stages can depend on earlier recon).
        """
        module_ids_in_order = tuple(plan.all_module_ids())
        try:
            admitted_children = consume_plan_context(
                dispatch_context,
                consumer=self,
                campaign_id=campaign.id,
                module_ids=module_ids_in_order,
            )
        except PermissionError as exc:
            return {
                module_id: EngineModuleResult(
                    module_id=module_id,
                    status=ModuleStatus.FAILED,
                    error=str(exc),
                )
                for module_id in module_ids_in_order
            }
        child_iterator = iter(admitted_children)
        self._semaphore = asyncio.Semaphore(self.max_parallel)
        results: dict[str, EngineModuleResult] = {}
        gp = global_params or {}

        total_mods = len(plan.all_module_ids())
        logger.info("engine_plan_start_stages_modules", total_mods=total_mods)

        _pivot_cleanup_needed = "network.pivot" in plan.all_module_ids()
        try:
            for stage in plan.stages:
                name = stage["name"]
                module_ids = stage["modules"]
                sp = stage.get("params", {})

                logger.info("engine_stage_modules_parallel", name=name)

                coros = [
                    self._guarded_run(
                        module_id=mid,
                        campaign=campaign,
                        params={**gp, **sp.get(mid, {})},
                        skip_validation=skip_validation,
                        timeout_seconds=timeout_per_module,
                        stage_name=name,
                        on_progress=on_progress,
                        actor_role=actor_role,
                        dispatch_context=next(child_iterator),
                    )
                    for mid in module_ids
                ]

                raw_results = await asyncio.gather(*coros, return_exceptions=True)
                stage_results: list[EngineModuleResult] = []
                for mid, res in zip(module_ids, raw_results):
                    if isinstance(res, Exception):
                        logger.error(
                            "engine_raised_unhandled_exception", mid=mid, res=res, exc_info=res
                        )
                        stage_results.append(
                            EngineModuleResult(
                                module_id=mid,
                                status=ModuleStatus.FAILED,
                                error=f"Unhandled: {res!s}"[:200],
                            )
                        )
                    else:
                        stage_results.append(res)
                for mid, res in zip(module_ids, stage_results):
                    results[mid] = res

            confirmed_total = sum(len(r.confirmed_findings) for r in results.values())
            logger.info("engine_plan_complete_confirmed_findings", confirmed_total=confirmed_total)
        finally:
            # Teardown: close any active pivot tunnels established during this plan
            # Guaranteed execution via finally block (MOD-018) regardless of plan outcome.
            if (
                "network.pivot" in results
                or _pivot_cleanup_needed
                or campaign.id in getattr(__import__("ares.modules.network.pivot", fromlist=["_PIVOT_MANAGERS"]), "_PIVOT_MANAGERS", {})
            ):
                try:
                    from ares.modules.network.pivot import _PIVOT_MANAGERS

                    campaign_id = campaign.id
                    manager = _PIVOT_MANAGERS.get(campaign_id)
                    if manager:
                        if hasattr(manager, "teardown_all"):
                            try:
                                res = manager.teardown_all()
                                if inspect.iscoroutine(res):
                                    await asyncio.wait_for(res, timeout=10.0)
                            except TimeoutError:
                                logger.warning("pivot_teardown_timeout", campaign_id=campaign_id[:8])
                            except Exception as e:
                                logger.warning("pivot_teardown_error", campaign_id=campaign_id[:8], error=str(e))
                        for tunnel in list(manager.all_tunnels() if hasattr(manager, "all_tunnels") else []):
                            try:
                                if tunnel._conn:
                                    tunnel._conn.close()
                                elif tunnel._proc:
                                    proc = tunnel._proc
                                    try:
                                        proc.terminate()
                                        try:
                                            if inspect.iscoroutinefunction(getattr(proc, "wait", None)):
                                                await asyncio.wait_for(proc.wait(), timeout=5)
                                            else:
                                                await asyncio.to_thread(lambda: proc.wait(timeout=5))  # noqa: B023  (awaited in-iteration; proc is stable)
                                        except Exception:
                                            try:
                                                proc.kill()
                                            except (ProcessLookupError, OSError):
                                                pass
                                    except (ProcessLookupError, OSError, AttributeError):
                                        pass
                            except Exception:
                                pass
                        _PIVOT_MANAGERS.pop(campaign_id, None)
                        logger.info("engine_pivot_teardown", campaign_id=campaign_id[:8])
                except Exception as teardown_exc:
                    logger.warning("engine_pivot_teardown_failed", error=str(teardown_exc)[:80])

            # ALWAYS clean up credential artifacts - regardless of which modules ran.
            # This runs unconditionally in finally to prevent accumulation in 24/7 operation.
            try:
                from ares.core.security import cleanup_credential_artifacts

                cleaned = cleanup_credential_artifacts(campaign.id)
                # Also clean global-scope artifacts (created outside campaign context)
                cleaned += cleanup_credential_artifacts()
                if cleaned:
                    logger.info(
                        "engine_credential_artifacts_cleaned",
                        count=cleaned,
                        campaign_id=campaign.id[:8],
                    )
            except Exception:
                pass

        return results

    def check_plan_dependencies(self, plan: "ExecutionPlan") -> list[dict[str, Any]]:
        """
        Validate each module's REQUIRES are satisfied by earlier stages.
        Returns list of warning dicts with module_id, missing_requirement, suggested_provider.
        Called automatically in run_plan - warnings logged, never blocking.
        """
        warnings_out: list[dict[str, Any]] = []
        available_outputs: set[str] = set()

        # reverse map: capability → module_id that provides it
        provider_map: dict[str, str] = {}
        for cls in self.registry.all():
            for out in getattr(cls, "OUTPUTS", []):
                provider_map[out] = getattr(cls, "MODULE_ID", cls.__name__)

        for stage in plan.stages:
            for mid in stage.get("modules", []):
                cls = self.registry.get(mid)
                if not cls:
                    continue
                for req in getattr(cls, "REQUIRES", []):
                    if req not in available_outputs:
                        suggested = provider_map.get(req, "unknown")
                        warnings_out.append(
                            {
                                "module_id": mid,
                                "missing_requirement": req,
                                "suggested_provider": suggested,
                                "message": (
                                    f"'{mid}' requires '{req}' - "
                                    f"add '{suggested}' to an earlier stage first"
                                ),
                            }
                        )
            for mid in stage.get("modules", []):
                cls = self.registry.get(mid)
                if cls:
                    available_outputs.update(getattr(cls, "OUTPUTS", []))

        return warnings_out

    def dry_run_plan(
        self,
        plan: "ExecutionPlan",
        global_params: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """
        Validate a plan without executing - pre-flight check.

        Returns:
            dry_run:          True
            plan[]:           stages with module details, opsec level, missing params
            param_validation: ok flag + per-field errors
            dependency_check: ok flag + missing REQUIRES warnings
            summary:          total stages/modules, ready_to_run bool

        Usage:
            POST /campaigns/{id}/run  {"dry_run": true}
            ares module run-plan --plan plan.json --dry-run
        """
        gp = global_params or {}
        dep_warnings = self.check_plan_dependencies(plan)
        stages_out: list[dict[str, Any]] = []
        param_errors: list[dict[str, str]] = []

        for stage in plan.stages:
            name = stage.get("name", "unnamed")
            mids = stage.get("modules", [])
            sp = stage.get("params", {})

            stage_info: dict[str, Any] = {
                "stage": name,
                "modules": [],
                "estimated_duration": _estimate_stage_duration(len(mids)),
            }

            for mid in mids:
                cls = self.registry.get(mid)
                if not cls:
                    param_errors.append(
                        {
                            "module_id": mid,
                            "field": "(module)",
                            "error": f"Module '{mid}' not found in registry",
                        }
                    )
                    stage_info["modules"].append(
                        {
                            "module_id": mid,
                            "status": "not_found",
                            "dry_run_status": "dry_run_unsupported",
                            "validated_params_summary": redact_module_params(
                                mid, {**gp, **sp.get(mid, {})}
                            ),
                            "missing_params": [],
                            "missing_dependencies": [],
                            "would_execute": False,
                            "warnings": ["The module is not present in the loaded registry."],
                            "operator_next_steps": [
                                "Refresh the module catalog or check module installation."
                            ],
                        }
                    )
                    continue

                merged = {**gp, **sp.get(mid, {})}
                mod_errors: list[str] = []
                try:
                    from ares.modules.params import MODULE_PARAMS

                    model_cls = MODULE_PARAMS.get(mid)
                    if model_cls:
                        for fname, field_info in model_cls.model_fields.items():
                            if field_info.is_required() and fname not in merged:
                                mod_errors.append(fname)
                                param_errors.append(
                                    {
                                        "module_id": mid,
                                        "field": fname,
                                        "error": f"Required param '{fname}' not provided",
                                    }
                                )
                except ImportError:
                    pass

                opsec = getattr(cls, "OPSEC_LEVEL", "?")
                dry_run_supported = bool(getattr(cls, "DRY_RUN_SUPPORTED", True))
                module_dry_status = (
                    "dry_run_blocked"
                    if mod_errors
                    else "dry_run_ok"
                    if dry_run_supported
                    else "dry_run_unsupported"
                )
                stage_info["modules"].append(
                    {
                        "module_id": mid,
                        "opsec_level": opsec.value if hasattr(opsec, "value") else str(opsec),
                        "requires": getattr(cls, "REQUIRES", []),
                        "outputs": getattr(cls, "OUTPUTS", []),
                        "mitre": getattr(cls, "MITRE_TECHNIQUES", []),
                        "missing_params": mod_errors,
                        "status": "error" if mod_errors else "ready",
                        "dry_run_status": module_dry_status,
                        "validated_params_summary": redact_module_params(mid, merged),
                        "missing_dependencies": [],
                        "would_execute": module_dry_status == "dry_run_ok",
                        "warnings": [
                            "Dry-run validates the plan only; no module code contacts a target."
                        ],
                        "operator_next_steps": [
                            "Review parameters and campaign scope before live execution."
                        ],
                    }
                )

            stages_out.append(stage_info)

        return {
            "dry_run": True,
            "status": "dry_run_blocked" if param_errors else "dry_run_ok",
            "plan": stages_out,
            "param_validation": {
                "ok": len(param_errors) == 0,
                "errors": param_errors,
            },
            "dependency_check": {
                "ok": len(dep_warnings) == 0,
                "warnings": dep_warnings,
            },
            "summary": {
                "total_stages": len(plan.stages),
                "total_modules": len(plan.all_module_ids()),
                "ready_to_run": len(param_errors) == 0,
            },
        }

    def dry_run_module(
        self,
        module_id: str,
        params: dict[str, Any] | None = None,
        missing_params: list[str] | None = None,
    ) -> dict[str, Any]:
        """Return a side-effect-free, stable preview for one module run."""
        raw_params = params or {}
        cls = self.registry.get(module_id)
        summary = redact_module_params(module_id, raw_params)
        is_disabled = getattr(self.registry, "is_disabled", None)
        if callable(is_disabled) and is_disabled(module_id) is True:
            reason = getattr(self.registry, "get_disabled_reason", lambda _: None)(module_id) or "module disabled: implementation incomplete, see MOD-005"
            return {
                "dry_run": True,
                "status": "disabled",
                "module_id": module_id,
                "validated_params_summary": summary,
                "missing_params": list(missing_params or []),
                "missing_dependencies": [],
                "would_execute": False,
                "warnings": [reason],
                "operator_next_steps": [reason],
            }
        if cls is None:
            return {
                "dry_run": True,
                "status": "dry_run_unsupported",
                "module_id": module_id,
                "validated_params_summary": summary,
                "missing_params": list(missing_params or []),
                "missing_dependencies": [],
                "would_execute": False,
                "warnings": ["The module is not present in the loaded registry."],
                "operator_next_steps": ["Refresh the module catalog or check module installation."],
            }

        supported = bool(getattr(cls, "DRY_RUN_SUPPORTED", True))
        if not supported:
            return {
                "dry_run": True,
                "status": "dry_run_unsupported",
                "module_id": module_id,
                "validated_params_summary": summary,
                "missing_params": list(missing_params or []),
                "missing_dependencies": [],
                "would_execute": False,
                "warnings": ["This module does not advertise a safe dry-run path."],
                "operator_next_steps": [
                    "Review the module documentation before an authorized live run."
                ],
            }

        missing = list(missing_params or [])
        if missing:
            return {
                "dry_run": True,
                "status": "dry_run_blocked",
                "module_id": module_id,
                "validated_params_summary": summary,
                "missing_params": missing,
                "missing_dependencies": [],
                "would_execute": False,
                "warnings": ["Required parameters are missing; no module code was executed."],
                "operator_next_steps": ["Provide the missing parameters and run dry-run again."],
            }

        warnings = ["Dry-run validates the request only; it does not contact the target."]
        if getattr(getattr(cls, "OPSEC_LEVEL", None), "value", "") == "high_noise":
            warnings.append("The selected module is high-noise and remains role/OPSEC guarded.")
        return {
            "dry_run": True,
            "status": "dry_run_ok",
            "module_id": module_id,
            "validated_params_summary": summary,
            "missing_params": [],
            "missing_dependencies": [],
            "would_execute": True,
            "warnings": warnings,
            "operator_next_steps": [
                "Review the validated parameters and campaign scope.",
                "Disable dry-run only after confirming authorization.",
            ],
        }

    async def assess_module_feasibility(
        self,
        module_id: str,
        campaign: Campaign,
        params: dict[str, Any],
    ) -> Any:
        """
        Evaluate pre-flight defense feasibility for a module against target defenses,
        session state, and noise profile without executing active operations.
        """
        from ares.modules.base import FeasibilityReport

        is_disabled = getattr(self.registry, "is_disabled", None)
        if callable(is_disabled) and is_disabled(module_id) is True:
            reason = getattr(self.registry, "get_disabled_reason", lambda _: None)(module_id) or "module disabled: implementation incomplete, see MOD-005"
            return FeasibilityReport(
                feasible=False,
                score=0.0,
                risk_level="high_noise",
                blockers=[reason],
            )

        if module_id not in self.registry:
            return FeasibilityReport(
                feasible=False,
                score=0.0,
                risk_level="high_noise",
                blockers=[f"Module '{module_id}' not found in registry"],
            )

        cls = self.registry.get(module_id)
        noise = NoiseController(campaign)
        instance = cls(settings=self.settings, campaign=campaign, noise=noise)
        runtime_state = await self.ensure_campaign_runtime(campaign)

        ctx = ExecutionContext.build(
            campaign=campaign,
            target=params.get("dc") or params.get("host") or params.get("target", ""),
            module_id=module_id,
            domain=params.get("domain", ""),
            params=params,
            operator=campaign.operator,
            credentials=runtime_state.safe_credentials(),
            session=runtime_state.session,
            vault=runtime_state.vault,
            artifact_store=runtime_state.artifact_store,
            runtime_state=runtime_state,
            settings=self.settings,
            noise=noise,
            telemetry=runtime_state.telemetry,
        )

        return await instance.assess_feasibility(ctx)

    async def _finalize_committed_module_result(
        self,
        campaign: Campaign,
        module_id: str,
        result: EngineModuleResult,
        dispatch_context: AdmittedDispatchContextV1,
    ) -> EngineModuleResult:
        """Release persistence and broadcasts only after durable terminal commit."""
        consume_terminal_commit_context(
            dispatch_context,
            consumer=self,
            campaign_id=campaign.id,
            module_id=module_id,
        )
        runtime_state = await self.ensure_campaign_runtime(campaign)

        for finding in result.findings:
            campaign.add_finding(finding)
            if self.db:
                try:
                    await self.db.save_finding(campaign.id, finding, module_id)
                except Exception as exc:
                    logger.warning("engine_db_save_failed_for_finding", error=str(exc)[:120])
            if self.notifier and self.notifier.should_notify(finding.severity):
                asyncio.create_task(self.notifier.notify_finding(finding, campaign))
            try:
                from ares.api.dashboard.app import broadcast_finding as dashboard_broadcast

                _fire_and_log(
                    dashboard_broadcast(
                        {
                            "event": "finding_discovered",
                            "campaign_id": campaign.id,
                            "title": finding.title,
                            "severity": finding.severity.value,
                            "confidence": finding.confidence,
                            "mitre_technique": finding.mitre_technique,
                            "host": finding.host,
                            "module_id": finding.module_id,
                            "timestamp": (
                                finding.discovered_at.isoformat()
                                if getattr(finding, "discovered_at", None)
                                else None
                            ),
                        }
                    ),
                    "committed_finding_broadcast",
                )
            except Exception as exc:
                logger.warning(
                    "committed_finding_broadcast_failed",
                    finding_id=getattr(finding, "id", None),
                    error=str(exc)[:120],
                )

        if self.db and runtime_state.vault is not None:
            try:
                await self._persist_vault_credentials(campaign, runtime_state.vault)
            except Exception as exc:
                logger.warning(
                    "engine_vault_persist_failed",
                    module_id=module_id,
                    error=str(exc)[:100],
                )

        try:
            from ares.normalize.artifacts import ArtifactNormalizer

            module_class = self.registry.get(module_id)
            outputs = getattr(module_class, "OUTPUTS", []) if module_class else []
            if outputs and result.raw_output:
                normalized = ArtifactNormalizer().normalize(
                    module_id=module_id,
                    outputs=outputs,
                    raw=result.raw_output,
                    store=runtime_state.artifact_store,
                )
                if normalized:
                    logger.debug("artifacts_normalized", module=module_id, count=normalized)
        except Exception as exc:
            logger.debug("artifact_normalization_skipped", error=str(exc)[:80])

        if self.db:
            await self._persist_runtime_hosts(campaign, runtime_state)
            await self._persist_runtime_graph(campaign, runtime_state)
            raw = getattr(result, "raw_output", {}) or {}
            loot_list = raw.get("loot") if isinstance(raw, dict) else None
            if isinstance(loot_list, list):
                from ares.db.database import Loot
                for item in loot_list:
                    try:
                        if isinstance(item, Loot):
                            await self.db.save_loot(item)
                        elif isinstance(item, dict):
                            loot_obj = Loot(
                                id=str(item.get("id") or f"loot_{uuid.uuid4().hex[:12]}"),
                                campaign_id=campaign.id,
                                host_id=item.get("host_id") or None,
                                loot_type=str(item.get("loot_type", "artifact")),
                                name=str(item.get("name", "Harvested Artifact")),
                                description=str(item.get("description", "")),
                                content=item.get("content", {}),
                                path_on_target=str(item.get("path_on_target", "")),
                                source_module=module_id,
                                tags=list(item.get("tags") or []),
                            )
                            await self.db.save_loot(loot_obj)
                    except Exception as exc:
                        logger.warning("engine_loot_persist_failed", module=module_id, error=str(exc)[:80])
        return await self._finalize_module_result(campaign, module_id, result)

    async def _finalize_module_result(
        self,
        campaign: Campaign,
        module_id: str,
        result: EngineModuleResult,
    ) -> EngineModuleResult:
        """Persist one safe execution record after the engine has a final result."""
        if self.db is None:
            return result

        outcome = module_outcome_value(result.outcome) or module_outcome_value(result.status)
        success = is_successful_module_outcome(outcome)
        duration_ms = max(0.0, float(result.duration_ms or 0.0))

        try:
            await self.db.record_module_run(
                campaign_id=campaign.id,
                module_id=module_id,
                outcome=(outcome or "unknown")[:64],
                success=success,
                duration_ms=duration_ms,
            )
        except Exception as exc:
            logger.warning(
                "engine_module_run_persist_failed",
                module_id=module_id,
                error=str(exc)[:120],
            )

        try:
            await self.db.audit(
                campaign.operator,
                "module_run",
                f"module={module_id} outcome={outcome or 'unknown'}",
                campaign.id,
                module_id,
            )
        except Exception as exc:
            logger.warning(
                "engine_module_audit_persist_failed",
                module_id=module_id,
                error=str(exc)[:120],
            )

        try:
            self.telemetry.record_execution(
                module_id,
                duration_ms,
                success=success,
                campaign_id=campaign.id,
            )
            if result.findings:
                self.telemetry.record_finding(len(result.findings))
        except Exception as exc:
            logger.debug(
                "engine_telemetry_record_failed", module_id=module_id, error=str(exc)[:120]
            )
        return result

    async def _persist_runtime_hosts(
        self,
        campaign: Campaign,
        runtime_state: CampaignRuntimeState,
    ) -> None:
        """Persist discovered host metadata without serializing runtime/session secrets."""
        if self.db is None or not hasattr(self.db, "upsert_host"):
            return

        from ares.db.database import Host

        for artifact in runtime_state.artifact_store.hosts():
            if artifact.ip_address:
                if (
                    hasattr(campaign, "is_in_scope")
                    and not campaign.is_in_scope(artifact.ip_address)
                ):
                    continue
                runtime_state.session.add_host(
                    artifact.ip_address,
                    hostname=artifact.hostname,
                    fqdn=artifact.fqdn,
                    os=artifact.os,
                    os_version=artifact.os_version,
                    domain=artifact.domain,
                    is_dc=artifact.is_dc,
                    open_ports=list(artifact.open_ports),
                )

        for host in runtime_state.session.all_hosts():
            if not host.ip_address:
                continue
            if (
                hasattr(campaign, "is_in_scope")
                and not campaign.is_in_scope(host.ip_address)
            ):
                continue
            try:
                await self.db.upsert_host(
                    Host(
                        campaign_id=campaign.id,
                        ip_address=host.ip_address,
                        hostname=host.hostname or None,
                        fqdn=host.fqdn or None,
                        os=host.os or None,
                        os_version=host.os_version or None,
                        domain=host.domain or None,
                        is_dc=host.is_dc,
                        open_ports=list(host.open_ports),
                        tags=list(host.tags),
                    )
                )
            except Exception as exc:
                logger.debug(
                    "engine_host_persist_failed",
                    campaign_id=campaign.id[:8],
                    error=str(exc)[:120],
                )

    async def _persist_runtime_graph(
        self,
        campaign: Campaign,
        runtime_state: CampaignRuntimeState,
    ) -> None:
        """Checkpoint a safe artifact graph using the existing encrypted loot store.

        The snapshot intentionally contains graph metadata only.  It never
        serializes vault values or artifact raw payloads, so rehydration cannot
        expose credential secrets through the graph API.
        """
        if self.db is None or not hasattr(self.db, "save_campaign_graph"):
            return
        try:
            from ares.graph.attack_graph import AttackGraph

            graph = AttackGraph()
            graph.build_from_store(runtime_state.artifact_store)
            runtime_state.attack_graph = graph
            await self.db.save_campaign_graph(campaign.id, graph.to_d3_json())
        except Exception as exc:
            logger.debug(
                "engine_graph_snapshot_persist_failed",
                campaign_id=campaign.id[:8],
                error=str(exc)[:120],
            )

    async def _persist_vault_credentials(
        self, campaign: "Campaign", vault: Any = None
    ) -> int:
        """
        Sync in-memory CredentialVault to the DB after each module run.
        Uses save_credential_preencrypted() to avoid double-encrypting secrets
        that are already vault-encrypted (AES-256-GCM v2).

        Returns: number of credentials saved/updated.
        """
        if vault is None:
            vault = getattr(campaign, "_vault", None)
        if not vault or not hasattr(vault, "_store") or not vault._store:
            return 0

        from ares.db.database import DBCredential

        saved = 0
        for cred_id, cred in vault._store.items():
            try:
                secret_enc = ""
                if hasattr(cred, "secret_enc") and cred.secret_enc:
                    secret_enc = (
                        cred.secret_enc.decode("utf-8", errors="replace")
                        if isinstance(cred.secret_enc, bytes)
                        else str(cred.secret_enc)
                    )
                db_cred = DBCredential(
                    id=cred.id,
                    campaign_id=campaign.id,
                    host_id=getattr(cred, "source_host", None) or None,
                    username=cred.username,
                    cred_type=(
                        cred.cred_type.value
                        if hasattr(cred.cred_type, "value")
                        else str(cred.cred_type)
                    ),
                    secret=secret_enc,
                    domain=getattr(cred, "domain", ""),
                    source_module=getattr(cred, "source_module", ""),
                    notes=getattr(cred, "notes", ""),
                )
                await self.db.save_credential_preencrypted(db_cred)
                saved += 1
            except Exception as exc:
                logger.debug("vault_persist_cred_failed", cred_id=cred_id[:8], error=str(exc)[:80])
        if saved:
            logger.debug("vault_persisted", campaign=campaign.id[:8], count=saved)
        return saved

    async def _guarded_run(
        self,
        module_id: str,
        campaign: Campaign,
        params: dict[str, Any],
        skip_validation: bool,
        timeout_seconds: int,
        stage_name: str,
        on_progress: ProgressCallback | None,
        actor_role: str,
        dispatch_context: AdmittedDispatchContextV1,
    ) -> EngineModuleResult:
        if self._semaphore is None:
            raise RuntimeError(
                "Engine semaphore not initialised - engine was not started correctly"
            )
        async with self._semaphore:
            if on_progress:
                await on_progress(
                    ProgressEvent(
                        stage=stage_name,
                        module_id=module_id,
                        status=ModuleStatus.RUNNING,
                    )
                )
            result = await self.run_module(
                module_id,
                campaign,
                params,
                skip_validation,
                timeout_seconds,
                actor_role=actor_role,
                dispatch_context=dispatch_context,
            )
            if on_progress:
                await on_progress(
                    ProgressEvent(
                        stage=stage_name,
                        module_id=module_id,
                        status=result.status,
                        finding_count=len(result.confirmed_findings),
                        error=result.error,
                        duration_ms=result.duration_ms,
                    )
                )
            return result


# Backward-compat alias
ModuleResult = EngineModuleResult  # noqa


# ── Campaign Templates ───────────────────────────────────────────────────────

CAMPAIGN_TEMPLATES: dict[str, dict] = {
    "internal_pentest": {
        "description": "Standard internal network penetration test",
        "stages": [
            {
                "name": "recon",
                "modules": [
                    "network.port_scan",
                    "network.service_detect",
                    "recon.fingerprint",
                    "network.dns_enum",
                ],
            },
            {
                "name": "ad_enum",
                "modules": [
                    "ad.enum_users",
                    "ad.enum_spn",
                    "ad.enum_computers",
                    "ad.enum_acl",
                ],
            },
            {
                "name": "credential_attack",
                "modules": [
                    "ad.kerberoast",
                    "ad.asreproast",
                ],
            },
            {
                "name": "credential_crack",
                "modules": [
                    "credential.crack",
                ],
            },
            {
                "name": "lateral_movement",
                "modules": [
                    "credential.reuse",
                    "lateral.smb_relay",
                    "lateral.ntlm_relay",
                ],
            },
        ],
    },
    "ad_full_compromise": {
        "description": "Full Active Directory compromise - recon to domain admin",
        "stages": [
            {
                "name": "recon",
                "modules": [
                    "recon.fingerprint",
                    "ad.enum_users",
                    "ad.enum_spn",
                    "ad.enum_computers",
                    "ad.enum_acl",
                ],
            },
            {
                "name": "credential_harvest",
                "modules": [
                    "ad.kerberoast",
                    "ad.asreproast",
                    "ad.laps_enum",
                ],
            },
            {
                "name": "crack_and_reuse",
                "modules": [
                    "credential.crack",
                    "credential.reuse",
                    "credential.pass_the_hash",
                ],
            },
            {
                "name": "escalation",
                "modules": [
                    "ad.delegation_abuse",
                    "ad.adcs",
                    "ad.sccm",
                ],
            },
            {
                "name": "domain_admin",
                "modules": [
                    "ad.dcsync",
                    "credential.golden_ticket",
                ],
            },
        ],
    },
    "cloud_assessment": {
        "description": "Multi-cloud security assessment - AWS, Azure, GCP",
        "stages": [
            {
                "name": "cloud_enum",
                "modules": [
                    "cloud.aws",
                    "cloud.azure",
                    "cloud.gcp",
                    "cloud.azure_ad",
                ],
            },
            {
                "name": "cloud_privesc",
                "modules": [
                    "cloud.aws_privesc",
                ],
            },
            {
                "name": "federation",
                "modules": [
                    "cloud.identity_federation_abuse",
                ],
            },
        ],
    },
    "assumed_breach": {
        "description": "Assumed breach - start with valid creds, test lateral + escalation",
        "stages": [
            {
                "name": "situational_awareness",
                "modules": [
                    "recon.fingerprint",
                    "ad.enum_users",
                    "ad.enum_computers",
                    "ad.enum_acl",
                ],
            },
            {
                "name": "escalation",
                "modules": [
                    "ad.kerberoast",
                    "ad.adcs",
                    "ad.delegation_abuse",
                    "ad.sccm",
                ],
            },
            {
                "name": "lateral",
                "modules": [
                    "lateral.smb_relay",
                    "lateral.ntlm_relay",
                    "credential.reuse",
                    "lateral.wmiexec",
                    "lateral.dcom",
                ],
            },
            {
                "name": "post_exploit",
                "modules": [
                    "windows.lsass_dump",
                    "windows.lsa_secrets",
                    "exfil.smb_shares",
                    "exfil.secrets_scan",
                ],
            },
        ],
    },
    "linux_pentest": {
        "description": "Linux infrastructure penetration test",
        "stages": [
            {
                "name": "recon",
                "modules": [
                    "network.port_scan",
                    "network.service_detect",
                    "recon.fingerprint",
                ],
            },
            {
                "name": "privesc",
                "modules": [
                    "linux.privesc",
                    "linux.kernel_suggester",
                    "linux.service_hijack",
                    "linux.ld_preload",
                ],
            },
            {
                "name": "post_exploit",
                "modules": [
                    "linux.container",
                    "linux.nfs_escape",
                    "exfil.secrets_scan",
                ],
            },
        ],
    },
}


def get_campaign_template(name: str) -> dict | None:
    """Return a campaign template by name, or None if not found."""
    return CAMPAIGN_TEMPLATES.get(name)


def list_campaign_templates() -> list[dict]:
    """Return list of available campaign templates with descriptions."""
    return [
        {
            "name": k,
            "description": v["description"],
            "stages": len(v["stages"]),
            "modules": sum(len(s["modules"]) for s in v["stages"]),
        }
        for k, v in CAMPAIGN_TEMPLATES.items()
    ]


def plan_from_template(name: str, custom_params: dict | None = None) -> "ExecutionPlan":
    """
    Build an ExecutionPlan from a named template.

    Usage:
        plan = plan_from_template("internal_pentest", {"dc": "10.0.0.5", "domain": "corp.local"})
        results = await engine.run_plan(plan, campaign, global_params)
    """
    template = CAMPAIGN_TEMPLATES.get(name)
    if not template:
        raise ValueError(f"Unknown template '{name}'. Available: {list(CAMPAIGN_TEMPLATES.keys())}")
    plan = ExecutionPlan()
    for stage in template["stages"]:
        plan.add_stage(
            name=stage["name"],
            module_ids=stage["modules"],
            params=custom_params or {},
        )
    return plan