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.

33.7 KB
Raw Blame
"""
ARES Base Module
All modules inherit from BaseModule.

Metadata system enables:
  - auto dependency checking before execution
  - attack chain auto-wiring (outputs → inputs)
  - opsec level enforcement (stealth mode skips HIGH_NOISE modules)
  - engine capability querying (list all modules that output 'spn_list')

Required class attributes:
    MODULE_ID          str  - unique dotted ID, e.g. "ad.kerberoast"
    MODULE_NAME        str  - human name
    MODULE_CATEGORY    str  - "ad" | "linux" | "cloud" | "reporting"
    MODULE_DESCRIPTION str  - one-liner for CLI list

Optional class attributes (defaults shown):
    OPSEC_LEVEL        OpsecLevel  - SILENT | LOW | MEDIUM | HIGH_NOISE
    REQUIRES           list[str]   - capabilities/outputs this module needs as input
    OUTPUTS            list[str]   - what this module produces (feeds downstream modules)
    MITRE_TECHNIQUES   list[str]   - ATT&CK technique IDs
    MODULE_AUTHOR      str
    MIN_NOISE_PROFILE  str | None  - block execution below this profile
"""
from __future__ import annotations

import abc
import os
import uuid
from dataclasses import dataclass, field
from enum import Enum
from typing import TYPE_CHECKING, Any, Generic, TypeVar

P = TypeVar("P", bound=Any)
R = TypeVar("R", bound=Any)

from ares.core.campaign import Campaign, Finding, Severity
from ares.core.config import AresSettings
from ares.core.logger import bind_context, clear_context, get_logger
from ares.core.noise import NoiseController
from ares.core.opsec.opsec import OpSecProfile

if TYPE_CHECKING:
    pass

logger = get_logger("ares.module")


MODULE_OUTCOME_SEMANTICS = [
    "confirmed_findings",
    "completed_no_findings",
    "operator_error",
    "dependency_error",
    "network_error",
    "unsupported",
    "module_error",
]
MODULE_SAFE_ERROR_CATEGORIES = [
    "operator_error",
    "dependency_error",
    "network_error",
    "unsupported",
    "module_error",
]


