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
"""
AD User Enumeration - Production Implementation
MITRE: T1087.002, T1201
ldap3 with NTLM auth, paged search, UAC flag parsing.
Detects: dormant accounts, ASREPRoastable, no-expiry, missing lockout.
"""
from __future__ import annotations
import asyncio
import datetime
from typing import Any
from ares.core.logger import get_logger
logger = get_logger("ares.modules.ad.enum_users")
from ares.core.campaign import Severity
from ares.core.errors import AresError, ModuleValidationError, NetworkError
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,
classify_ad_ldap_bind_failure,
)
from ares.modules.params import DomainAuthParams
from ares.sdk import (
BaseModule,
EvidenceRecord,
LockoutCircuitBreaker,
ModuleResult,
NetworkPermission,
OpsecLevel,
ProcessPermission,
module_contract,
)
UAC_ACCOUNT_DISABLE = 0x0002
UAC_DONT_EXPIRE_PASSWORD = 0x10000
UAC_PREAUTH_NOT_REQUIRED = 0x400000
from ares.modules._tls_security import ldap_tls
def _dn_to_base(domain: str) -> str:
return ",".join(f"DC={p}" for p in domain.upper().split("."))
def _parse_windows_ts(ts: Any) -> datetime.datetime | None:
if not ts or str(ts) in ("0", "9223372036854775807"):
return None
try:
return datetime.datetime(1601, 1, 1) + datetime.timedelta(microseconds=int(str(ts)) // 10)
except (ValueError, OverflowError, TypeError):
return None
def _days_since(dt: datetime.datetime | None) -> int | None:
if dt is None:
return None
return max(0, (datetime.datetime.now(datetime.UTC).replace(tzinfo=None) - dt).days)
@module_contract(
permissions=[
NetworkPermission(ports=[389, 636], protocols=["tcp"]),
ProcessPermission(allow_subprocesses=False),
],
circuit_breaker=LockoutCircuitBreaker(),
params_model=DomainAuthParams,
)
class ADEnumUsersModule(BaseModule[DomainAuthParams, ModuleResult]):
"""
ad.enum_users - Enumerate domain users, attributes, dormant accounts, password policy
OPSEC: LOW
MITRE: "T1087.002", "T1201"
OUTPUTS: "user_list"
"""
MODULE_ID = "ad.enum_users"
MODULE_NAME = "AD User Enumeration"
MODULE_CATEGORY = "ad"
MODULE_DESCRIPTION = "Enumerate domain users, attributes, dormant accounts, password policy"
MODULE_AUTHOR = "ARES Team <[email protected]>"
OPSEC_LEVEL = OpsecLevel.LOW
REQUIRES = []
OUTPUTS = ["user_list"]
MITRE_TECHNIQUES = ["T1087.002", "T1201"]
MODULE_TIMEOUT_SECONDS: int | None = 90 # seconds
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_users requires 'dc' (Domain Controller IP or hostname). "
"Pass via params['dc'] or set as target.",
module_id=self.MODULE_ID, field="dc",
)
if not ad["domain"]:
raise ModuleValidationError(
"ad.enum_users requires 'domain' (e.g. corp.local).",
module_id=self.MODULE_ID, field="domain",
)
if not ad["username"]:
raise ModuleValidationError(
"ad.enum_users 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"]
use_ldaps = ctx.params.get("use_ldaps", True)
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, use_ldaps=use_ldaps,
)
# Cryptographic Evidence Records with SHA-256 Merkle Provenance
evidence_chain: list[EvidenceRecord] = []
for user in (raw.get("users") or raw.get("user_list", [])):
username_val = user.get("samAccountName", user.get("username", "unknown"))
ev = EvidenceRecord(
artifact_id=f"user-{str(username_val).lower()}",
source_target=dc,
collected_by=self.MODULE_ID,
data={
"username": username_val,
"enabled": user.get("enabled", True),
"admin_count": user.get("adminCount", 0),
"spns": user.get("spns", []),
"dont_expire_password": user.get("dontExpirePassword", False),
"no_preauth": user.get("noPreauth", False),
},
tags=["ad", "user", "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
user_target = dc or "DomainController"
kql_query = (
"// ARES Closed-Loop Telemetry: Detect Mass AD User & Privileged Account Enumeration\n"
"// Monitors Directory Service Event 1644 for LDAP queries looking for adminCount=1 or DONT_REQ_PREAUTH\n"
"DirectoryServiceAccess\n"
"| where EventID == 1644\n"
"| where SearchFilter has \"adminCount=1\" or SearchFilter has \"userAccountControl:1.2.840.113556.1.4.803:=4194304\"\n"
"| project TimeGenerated, ClientIP, SearchFilter, AttributeList, ReturnedEntriesCount\n"
)
sigma_rule = (
f"title: Active Directory Privileged & Roastable User Enumeration ({user_target})\n"
f"id: 4f5a6b7c-ares-users-{abs(hash(user_target)) % 1000000:06d}\n"
f"status: experimental\n"
f"description: Detects LDAP queries enumerating privileged domain users (adminCount=1) or AS-REP roastable accounts.\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:\n"
f" - 'adminCount=1'\n"
f" - 'userAccountControl'\n"
f" condition: selection\n"
f"level: medium\n"
f"tags:\n"
f" - attack.discovery\n"
f" - attack.t1087.002\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 User Enumeration ({user_target})",
"loot_type": "detection_rule_kql",
"description": "Microsoft Sentinel KQL query for detecting LDAP user and privileged account enumeration",
"content": {"kql": kql_query, "target": user_target},
"tags": ["detection", "kql", "sentinel", "blue_team"],
},
{
"name": f"Detection Rule (Sigma): AD User Enumeration ({user_target})",
"loot_type": "detection_rule_sigma",
"description": "Sigma detection rule for LDAP user enumeration",
"content": {"sigma": sigma_rule, "target": user_target},
"tags": ["detection", "sigma", "blue_team"],
},
])
raw["loot"] = loot_items
raw["privileged_users_evaluated"] = True
raw["asrep_roastable_users_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_users")
async def run(self, dc, username, password, domain, use_ldaps=True, **kwargs):
dc, username, domain = sanitize_hostname(dc), sanitize_ldap(username), sanitize_ldap(domain)
await self.before_request(dc, "ldap")
page_size = self.noise.get_ldap_page_size()
logger.info("ad.enum_users_start", dc=dc, domain=domain, ldaps=use_ldaps)
try:
loop = asyncio.get_running_loop()
users, policy = await loop.run_in_executor(
None,
lambda: self._ldap_query_sync(dc, username, password, domain, use_ldaps, page_size),
)
except AresError:
raise
except Exception as exc:
raise NetworkError(f"LDAP failed on {dc}: {exc}") from exc
raw = {"user_list": users, "users": users, "password_policy": policy}
# ISU-07: produce UserArtifact objects for ArtifactIntelEngine
try:
from ares.normalize.artifacts import ArtifactStore, UserArtifact
store = getattr(getattr(self, "campaign", None), "_artifact_store", None)
if store is None:
store = ArtifactStore()
for u in users:
artifact = UserArtifact(
username=u.get("samAccountName", u.get("username", "")),
domain=domain,
enabled=u.get("enabled", True),
no_preauth=bool(u.get("noPreauth")),
spns=u.get("spns", []),
is_admin="Admins" in " ".join(u.get("memberOf", [])),
)
store.add(artifact)
except Exception:
pass # artifact creation is best-effort
await self.noise.jitter.sleep()
self._analyze(raw)
logger.info("ad.enum_users_done", total=len(users), findings=len(self._findings))
return self._findings, raw
def _ldap_query_sync(self, dc, username, password, domain, use_ldaps, page_size):
"""
Sync (non-async) - runs in executor so it never blocks the event loop.
Fix Issue #1: moved from async def to sync def + run_in_executor call above.
Fix Issue #2: conn.unbind() in try/finally - always closes even on exception.
"""
import ldap3
from ldap3 import ALL, NTLM, SUBTREE, Connection, Server
from ldap3.core.exceptions import LDAPBindError
bind_plan = build_ad_bind_plan(username, domain)
last_failure: AresError | None = None
conn = None
for port, use_ssl in ([(636, True), (389, False)] if use_ldaps else [(389, False)]):
attempt_conn = None
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
attempt_conn = Connection(server, **conn_kwargs)
result = attempt_conn.bind()
if not result:
bind_error = LDAPBindError(f"Bind failed: {attempt_conn.result}")
classified = classify_ad_ldap_bind_failure(
bind_error,
module_id=self.MODULE_ID,
dc=dc,
bind_plan=bind_plan,
result=attempt_conn.result,
)
if isinstance(classified, ModuleValidationError):
raise classified from bind_error
last_failure = classified
continue
conn = attempt_conn
break
except ModuleValidationError:
raise
except Exception as exc:
classified = classify_ad_ldap_bind_failure(
exc,
module_id=self.MODULE_ID,
dc=dc,
bind_plan=bind_plan,
result=getattr(attempt_conn, "result", None),
)
if isinstance(classified, ModuleValidationError):
raise classified from exc
last_failure = classified
finally:
if attempt_conn is not None and attempt_conn is not conn:
try:
attempt_conn.unbind()
except Exception:
pass
if conn is None:
if isinstance(last_failure, NetworkError):
raise NetworkError(
f"{last_failure.message} Verify use_ldaps={str(use_ldaps).lower()}, "
"LDAP port 389 versus LDAPS port 636, firewall rules, and "
"DC certificate/LDAPS configuration.",
module_id=self.MODULE_ID,
target=dc,
context=last_failure.context,
) from last_failure
raise NetworkError(
f"{self.MODULE_ID} could not bind to {dc} using "
f"use_ldaps={str(use_ldaps).lower()} on ports 389/636.",
module_id=self.MODULE_ID,
target=dc,
)
base = _dn_to_base(domain)
users: list[dict] = []
# Issue #2: unbind always fires, even if an entry parse crashes mid-loop
try:
cookie: bytes | bool = True
while cookie:
conn.search(
base,
"(&(objectClass=user)(objectCategory=person))",
search_scope=SUBTREE,
paged_size=page_size,
paged_cookie=None if cookie is True else cookie,
attributes=["sAMAccountName", "memberOf", "userAccountControl",
"pwdLastSet", "lastLogon", "badPwdCount"],
)
for e in conn.entries:
try:
uac = int(e.userAccountControl.value or 0)
groups = [str(g) for g in (e.memberOf.values or [])]
is_admin = any(
"Domain Admins" in g or "Enterprise Admins" in g or
"CN=Administrators" in g
for g in groups
)
users.append({
"samAccountName": str(e.sAMAccountName),
"enabled": not bool(uac & UAC_ACCOUNT_DISABLE),
"noExpiry": bool(uac & UAC_DONT_EXPIRE_PASSWORD),
"noPreauth": bool(uac & UAC_PREAUTH_NOT_REQUIRED),
"isAdmin": is_admin,
"badPwdCount": int(e.badPwdCount.value or 0),
"days_since_login": _days_since(_parse_windows_ts(e.lastLogon.value)),
"days_since_pwd": _days_since(_parse_windows_ts(e.pwdLastSet.value)),
})
except Exception:
pass # skip malformed entry, continue
cookie = (
conn.result.get("controls", {})
.get("1.2.840.113556.1.4.319", {})
.get("value", {})
.get("cookie")
)
conn.search(base, "(objectClass=domainDNS)",
attributes=["minPwdLength", "pwdHistoryLength", "lockoutThreshold"])
policy: dict = {}
if conn.entries:
ep = conn.entries[0]
policy = {
"minPwdLength": int(ep.minPwdLength.value or 0),
"pwdHistoryLength": int(ep.pwdHistoryLength.value or 0),
"lockoutThreshold": int(ep.lockoutThreshold.value or 0),
}
return users, policy
finally:
try:
conn.unbind() # Issue #2: always runs, no leak
except Exception:
pass
def _analyze(self, raw):
users = raw.get("users") or raw.get("user_list", [])
policy = raw.get("password_policy", {})
dormant = [u for u in users if u.get("enabled") and (u.get("days_since_login") or 0) > 90]
if dormant:
self.finding(title=f"Dormant Active Accounts ({len(dormant)})",
description=f"{len(dormant)} enabled accounts unused 90+ days - low-detection targets.",
severity=Severity.MEDIUM, mitre_technique="T1078.002", mitre_tactic="Initial Access",
evidence={"accounts":[u["samAccountName"] for u in dormant[:15]]},
remediation="Auto-disable after 90 days inactivity.")
no_preauth = [u for u in users if u.get("noPreauth") and u.get("enabled")]
if no_preauth:
self.finding(title=f"ASREPRoastable Accounts ({len(no_preauth)})",
description=f"{len(no_preauth)} accounts have Kerberos pre-auth disabled.",
severity=Severity.HIGH, mitre_technique="T1558.004", mitre_tactic="Credential Access",
evidence={"accounts":[u["samAccountName"] for u in no_preauth]},
remediation="Enable Kerberos pre-authentication on all accounts.")
no_expiry = [u for u in users if u.get("noExpiry") and u.get("enabled")]
if no_expiry:
self.finding(title=f"Passwords Never Expire ({len(no_expiry)})",
description=f"{len(no_expiry)} accounts retain old passwords indefinitely.",
severity=Severity.LOW, mitre_technique="T1201", mitre_tactic="Discovery",
evidence={"accounts":[u["samAccountName"] for u in no_expiry[:15]]},
remediation="Enforce password rotation. Remove DONT_EXPIRE_PASSWORD flag.")
min_len = policy.get("minPwdLength", 0)
if isinstance(min_len, int) and 0 < min_len < 12:
self.finding(title=f"Weak Password Policy (min length: {min_len})",
description=f"Domain minimum password length is {min_len}. Standard is 14+.",
severity=Severity.MEDIUM, mitre_technique="T1201", mitre_tactic="Discovery",
evidence={"policy":policy},
remediation="Set minimum password length to 14+.")
if policy.get("lockoutThreshold", 0) == 0:
self.finding(title="No Account Lockout - Password Spray Possible",
description="No lockout threshold allows unlimited spray attempts.",
severity=Severity.HIGH, mitre_technique="T1110.003", mitre_tactic="Credential Access",
evidence={"lockoutThreshold":0},
remediation="Set lockout threshold to 5-10 attempts.")