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.

16.9 KB
Raw Blame
"""AD SPN Enumeration - Production ldap3 Implementation. MITRE: T1558.003, T1087.002"""
from __future__ import annotations

import datetime
from typing import Any

from ares.core.logger import get_logger

logger = get_logger("ares.modules.ad.enum_spn")
from ares.core.campaign import Severity
from ares.core.errors import AresError, ModuleValidationError
from ares.core.security import sanitize_hostname, sanitize_ldap
from ares.core.tracing import trace_module
from ares.modules._tls_security import ldap_tls
from ares.modules.ad.dependencies import (
    ad_bind_dry_run_metadata,
    build_ad_bind_plan,
    classify_ad_ldap_bind_failure,
    sanitize_ad_username,
)
from ares.modules.params import DomainAuthParams
from ares.sdk import (
    BaseModule,
    EvidenceRecord,
    LockoutCircuitBreaker,
    ModuleResult,
    NetworkPermission,
    OpsecLevel,
    ProcessPermission,
    module_contract,
)


def _dn_to_base(domain):
    return ",".join(f"DC={p}" for p in domain.upper().split("."))

def _days_since_ts(ts):
    if not ts or str(ts) in ("0","9223372036854775807"): return None
    try:
        dt = datetime.datetime(1601,1,1) + datetime.timedelta(microseconds=int(str(ts))//10)
        return max(0,(datetime.datetime.now(datetime.UTC).replace(tzinfo=None)-dt).days)
    except Exception: return None


def classify_enum_spn_outcome(spn_count: int) -> tuple[str, str]:
    """Explain whether LDAP found any service principal candidates."""
    if spn_count:
        return "confirmed_findings", f"Found {spn_count} service principal candidate(s)."
    return (
        "completed_no_findings",
        "LDAP completed successfully; no enabled user accounts with service principals were found.",
    )

@module_contract(
    permissions=[
        NetworkPermission(ports=[389, 636], protocols=["tcp"]),
        ProcessPermission(allow_subprocesses=False),
    ],
    circuit_breaker=LockoutCircuitBreaker(),
    params_model=DomainAuthParams,
)
class ADEnumSPNModule(BaseModule[DomainAuthParams, ModuleResult]):
    """
    ad.enum_spn - Find SPN accounts (Kerberoasting candidates)

    OPSEC: LOW
    MITRE: "T1558.003","T1087.002"
    OUTPUTS:  "spns", "spn_list"
    """
    MODULE_ID="ad.enum_spn"; MODULE_NAME="AD SPN Enumeration"; MODULE_CATEGORY="ad"
    MODULE_DESCRIPTION="Find SPN accounts (Kerberoasting candidates)"
    MODULE_AUTHOR      = "ARES Team <[email protected]>"
    OPSEC_LEVEL=OpsecLevel.LOW; REQUIRES=[]; OUTPUTS=["spns", "spn_list"]
    MITRE_TECHNIQUES=["T1558.003","T1087.002"]
    PARAMS_MODEL       = DomainAuthParams

    async def validate(self, ctx: "Any") -> None:
        """Enforce dc, domain, and credentials before any LDAP connection is made."""
        from ares.core.context import ExecutionContext
        from ares.core.errors import ModuleValidationError
        if not isinstance(ctx, ExecutionContext):
            return
        ad = self._extract_ad_params(ctx)
        if not ad["dc"]:
            raise ModuleValidationError(
                "ad.enum_spn requires 'dc' (Domain Controller IP or hostname).",
                module_id=self.MODULE_ID, field="dc",
            )
        if not ad["domain"]:
            raise ModuleValidationError(
                "ad.enum_spn requires 'domain' (e.g. corp.local).",
                module_id=self.MODULE_ID, field="domain",
            )
        if not ad["username"]:
            raise ModuleValidationError(
                "ad.enum_spn requires domain credentials - "
                "pass 'username'/'password' in params or provide a vault credential.",
                module_id=self.MODULE_ID, field="username",
            )
        if isinstance(ctx.params, dict):
            for k in ("dc", "domain", "username", "password"):
                if k not in ctx.params and ad.get(k):
                    ctx.params[k] = ad[k]
        await super().validate(ctx)

    async def execute(self, ctx: "Any") -> "ModuleResult":
        """ExecutionContext-based entry point (v0.9.0+). Credentials sourced from vault."""
        from ares.modules.base import ModuleResult
        ad = self._extract_ad_params(ctx)
        dc, domain, username, password = ad["dc"], ad["domain"], ad["username"], ad["password"]
        if getattr(ctx, "dry_run", False):
            return ModuleResult(
                status="dry_run", module_id=self.MODULE_ID,
                raw={
                    "dry_run": True,
                    "dc": dc,
                    "domain": domain,
                    **ad_bind_dry_run_metadata(username, domain),
                },
            )
        findings, raw = await self.run(
            dc=dc, username=username, password=password, domain=domain,
        )

        # Cryptographic Evidence Records with SHA-256 Merkle Provenance
        evidence_chain: list[EvidenceRecord] = []
        for spn in (raw.get("spns") or raw.get("spn_list", [])):
            ev = EvidenceRecord(
                artifact_id=f"spn-{(spn.get('samAccountName') or spn.get('name') or 'unknown').lower()}",
                source_target=dc,
                collected_by=self.MODULE_ID,
                data={
                    "samAccountName": spn.get("samAccountName") or spn.get("name"),
                    "spns": spn.get("spns") or spn.get("spn_list"),
                    "memberOf": spn.get("memberOf"),
                },
                tags=["ad", "spn", "kerberoasting", "enumeration"],
            )
            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
        spn_target = dc or "DomainController"
        kql_query = (
            "// ARES Closed-Loop Telemetry: Detect Kerberoasting Reconnaissance / SPN Enumeration\n"
            "// Monitors Directory Service Event 1644 for LDAP queries searching for accounts with servicePrincipalName\n"
            "DirectoryServiceAccess\n"
            "| where EventID == 1644\n"
            "| where SearchFilter has \"servicePrincipalName=*\" and SearchFilter has \"!(userAccountControl:1.2.840.113556.1.4.803:=2)\"\n"
            "| project TimeGenerated, ClientIP, SearchFilter, AttributeList, ReturnedEntriesCount\n"
        )
        sigma_rule = (
            f"title: Active Directory SPN Query Reconnaissance ({spn_target})\n"
            f"id: 3e4f5a6b-ares-spn-{abs(hash(spn_target)) % 1000000:06d}\n"
            f"status: experimental\n"
            f"description: Detects LDAP queries enumerating Service Principal Names (SPNs) typically conducted prior to Kerberoasting.\n"
            f"logsource:\n"
            f"  product: windows\n"
            f"  service: directory_service\n"
            f"detection:\n"
            f"  selection:\n"
            f"    EventID: 1644\n"
            f"    SearchFilter|contains: 'servicePrincipalName=*'\n"
            f"  condition: selection\n"
            f"level: medium\n"
            f"tags:\n"
            f"  - attack.discovery\n"
            f"  - attack.t1087.002\n"
            f"  - attack.t1558.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): SPN Enumeration ({spn_target})",
                    "loot_type": "detection_rule_kql",
                    "description": "Microsoft Sentinel KQL query for detecting LDAP SPN enumeration for Kerberoasting",
                    "content": {"kql": kql_query, "target": spn_target},
                    "tags": ["detection", "kql", "sentinel", "blue_team"],
                },
                {
                    "name": f"Detection Rule (Sigma): SPN Enumeration ({spn_target})",
                    "loot_type": "detection_rule_sigma",
                    "description": "Sigma detection rule for LDAP SPN enumeration",
                    "content": {"sigma": sigma_rule, "target": spn_target},
                    "tags": ["detection", "sigma", "blue_team"],
                },
            ])
        raw["loot"] = loot_items
        raw["spn_accounts_enumerated"] = True
        raw["kerberoastable_surface_mapped"] = 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("ad.enum_spn")
    async def run(self, dc, username, password, domain, **kwargs):
        dc, username, domain = (
            sanitize_hostname(dc),
            sanitize_ad_username(username),
            sanitize_ldap(domain),
        )
        await self.before_request(dc,"ldap")
        logger.info("ad.enum_spn_start", dc=dc)
        try:
            import asyncio as _asyncio
            loop = _asyncio.get_running_loop()
            spns = await loop.run_in_executor(
                None,
                lambda: self._fetch_spns_sync(dc, username, password, domain),
            )
        except AresError:
            raise
        except Exception as exc:
            from ares.core.errors import NetworkError
            raise NetworkError(f"LDAP SPN failed: {exc}") from exc
        category, message = classify_enum_spn_outcome(len(spns))
        raw = {
            "spns": spns,
            "spn_list": spns,
            "outcome_category": category,
            "outcome_message": message,
        }
        # ISU-07: produce UserArtifact objects (is_kerberoastable=True)
        try:
            from ares.normalize.artifacts import ArtifactStore, UserArtifact
            store = getattr(getattr(self, "campaign", None), "_artifact_store", None)
            if store is None:
                store = ArtifactStore()
            for spn_entry in spns:
                artifact = UserArtifact(
                    username=spn_entry.get("samAccountName") or spn_entry.get("name", ""),
                    domain=domain,
                    enabled=True,
                    spns=spn_entry.get("spns") or spn_entry.get("spn_list", []),
                    is_service=True,
                )
                store.add(artifact)
        except Exception:
            pass
        await self.noise.jitter.sleep()
        self._analyze(raw)
        logger.info("ad.enum_spn_done", total=len(spns))
        return self._findings, raw

    def _fetch_spns_sync(self, dc, username, password, domain):
        """
        Sync (non-async) - runs in executor so it never blocks the event loop.
        Issue #1 fix: moved from async def to sync def + run_in_executor call above.
        Issue #2 fix: conn.unbind() in try/finally - always closes even on exception.
        """

        import ldap3
        from ldap3 import ALL, SUBTREE, Connection, Server
        from ldap3.core.exceptions import LDAPBindError

        # Try LDAPS first, fallback to plain LDAP
        bind_plan = build_ad_bind_plan(username, domain)
        conn = None
        last_error = None
        for port, use_ssl in [(636, True), (389, False)]:
            try:
                tls_arg = ldap_tls(use_ssl)
                server  = Server(dc, port=port, use_ssl=use_ssl,
                                 tls=tls_arg, get_info=ALL,
                                 connect_timeout=10)
                conn_kwargs = {
                    "user": bind_plan.user,
                    "password": password,
                    "auto_bind": ldap3.AUTO_BIND_NONE,
                    "receive_timeout": 30,
                }
                if bind_plan.mode == "ntlm":
                    conn_kwargs["authentication"] = ldap3.NTLM
                conn = Connection(server, **conn_kwargs)
                result = conn.bind()
                if not result:
                    ldap_result = getattr(conn, "result", {}) or {}
                    raise classify_ad_ldap_bind_failure(
                        LDAPBindError("LDAP bind returned false"),
                        module_id=self.MODULE_ID,
                        dc=dc,
                        bind_plan=bind_plan,
                        result=ldap_result,
                    )
                break
            except AresError:
                raise
            except Exception as exc:
                last_error = classify_ad_ldap_bind_failure(
                    exc,
                    module_id=self.MODULE_ID,
                    dc=dc,
                    bind_plan=bind_plan,
                )
                if isinstance(last_error, ModuleValidationError):
                    raise last_error  # noqa: B904
                conn = None
                continue

        if conn is None:
            if last_error is not None:
                raise last_error
            raise ConnectionError(f"Could not bind to {dc} on ports 636 or 389")

        base       = _dn_to_base(domain)
        spn_filter = (
            "(&(objectClass=user)(servicePrincipalName=*)"
            "(!(userAccountControl:1.2.840.113556.1.4.803:=2)))"
        )
        spns: list[dict] = []

        try:
            cookie: bytes | bool = True
            while cookie:
                conn.search(
                    base, spn_filter,
                    search_scope=SUBTREE,
                    paged_size=200,
                    paged_cookie=None if cookie is True else cookie,
                    attributes=["sAMAccountName", "servicePrincipalName", "memberOf",
                                "msDS-SupportedEncryptionTypes", "pwdLastSet",
                                "userAccountControl"],
                )
                for e in conn.entries:
                    try:
                        uac    = int(e.userAccountControl.value or 0)
                        enc_raw = 0
                        try:
                            enc_attr = getattr(e, "msDS-SupportedEncryptionTypes", None)
                            if enc_attr and enc_attr.value is not None:
                                enc_raw = int(enc_attr.value)
                        except Exception:
                            enc_raw = 0
                        groups   = [str(g) for g in (e.memberOf.values or [])]
                        is_admin = any(
                            "Domain Admins" in g or "Enterprise Admins" in g for g in groups
                        )
                        spn_values = [str(s) for s in (e.servicePrincipalName.values or [])]
                        spns.append({
                            "name":           str(e.sAMAccountName),
                            "samAccountName": str(e.sAMAccountName),
                            "spns":           spn_values,
                            "spn_list":       spn_values,
                            "is_admin":       is_admin,
                            "uses_rc4":       (enc_raw == 0) or bool(enc_raw & 0x4),
                            "days_since_pwd": _days_since_ts(e.pwdLastSet.value),
                            "enabled":        not bool(uac & 0x0002),
                        })
                    except Exception:
                        pass   # skip malformed entry
                cookie = (
                    conn.result.get("controls", {})
                        .get("1.2.840.113556.1.4.319", {})
                        .get("value", {})
                        .get("cookie")
                )
            return spns
        finally:
            try:
                conn.unbind()     # Issue #2: always runs, no resource leak
            except Exception:
                pass

    def _analyze(self, raw):
        spns = raw.get("spns") or raw.get("spn_list", [])
        if not spns: return
        rc4      = [s for s in spns if s.get("uses_rc4")]
        privd    = [s for s in spns if s.get("is_admin")]
        old_pass = [s for s in spns if (s.get("days_since_pwd") or 0) > 365]
        self.finding(title=f"Kerberoastable Service Accounts ({len(spns)})",
            description=(f"{len(spns)} SPN accounts - {len(rc4)} use RC4 (fastest to crack), "
                         f"{len(privd)} in privileged groups."),
            severity=Severity.CRITICAL if privd else Severity.HIGH,
            mitre_technique="T1558.003", mitre_tactic="Credential Access",
            evidence={"total_spns":len(spns),"rc4_accounts":[s["name"] for s in rc4[:10]],
                      "privileged_spns":[s["name"] for s in privd[:10]],"hashcat_mode_rc4":13100},
            remediation=("1. Migrate to gMSA. 2. Set-ADUser -KerberosEncryptionType AES256. "
                         "3. Monitor Event ID 4769."))
        if old_pass:
            self.finding(title=f"Service Accounts with Stale Passwords ({len(old_pass)})",
                description=f"{len(old_pass)} SPN accounts have passwords older than 1 year.",
                severity=Severity.MEDIUM, mitre_technique="T1558.003", mitre_tactic="Credential Access",
                evidence={"accounts":[s["name"] for s in old_pass]},
                remediation="Rotate service account passwords annually, or migrate to gMSA.")