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
fix: classify enum_computers LDAP connection failures
Mafifrizi82a94b70db1e
diff --git a/ares/modules/ad/enum_computers.py b/ares/modules/ad/enum_computers.pyindex 52f563c..88b1740 100644--- a/ares/modules/ad/enum_computers.py+++ b/ares/modules/ad/enum_computers.py@@ -5,6 +5,7 @@ MITRE: T1018, T1087.002"""from __future__ import annotationsimport datetime+import refrom typing import Anyfrom ares.core.logger import get_logger@@ -13,6 +14,8 @@ from ares.core.campaign import Finding, Severityfrom ares.core.security import sanitize_hostname, sanitize_ldapfrom ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_module+from ares.core.errors import AresError, ModuleValidationError, NetworkError+from ares.modules.ad.dependencies import build_ad_bind_plandef _days_since_ts(ts):if not ts or str(ts) in ("0","9223372036854775807"): return None@@ -21,6 +24,46 @@ def _days_since_ts(ts):return max(0,(datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)-dt).days)except Exception: return None++def _safe_ldap_exception_text(exc: BaseException) -> str:+ text = " ".join(str(exc).split())[:160]+ return re.sub(+ r"(?i)\b(password|passwd|secret|token|api[_-]?key)\b\s*([:=])\s*[^\s,;]+",+ r"\1\2[redacted]",+ text,+ ) or type(exc).__name__+++def _is_ldap_configuration_failure(exc: BaseException) -> bool:+ text = f"{type(exc).__name__}: {exc}".lower()+ return any(+ marker in text+ for marker in (+ "ssl wrapping",+ "sslerror",+ "tls",+ "certificate",+ "wrong version number",+ "winerror 10054",+ "forcibly closed",+ "connection reset",+ )+ )+++def _format_ldap_connection_failure(+ *, dc: str, port: int, use_ldaps: bool, exc: BaseException+) -> str:+ mode = "LDAPS" if use_ldaps else "plain LDAP"+ return (+ f"ad.enum_computers {mode} connection failed for dc {dc} "+ f"(use_ldaps={str(use_ldaps).lower()}, port {port}). "+ f"Verify DC LDAP/LDAPS support ({'LDAPS on port 636' if use_ldaps else 'plain LDAP on port 389'}), "+ "or switch use_ldaps to the supported mode; check the 389 vs 636 port, "+ "firewall rules, and certificate/LDAPS configuration. "+ f"Reason: {_safe_ldap_exception_text(exc)}"+ )+class ADEnumComputersModule(BaseModule):"""ad.enum_computers — Enumerate domain computers, OS versions, stale accounts, DCs@@ -64,6 +107,7 @@ class ADEnumComputersModule(BaseModule):from ares.modules.base import ModuleResultad = 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,@@ -71,6 +115,7 @@ class ADEnumComputersModule(BaseModule):)findings, raw = await self.run(dc=dc, username=username, password=password, domain=domain,+ use_ldaps=use_ldaps,)return ModuleResult(status="success" if (findings or raw) else "partial",@@ -80,14 +125,17 @@ class ADEnumComputersModule(BaseModule):)@trace_module("ad.enum_computers")- async def run(self, dc, username, password, domain, **kwargs):+ 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")- logger.info("ad.enum_computers_start", dc=dc)+ logger.info("ad.enum_computers_start", dc=dc, ldaps=use_ldaps)try:- computers = await self._fetch_computers(dc, username, password, domain)+ computers = await self._fetch_computers(+ dc, username, password, domain, use_ldaps=use_ldaps+ )+ except AresError:+ raiseexcept Exception as exc:- from ares.core.errors import NetworkErrorraise NetworkError(f"Computer enum failed: {exc}") from excraw = {"computer_list": computers}# ISU-07: produce HostArtifact objects for ArtifactIntelEngine@@ -111,32 +159,68 @@ class ADEnumComputersModule(BaseModule):logger.info("ad.enum_computers_done", total=len(computers))return self._findings, raw- async def _fetch_computers(self, dc, username, password, domain):+ async def _fetch_computers(self, dc, username, password, domain, use_ldaps=True):import sslfrom ldap3 import Server, Connection, ALL, NTLM, SUBTREE, AUTO_BIND_NO_TLS, Tls- tls = Tls(validate=ssl.CERT_NONE)- server = Server(dc, port=636, use_ssl=True, tls=tls, get_info=ALL)- conn = Connection(server, user=f"{domain.upper()}\\{username}", password=password,- authentication=NTLM, auto_bind=AUTO_BIND_NO_TLS)+ port = 636 if use_ldaps else 389+ tls = Tls(validate=ssl.CERT_NONE) if use_ldaps else None+ bind_plan = build_ad_bind_plan(username, domain)+ try:+ server = Server(+ dc,+ port=port,+ use_ssl=use_ldaps,+ tls=tls,+ get_info=ALL,+ connect_timeout=10,+ )+ conn_kwargs = {+ "user": bind_plan.user,+ "password": password,+ "auto_bind": AUTO_BIND_NO_TLS,+ "receive_timeout": 30,+ }+ if bind_plan.mode == "ntlm":+ conn_kwargs["authentication"] = NTLM+ conn = Connection(server, **conn_kwargs)+ if not conn.bind():+ raise ConnectionError(f"LDAP bind returned false: {conn.result}")+ except Exception as exc:+ message = _format_ldap_connection_failure(+ dc=dc, port=port, use_ldaps=use_ldaps, exc=exc+ )+ if _is_ldap_configuration_failure(exc):+ raise ModuleValidationError(+ f"LDAP configuration validation failed: {message}",+ module_id=self.MODULE_ID,+ field="use_ldaps",+ target=dc,+ ) from exc+ raise NetworkError(message, module_id=self.MODULE_ID, target=dc) from excbase = ",".join(f"DC={p}" for p in domain.upper().split("."))- conn.search(base, "(objectClass=computer)", search_scope=SUBTREE,- attributes=["name","dNSHostName","operatingSystem","operatingSystemVersion",- "lastLogon","userAccountControl","primaryGroupID","whenCreated"])- computers = []- for e in conn.entries:- uac = int(e.userAccountControl.value or 0)- pgid = int(e.primaryGroupID.value or 0)- computers.append({- "name": str(e.name),- "dns": str(e.dNSHostName or ""),- "os": str(e.operatingSystem or "Unknown"),- "os_version": str(e.operatingSystemVersion or ""),- "is_dc": pgid in (516, 521), # Domain Controllers group- "enabled": not bool(uac & 0x0002),- "days_since_logon": _days_since_ts(e.lastLogon.value),- })- conn.unbind()- return computers+ try:+ conn.search(base, "(objectClass=computer)", search_scope=SUBTREE,+ attributes=["name","dNSHostName","operatingSystem","operatingSystemVersion",+ "lastLogon","userAccountControl","primaryGroupID","whenCreated"])+ computers = []+ for e in conn.entries:+ uac = int(e.userAccountControl.value or 0)+ pgid = int(e.primaryGroupID.value or 0)+ computers.append({+ "name": str(e.name),+ "dns": str(e.dNSHostName or ""),+ "os": str(e.operatingSystem or "Unknown"),+ "os_version": str(e.operatingSystemVersion or ""),+ "is_dc": pgid in (516, 521), # Domain Controllers group+ "enabled": not bool(uac & 0x0002),+ "days_since_logon": _days_since_ts(e.lastLogon.value),+ })+ return computers+ finally:+ try:+ conn.unbind()+ except Exception:+ passdef _analyze(self, raw):computers = raw.get("computer_list",[])diff --git a/tests/unit/test_ad_bind_behavior.py b/tests/unit/test_ad_bind_behavior.pyindex dffd28f..349e49e 100644--- a/tests/unit/test_ad_bind_behavior.py+++ b/tests/unit/test_ad_bind_behavior.py@@ -532,6 +532,108 @@ async def test_asreproast_candidate_hash_is_confirmed_with_high_confidence(monkeassert validation.confidence >= 0.90+def _install_fake_ldap3_ssl_close(monkeypatch):+ class FakeTls:+ def __init__(self, *args, **kwargs):+ self.args = args+ self.kwargs = kwargs++ class FakeServer:+ def __init__(self, *args, **kwargs):+ self.args = args+ self.kwargs = kwargs++ class FakeConnection:+ def __init__(self, *args, **kwargs):+ raise OSError(+ "socket ssl wrapping error: [WinError 10054] "+ "An existing connection was forcibly closed by the remote host"+ )++ ldap3_mod = types.ModuleType("ldap3")+ ldap3_mod.ALL = "ALL"+ ldap3_mod.NTLM = "NTLM"+ ldap3_mod.SUBTREE = "SUBTREE"+ ldap3_mod.AUTO_BIND_NO_TLS = "AUTO_BIND_NO_TLS"+ ldap3_mod.Connection = FakeConnection+ ldap3_mod.Server = FakeServer+ ldap3_mod.Tls = FakeTls+ monkeypatch.setitem(sys.modules, "ldap3", ldap3_mod)+++async def test_enum_computers_ssl_close_is_actionable_operator_error(monkeypatch):+ from ares.core.errors import ModuleValidationError+ from ares.modules.ad.enum_computers import ADEnumComputersModule++ _install_fake_ldap3_ssl_close(monkeypatch)+ module, _ = _make_module(ADEnumComputersModule)++ with pytest.raises(ModuleValidationError) as exc_info:+ await module.run(+ dc="10.0.0.5",+ domain="lab.local",+ username="[email protected]",+ password="Password1!",+ use_ldaps=False,+ )++ message = str(exc_info.value)+ assert exc_info.value.action == "abort"+ assert "module_error" not in message+ assert "use_ldaps=false" in message+ assert "389" in message and "636" in message+ assert "LDAP/LDAPS" in message+ assert "firewall" in message+ assert "certificate/LDAPS configuration" in message+ assert module._findings == []+ assert "Password1!" not in message+++async def test_enum_computers_config_error_does_not_retry(monkeypatch, minimal_campaign):+ from unittest.mock import AsyncMock, patch++ from ares.core.engine import AresEngine+ from ares.core.config import AresSettings+ from ares.core.noise import JitterEngine+ from ares.modules.ad.enum_computers import ADEnumComputersModule++ engine = AresEngine(settings=AresSettings())+ engine.load_modules()+ _install_fake_ldap3_ssl_close(monkeypatch)+ calls = 0++ original_fetch = ADEnumComputersModule._fetch_computers++ async def counted_fetch(self, *args, **kwargs):+ nonlocal calls+ calls += 1+ return await original_fetch(self, *args, **kwargs)++ monkeypatch.setattr(ADEnumComputersModule, "_fetch_computers", counted_fetch)+ async def no_noise_sleep(*args, **kwargs):+ return None++ monkeypatch.setattr(JitterEngine, "sleep", no_noise_sleep)+ params = {+ "dc": "10.0.0.5",+ "domain": "lab.local",+ "username": "[email protected]",+ "password": "Password1!",+ "use_ldaps": False,+ }+ with patch("ares.core.engine.asyncio.sleep", new=AsyncMock()) as retry_sleep:+ result = await engine.run_module("ad.enum_computers", minimal_campaign, params)++ assert calls == 1+ assert retry_sleep.await_count == 0+ assert result.outcome == "operator_error"+ assert result.findings == []+ assert "use_ldaps=false" in result.outcome_message+ assert "389" in result.outcome_message and "636" in result.outcome_message++@pytest.mark.asyncioasync def test_asreproast_candidate_kerberos_failure_is_candidate_aware(monkeypatch):import ares.modules.ad.asreproast as asreproast_mod