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: harden AD dependency preflight on Windows

Mafifrizi08f80fb09c65
diff --git a/QUICKSTART.md b/QUICKSTART.md
index dc49b97..8765219 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -67,6 +67,7 @@ Windows PowerShell:
```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[ad]"
+.\.venv\Scripts\python.exe -m pip install -e ".[ad-support]"
.\.venv\Scripts\python.exe -m pip install -e ".[cloud]"
.\.venv\Scripts\python.exe -m pip install -e ".[windows]"
.\.venv\Scripts\python.exe -m pip install -e ".[full]"
@@ -76,11 +77,20 @@ Linux/macOS:
```bash
python -m pip install -e ".[ad]"
+python -m pip install -e ".[ad-support]"
python -m pip install -e ".[cloud]"
python -m pip install -e ".[windows]"
python -m pip install -e ".[full]"
```
+For AD modules, use `.[ad]` for a normal full AD install. If `ares doctor`
+already reports `impacket` as importable from a source/local install, use
+`.[ad-support]` to install the remaining direct AD support libraries
+(`pyasn1`, `pyasn1_modules`, `ldap3`, and `httpx_ntlm`) without forcing another
+PyPI Impacket wheel install. After installing AD dependencies, restart
+`ares dashboard dev --no-reload`, rerun `ares doctor --pdf-smoke`, and confirm
+`pyasn1`, `pyasn1_modules`, `ldap3`, and `httpx_ntlm` are no longer missing.
+
### D. Install frontend dependencies
Windows PowerShell:
@@ -359,8 +369,8 @@ yet.`
| `ares` command not found on Windows | Use `.\.venv\Scripts\ares.exe ...` from the repository root. |
| `frontend/node_modules` missing | Run `npm ci` in `frontend/`, or start with `ares dashboard dev --install`. |
| PDF smoke warning on Windows | Use normal non-Administrator PowerShell, set `$env:ARES_PDF_BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"`, then run `.\.venv\Scripts\ares.exe doctor --pdf-smoke`. |
-| Optional module dependency warning | Install the relevant extra only when that module family is needed, for example `.[ad]`, `.[cloud]`, `.[windows]`, or `.[full]`. |
-| Impacket source/local install version unknown | OK if Impacket is importable; missing or too-old Impacket still warns. |
+| Optional module dependency warning | Install the relevant extra only when that module family is needed, for example `.[ad]`, `.[cloud]`, `.[windows]`, or `.[full]`. For source/local Impacket AD setups, use `.[ad-support]` for the remaining direct AD support libraries. |
+| Impacket source/local install version unknown | OK if Impacket is importable; install `.[ad-support]` if `pyasn1`, `pyasn1_modules`, `ldap3`, or `httpx_ntlm` still warn. Missing or too-old Impacket still warns. |
| `Invalid credentials` | Use the current admin password. Updating `ARES_DEFAULT_ADMIN_PASSWORD` after admin exists does not reset that password. |
| `Target is not in campaign scope` | Add the target CIDR to the campaign scope, for example `127.0.0.1/32` for local testing. |
| Report direct URL returns `401` | Use the authenticated dashboard Download button. |
diff --git a/README.md b/README.md
index b88d735..d212c17 100644
--- a/README.md
+++ b/README.md
@@ -401,7 +401,10 @@ first-run path from clone to report. The universal order is:
reports from the Report Library.
Optional module families are installed only when needed, for example `.[ad]`,
-`.[cloud]`, `.[windows]`, or `.[full]`.
+`.[cloud]`, `.[windows]`, or `.[full]`. For AD users with source/local
+Impacket already importable, use `.[ad-support]` for the remaining direct AD
+support libraries; see [QUICKSTART.md](QUICKSTART.md) for the full decision
+path.
---
diff --git a/ares/cli/typer_main.py b/ares/cli/typer_main.py
index 82a2a99..26ff29d 100644
--- a/ares/cli/typer_main.py
+++ b/ares/cli/typer_main.py
@@ -1160,6 +1160,7 @@ def doctor(
import importlib, shutil, os
from importlib import metadata as importlib_metadata
from pathlib import Path
+ from ares.modules.ad.dependencies import AD_INSTALL_HINT, AD_SUPPORT_DEPENDENCIES
console.print("\n[bold]ARES Doctor[/bold] — prerequisite check\n")
@@ -1240,7 +1241,7 @@ def doctor(
check(
label,
"warn",
- import_failure_detail(import_name, exc, "pip install ares-redteam[ad]"),
+ import_failure_detail(import_name, exc, AD_INSTALL_HINT),
)
elif pkg == "paramiko":
check(
@@ -1272,15 +1273,26 @@ def doctor(
check(
"impacket",
"warn",
- import_failure_detail("impacket", exc, "pip install ares-redteam[ad]"),
+ import_failure_detail("impacket", exc, AD_INSTALL_HINT),
)
+ # Direct AD support dependencies used by AD modules before runtime.
+ for import_name, label in AD_SUPPORT_DEPENDENCIES:
+ if import_name in {"ldap3", "httpx_ntlm"}:
+ continue
+ try:
+ mod = importlib.import_module(import_name)
+ ver = getattr(mod, "__version__", "")
+ check(label, "ok", ver or "available")
+ except Exception as exc:
+ check(label, "warn", import_failure_detail(import_name, exc, AD_INSTALL_HINT))
+
# ── ldap3 ─────────────────────────────────────────────────────────────────
try:
import ldap3
check(f"ldap3 {ldap3.__version__}", "ok", "AD LDAP enumeration ready")
except Exception as exc:
- check("ldap3", "warn", import_failure_detail("ldap3", exc, "pip install ares-redteam[ad]"))
+ check("ldap3", "warn", import_failure_detail("ldap3", exc, AD_INSTALL_HINT))
# ── optional Windows modules ───────────────────────────────────────────────
try:
@@ -1295,7 +1307,7 @@ def doctor(
check("httpx-ntlm (ad.adcs ESC1)", "ok", "ADCS HTTP enrollment ready")
except Exception as exc:
check("httpx-ntlm (ad.adcs ESC1)", "warn",
- import_failure_detail("httpx_ntlm", exc, "pip install ares-redteam[ad]"))
+ import_failure_detail("httpx_ntlm", exc, AD_INSTALL_HINT))
# ── cloud SDKs ────────────────────────────────────────────────────────────
for import_name, module_label in [
diff --git a/ares/modules/ad/asreproast.py b/ares/modules/ad/asreproast.py
index 9b84f87..a29172c 100644
--- a/ares/modules/ad/asreproast.py
+++ b/ares/modules/ad/asreproast.py
@@ -23,6 +23,7 @@ from ares.core.security import sanitize_hostname, sanitize_ldap
from ares.modules.base import BaseModule, OpsecLevel
from ares.core.tracing import trace_module
from ares.core.errors import ModuleValidationError
+from ares.modules.ad.dependencies import ensure_ad_dependencies
def _capture_asrep_raw(dc: str, domain: str, username: str) -> bytes | None:
@@ -189,6 +190,10 @@ class ASREPRoastModule(BaseModule):
@trace_module("ad.asreproast")
async def run(self, dc, domain, username=None, password=None,
userfile=None, usernames=None, **kwargs):
+ ensure_ad_dependencies(
+ ("impacket", "pyasn1", "pyasn1_modules"),
+ module_id=self.MODULE_ID,
+ )
dc, domain = sanitize_hostname(dc), sanitize_ldap(domain)
if username:
username = sanitize_ldap(username)
@@ -210,6 +215,8 @@ class ASREPRoastModule(BaseModule):
hashes, accounts = await self._get_asrep_hashes(
dc, domain, username, password, userfile, usernames or [], mode
)
+ except ModuleValidationError:
+ raise
except Exception as exc:
from ares.core.errors import NetworkError
raise NetworkError(f"ASREPRoast failed: {exc}") from exc
@@ -229,6 +236,10 @@ class ASREPRoastModule(BaseModule):
KDC_ERR_C_PRINCIPAL_UNKNOWN -> username does not exist
Success (returns AS-REP) -> account IS vulnerable, hash captured
"""
+ ensure_ad_dependencies(
+ ("impacket", "pyasn1", "pyasn1_modules"),
+ module_id=self.MODULE_ID,
+ )
from impacket.krb5.kerberosv5 import getKerberosTGT
from impacket.krb5.types import Principal
from impacket.krb5 import constants
@@ -289,6 +300,7 @@ class ASREPRoastModule(BaseModule):
async def _ldap_get_nopreauth(self, dc, domain, username, password):
"""Query LDAP for accounts with DONT_REQUIRE_PREAUTH enabled."""
+ ensure_ad_dependencies(("ldap3",), module_id=self.MODULE_ID)
import ssl
import ldap3
from ldap3 import Server, Connection, NTLM, SUBTREE, Tls, ALL
diff --git a/ares/modules/ad/dependencies.py b/ares/modules/ad/dependencies.py
new file mode 100644
index 0000000..a4e3943
--- /dev/null
+++ b/ares/modules/ad/dependencies.py
@@ -0,0 +1,38 @@
+"""Shared Active Directory optional dependency checks."""
+from __future__ import annotations
+
+import importlib
+from collections.abc import Iterable
+
+from ares.core.errors import ModuleValidationError
+
+
+AD_INSTALL_HINT = (
+ 'Install AD dependencies with .\\.venv\\Scripts\\python.exe -m pip install -e ".[ad]" '
+ 'for a normal source checkout, or .\\.venv\\Scripts\\python.exe -m pip install -e ".[ad-support]" '
+ "when using source/local Impacket; then restart the dashboard and rerun "
+ "ares doctor --pdf-smoke."
+)
+
+AD_SUPPORT_DEPENDENCIES: tuple[tuple[str, str], ...] = (
+ ("pyasn1", "pyasn1 (AD Kerberos helpers)"),
+ ("pyasn1_modules", "pyasn1_modules (AD Kerberos helpers)"),
+ ("ldap3", "ldap3 (AD LDAP enumeration)"),
+ ("httpx_ntlm", "httpx-ntlm (ADCS HTTP enrollment)"),
+)
+
+
+def ensure_ad_dependencies(import_names: Iterable[str], *, module_id: str) -> None:
+ """Raise a non-retryable ARES validation error for missing AD local deps."""
+ for import_name in import_names:
+ try:
+ importlib.import_module(import_name)
+ except (ImportError, OSError, RuntimeError) as exc:
+ raise ModuleValidationError(
+ (
+ f"{module_id} cannot run because AD dependency {import_name!r} "
+ f"is missing or broken ({exc.__class__.__name__}). {AD_INSTALL_HINT}"
+ ),
+ module_id=module_id,
+ field=import_name,
+ ) from exc
diff --git a/ares/modules/ad/kerberoast.py b/ares/modules/ad/kerberoast.py
index c02bf82..42cd6d6 100644
--- a/ares/modules/ad/kerberoast.py
+++ b/ares/modules/ad/kerberoast.py
@@ -12,6 +12,8 @@ from ares.core.campaign import Finding, Severity, NoiseProfile
from ares.core.security import sanitize_hostname, sanitize_ldap
from ares.modules.base import BaseModule, OpsecLevel
from ares.core.tracing import trace_module
+from ares.core.errors import ModuleValidationError
+from ares.modules.ad.dependencies import ensure_ad_dependencies
def _format_krb5tgs_hash(tgs: bytes, cipher: "Any", spn: str, domain: str) -> str:
@@ -119,6 +121,10 @@ class KerberoastModule(BaseModule):
@trace_module("ad.kerberoast")
async def run(self, dc, username, password, domain, target_user=None, **kwargs):
+ ensure_ad_dependencies(
+ ("impacket", "pyasn1", "pyasn1_modules"),
+ module_id=self.MODULE_ID,
+ )
dc, username, domain = sanitize_hostname(dc), sanitize_ldap(username), sanitize_ldap(domain)
if self.campaign.noise_profile == NoiseProfile.STEALTH:
logger.warning("kerberoast_skipped", reason="stealth_profile")
@@ -127,6 +133,8 @@ class KerberoastModule(BaseModule):
logger.info("kerberoast_start", dc=dc, domain=domain, target=target_user)
try:
hashes, accounts = await self._request_tickets(dc, username, password, domain, target_user)
+ except ModuleValidationError:
+ raise
except Exception as exc:
from ares.core.errors import AuthenticationFailed, NetworkError
err = str(exc).lower()
@@ -144,6 +152,10 @@ class KerberoastModule(BaseModule):
Fix Bug 2: Jitter after every single TGS request — not burst then sleep.
Fix Bug 3: Explicit per-noise-profile rate limit (10/min NORMAL, 50/min AGGRESSIVE).
"""
+ ensure_ad_dependencies(
+ ("impacket", "pyasn1", "pyasn1_modules"),
+ module_id=self.MODULE_ID,
+ )
from impacket.krb5.kerberosv5 import getKerberosTGT, getKerberosTGS
from impacket.krb5.types import Principal
from impacket.krb5 import constants
diff --git a/docs/modules.md b/docs/modules.md
index 2fa5ebe..6179a39 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -92,6 +92,10 @@ Invoke-RestMethod `
Optional extras and native tools depend on the module family. The base
dashboard/reporting workflow uses the `dev,pdf` baseline; install `.[ad]`,
`.[cloud]`, `.[windows]`, or `.[full]` only when those modules are needed.
+For AD modules, `.[ad]` is the normal full install. If `ares doctor` already
+shows Impacket as importable from a source/local install, use `.[ad-support]`
+to install the direct AD support libraries (`pyasn1`, `pyasn1_modules`,
+`ldap3`, and `httpx_ntlm`) without forcing another Impacket wheel install.
## Module Categories
diff --git a/pyproject.toml b/pyproject.toml
index 23f283e..f70b1d1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -66,11 +66,19 @@ postgres = [
]
ad = [
"impacket>=0.11",
+ "pyasn1>=0.5",
+ "pyasn1-modules>=0.3",
"ldap3>=2.9",
"pywinrm>=0.4",
"asyncssh>=2.14",
"httpx-ntlm>=1.4", # ADCS ESC1 HTTP enrollment (ad.adcs exploit_esc1)
]
+ad-support = [
+ "pyasn1>=0.5",
+ "pyasn1-modules>=0.3",
+ "ldap3>=2.9",
+ "httpx-ntlm>=1.4",
+]
cloud = [
"boto3>=1.34",
"botocore>=1.34",
diff --git a/requirements-lock.txt b/requirements-lock.txt
index 383121b..42af9aa 100644
--- a/requirements-lock.txt
+++ b/requirements-lock.txt
@@ -68,11 +68,19 @@ paramiko>=3.4
# [ad] extra - Active Directory + SMB
impacket>=0.11
+pyasn1>=0.5
+pyasn1-modules>=0.3
ldap3>=2.9
pywinrm>=0.4
asyncssh>=2.14
httpx-ntlm>=1.4
+# [ad-support] extra - AD support deps for source/local Impacket users
+pyasn1>=0.5
+pyasn1-modules>=0.3
+ldap3>=2.9
+httpx-ntlm>=1.4
+
# [cloud] extra
boto3>=1.34
botocore>=1.34
diff --git a/tests/unit/test_ad_dependency_preflight.py b/tests/unit/test_ad_dependency_preflight.py
new file mode 100644
index 0000000..228e777
--- /dev/null
+++ b/tests/unit/test_ad_dependency_preflight.py
@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import sys
+import types
+
+import pytest
+
+from ares.core.errors import ModuleValidationError, NetworkError
+
+
+async def test_asreproast_missing_pyasn1_is_actionable_preflight_error(monkeypatch):
+ from ares.modules.ad.asreproast import ASREPRoastModule
+
+ monkeypatch.setitem(sys.modules, "impacket", types.ModuleType("impacket"))
+ monkeypatch.setitem(sys.modules, "pyasn1", None)
+ monkeypatch.setitem(sys.modules, "pyasn1_modules", types.ModuleType("pyasn1_modules"))
+
+ module = object.__new__(ASREPRoastModule)
+
+ with pytest.raises(ModuleValidationError) as exc_info:
+ await module.run(
+ dc="127.0.0.1",
+ domain="corp.local",
+ usernames=["alice"],
+ )
+
+ message = str(exc_info.value)
+ assert exc_info.value.action == "abort"
+ assert exc_info.value.field == "pyasn1"
+ assert not isinstance(exc_info.value, NetworkError)
+ assert "ad.asreproast" in message
+ assert "pyasn1" in message
+ assert "Install AD dependencies" in message
+ assert "restart the dashboard" in message
+ assert "No module named" not in message
+
+
+async def test_kerberoast_missing_impacket_is_actionable_preflight_error(monkeypatch):
+ from ares.modules.ad.kerberoast import KerberoastModule
+
+ monkeypatch.setitem(sys.modules, "impacket", None)
+ monkeypatch.setitem(sys.modules, "pyasn1", types.ModuleType("pyasn1"))
+ monkeypatch.setitem(sys.modules, "pyasn1_modules", types.ModuleType("pyasn1_modules"))
+
+ module = object.__new__(KerberoastModule)
+
+ with pytest.raises(ModuleValidationError) as exc_info:
+ await module.run(
+ dc="127.0.0.1",
+ username="alice",
+ password="Password123!",
+ domain="corp.local",
+ target_user="HTTP/web.corp.local",
+ )
+
+ message = str(exc_info.value)
+ assert exc_info.value.action == "abort"
+ assert exc_info.value.field == "impacket"
+ assert not isinstance(exc_info.value, NetworkError)
+ assert "ad.kerberoast" in message
+ assert "impacket" in message
+ assert "Install AD dependencies" in message
+ assert "restart the dashboard" in message
+ assert "No module named" not in message
diff --git a/tests/unit/test_cli_doctor.py b/tests/unit/test_cli_doctor.py
index 4d31fae..7f602dd 100644
--- a/tests/unit/test_cli_doctor.py
+++ b/tests/unit/test_cli_doctor.py
@@ -3,6 +3,7 @@ from __future__ import annotations
import importlib.metadata
import os
import sys
+import tomllib
import types
from collections import namedtuple
from pathlib import Path
@@ -51,7 +52,7 @@ def test_doctor_uses_distribution_metadata_for_impacket(monkeypatch, tmp_path, c
assert "impacket 0.13.1" in output
assert "[WARN] impacket" not in output
assert "too old (0.0.0)" not in output
- assert "ares-redteam[ad]" in output
+ assert "ad-support" in output
def test_doctor_accepts_supported_impacket_metadata_version(monkeypatch, tmp_path, capsys):
@@ -159,10 +160,60 @@ def test_doctor_warns_when_impacket_import_fails(monkeypatch, tmp_path, capsys):
output = _run_doctor(monkeypatch, tmp_path, capsys)
assert "[WARN] impacket" in output
- assert "pip install ares-redteam[ad]" in output
+ assert '".[ad]"' in output
assert "installed, but version could not be detected" not in output
+def test_doctor_warns_for_missing_direct_ad_support_dependencies(
+ monkeypatch, tmp_path, capsys
+):
+ fake_impacket = types.ModuleType("impacket")
+
+ def fake_version(package_name: str) -> str:
+ if package_name == "impacket":
+ return "0.13.1"
+ raise importlib.metadata.PackageNotFoundError(package_name)
+
+ monkeypatch.setattr(importlib.metadata, "version", fake_version)
+ monkeypatch.setitem(sys.modules, "impacket", fake_impacket)
+ for import_name in ("pyasn1", "pyasn1_modules", "ldap3", "httpx_ntlm"):
+ monkeypatch.setitem(sys.modules, import_name, None)
+
+ output = _run_doctor(monkeypatch, tmp_path, capsys)
+ normalized = " ".join(output.split())
+
+ assert "[WARN] pyasn1 (AD Kerberos helpers)" in output
+ assert "[WARN] pyasn1_modules (AD Kerberos helpers)" in output
+ assert "[WARN] ldap3" in output
+ assert "[WARN] httpx-ntlm (ad.adcs ESC1)" in output
+ assert "install -e \".[ad]\"" in normalized
+ assert "install -e \".[ad-support]\"" in normalized
+ assert "restart the dashboard" in normalized
+
+
+def test_pyproject_exposes_ad_support_extra_for_source_impacket_users():
+ pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+ extras = pyproject["project"]["optional-dependencies"]
+
+ assert "ad-support" in extras
+ assert {"pyasn1>=0.5", "pyasn1-modules>=0.3", "ldap3>=2.9", "httpx-ntlm>=1.4"} <= set(
+ extras["ad-support"]
+ )
+ assert {"pyasn1>=0.5", "pyasn1-modules>=0.3"} <= set(extras["ad"])
+
+
+def test_docs_mention_ad_support_extra_for_source_impacket_users():
+ docs = "\n".join(
+ Path(path).read_text(encoding="utf-8")
+ for path in ("README.md", "QUICKSTART.md", "docs/modules.md")
+ )
+
+ assert ".[ad-support]" in docs
+ assert "source/local" in docs
+ assert "Impacket" in docs
+ assert "pyasn1_modules" in docs
+
+
def test_doctor_reports_broken_optional_import_and_continues(monkeypatch, tmp_path, capsys):
import importlib
diff --git a/tests/unit/test_property_based.py b/tests/unit/test_property_based.py
index 6bfd9fc..d770c18 100644
--- a/tests/unit/test_property_based.py
+++ b/tests/unit/test_property_based.py
@@ -316,7 +316,7 @@ class TestDataEncryptorProperties:
_enc = DataEncryptor("hypothesis-test-encryption-key!!")
@given(st.text(min_size=0, max_size=1000))
- @settings(max_examples=200, suppress_health_check=[HealthCheck.too_slow])
+ @settings(max_examples=200, deadline=None, suppress_health_check=[HealthCheck.too_slow])
def test_roundtrip_any_text(self, value: str) -> None:
"""encrypt → decrypt must recover original value for any text."""
enc = DataEncryptor("hyp-test-key-32chars-minimum-req")
@@ -326,7 +326,7 @@ class TestDataEncryptorProperties:
)
@given(st.binary(min_size=1, max_size=50))
- @settings(max_examples=200)
+ @settings(max_examples=200, deadline=None)
def test_tampered_returns_none(self, noise: bytes) -> None:
"""Appending random bytes to ciphertext must return None, never raise."""
enc = DataEncryptor("hyp-test-key-32chars-minimum-req")
@@ -342,7 +342,7 @@ class TestDataEncryptorProperties:
assert result is None
@given(st.text(min_size=0, max_size=500))
- @settings(max_examples=200, suppress_health_check=[HealthCheck.too_slow])
+ @settings(max_examples=200, deadline=None, suppress_health_check=[HealthCheck.too_slow])
def test_different_keys_cant_decrypt(self, value: str) -> None:
"""Ciphertext from key A must not be decryptable by key B."""
enc_a = DataEncryptor("key-a-for-hypothesis-test-32ch!!")