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.

46.5 KB
Raw Blame
"""
ares.strategy.engine - Autonomous Engagement Strategy Engine

Orchestrates strategic modules in a continuous adaptive engagement loop.
Extracted from strategy/__init__.py for maintainability.

See strategy/models.py for data models, strategy/knowledge_base.py for
outcome tracking, and strategy/notifier.py for operator notifications.
"""
from __future__ import annotations

import asyncio
import json
import time
from collections.abc import Mapping
from typing import Any

from ares.core.logger import audit, get_logger
from ares.strategy.enforcer import ConstitutionEnforcer
from ares.strategy.knowledge_base import OutcomeKnowledgeBase
from ares.strategy.models import (
    EngagementResult,
    ModuleOutcome,
    RoundResult,
)
from ares.strategy.notifier import OperatorNotifier
from ares.strategy.target_state import TargetStateMap

logger = get_logger("ares.strategy.engine")


class StrategyEngine:
    """
    Orchestrates all 4 strategic modules in an adaptive engagement loop.

    Each round:
      1. Check detection probability - stop if too hot
      2. Gather EDR context for bypass planning
      3. AI re-plans with full accumulated context
      4. Execute plan with bypass techniques applied
      5. Record outcomes → KnowledgeBase learns
      6. Check if goal achieved

    The engine is designed to be interruptible:
      - max_detection_probability guard prevents uncontrolled noise
      - confidence_threshold prevents executing uncertain plans
      - max_rounds provides absolute iteration limit
    """

    def __init__(
        self,
        ares_engine:      "Any",     # AresEngine instance
        settings:         "Any",     # AresSettings
        notifier:         OperatorNotifier | None = None,
    ) -> None:
        self._engine       = ares_engine
        self._settings     = settings
        self._notifier     = notifier or OperatorNotifier()
        self._kb           = OutcomeKnowledgeBase()
        self._target_state = TargetStateMap()
        # There is intentionally no production configuration surface for this
        # seam.  The generation-11 catalog currently makes every descriptor
        # ineligible, so production Strategy must stop before planning or any
        # effect.  Tests may populate the private, canonical plan below to
        # exercise the coordinator wiring without enabling a production path.
        self._c_live_test_coordinator: Any | None = None
        self._c_live_test_principal: Any | None = None
        self._c_live_test_parent_key: str | None = None
        self._c_live_test_plan_json: str | None = None
        self._c_live_test_plan_digest: str | None = None

    def _configure_c_live_test_plan(
        self,
        *,
        coordinator: Any,
        principal: Any,
        idempotency_key: str,
        plan: tuple[Mapping[str, Any], ...],
    ) -> None:
        """Install one pure deterministic plan for C-LIVE wiring tests only.

        This leading-underscore seam is not read from settings, environment,
        request data, or a plugin.  Production construction therefore cannot
        activate Strategy while descriptors remain ineligible.
        """
        from ares.core.execution_admission import canonical_intent_digest
        from ares.db.execution_lifecycle import TrustedPrincipal, valid_uuid

        if (
            not callable(getattr(coordinator, "execute_module", None))
            or type(principal) is not TrustedPrincipal
            or not valid_uuid(idempotency_key)
            or type(plan) is not tuple
        ):
            raise ValueError("invalid deterministic C-LIVE strategy test plan")

        occurrence_by_module: dict[str, int] = {}
        normalized: list[dict[str, Any]] = []
        for module_ordinal, value in enumerate(plan):
            if not isinstance(value, Mapping) or set(value) - {
                "module_id",
                "params",
                "stage_ordinal",
                "decision_ordinal",
            }:
                raise ValueError("invalid deterministic C-LIVE strategy test plan")
            module_id = value.get("module_id")
            params = value.get("params", {})
            stage_ordinal = value.get("stage_ordinal", module_ordinal)
            decision_ordinal = value.get("decision_ordinal", 0)
            if (
                type(module_id) is not str
                or not module_id
                or not isinstance(params, Mapping)
                or type(stage_ordinal) is not int
                or type(decision_ordinal) is not int
                or not 0 <= stage_ordinal <= 9_007_199_254_740_991
                or not 0 <= decision_ordinal <= 9_007_199_254_740_991
            ):
                raise ValueError("invalid deterministic C-LIVE strategy test plan")
            occurrence = occurrence_by_module.get(module_id, 0)
            occurrence_by_module[module_id] = occurrence + 1
            normalized.append(
                {
                    "module_id": module_id,
                    "params": dict(params),
                    "occurrence": occurrence,
                    "stage_ordinal": stage_ordinal,
                    "decision_ordinal": decision_ordinal,
                    "module_ordinal": module_ordinal,
                }
            )

        try:
            plan_json = json.dumps(
                normalized,
                sort_keys=True,
                separators=(",", ":"),
                ensure_ascii=False,
                allow_nan=False,
            )
            frozen_plan = json.loads(plan_json)
            digest = canonical_intent_digest(frozen_plan)
        except (TypeError, ValueError) as exc:
            raise ValueError("invalid deterministic C-LIVE strategy test plan") from exc

        self._c_live_test_coordinator = coordinator
        self._c_live_test_principal = principal
        self._c_live_test_parent_key = idempotency_key
        self._c_live_test_plan_json = plan_json
        self._c_live_test_plan_digest = digest

    @staticmethod
    def _c_live_non_dispatchable(goal: str) -> EngagementResult:
        return EngagementResult(
            goal=goal,
            total_rounds=0,
            final_status="non_dispatchable",
            rounds=[],
            final_detection_score=0.0,
            modules_succeeded=[],
            modules_failed=[],
            knowledge_updates=0,
            elapsed_seconds=0.0,
        )

    async def _run_c_live_test_plan(self, campaign: Any, goal: str) -> EngagementResult:
        """Dispatch the already-frozen test plan through admission, in order."""
        from ares.core.engine import is_successful_module_outcome
        from ares.core.execution_admission import (
            DispatchDispositionV1,
            DispatchRequestV1,
            canonical_intent_digest,
        )

        started_at = time.monotonic()
        if (
            self._c_live_test_coordinator is None
            or self._c_live_test_principal is None
            or self._c_live_test_parent_key is None
            or self._c_live_test_plan_json is None
            or self._c_live_test_plan_digest is None
        ):
            return self._c_live_non_dispatchable(goal)

        # Decode and verify the *complete* plan before the first coordinator
        # call.  No provider, planner, module, notifier, or network helper runs
        # while this fan-out is being formed.
        try:
            children = json.loads(self._c_live_test_plan_json)
            if (
                type(children) is not list
                or canonical_intent_digest(children) != self._c_live_test_plan_digest
                or not children
            ):
                raise ValueError
        except (TypeError, ValueError, json.JSONDecodeError):
            return self._c_live_non_dispatchable(goal)

        round_outcomes: list[ModuleOutcome] = []
        modules_executed: list[str] = []
        succeeded: list[str] = []
        failed: list[str] = []
        final_status = "terminal"

        for child in children:
            module_id = child["module_id"]
            request = DispatchRequestV1(
                campaign_id=campaign.id,
                module_id=module_id,
                ingress_code="strategy",
                idempotency_key=self._c_live_test_parent_key,
                raw_parameters=child["params"],
                whole_intent_digest=self._c_live_test_plan_digest,
                occurrence=child["occurrence"],
                stage_ordinal=child["stage_ordinal"],
                decision_ordinal=child["decision_ordinal"],
                module_ordinal=child["module_ordinal"],
            )
            outcome = await self._c_live_test_coordinator.execute_module(
                self._c_live_test_principal,
                request,
                campaign,
            )
            modules_executed.append(module_id)
            if outcome.disposition is DispatchDispositionV1.REPLAYED:
                round_outcomes.append(
                    ModuleOutcome(
                        module_id=module_id,
                        success=False,
                        quality=0.0,
                        evidence="durable_terminal_replay",
                    )
                )
                continue
            if outcome.disposition is not DispatchDispositionV1.TERMINAL:
                final_status = outcome.disposition.value
                break

            result = outcome.module_result
            status = getattr(result, "outcome", None) or getattr(result, "status", "")
            success = is_successful_module_outcome(status)
            if success:
                succeeded.append(module_id)
            else:
                failed.append(module_id)
            round_outcomes.append(
                ModuleOutcome(
                    module_id=module_id,
                    success=success,
                    quality=1.0 if success else 0.0,
                    evidence=str(
                        getattr(result, "outcome_message", "")
                        or getattr(result, "error", "")
                        or status
                    )[:200],
                    findings_count=len(getattr(result, "findings", ()) or ()),
                )
            )

        elapsed = max(0.0, time.monotonic() - started_at)
        round_result = RoundResult(
            round_num=1,
            plan_confidence=1.0,
            detection_score=0.0,
            modules_executed=modules_executed,
            outcomes=round_outcomes,
            stopped_reason="" if final_status == "terminal" else final_status,
        )
        return EngagementResult(
            goal=goal,
            total_rounds=1,
            final_status=final_status,
            rounds=[round_result],
            final_detection_score=0.0,
            modules_succeeded=succeeded,
            modules_failed=failed,
            knowledge_updates=0,
            elapsed_seconds=elapsed,
        )

    async def run_autonomous_engagement(
        self,
        campaign:                   "Any",
        goal:                       str   = "domain_admin",
        max_rounds:                 int   = 10,
        max_detection_probability:  float = 0.60,
        confidence_threshold:       float = 0.50,
        llm_backend:                str   = "claude",
        secondary_backend:          str   = "",   # for consensus mode
        adversarial_sim:            bool  = False,
        actor_role:                 str   = "operator",
        authorizations:             list  | None = None,   # modules needing auth
        forbidden_modules:          set   | None = None,
        allow_persistence:          bool  = False,
    ) -> EngagementResult:
        """
        Run an autonomous multi-round red team engagement.

        Args:
            campaign:                   Active ARES campaign object
            goal:                       Target objective (domain_admin, etc.)
            max_rounds:                 Hard limit on engagement rounds
            max_detection_probability:  Stop if coverage predictor exceeds this
            confidence_threshold:       Stop if AI plan confidence below this
            llm_backend:                Primary LLM backend (claude/openai/local)
            secondary_backend:          Secondary for consensus mode (optional)
            adversarial_sim:            Run blue-team simulation after each plan
            actor_role:                 RBAC role for module execution
        """
        _ = (
            max_rounds,
            max_detection_probability,
            confidence_threshold,
            llm_backend,
            secondary_backend,
            adversarial_sim,
            actor_role,
            authorizations,
            forbidden_modules,
            allow_persistence,
        )
        # C-LIVE-v1 is safety wiring, not activation.  With all production
        # descriptors disabled/ineligible, the public constructor always
        # returns here before legacy Strategy helpers, planning, notifications,
        # campaign runtime setup, or target-module execution.
        return await self._run_c_live_test_plan(campaign, goal)

        # The pre-C-LIVE autonomous implementation remains below only as
        # historical context during this bounded batch; it is unreachable from
        # the public entrypoint and every former effectful helper is fail-closed.
        start_time   = time.monotonic()
        rounds:       list[RoundResult] = []
        succeeded:    list[str] = []
        failed:       list[str] = []
        final_status  = "max_rounds"

        audit("strategy_engine_start", actor="operator",
              detail=f"goal={goal} max_rounds={max_rounds} max_detect={max_detection_probability}")
        logger.info("strategy_engine_start", goal=goal, max_rounds=max_rounds,
                    llm_backend=llm_backend, consensus=bool(secondary_backend))

        # Strategy executions must share the same campaign vault, session, and
        # artifact store as API and plan executions.  The engine owns the
        # rehydration boundary, including durable credentials and hosts.
        if self._engine and hasattr(self._engine, "ensure_campaign_runtime"):
            await self._engine.ensure_campaign_runtime(campaign)

        for round_num in range(1, max_rounds + 1):
            logger.info("strategy_round_start", round=round_num, goal=goal)

            # ── Step 1: Detection risk check ─────────────────────────────────
            coverage = await self._run_coverage_predictor(campaign)
            det_score = coverage.get("detection_score", 0.0)

            if det_score > max_detection_probability:
                wait_hrs = coverage.get("wait_recommendation", {}).get("hours", 0)
                msg = (
                    f"Round {round_num}: Detection score {det_score:.0%} exceeds "
                    f"threshold {max_detection_probability:.0%}. "
                    f"Recommended pause: {wait_hrs}h"
                )
                logger.warning("strategy_detection_threshold", score=det_score, round=round_num)
                await self._notifier.send("detection_threshold_exceeded", {
                    "round": round_num, "score": det_score,
                    "threshold": max_detection_probability, "wait_hours": wait_hrs,
                    "message": msg,
                })
                rounds.append(RoundResult(
                    round_num=round_num, plan_confidence=0.0,
                    detection_score=det_score, modules_executed=[],
                    outcomes=[], stopped_reason=msg,
                ))
                final_status = "detection_threshold"
                break

            # ── Step 2: EDR context ───────────────────────────────────────────
            edr_context = await self._get_edr_context(campaign)

            # Build reusable extra_context dict for planner calls this round
            round_extra_context = {
                "detection_probability":    det_score,
                "edr_bypass_available":     edr_context.get("viable_techniques", [])[:5],
                "historical_success_rates": self._kb.get_success_rates(),
                "rounds_completed":         round_num - 1,
                "target_states":            self._target_state.to_llm_context(),
                "effective_vs_edr":         self._kb.get_effective_techniques(
                    edr_context.get("edr_vendor", "unknown")
                ),
            }

            # ── Step 3: AI re-plan with full accumulated context ──────────────
            plan_result = await self._run_ai_planner(
                campaign=campaign,
                goal=goal,
                llm_backend=llm_backend,
                secondary_backend=secondary_backend,
                adversarial_sim=adversarial_sim,
                extra_context=round_extra_context,
            )

            plan_confidence = plan_result.get("confidence_score", 0.0)
            exec_plan       = plan_result.get("execution_plan", [])

            if plan_confidence < confidence_threshold:
                msg = (
                    f"Round {round_num}: AI plan confidence {plan_confidence:.0%} "
                    f"below threshold {confidence_threshold:.0%}. "
                    f"Reasoning: {plan_result.get('ai_reasoning', '')[:150]}"
                )
                logger.warning("strategy_low_confidence", confidence=plan_confidence, round=round_num)
                await self._notifier.send("low_confidence_plan", {
                    "round": round_num, "confidence": plan_confidence, "message": msg,
                    "warnings": plan_result.get("warnings", []),
                })
                rounds.append(RoundResult(
                    round_num=round_num, plan_confidence=plan_confidence,
                    detection_score=det_score, modules_executed=[],
                    outcomes=[], stopped_reason=msg,
                ))
                final_status = "low_confidence"
                break

            # ── ConstitutionEnforcer - Python-layer safety, cannot be bypassed ─
            # Build AIPlan object from raw planner output for enforcer
            from ares.modules.ai.autonomous_planner import AIPlan
            ai_plan = AIPlan(
                reasoning=plan_result.get("ai_reasoning", ""),
                stages=exec_plan if isinstance(exec_plan, list) else [],
                confidence=plan_confidence,
                warnings=plan_result.get("warnings", []),
            )
            enforcer = ConstitutionEnforcer(
                authorizations=authorizations,
                forbidden_modules=forbidden_modules,
                allow_persistence=allow_persistence,
            )
            ai_plan, violations = enforcer.enforce(ai_plan, campaign)
            if violations:
                await self._notifier.send("constitution_violations", {
                    "round":      round_num,
                    "violations": [
                        {"module": v.module_id, "reason": v.reason, "severity": v.severity}
                        for v in violations
                    ],
                    "note": "These modules were removed by ConstitutionEnforcer before execution",
                })
            if not ai_plan.stages:
                logger.warning("constitution_all_stages_emptied", round=round_num)
                rounds.append(RoundResult(
                    round_num=round_num, plan_confidence=plan_confidence,
                    detection_score=det_score, modules_executed=[],
                    outcomes=[], stopped_reason="ConstitutionEnforcer removed all modules",
                ))
                final_status = "constitution_blocked"
                break
            # Re-extract exec_plan after enforcer may have modified it
            exec_plan = [
                {"name": s.get("name",""), "modules": s.get("modules",[]),
                 "params": s.get("params",{})}
                for s in ai_plan.stages
            ]

            # Notify operator - plan ready for review
            await self._notifier.send("plan_ready", {
                "round":          round_num,
                "confidence":     plan_confidence,
                "stages":         len(exec_plan),
                "modules":        [m for s in exec_plan for m in s.get("modules", [])],
                "warnings":       plan_result.get("warnings", []),
                "adversarial_sim": plan_result.get("adversarial_sim", {}),
            })

            # ── Step 3.5: Pre-execution detection risk prediction ────────────
            try:
                from ares.core.noise import NoiseController
                from ares.modules.opsec.coverage_predictor import CoveragePredictorModule
                predictor_mod = CoveragePredictorModule(
                    settings=self._settings, campaign=campaign,
                    noise=NoiseController(campaign),
                )
                planned_mids = [m for s in exec_plan for m in s.get("modules", [])]
                projection = predictor_mod.predict_planned_actions(
                    planned_modules=planned_mids,
                    current_score=det_score,
                    campaign=campaign,
                )
                logger.info("pre_exec_projection",
                            round=round_num,
                            projected=projection["projected_score"],
                            safe=projection["safe_to_execute"])
                if not projection["safe_to_execute"]:
                    await self._notifier.send("projected_detection_too_high", {
                        "round": round_num, "projection": projection,
                    })
                    # Request stealth replan instead of stopping immediately
                    logger.warning("pre_exec_replan_requested",
                                   round=round_num,
                                   projected=projection["projected_score"])
                    replan_result = await self._run_ai_planner(
                        campaign=campaign, goal=goal,
                        llm_backend=llm_backend,
                        secondary_backend=secondary_backend,
                        adversarial_sim=False,
                        extra_context={
                            **round_extra_context,
                            "rejected_plan_reason": (
                                f"Plan rejected: projected detection "
                                f"{projection['projected_score']:.0%} - too high. "
                                "Use STEALTH techniques only. "
                                "Avoid HIGH_NOISE modules. "
                                f"Flagged modules: "
                                f"{[b['module'] for b in projection['module_breakdown'][:3]]}"
                            ),
                        },
                    )
                    replan_conf  = replan_result.get("confidence_score", 0.0)
                    replan_plan  = replan_result.get("execution_plan", [])
                    if replan_conf >= confidence_threshold and replan_plan:
                        # Accept revised plan - re-enforce and re-check projection
                        ai_plan.stages = replan_plan
                        ai_plan, _ = enforcer.enforce(ai_plan, campaign)
                        exec_plan = [
                            {"name": s.get("name",""), "modules": s.get("modules",[]),
                             "params": s.get("params",{})}
                            for s in ai_plan.stages
                        ]
                        logger.info("pre_exec_replan_accepted",
                                    round=round_num, confidence=replan_conf)
                    else:
                        # Replan also failed - stop this round
                        logger.warning("pre_exec_replan_failed",
                                       round=round_num, confidence=replan_conf)
                        rounds.append(RoundResult(
                            round_num=round_num, plan_confidence=plan_confidence,
                            detection_score=det_score, modules_executed=[],
                            outcomes=[],
                            stopped_reason=f"Pre-exec blocked and replan failed "
                                           f"(projected: {projection['projected_score']:.0%})",
                        ))
                        final_status = "pre_exec_blocked"
                        break
            except Exception as pe_exc:
                logger.debug("pre_exec_prediction_failed", error=str(pe_exc)[:80])

            # ── Step 4: Execute plan stages ───────────────────────────────────
            round_outcomes: list[ModuleOutcome] = []
            all_modules_this_round: list[str]   = []
            bypass_tech = edr_context.get("recommended_approach", {}) or {}
            bypass_name = bypass_tech.get("id", "") if isinstance(bypass_tech, dict) else ""
            edr_vendor  = edr_context.get("edr_vendor", "unknown")

            for stage in exec_plan:
                stage_modules = stage.get("modules", [])
                stage_params  = stage.get("params", {})

                logger.info("strategy_stage_execute",
                            round=round_num, stage=stage.get("name"),
                            modules=stage_modules)

                # Run modules in parallel within stage
                stage_tasks = [
                    self._run_single_module(
                        module_id=mid,
                        campaign=campaign,
                        params={**self._build_base_params(campaign), **stage_params.get(mid, {})},  # LLM params override base
                        actor_role=actor_role,
                    )
                    for mid in stage_modules
                ]
                stage_results = await asyncio.gather(*stage_tasks, return_exceptions=True)

                for mid, result in zip(stage_modules, stage_results):
                    all_modules_this_round.append(mid)
                    if isinstance(result, Exception):
                        success = False
                        findings_count = 0
                        quality = 0.0
                        evidence = f"module_error: {str(result)[:160]}"
                        logger.warning("strategy_module_error", module=mid,
                                       error=str(result)[:100])
                    else:
                        from ares.core.engine import is_successful_module_outcome

                        status = getattr(result, "status", "")
                        outcome_value = getattr(result, "outcome", "") or status
                        success = is_successful_module_outcome(outcome_value)
                        findings_count = len(getattr(result, "findings", []))
                        validations = list(getattr(result, "validation_results", []) or [])
                        passed_confidence = [
                            float(getattr(validation, "confidence", 0.0))
                            for validation in validations
                            if bool(getattr(validation, "passed", False))
                        ]
                        if passed_confidence:
                            quality = sum(passed_confidence) / len(passed_confidence)
                        elif findings_count:
                            # EngineModuleResult.findings contains only confirmed findings.
                            quality = 0.6
                        else:
                            # ModuleStatus.DONE is a successful, evidence-light result.
                            quality = 0.5 if success else 0.0
                        evidence = str(
                            getattr(result, "outcome_message", "")
                            or getattr(result, "error", "")
                            or getattr(result, "outcome", "")
                            or ""
                        )[:200]
                    outcome = ModuleOutcome(
                        module_id=mid, success=success and quality >= 0.5,
                        quality=quality, evidence=evidence,
                        edr_vendor=edr_vendor, bypass_used=bypass_name,
                        findings_count=findings_count,
                    )
                    round_outcomes.append(outcome)
                    self._kb.record_outcome(
                        mid, success=outcome.success, quality=quality,
                        evidence=evidence, edr_vendor=edr_vendor, bypass_used=bypass_name
                    )
                    # Persist bypass outcome to DB for cross-session learning
                    if bypass_name and self._engine:
                        _db_ref = getattr(self._engine, "db", None)
                        if _db_ref and hasattr(_db_ref, "save_bypass_outcome"):
                            try:
                                await _db_ref.save_bypass_outcome(
                                    technique_id=bypass_name,
                                    edr_vendor=edr_vendor,
                                    edr_version="",
                                    success=outcome.success,
                                    campaign_id=getattr(campaign, "id", ""),
                                    notes=evidence[:200] if evidence else "",
                                )
                            except Exception as exc:
                                logger.debug("strategy_bypass_outcome_persist_failed", error=str(exc)[:100])
                    # Update per-host state memory
                    # AD modules use "dc" key, Linux use "host", others use "target"
                    _mp = stage_params.get(mid, {}) if isinstance(stage_params, dict) else {}
                    target_hint = (
                        _mp.get("target") or _mp.get("dc") or _mp.get("host") or
                        stage_params.get("target") or stage_params.get("dc") or
                        stage_params.get("host", "")
                    )
                    if target_hint and not isinstance(result, Exception):
                        self._target_state.update_from_result(mid, target_hint, result)

                    if outcome.success:
                        succeeded.append(mid)
                    else:
                        failed.append(mid)

            # ── Step 4.5: Detection spike rollback ──────────────────────────────
            coverage_after = await self._run_coverage_predictor(campaign)
            det_after      = coverage_after.get("detection_score", 0.0)
            spike          = det_after - det_score

            if spike > 0.15:  # >15% rise in one round = danger
                msg = (
                    f"DETECTION SPIKE: +{spike:.0%} in round {round_num}. "
                    f"Score: {det_score:.0%} → {det_after:.0%}. "
                    "Engagement paused. Manual operator review required."
                )
                logger.critical("detection_spike",
                                spike=spike, round=round_num,
                                before=det_score, after=det_after)
                await self._notifier.send("detection_spike", {
                    "round":        round_num,
                    "spike":        round(spike, 3),
                    "score_before": det_score,
                    "score_after":  det_after,
                    "message":      msg,
                    "safe_actions": [
                        "Do not run any modules for 24+ hours",
                        "Review artifacts from this round for IOCs",
                        "Consider cleaning up persistence if any was established",
                        "Operator manual review required before continuing",
                    ],
                })
                rounds.append(RoundResult(
                    round_num=round_num, plan_confidence=plan_confidence,
                    detection_score=det_after, modules_executed=all_modules_this_round,
                    outcomes=round_outcomes, stopped_reason=msg,
                ))
                final_status = "detection_spike"
                break

            # ── Step 5: Check goal achieved ───────────────────────────────────
            goal_achieved = self._check_goal_achieved(campaign, goal)

            round_result = RoundResult(
                round_num=round_num, plan_confidence=plan_confidence,
                detection_score=det_score, modules_executed=all_modules_this_round,
                outcomes=round_outcomes, goal_achieved=goal_achieved,
                stopped_reason="" if not goal_achieved else "goal_achieved",
            )
            rounds.append(round_result)

            logger.info("strategy_round_complete",
                        round=round_num, modules=len(all_modules_this_round),
                        successes=sum(1 for o in round_outcomes if o.success),
                        goal_achieved=goal_achieved)

            await self._notifier.send("round_complete", {
                "round":          round_num,
                "modules_run":    all_modules_this_round,
                "successes":      sum(1 for o in round_outcomes if o.success),
                "detection_score": det_score,
                "goal_achieved":  goal_achieved,
            })

            if goal_achieved:
                final_status = "goal_achieved"
                logger.info("strategy_goal_achieved", goal=goal, rounds=round_num)
                await self._notifier.send("goal_achieved", {
                    "goal": goal, "rounds_needed": round_num,
                    "total_findings": sum(o.findings_count for r in rounds for o in r.outcomes),
                })
                break

        elapsed = time.monotonic() - start_time
        audit("strategy_engine_complete", actor="operator",
              detail=f"status={final_status} rounds={len(rounds)} elapsed={elapsed:.1f}s")

        return EngagementResult(
            goal=goal,
            total_rounds=len(rounds),
            final_status=final_status,
            rounds=rounds,
            final_detection_score=rounds[-1].detection_score if rounds else 0.0,
            modules_succeeded=list(dict.fromkeys(succeeded)),
            modules_failed=list(dict.fromkeys(failed)),
            knowledge_updates=sum(
                len(r.outcomes) for r in rounds
            ),
            elapsed_seconds=elapsed,
        )

    async def _run_coverage_predictor(self, campaign: "Any") -> dict:
        """Disabled C-LIVE-v1 helper; it never constructs or runs a module."""
        del campaign
        return {
            "detection_score": 0.0,
            "wait_recommendation": {
                "hours": 0,
                "reason": "c-live-strategy-non-dispatchable",
            },
        }

    async def _get_edr_context(self, campaign: "Any") -> dict:
        """Disabled C-LIVE-v1 helper; it performs no artifact or module work."""
        del campaign
        return {
            "edr_vendor": "unknown",
            "viable_techniques": [],
            "recommended_approach": None,
        }

    async def _run_ai_planner(
        self, campaign: "Any", goal: str,
        llm_backend: str, secondary_backend: str,
        adversarial_sim: bool, extra_context: dict,
    ) -> dict:
        """Disabled C-LIVE-v1 helper; no LLM or planning network is used."""
        del campaign, goal, llm_backend, secondary_backend, adversarial_sim, extra_context
        return {
            "confidence_score": 0.0,
            "execution_plan": [],
            "warnings": ["c-live-strategy-non-dispatchable"],
        }

    async def _run_single_module(
        self, module_id: str, campaign: "Any",
        params: dict, actor_role: str,
    ) -> "Any":
        """Reject the former direct-engine Strategy bypass."""
        del module_id, campaign, params, actor_role
        raise PermissionError("C-LIVE Strategy dispatch requires coordinator admission")

    def _build_base_params(self, campaign: "Any") -> dict:
        """
        Return base params that all modules inherit - intentionally minimal.
        DO NOT set "target" here: CIDR network address (e.g. 10.0.0.0) is not
        a valid scan target. LLM stage_params must specify the actual host.
        If LLM omits target, the module will fail with a validation error
        rather than silently scan the wrong IP.
        """
        params: dict = {}
        # Only inject non-target params that are safe to default
        noise = getattr(campaign, "noise_profile", None)
        if noise:
            params["noise_profile"] = str(noise)
        return params


    async def generate_engagement_report(
        self,
        result:      "EngagementResult",
        campaign:    Any,
        llm_backend: str = "claude",
    ) -> str:
        """
        Generate executive red team report from EngagementResult via LLM.
        Returns markdown ready to paste into engagement report.

        Includes:
          1. Executive Summary (3 sentences, business language)
          2. Attack Chain Timeline (bullet per round)
          3. Key Findings with Business Impact
          4. Priority Recommendations (Critical/High/Medium)
          5. Detection Risk Score
        """
        from ares.modules.ai.autonomous_planner import ClaudeBackend, OpenAIBackend

        summary = {
            "goal":              result.goal,
            "final_status":      result.final_status,
            "total_rounds":      result.total_rounds,
            "elapsed_hours":     round(result.elapsed_seconds / 3600, 1),
            "modules_succeeded": result.modules_succeeded,
            "modules_failed":    result.modules_failed,
            "final_detection":   f"{result.final_detection_score:.0%}",
            "total_findings":    sum(
                o.findings_count for r in result.rounds for o in r.outcomes
            ),
            "knowledge_updates": result.knowledge_updates,
            "rounds_detail": [
                {
                    "round":       r.round_num,
                    "confidence":  r.plan_confidence,
                    "detection":   r.detection_score,
                    "modules":     r.modules_executed,
                    "successes":   sum(1 for o in r.outcomes if o.success),
                    "stopped":     r.stopped_reason or "completed",
                    "outcomes":    [
                        {"module": o.module_id, "quality": getattr(o, "quality", 0),
                         "evidence": getattr(o, "evidence", "")}
                        for o in r.outcomes
                    ],
                }
                for r in result.rounds
            ],
        }

        REPORT_SYSTEM = (
            "You are a professional red team report writer. "
            "Write clear, concise, business-focused reports. "
            "Use markdown formatting. "
            "Be specific about what was found and what business risk it represents. "
            "Avoid technical jargon in the Executive Summary."
        )
        REPORT_USER = (
            "Generate an executive red team engagement report from this data.\n\n"
            "Include these sections:\n"
            "## Executive Summary\n"
            "3 sentences max. Business language. What was achieved, what was the risk level.\n\n"
            "## Attack Chain Timeline\n"
            "Bullet per round showing what happened.\n\n"
            "## Key Findings\n"
            "Top 5 findings with business impact per finding.\n\n"
            "## Priority Recommendations\n"
            "Critical, High, Medium buckets.\n\n"
            "## Detection Risk\n"
            "Final detection probability and what it means.\n\n"
            f"Data:\n{json.dumps(summary, indent=2)}"
        )

        try:
            backend_map = {
                "claude": lambda: ClaudeBackend(),
                "openai": lambda: OpenAIBackend(),
            }
            backend = backend_map.get(llm_backend, backend_map["claude"])()
            report_result = await backend.generate_plan(REPORT_SYSTEM, REPORT_USER)
            return report_result.get("content", "Report generation failed.")
        except Exception as exc:
            logger.warning("report_generation_failed", error=str(exc)[:100])
            # Fallback: generate simple text report
            lines = [
                "# ARES Red Team Engagement Report",
                "",
                f"**Goal:** {result.goal}",
                f"**Status:** {result.final_status}",
                f"**Rounds:** {result.total_rounds}",
                f"**Duration:** {result.elapsed_seconds/3600:.1f}h",
                f"**Detection Score:** {result.final_detection_score:.0%}",
                "",
                "## Modules Succeeded",
                *[f"- {m}" for m in result.modules_succeeded],
                "",
                "## Modules Failed",
                *[f"- {m}" for m in result.modules_failed],
                "",
                f"*(LLM report failed: {str(exc)[:80]})*",
            ]
            return "\n".join(lines)

    def _check_goal_achieved(
        self,
        campaign: "Any",
        goal: str,
        confirmed_findings: list[Any] | None = None,
    ) -> bool:
        """
        Check if the engagement goal has been achieved via verified campaign artifacts.

        Gate 5 Enforcement:
        - Layer 1: Title matching ONLY against confirmed findings (passed Gate 3).
        - Layer 2: For privilege goals (domain_admin, credential_access, root_access, full_compromise),
          supporting credentials must actually exist in the Campaign Vault.
        """
        goal_indicators = {
            "domain_admin":     ["DCSync", "Domain Admin", "krbtgt", "ntlm_hash"],
            "cloud_admin":      ["Global Admin", "AWS Admin", "Storage Admin", "GCP Owner"],
            "data_exfil":       ["Sensitive File", "credential_list", "sensitive_data"],
            "persistence":      ["Scheduled Task Created", "WMI Subscription", "Registry Run"],
            "full_compromise":  ["DCSync", "Global Admin"],
        }
        indicators = goal_indicators.get(goal, [])
        if not indicators:
            return False

        # ── Layer 1: Filter strictly to confirmed findings ─────────────────
        if confirmed_findings is not None:
            active_findings = confirmed_findings
        else:
            all_findings = getattr(campaign, "findings", []) or []
            active_findings = []
            for f in all_findings:
                if isinstance(f, dict):
                    is_val = bool(f.get("validated", False))
                    is_fp = bool(f.get("false_positive", False))
                else:
                    val_attr = getattr(f, "validated", False)
                    fp_attr = getattr(f, "false_positive", False)
                    is_val = bool(val_attr)
                    is_fp = bool(fp_attr) if isinstance(fp_attr, bool) else False
                if is_val and not is_fp:
                    active_findings.append(f)

        title_match = False
        matching_title = ""
        for finding in active_findings:
            title = (getattr(finding, "title", "") or
                     (finding.get("title", "") if isinstance(finding, dict) else ""))
            if any(ind.lower() in title.lower() for ind in indicators):
                title_match = True
                matching_title = title
                break

        if not title_match:
            return False

        # ── Layer 2: Privilege goals require verified credentials in vault ─
        privilege_goals = {"domain_admin", "credential_access", "root_access", "full_compromise"}
        if goal in privilege_goals:
            vault = (
                getattr(campaign, "vault", None)
                or getattr(campaign, "_vault", None)
                or (
                    getattr(self._engine, "_runtime_states", None)
                    and getattr(self._engine._runtime_states.get(getattr(campaign, "id", "")), "vault", None)
                )
                or getattr(self, "_vault", None)
            )

            has_creds = self._verify_vault_evidence(vault, goal)
            if not has_creds:
                logger.info(
                    "goal_not_achieved_no_vault_evidence",
                    goal_type=goal,
                    title_matches=True,
                    matching_title=matching_title,
                    vault_has_creds=False,
                )
                return False

        return True

    def _verify_vault_evidence(self, vault: Any, goal: str) -> bool:
        """Verify that vault contains credentials supporting the goal."""
        if not vault:
            return False

        # Try domain_admins() method if present
        if goal in ("domain_admin", "full_compromise"):
            if hasattr(vault, "domain_admins") and callable(vault.domain_admins):
                da_creds = vault.domain_admins()
                if da_creds:
                    return True

        # Extract credentials collection from vault
        creds: list[Any] = []
        if hasattr(vault, "all") and callable(vault.all):
            creds = vault.all()
        elif hasattr(vault, "_store") and isinstance(vault._store, dict):
            creds = list(vault._store.values())
        elif hasattr(vault, "has_credentials") and callable(vault.has_credentials):
            return bool(vault.has_credentials(min_privilege=goal))
        elif isinstance(vault, dict):
            creds = vault.get("credentials") or list(vault.values())
        elif isinstance(vault, (list, tuple)):
            creds = list(vault)

        if not creds:
            return False

        # Check privilege level of credentials
        for c in creds:
            if isinstance(c, dict):
                priv = str(c.get("privilege", "")).lower()
                user = str(c.get("username", "")).lower()
                ctype = str(c.get("cred_type", "")).lower()
            else:
                p_attr = getattr(c, "privilege", "")
                priv = p_attr.value.lower() if hasattr(p_attr, "value") else str(p_attr or "").lower()
                user = str(getattr(c, "username", "") or "").lower()
                ct_attr = getattr(c, "cred_type", "")
                ctype = ct_attr.value.lower() if hasattr(ct_attr, "value") else str(ct_attr or "").lower()

            if goal in ("domain_admin", "full_compromise"):
                if priv in ("domain_admin", "enterprise_admin") or "krbtgt" in user:
                    return True
                # Fallback: any valid non-unknown credential if privilege not set
                if ctype and ctype not in ("unknown", ""):
                    return True
            else:
                if (ctype and ctype not in ("unknown", "")) or (priv and priv not in ("unknown", "")):
                    return True

        return False