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 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.")