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.7 KB
Raw Blame
"""
AD ACL Enumeration - Production ldap3 Implementation
Find dangerous ACL delegations: WriteDACL, GenericAll, GenericWrite, DCSync rights.
MITRE: T1222.001, T1003.006
"""
from __future__ import annotations

from typing import Any

from ares.core.logger import get_logger
from ares.modules._tls_security import ldap_tls

logger = get_logger("ares.modules.ad.enum_acl")
from ares.core.campaign import Severity
from ares.core.security import sanitize_hostname, sanitize_ldap
from ares.core.tracing import trace_module
from ares.modules.ad.dependencies import build_ad_bind_plan
from ares.modules.params import DomainAuthParams
from ares.sdk import (
    BaseModule,
    EvidenceRecord,
    LockoutCircuitBreaker,
    ModuleResult,
    NetworkPermission,
    OpsecLevel,
    ProcessPermission,
    module_contract,
)

# Active Directory extended rights GUIDs
DCSYNC_RIGHTS = {
    "1131f6aa-9c07-11d1-f79f-00c04fc2dcd2": "DS-Replication-Get-Changes",
    "1131f6ad-9c07-11d1-f79f-00c04fc2dcd2": "DS-Replication-Get-Changes-All",
}

@module_contract(
    permissions=[
        NetworkPermission(ports=[389, 636], protocols=["tcp"]),
        ProcessPermission(allow_subprocesses=False),
    ],
    circuit_breaker=LockoutCircuitBreaker(),
    params_model=DomainAuthParams,
)
class ADEnumACLModule(BaseModule[DomainAuthParams, ModuleResult]):
    """
    ad.enum_acl - Find WriteDACL, GenericAll, GenericWrite, DCSync delegation misconfigs

    OPSEC: LOW
    MITRE: "T1222.001","T1003.006"
    OUTPUTS:  "acl_findings"
    """
    MODULE_ID="ad.enum_acl"; MODULE_NAME="AD ACL Enumeration"; MODULE_CATEGORY="ad"
    MODULE_DESCRIPTION="Find WriteDACL, GenericAll, GenericWrite, DCSync delegation misconfigs"
    MODULE_AUTHOR      = "ARES Team <[email protected]>"
    OPSEC_LEVEL=OpsecLevel.LOW; REQUIRES=[]; OUTPUTS=["acl_findings"]
    MITRE_TECHNIQUES=["T1222.001","T1003.006"]
    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_acl requires 'dc' (Domain Controller IP or hostname).",
                module_id=self.MODULE_ID, field="dc",
            )
        if not ad["domain"]:
            raise ModuleValidationError(
                "ad.enum_acl requires 'domain' (e.g. corp.local).",
                module_id=self.MODULE_ID, field="domain",
            )
        if not ad["username"]:
            raise ModuleValidationError(
                "ad.enum_acl 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},
            )
        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 finding in findings:
            ev = EvidenceRecord(
                artifact_id=f"acl-{finding.title[:20].lower().replace(' ', '-')}",
                source_target=dc,
                collected_by=self.MODULE_ID,
                data={
                    "title": finding.title,
                    "severity": str(finding.severity),
                    "description": finding.description,
                    "mitre": finding.mitre_technique,
                },
                tags=["ad", "acl", "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
        acl_target = dc or "DomainController"
        kql_query = (
            "// ARES Closed-Loop Telemetry: Detect Active Directory ACL & DACL Modification\n"
            "// Monitors Security Event 5136 and 4670 for nTSecurityDescriptor changes or WriteDacl/GenericAll grant\n"
            "SecurityEvent\n"
            "| where EventID in (4670, 5136)\n"
            "| where AttributeLDAPDisplayName == \"nTSecurityDescriptor\"\n"
            "| project TimeGenerated, Computer, SubjectUserName, ObjectDN, AttributeLDAPDisplayName, OperationType\n"
        )
        sigma_rule = (
            f"title: Active Directory DACL / Object Permission Modification ({acl_target})\n"
            f"id: 1c2d3e4f-ares-acl-{abs(hash(acl_target)) % 1000000:06d}\n"
            f"status: experimental\n"
            f"description: Detects modifications to Active Directory object security descriptors (nTSecurityDescriptor) granting WriteDacl or GenericAll.\n"
            f"logsource:\n"
            f"  product: windows\n"
            f"  service: security\n"
            f"detection:\n"
            f"  selection:\n"
            f"    EventID: 5136\n"
            f"    AttributeLDAPDisplayName: 'nTSecurityDescriptor'\n"
            f"  condition: selection\n"
            f"level: high\n"
            f"tags:\n"
            f"  - attack.persistence\n"
            f"  - attack.privilege_escalation\n"
            f"  - attack.t1098\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): AD DACL / Permission Modification ({acl_target})",
                    "loot_type": "detection_rule_kql",
                    "description": "Microsoft Sentinel KQL query for detecting Active Directory object permission changes",
                    "content": {"kql": kql_query, "target": acl_target},
                    "tags": ["detection", "kql", "sentinel", "blue_team"],
                },
                {
                    "name": f"Detection Rule (Sigma): AD DACL / Permission Modification ({acl_target})",
                    "loot_type": "detection_rule_sigma",
                    "description": "Sigma detection rule for Active Directory object permission changes",
                    "content": {"sigma": sigma_rule, "target": acl_target},
                    "tags": ["detection", "sigma", "blue_team"],
                },
            ])
        raw["loot"] = loot_items
        raw["acl_abuse_paths_evaluated"] = True
        raw["dacl_writedacl_identified"] = 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_acl")
    async def run(self, dc, username, password, domain, **kwargs):
        dc,username,domain = sanitize_hostname(dc),sanitize_ldap(username),sanitize_ldap(domain)
        await self.before_request(dc,"ldap")
        logger.info("ad.enum_acl_start", dc=dc)
        try:
            import asyncio as _asyncio
            loop = _asyncio.get_running_loop()
            misconfigs = await loop.run_in_executor(
                None,
                lambda: self._enum_acls_sync(dc, username, password, domain),
            )
        except Exception as exc:
            from ares.core.errors import NetworkError
            raise NetworkError(f"ACL enum failed: {exc}") from exc
        raw = {"misconfigs": misconfigs, "acl_findings": misconfigs}  # acl_findings = OUTPUTS key
        # ISU-07: produce PermissionArtifact objects for ArtifactIntelEngine
        try:
            from ares.normalize.artifacts import ArtifactStore, PermissionArtifact
            store = getattr(getattr(self, "campaign", None), "_artifact_store", None)
            if store is None:
                store = ArtifactStore()
            for m in misconfigs:
                artifact = PermissionArtifact(
                    principal=m.get("trustee", m.get("principal", "")),
                    target=m.get("target_dn", m.get("target", "")),
                    right=m.get("right", m.get("ace_type", "")),
                    domain=domain,
                )
                store.add(artifact)
        except Exception:
            pass  # artifact creation is best-effort
        await self.noise.jitter.sleep()
        self._analyze(raw)
        logger.info("ad.enum_acl_done", total=len(misconfigs))
        return self._findings, raw

    def _enum_acls_sync(self, dc, username, password, domain):
        """
        Sync - runs in executor (fix: was async def blocking event loop).
        Fixes: AUTO_BIND_NONE, cookie loop, LDAPS fallback, try/finally unbind.
        """

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

        bind_plan = build_ad_bind_plan(username, domain)
        conn = 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"] = NTLM
                conn = Connection(server, **conn_kwargs)
                if not conn.bind():
                    raise LDAPBindError(f"Bind failed: {conn.result}")
                break
            except Exception:
                conn = None
                continue

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

        base = ",".join(f"DC={p}" for p in domain.upper().split("."))
        dangerous_rights = {
            0x000F01FF: "GenericAll",
            0x00020028: "WriteDACL",
            0x00020000: "GenericWrite",
            0x00080000: "WriteOwner",
        }
        sd_control = [("1.2.840.113556.1.4.801", True, bytes([0x30, 0x03, 0x02, 0x01, 0x07]))]
        dangerous: list[dict] = []

        try:
            cookie: bytes | bool = True
            while cookie:
                conn.search(
                    base,
                    "(&(objectClass=user)(objectCategory=person))",
                    search_scope=SUBTREE,
                    paged_size=100,
                    paged_cookie=None if cookie is True else cookie,
                    attributes=["sAMAccountName", "ntSecurityDescriptor"],
                    controls=sd_control,
                )
                for entry in conn.entries:
                    sd = getattr(entry, "ntSecurityDescriptor", None)
                    if not sd or not sd.value:
                        continue
                    try:
                        from impacket.ldap.ldaptypes import SR_SECURITY_DESCRIPTOR
                        raw_sd = sd.raw_values[0] if hasattr(sd, "raw_values") else None
                        if not raw_sd:
                            continue
                        sd_obj = SR_SECURITY_DESCRIPTOR(data=raw_sd)
                        if not sd_obj.get("Dacl"):
                            continue
                        for ace in sd_obj["Dacl"]["Data"]:
                            if ace["AceType"] not in (0x00, 0x05):
                                continue
                            try:
                                mask = ace["Ace"]["Mask"]["MaskFields"]
                            except (KeyError, AttributeError):
                                continue
                            for right_mask, right_name in dangerous_rights.items():
                                if mask & right_mask == right_mask:
                                    from ldap3.protocol.formatters.formatters import format_sid
                                    sid = format_sid(ace["Ace"]["Sid"].getData())
                                    dangerous.append({
                                        "target":      str(entry.sAMAccountName),
                                        "right":       right_name,
                                        "trustee_sid": sid,
                                    })
                                    break
                    except Exception:
                        pass
                cookie = (
                    conn.result.get("controls", {})
                        .get("1.2.840.113556.1.4.319", {})
                        .get("value", {})
                        .get("cookie")
                )

            # Check domain object for DCSync rights
            conn.search(
                base, "(objectClass=domainDNS)",
                attributes=["distinguishedName", "ntSecurityDescriptor"],
                controls=sd_control,
            )
            for entry in conn.entries:
                sd = getattr(entry, "ntSecurityDescriptor", None)
                if not sd or not sd.value:
                    continue
                try:
                    from impacket.ldap.ldaptypes import SR_SECURITY_DESCRIPTOR
                    raw_sd = sd.raw_values[0] if hasattr(sd, "raw_values") else None
                    if not raw_sd:
                        continue
                    sd_obj = SR_SECURITY_DESCRIPTOR(data=raw_sd)
                    if not sd_obj.get("Dacl"):
                        continue
                    repl_rights: dict[str, set] = {}
                    for ace in sd_obj["Dacl"]["Data"]:
                        if ace["AceType"] != 0x05:
                            continue
                        try:
                            obj_type = bytes(ace["Ace"]["ObjectType"]).hex()
                            from ldap3.protocol.formatters.formatters import format_sid
                            sid = format_sid(ace["Ace"]["Sid"].getData())
                            if obj_type in DCSYNC_RIGHTS:
                                repl_rights.setdefault(sid, set()).add(DCSYNC_RIGHTS[obj_type])
                        except Exception:
                            pass
                    for sid, rights in repl_rights.items():
                        if len(rights) >= 2:
                            dangerous.append({
                                "target":      "domain",
                                "right":       "DCSync",
                                "trustee_sid": sid,
                            })
                except Exception:
                    pass
            return dangerous
        finally:
            try:
                conn.unbind()
            except Exception:
                pass
    def _analyze(self, raw):
        misconfigs = raw.get("misconfigs",[])
        if not misconfigs: return
        write_dacl  = [m for m in misconfigs if m["right"] == "WriteDACL"]
        generic_all = [m for m in misconfigs if m["right"] == "GenericAll"]
        if generic_all:
            self.finding(title=f"GenericAll ACE on {len(generic_all)} Objects",
                description=f"{len(generic_all)} objects have GenericAll ACE - full control over target.",
                severity=Severity.CRITICAL, mitre_technique="T1222.001", mitre_tactic="Defense Evasion",
                evidence={"objects": generic_all[:10]},
                remediation="Remove GenericAll ACE. Use specific delegations instead.")
        if write_dacl:
            self.finding(title=f"WriteDACL on {len(write_dacl)} Objects",
                description=f"{len(write_dacl)} objects have WriteDACL - attacker can grant arbitrary rights.",
                severity=Severity.HIGH, mitre_technique="T1222.001", mitre_tactic="Defense Evasion",
                evidence={"objects": write_dacl[:10]},
                remediation="Audit and remove WriteDACL delegations. Enable AD Protected Users.")