def normalize_module_metadata(
    cls: Any,
    *,
    param_schema: dict[str, Any] | None = None,
    base: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Return the stable metadata contract exposed by the registry and API."""
    metadata = dict(base or {})

    if not param_schema:
        params_model = getattr(cls, "PARAMS_MODEL", None)
        if params_model is not None and hasattr(params_model, "schema_for_api"):
            param_schema = params_model.schema_for_api()
        else:
            try:
                from ares.modules.params import MODULE_PARAMS

                model = MODULE_PARAMS.get(str(getattr(cls, "MODULE_ID", "")))
                param_schema = model.schema_for_api() if model else {}
            except (ImportError, AttributeError):
                param_schema = {}

    schema = param_schema or {}
    required_params = [
        name for name, field in schema.items() if bool(field.get("required"))
    ]
    optional_params = [
        name for name, field in schema.items() if not bool(field.get("required"))
    ]
    defaults = {
        name: field["default"]
        for name, field in schema.items()
        if "default" in field and field.get("default") is not None
    }

    def _list_attr(name: str, default: list[str]) -> list[str]:
        value = getattr(cls, name, default)
        if isinstance(value, str):
            return [value]
        return list(value or [])

    for key, attr, fallback in (
        ("id", "MODULE_ID", ""),
        ("name", "MODULE_NAME", ""),
        ("category", "MODULE_CATEGORY", ""),
        ("description", "MODULE_DESCRIPTION", ""),
    ):
        if not metadata.get(key):
            metadata[key] = getattr(cls, attr, fallback)

    metadata.setdefault("required_params", required_params)
    metadata.setdefault("optional_params", optional_params)
    metadata.setdefault("defaults", defaults)
    metadata.setdefault("capability_flags", _list_attr("CAPABILITIES", []))
    metadata.setdefault(
        "dry_run_supported", bool(getattr(cls, "DRY_RUN_SUPPORTED", True))
    )
    metadata.setdefault(
        "supported_modes", _list_attr("SUPPORTED_MODES", ["standard"])
    )
    metadata.setdefault(
        "dependency_notes", _list_attr("DEPENDENCY_NOTES", [])
    )
    metadata.setdefault("outcome_semantics", list(MODULE_OUTCOME_SEMANTICS))
    metadata.setdefault(
        "safe_error_categories", list(MODULE_SAFE_ERROR_CATEGORIES)
    )
    metadata.setdefault("enabled", bool(getattr(cls, "ENABLED", True)))
    metadata["param_schema"] = schema
    return metadata


# ── OpSec level enum ──────────────────────────────────────────────────────────

class OpsecLevel(str, Enum):
    SILENT     = "silent"      # passive/local only, zero network traffic
    LOCAL      = "local"       # alias for SILENT - cracking, local-only ops
    LOW        = "low"         # read-only LDAP, basic API calls
    MEDIUM     = "medium"      # active queries, Kerberos TGS
    HIGH_NOISE = "high_noise"  # DCSync, brute force - blocked in stealth


# ── Feasibility Report ────────────────────────────────────────────────────────

@dataclass
class FeasibilityReport:
    """
    Structured pre-flight feasibility evaluation report.
    Assesses target defense posture, likelihood of success, OPSEC risk,
    and recommends alternative modules if unfeasible.
    """
    feasible: bool = True
    score: float = 1.0  # 0.0 (impossible/blocked) to 1.0 (optimal)
    risk_level: str = "low"  # silent, low, medium, high_noise, critical_alarm
    blockers: list[str] = field(default_factory=list)
    recommended_alternatives: list[str] = field(default_factory=list)
    opsec_tuning: dict[str, Any] = field(default_factory=dict)
    details: dict[str, Any] = field(default_factory=dict)

    def to_dict(self) -> dict[str, Any]:
        return {
            "feasible": self.feasible,
            "score": round(self.score, 3),
            "risk_level": self.risk_level,
            "blockers": list(self.blockers),
            "recommended_alternatives": list(self.recommended_alternatives),
            "opsec_tuning": dict(self.opsec_tuning),
            "details": dict(self.details),
        }


# ── BaseModule ────────────────────────────────────────────────────────────────

class BaseModule(abc.ABC, Generic[P, R]):
    """
    Abstract base for all ARES modules.

    Subclass and implement:
        async def run(self, **kwargs) -> tuple[list[Finding], dict[str, Any]]:
            ...

    Formal SDK contract (v0.9.0+) - see validate(), before_request(), finding().
    """

    PARAMS_MODEL: Any = None

    async def assess_feasibility(self, ctx: "Any") -> FeasibilityReport:
        """
        Evaluate whether this module is feasible against target defenses
        prior to execution. Does not make aggressive network calls.

        Default implementation:
            - Inspects target host defense profile in ctx.session if available
            - Evaluates OPSEC level against campaign noise profile
            - Subclasses override to provide defense-specific logic (e.g. EDR, Credential Guard)
        """
        risk = getattr(self.OPSEC_LEVEL, "value", str(self.OPSEC_LEVEL or "low"))
        noise_profile = getattr(ctx, "opsec_profile", "normal")

        if noise_profile == "stealth" and risk == "high_noise":
            return FeasibilityReport(
                feasible=False,
                score=0.2,
                risk_level="high_noise",
                blockers=["Module OPSEC level is high_noise under a stealth campaign profile"],
                recommended_alternatives=[],
                opsec_tuning={"suggested_profile": "normal"},
            )

        return FeasibilityReport(
            feasible=True,
            score=1.0,
            risk_level=risk,
            blockers=[],
            recommended_alternatives=[],
            opsec_tuning={},
            details={},
        )

    async def validate(self, ctx: "Any") -> None:
        """
        Validate the execution context BEFORE running the module.
        Called automatically by the engine - do not call manually.
        Raise ModuleValidationError if context is insufficient.

        Default: checks target is set and all REQUIRES entries are available.
        Override to add module-specific validation (format checks, etc.).
        Do NOT make network calls here - validate() must complete in < 10s.

        Example override:
            async def validate(self, ctx):
                await super().validate(ctx)            # keep default checks
                if not ctx.params.get("dc"):
                    raise ModuleValidationError(
                        f"{self.MODULE_ID} requires 'dc' (Domain Controller IP)",
                        module_id=self.MODULE_ID, field="dc",
                    )
        """
        from ares.core.context import ExecutionContext
        from ares.core.errors import ModuleValidationError

        if isinstance(ctx, dict):
            req_params = getattr(self.__class__, "REQUIRED_PARAMS", []) or getattr(self, "REQUIRED_PARAMS", [])
            for param in req_params:
                if param not in ctx or ctx[param] is None:
                    raise ModuleValidationError(
                        f"{self.MODULE_ID} requires parameter '{param}'",
                        module_id=self.MODULE_ID,
                        field=param,
                    )
            return

        if not isinstance(ctx, ExecutionContext):
            return  # legacy context - skip validation

        req_params = getattr(self.__class__, "REQUIRED_PARAMS", []) or getattr(self, "REQUIRED_PARAMS", [])
        if req_params:
            params_dict = (
                ctx.params.model_dump()
                if hasattr(getattr(ctx, "params", None), "model_dump")
                else (getattr(ctx, "params", {}) or {})
            )
            for param in req_params:
                if param not in params_dict or params_dict[param] is None:
                    raise ModuleValidationError(
                        f"{self.MODULE_ID} requires parameter '{param}'",
                        module_id=self.MODULE_ID,
                        field=param,
                    )

        if getattr(self, "PARAMS_MODEL", None) is not None:
            from ares.sdk.params import validate_params

            ctx.params = validate_params(self.PARAMS_MODEL, ctx.params, module_id=self.MODULE_ID)

        # Categories that use API credentials instead of a target IP - skip target check
        _NO_TARGET_CATEGORIES = {"cloud", "reporting", "recon"}
        if getattr(self.__class__, "MODULE_CATEGORY", "") in _NO_TARGET_CATEGORIES:
            return

        # Check target is set
        if not ctx.target:
            raise ModuleValidationError(
                f"Module {self.MODULE_ID!r} requires 'target' - "
                "set via params['target'], params['dc'], or params['host']",
                module_id=self.MODULE_ID,
                field="target",
            )

        # Check REQUIRES list - each item must be present in params or context
        requires = getattr(self.__class__, "REQUIRES", [])
        if requires:
            raw_params = ctx.params.model_dump() if hasattr(ctx.params, "model_dump") else (ctx.params or {})
            available: set[str] = set(raw_params.keys())
            if ctx.target:                 available.add("target")
            if ctx.domain:                 available.add("domain")
            if getattr(ctx, "vault", None): available.add("vault")
            params = raw_params

            def _present(*names: str) -> bool:
                return any(params.get(name) not in (None, "", []) for name in names)

            has_username = _present("username", "ssh_user", "sql_user")
            has_secret = _present(
                "password", "secret", "nt_hash", "lm_hash",
                "krbtgt_hash", "key_path", "ssh_key", "ssh_pass",
                "ticket", "ccache_path",
            ) or bool(os.environ.get("KRB5CCNAME"))
            has_domain = bool(ctx.domain) or _present("domain")
            if has_username and has_secret:
                available.add("credentials")
                if has_domain:
                    available.add("domain_creds")
                    # Privilege level cannot be proven before the remote auth
                    # attempt; explicit domain credentials satisfy the input
                    # contract, while the module/runtime enforces real access.
                    available.add("domain_admin_creds")
            # credentials/domain_creds: available if vault has entries
            vault = getattr(ctx, "vault", None)
            if vault and hasattr(vault, "_store") and vault._store:
                available.add("credentials")
                available.add("domain_creds")

            # Only check "capability" requirements (lowercase, no spaces)
            # Skip output-type requirements like "spn_list" or "kerberos_hashes"
            # which are satisfied by chaining, not direct params
            hard_requires = [
                r for r in requires
                if r in ("target", "domain", "vault", "credentials",
                         "domain_creds", "domain_admin_creds")
            ]
            missing = [r for r in hard_requires if r not in available]
            if missing:
                raise ModuleValidationError(
                    f"Module {self.MODULE_ID!r} missing required inputs: {missing}",
                    module_id=self.MODULE_ID,
                    field=str(missing),
                )

    async def execute(self, ctx: "Any") -> "ModuleResult":
        """
        Execute the module using the ExecutionContext (v0.9.0+ interface).

        Default implementation delegates to run() for backwards compatibility.
        New modules should override execute() directly.

        Returns:
            ModuleResult - structured result consumed by engine
        """
        raw_params = getattr(ctx, "params", {})
        if hasattr(raw_params, "model_dump"):
            kwargs = raw_params.model_dump()
        elif isinstance(raw_params, dict):
            kwargs = raw_params
        else:
            kwargs = {}

        try:
            findings, raw = await self.run(**kwargs)
            return ModuleResult(
                status    = "success" if findings or raw else "partial",
                findings  = findings,
                raw       = raw,
                module_id = self.MODULE_ID,
                execution_id = getattr(ctx, "execution_id", ""),
            )
        except NotImplementedError:
            findings = getattr(ctx, "findings", [])
            return ModuleResult(
                status    = "success" if findings else "partial",
                findings  = findings,
                raw       = {},
                module_id = self.MODULE_ID,
                execution_id = getattr(ctx, "execution_id", ""),
            )

    def report(self, result: "ModuleResult") -> dict:
        """
        Format this module's result for the report engine.
        Called by ReportGenerator when building the campaign report.

        Default: returns a structured summary dict.
        Override to add module-specific narrative or MITRE context.

        Returns:
            dict with keys: title, summary, findings, mitre, severity
        """
        from ares.technique.library import TechniqueMapper
        mapper   = TechniqueMapper()
        techs    = mapper.for_module(self.MODULE_ID)
        return {
            "module_id":   self.MODULE_ID,
            "module_name": self.MODULE_NAME,
            "title":       f"{self.MODULE_NAME} Results",
            "summary":     (
                f"{len(result.findings)} finding(s) from {self.MODULE_NAME}. "
                f"Status: {result.status}."
            ),
            "findings":    [f.to_dict() if hasattr(f, "to_dict") else {} for f in result.findings],
            "mitre":       [t.to_dict() for t in techs],
            "new_credentials": len(result.new_credentials),
            "discovered_hosts": result.discovered_hosts,
            "severity":    (
                max((f.severity.value for f in result.findings), default="info")
                if result.findings else "info"
            ),
        }


    # ── Required metadata ──────────────────────────────────────────────────
    MODULE_ID:          str = ""
    MODULE_NAME:        str = ""
    MODULE_CATEGORY:    str = ""
    MODULE_DESCRIPTION: str = ""

    # ── Optional metadata ──────────────────────────────────────────────────
    ENABLED:            bool        = True
    DISABLED_REASON:    str         = ""
    OPSEC_LEVEL:        OpsecLevel  = OpsecLevel.LOW
    REQUIRED_PARAMS:    list[str]   = []   # Declarative required param keys for Gate 1
    REQUIRES:           list[str]   = []   # e.g. ["domain_creds", "ldap_access"]
    OUTPUTS:            list[str]   = []   # e.g. ["spn_list", "user_list"]
    MITRE_TECHNIQUES:   list[str]   = []
    MODULE_AUTHOR:      str         = "ARES Team"
    MIN_NOISE_PROFILE:  str | None  = None  # None = runs in any profile
    CAPABILITIES:       list[str]   = []
    DRY_RUN_SUPPORTED:  bool        = True
    SUPPORTED_MODES:    list[str]   = ["standard"]
    DEPENDENCY_NOTES:   list[str]   = []

    # Per-module timeout override (seconds). None = use engine default (120s).
    # Set higher for slow ops: dcsync on WAN, lsass_dump transfer, crack jobs.
    # Set lower for fast ops: laps_enum, enum_users on fast LAN.
    MODULE_TIMEOUT_SECONDS: int | None = None

    def __init__(
        self,
        settings:  AresSettings,
        campaign:  Campaign,
        noise:     NoiseController,
        opsec:     OpSecProfile | None = None,
    ) -> None:
        self.settings = settings
        self.campaign = campaign
        self.noise    = noise
        self.opsec    = opsec or OpSecProfile.from_noise_profile(campaign.noise_profile)
        self._findings: list[Finding] = []

    # ── Abstract interface ─────────────────────────────────────────────────

    async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:
        """
        Execute the module.

        Returns:
            findings  - list of Finding objects (unvalidated)
            raw       - raw output dict (evidence, debug info)

        Subclasses should override this method. The default implementation
        raises NotImplementedError to catch unimplemented modules at runtime.
        """
        # Abstract method - enforced by abc.ABC inheritance on BaseModule.
        # Subclasses must override this.  Using raise rather than @abstractmethod
        # here preserves Mypy compatibility with the dynamic MODULE_ID attribute.
        raise NotImplementedError(  # abstract - subclasses must implement run()
            f"Module '{self.MODULE_ID}' must implement run()"
        )

    # ── Cloud Scope Guardrail ──────────────────────────────────────────────

    def validate_cloud_scope(self, identifier: str, provider: str) -> None:
        """
        Validate that the specified cloud identifier is authorized by the campaign's CloudScope.

        If cloud_scope is unconfigured (empty list for provider), validation passes
        (backward compatible).
        Raises ScopeViolationError if the identifier is unauthorized.
        """
        if not identifier:
            return

        from ares.core.errors import ScopeViolationError

        campaign = getattr(self, "campaign", None)
        if not campaign:
            return

        cloud_scope = getattr(campaign, "cloud_scope", None)
        if cloud_scope is None and hasattr(campaign, "scope"):
            cloud_scope = getattr(campaign.scope, "cloud_scope", None)

        if cloud_scope and not cloud_scope.is_authorized(identifier, provider):
            mapping = {
                "aws": "aws_account_ids",
                "azure": "azure_subscription_ids",
                "azure_ad": "azure_tenant_ids",
                "gcp": "gcp_project_ids",
            }
            authorized = getattr(cloud_scope, mapping.get(provider, f"{provider}_ids"), [])
            raise ScopeViolationError(
                f"Cloud {provider} identifier '{identifier}' is not "
                f"in authorized campaign scope. "
                f"Authorized: {authorized}",
                module_id=getattr(self, "MODULE_ID", ""),
                target=str(identifier),
            )

    # ── Pre-request hook ───────────────────────────────────────────────────

    async def before_request(self, target: str, action: str = "default") -> None:
        """
        Call before every network request.
        Enforces: scope check → rate limit → opsec sleep.
        """
        self.noise.scope_guard.assert_in_scope(target)
        await self.noise.rate_limiter.acquire(action)
        await self.noise.jitter.sleep()

    # ── Error classification helper ────────────────────────────────────────

    def _classify_error(self, exc: Exception, target: str = "",
                        username: str = "") -> Exception:
        """
        Map a raw exception to an ARES typed exception so AdaptiveOpsecEngine
        can choose the correct fallback strategy.

        Usage in modules:
            except Exception as exc:
                raise self._classify_error(exc, target=target, username=username) from exc

        Mapping:
            auth/credential errors  → AuthenticationFailed
            timeout/refused         → HostUnreachable or ConnectionTimeout
            access denied/privilege → InsufficientPrivilege
            rate limiting           → RateLimited
            everything else         → NetworkError (retryable)
        """
        from ares.core.errors import (
            AuthenticationFailed,
            ConnectionTimeout,
            HostUnreachable,
            InsufficientPrivilege,
            NetworkError,
            RateLimited,
        )
        msg = str(exc).lower()

        # Authentication / credential failures
        if any(s in msg for s in (
            "logon failure", "invalid credentials", "authentication failed",
            "wrong password", "bad credentials", "status_logon_failure",
            "login failed", "invalid username", "18456",
        )):
            return AuthenticationFailed(
                f"{self.MODULE_ID} auth failed on {target}: {exc}",
                username=username, module_id=self.MODULE_ID, target=target,
            )

        # Privilege / access denied
        if any(s in msg for s in (
            "access denied", "insufficient privilege", "status_access_denied",
            "permission denied", "forbidden", "not authorized",
        )):
            return InsufficientPrivilege(
                f"{self.MODULE_ID} insufficient privilege on {target}: {exc}",
                module_id=self.MODULE_ID,
            )

        # Timeout
        if any(s in msg for s in ("timed out", "timeout", "asyncio.timeouterror")):
            return ConnectionTimeout(
                f"{self.MODULE_ID} timed out on {target}: {exc}",
                timeout_s=0, target=target, module_id=self.MODULE_ID,
            )

        # Connection refused / unreachable
        if any(s in msg for s in (
            "connection refused", "no route to host",
            "network unreachable", "host unreachable", "errno 111",
        )):
            return HostUnreachable(
                f"{self.MODULE_ID} host unreachable: {target}: {exc}",
                target=target, module_id=self.MODULE_ID,
            )

        # Rate limiting
        if any(s in msg for s in ("rate limit", "too many requests", "429", "throttl")):
            return RateLimited(f"{self.MODULE_ID} rate limited: {exc}")

        # Fallback - general network error (engine will retry)
        return NetworkError(f"{self.MODULE_ID} network error on {target}: {exc}")

    # ── Finding helper ─────────────────────────────────────────────────────

    def finding(
        self,
        title:           str,
        description:     str,
        severity:        Severity,
        mitre_technique: str | None = None,
        mitre_tactic:    str | None = None,
        evidence:        dict[str, Any] | None = None,
        remediation:     str = "",
        host:            str | None = None,
        confidence:      float = 1.0,
    ) -> Finding:
        """Create, register, and return a finding."""
        f = Finding(
            id              = str(uuid.uuid4()),
            title           = title,
            description     = description,
            severity        = severity,
            mitre_technique = mitre_technique,
            mitre_tactic    = mitre_tactic,
            evidence        = evidence or {},
            remediation     = remediation,
            host            = host,
            confidence      = confidence,
            module_id       = self.MODULE_ID,
        )
        self._findings.append(f)
        logger.info(
            "finding_created",
            module=self.MODULE_ID,
            title=title,
            severity=severity.value,
            confidence=confidence,
            mitre=mitre_technique,
        )
        return f

    # ── Metadata helpers ───────────────────────────────────────────────────

    @classmethod
    def metadata(cls) -> dict[str, Any]:
        """Return full module metadata as a dict (used by registry + API)."""
        return normalize_module_metadata(cls, base={
            "id":               cls.MODULE_ID,
            "name":             cls.MODULE_NAME,
            "category":         cls.MODULE_CATEGORY,
            "description":      cls.MODULE_DESCRIPTION,
            "opsec_level":      cls.OPSEC_LEVEL.value if isinstance(cls.OPSEC_LEVEL, OpsecLevel) else cls.OPSEC_LEVEL,
            "requires":         cls.REQUIRES,
            "outputs":          cls.OUTPUTS,
            "mitre":            ", ".join(cls.MITRE_TECHNIQUES),
            "mitre_list":       cls.MITRE_TECHNIQUES,
            "author":           cls.MODULE_AUTHOR,
            "min_noise_profile": cls.MIN_NOISE_PROFILE,
            "required_privilege": getattr(cls, "REQUIRED_PRIVILEGE", None),
        })

    @classmethod
    def can_run_with_noise(cls, noise_profile: str) -> bool:
        """Check if this module is safe to run at the given noise level."""
        # HIGH_NOISE modules blocked in stealth
        if cls.OPSEC_LEVEL == OpsecLevel.HIGH_NOISE and noise_profile == "stealth":
            return False
        # Respect MIN_NOISE_PROFILE
        if cls.MIN_NOISE_PROFILE:
            order = ["stealth", "normal", "aggressive"]
            try:
                required_idx = order.index(cls.MIN_NOISE_PROFILE)
                current_idx  = order.index(noise_profile)
                return current_idx >= required_idx
            except ValueError:
                pass
        return True

    @classmethod
    def satisfies(cls, capability: str) -> bool:
        """Check if this module produces a given capability/output."""
        return capability in cls.OUTPUTS

    @classmethod
    def needs(cls, capability: str) -> bool:
        """Check if this module requires a given capability/input."""
        return capability in cls.REQUIRES

    # ── Context binding ────────────────────────────────────────────────────

    def _bind_log_context(self, target: str = "") -> None:
        """Bind module context to structlog for the duration of this run."""
        bind_context(
            module=self.MODULE_ID,
            campaign=self.campaign.id[:8],
            operator=self.campaign.operator,
            noise=self.campaign.noise_profile.value,
            target=target,
        )

    def _clear_log_context(self) -> None:
        clear_context()

    # ── Context helpers ────────────────────────────────────────────────────

    def _extract_ad_params(self, ctx: "Any") -> dict:
        """
        Extract common AD module params from ExecutionContext.
        Pulls dc, domain, username, password - trying vault first.
        Safe to call even when ctx is a bare namespace (test mode).
        """
        cred = getattr(ctx, "best_credential", lambda: None)()
        params = ctx.params if hasattr(ctx, "params") and ctx.params is not None else {}
        def _get_val(k: str, default: Any = "") -> Any:
            if hasattr(params, "get"):
                val = params.get(k, default)
            else:
                val = getattr(params, k, default)
            if hasattr(val, "get_secret_value"):
                return val.get_secret_value()
            return val

        username = _get_val("username") or (cred.username if cred else "")
        password = _get_val("password", "")
        if cred and not password:
            vault = getattr(ctx, "vault", None)
            if vault:
                try:
                    password = vault.reveal(cred.id)
                except Exception:
                    pass
        return {
            "dc":       _get_val("dc") or getattr(ctx, "target", ""),
            "domain":   getattr(ctx, "domain", "") or _get_val("domain", ""),
            "username": username,
            "password": password,
        }


# ── ModuleResult ──────────────────────────────────────────────────────────────
@dataclass
class ModuleResult:
    """
    Standardized output from every module execution.
    Engine uses this to auto-continue attack chains.
    """
    status:           str                   = "success"
    findings:         list = field(default_factory=list)
    artifacts:        dict = field(default_factory=dict)
    new_credentials:  list = field(default_factory=list)
    discovered_hosts: list = field(default_factory=list)
    raw:              dict = field(default_factory=dict)
    error:            str   = ""
    module_id:        str   = ""
    execution_id:     str   = ""
    # Outcome quality - 0.0=failed/empty, 0.5=partial, 1.0=full success
    # Enables accurate learning in OutcomeKnowledgeBase (not just status string)
    outcome_quality:  float = -1.0   # -1.0 = not set by module (auto-computed)
    outcome_evidence: str   = ""     # e.g. "3 TGS tickets from corp.local"

    @property
    def data(self) -> dict:
        """Alias for raw dictionary for developer ergonomics and backward compatibility."""
        return self.raw

    @property
    def effective_quality(self) -> float:
        """Returns explicitly set quality, or auto-derives from status+findings."""
        if self.outcome_quality >= 0.0:
            return self.outcome_quality
        # Auto-derive
        if self.status in ("dry_run", "skipped"):
            return 0.0
        if self.status == "failed" or self.error:
            return 0.0
        if self.status == "partial":
            return 0.5 if not self.findings else min(len(self.findings) / 3.0, 0.8)
        # status == "success"
        return 1.0 if self.findings else 0.5

    @property
    def success(self) -> bool:
        return self.status == "success"

    @property
    def has_credentials(self) -> bool:
        return len(self.new_credentials) > 0

    @property
    def has_new_hosts(self) -> bool:
        return len(self.discovered_hosts) > 0

    def to_dict(self) -> dict:
        return {
            "status":           self.status,
            "findings":         len(self.findings),
            "new_credentials":  len(self.new_credentials),
            "discovered_hosts": self.discovered_hosts,
            "error":            self.error,
            "module_id":        self.module_id,
        }

    @classmethod
    def ok(cls, message: str = "", module_id: str = "", **kwargs: Any) -> ModuleResult:
        """Create a successful ModuleResult with optional narrative message."""
        raw = kwargs.pop("raw", {})
        if message and "message" not in raw:
            raw = {**raw, "message": message}
        return cls(status="success", module_id=module_id, raw=raw, **kwargs)

    @classmethod
    def failed(cls, error: str = "", module_id: str = "", **kwargs: Any) -> ModuleResult:
        """Create a failed ModuleResult with an error message."""
        return cls(status="failed", module_id=module_id, error=error, **kwargs)


_REQUIRED_MODULE_ATTRS: list[str] = [
    "MODULE_ID", "MODULE_NAME", "MODULE_CATEGORY", "MODULE_DESCRIPTION",
]


def validate_module_class(cls: type) -> list[str]:
    """
    Validate community module class has all required metadata.
    Returns list of errors (empty = valid).
    """
    errors: list[str] = []
    for attr in _REQUIRED_MODULE_ATTRS:
        val = getattr(cls, attr, "")
        if not val:
            errors.append(f"Missing required attribute: {attr!r}")
    mid = getattr(cls, "MODULE_ID", "")
    if mid and "." not in mid:
        errors.append(f"MODULE_ID {mid!r} must use dotted format 'category.name'")
    return errors