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
feat(modules): modernize Wave 2 Active Directory modules to Next-Gen Sovereign SDK v2
Mafifrizib6c1a62dee7d
diff --git a/ares/modules/ad/adcs.py b/ares/modules/ad/adcs.pyindex 7c0bb3d..8cbfc8a 100644--- a/ares/modules/ad/adcs.py+++ b/ares/modules/ad/adcs.py@@ -26,8 +26,21 @@ from typing import Anyfrom ares.core.campaign import Finding, Severityfrom ares.core.logger import audit, get_loggerfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_module+from ares.core.errors import ModuleValidationError+from ares.modules.params import ADCSParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ UntrustedTargetData,+ module_contract,+)logger = get_logger("ares.modules.ad.adcs")@@ -51,7 +64,15 @@ _DANGEROUS_RIGHTS = {}-class ADCSModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[80, 443, 389, 636], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=ADCSParams,+)+class ADCSModule(BaseModule[ADCSParams, ModuleResult]):"""ad.adcs — Detect ADCS ESC1–ESC8 misconfigurations via LDAP. Exploit ESC1 to obtain a certificate as any us@@ -72,6 +93,7 @@ class ADCSModule(BaseModule):OUTPUTS = ["adcs_findings", "certificate"]MITRE_TECHNIQUES = ["T1649"]MODULE_TIMEOUT_SECONDS: int | None = 180 # seconds+ PARAMS_MODEL = ADCSParamsasync def assess_feasibility(self, ctx: "Any") -> Any:"""@@ -122,7 +144,6 @@ class ADCSModule(BaseModule):)async def validate(self, ctx: "Any") -> None:- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -143,6 +164,11 @@ class ADCSModule(BaseModule):"ad.adcs requires domain credentials — pass 'username'/'password'.",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+).@@ -161,6 +187,27 @@ class ADCSModule(BaseModule):username=ad["username"], password=ad["password"],exploit_esc1=exploit_esc1, target_user=target_user,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"adcs-{finding.title[:20].lower().replace(' ', '-')}",+ source_target=ad["dc"],+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "severity": str(finding.severity),+ "description": finding.description,+ "mitre": finding.mitre_technique,+ },+ tags=["ad", "adcs", "certificates"],+ )+ 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]+return ModuleResult(status="success" if (findings or raw) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/ad/asreproast.py b/ares/modules/ad/asreproast.pyindex d223bad..2ed57db 100644--- a/ares/modules/ad/asreproast.py+++ b/ares/modules/ad/asreproast.py@@ -21,9 +21,21 @@ from ares.core.logger import get_loggerlogger = get_logger("ares.modules.ad.asreproast")from ares.core.campaign import Finding, Severityfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_modulefrom ares.core.errors import AresError, ModuleValidationError+from ares.modules.params import ASREPRoastParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ UntrustedTargetData,+ module_contract,+)from ares.modules.ad.dependencies import (ad_bind_dry_run_metadata,build_ad_bind_plan,@@ -196,7 +208,15 @@ def classify_asrep_request_error(exc: BaseException) -> tuple[str, str]:return "module_error", _sanitize_asrep_failure_reason(exc)-class ASREPRoastModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[88, 389, 636], protocols=["tcp", "udp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=ASREPRoastParams,+)+class ASREPRoastModule(BaseModule[ASREPRoastParams, ModuleResult]):"""ad.asreproast — Capture AS-REP hashes from accounts without Kerberos pre-auth@@ -213,6 +233,7 @@ class ASREPRoastModule(BaseModule):REQUIRES = []OUTPUTS = ["asrep_hashes"]MITRE_TECHNIQUES = ["T1558.004"]+ PARAMS_MODEL = ASREPRoastParamsasync def assess_feasibility(self, ctx: "Any") -> Any:"""@@ -269,12 +290,12 @@ class ASREPRoastModule(BaseModule):domain = ctx.params.get("domain") or ctx.domainif not dc:raise ModuleValidationError(- "ad.asreproast requires \'dc\' (Domain Controller IP)",+ "ad.asreproast requires 'dc' (Domain Controller IP)",module_id=self.MODULE_ID, field="dc",)if not domain:raise ModuleValidationError(- "ad.asreproast requires \'domain\' (e.g. corp.local)",+ "ad.asreproast requires 'domain' (e.g. corp.local)",module_id=self.MODULE_ID, field="domain",)ad = self._extract_ad_params(ctx)@@ -284,10 +305,20 @@ class ASREPRoastModule(BaseModule):if not has_creds and not has_file and not has_list:raise ModuleValidationError("ad.asreproast requires one of: domain credentials (username+password), "- "\'userfile\' param (path to username list), or "- "\'usernames\' param (inline list).",+ "'userfile' param (path to username list), or "+ "'usernames' param (inline list).",module_id=self.MODULE_ID, field="usernames",)+ if isinstance(ctx.params, dict):+ if "dc" not in ctx.params and dc:+ ctx.params["dc"] = dc+ if "domain" not in ctx.params and domain:+ ctx.params["domain"] = domain+ if ad.get("username") and "username" not in ctx.params:+ ctx.params["username"] = ad["username"]+ if ad.get("password") and "password" not in ctx.params:+ ctx.params["password"] = ad["password"]+ await super().validate(ctx)async def execute(self, ctx: "Any") -> "ModuleResult":"""ExecutionContext-based entry point (v0.9.0+)."""@@ -318,6 +349,27 @@ class ASREPRoastModule(BaseModule):dc=dc, username=username, password=password,domain=domain, userfile=userfile, usernames=usernames,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"asrep-{finding.title[:20].lower().replace(' ', '-')}",+ source_target=dc,+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "severity": str(finding.severity),+ "description": finding.description,+ "mitre": finding.mitre_technique,+ },+ tags=["ad", "asrep", "asreproast"],+ )+ 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]+return ModuleResult(status="success" if (findings or raw) else "partial",findings=findings, raw=raw,diff --git a/ares/modules/ad/coerce.py b/ares/modules/ad/coerce.pyindex 3d741f3..19b7dfd 100644--- a/ares/modules/ad/coerce.py+++ b/ares/modules/ad/coerce.py@@ -28,13 +28,34 @@ from typing import Anyfrom ares.core.campaign import Finding, Severity, NoiseProfilefrom ares.core.logger import audit, get_loggerfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_module+from ares.core.errors import ModuleValidationError+from ares.modules.params import CoerceParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ UntrustedTargetData,+ module_contract,+)logger = get_logger("ares.modules.ad.coerce")-class CoerceModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[135, 445], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=CoerceParams,+)+class CoerceModule(BaseModule[CoerceParams, ModuleResult]):"""ad.coerce — Force target to authenticate to attacker listener via PetitPotam (MS-EFSRPC@@ -56,9 +77,9 @@ class CoerceModule(BaseModule):OUTPUTS = ["coercion_sent"]MITRE_TECHNIQUES = ["T1187"]MODULE_AUTHOR = "ARES Team <[email protected]>"+ PARAMS_MODEL = CoerceParamsasync def validate(self, ctx: "Any") -> None:- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -86,6 +107,11 @@ class CoerceModule(BaseModule):"Start lateral.smb_relay first, then run ad.coerce.",module_id=self.MODULE_ID, field="listener_ip",)+ 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+).@@ -104,6 +130,27 @@ class CoerceModule(BaseModule):dc=ad["dc"], username=ad["username"], password=ad["password"],domain=ad["domain"], listener_ip=listener_ip, method=method,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"coerce-{finding.title[:20].lower().replace(' ', '-')}",+ source_target=ad["dc"],+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "severity": str(finding.severity),+ "description": finding.description,+ "mitre": finding.mitre_technique,+ },+ tags=["ad", "coerce", "forced_auth"],+ )+ 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]+return ModuleResult(status="success" if findings else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/ad/dcsync.py b/ares/modules/ad/dcsync.pyindex 3c25e76..6169880 100644--- a/ares/modules/ad/dcsync.py+++ b/ares/modules/ad/dcsync.py@@ -10,10 +10,31 @@ from ares.core.logger import get_loggerlogger = get_logger("ares.modules.ad.dcsync")from ares.core.campaign import Finding, Severity, NoiseProfilefrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_module+from ares.core.errors import ModuleValidationError+from ares.modules.params import DCSyncParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ UntrustedTargetData,+ module_contract,+)-class DCSyncModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[135, 445], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=DCSyncParams,+)+class DCSyncModule(BaseModule[DCSyncParams, ModuleResult]):"""ad.dcsync — Replicate domain hashes via MS-DRSR (requires DA or replication rights)@@ -33,6 +54,7 @@ class DCSyncModule(BaseModule):OUTPUTS = ["ntlm_hashes"]MITRE_TECHNIQUES = ["T1003.006"]MODULE_TIMEOUT_SECONDS: int | None = 600 # seconds+ PARAMS_MODEL = DCSyncParamsasync def assess_feasibility(self, ctx: "Any") -> Any:"""@@ -93,7 +115,6 @@ class DCSyncModule(BaseModule):Enforce dc, domain, domain-admin credentials, and noise profile.DCSync requires DA-level credentials — catch misconfigured runs early."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorfrom ares.core.campaign import NoiseProfile@@ -125,6 +146,11 @@ class DCSyncModule(BaseModule):"immediately. Use NORMAL or AGGRESSIVE profile.",module_id=self.MODULE_ID, field="noise_profile",)+ 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."""@@ -140,6 +166,27 @@ class DCSyncModule(BaseModule):findings, raw = await self.run(dc=dc, username=username, password=password, domain=domain, target_user=target_user,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"dcsync-{finding.title[:20].lower().replace(' ', '-')}",+ source_target=dc,+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "severity": str(finding.severity),+ "description": finding.description,+ "mitre": finding.mitre_technique,+ },+ tags=["ad", "dcsync", "ntlm"],+ )+ 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]+return ModuleResult(status="success" if (findings or raw) else "partial",findings=findings, raw=raw,diff --git a/ares/modules/ad/delegation_abuse.py b/ares/modules/ad/delegation_abuse.pyindex e55518d..4456887 100644--- a/ares/modules/ad/delegation_abuse.py+++ b/ares/modules/ad/delegation_abuse.py@@ -29,13 +29,34 @@ from typing import Anyfrom ares.core.campaign import Finding, Severityfrom ares.core.logger import audit, get_loggerfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_module+from ares.core.errors import ModuleValidationError+from ares.modules.params import DelegationAbuseParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ UntrustedTargetData,+ module_contract,+)logger = get_logger("ares.modules.ad.delegation_abuse")-class DelegationAbuseModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[88, 389, 636, 445], protocols=["tcp", "udp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=DelegationAbuseParams,+)+class DelegationAbuseModule(BaseModule[DelegationAbuseParams, ModuleResult]):"""ad.delegation_abuse — Exploit unconstrained / constrained / RBCD Kerberos delegation. RBCD: GenericWrite on computer →@@ -56,9 +77,9 @@ class DelegationAbuseModule(BaseModule):REQUIRES = []OUTPUTS = ["kerberos_ticket", "owned_hosts"]MITRE_TECHNIQUES = ["T1558.001", "T1134.001"]+ PARAMS_MODEL = DelegationAbuseParamsasync def validate(self, ctx: "Any") -> None:- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -87,6 +108,11 @@ class DelegationAbuseModule(BaseModule):"the computer object where GenericWrite was found by ad.enum_acl.",module_id=self.MODULE_ID, field="target_computer",)+ 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+).@@ -108,6 +134,27 @@ class DelegationAbuseModule(BaseModule):mode=mode, target_computer=target_computer,impersonate_user=impersonate_user, target_service=target_service,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"deleg-{finding.title[:20].lower().replace(' ', '-')}",+ source_target=ad["dc"],+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "severity": str(finding.severity),+ "description": finding.description,+ "mitre": finding.mitre_technique,+ },+ tags=["ad", "delegation", "kerberos"],+ )+ 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]+return ModuleResult(status="success" if findings else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/ad/enum_acl.py b/ares/modules/ad/enum_acl.pyindex c68fac1..77e8ec9 100644--- a/ares/modules/ad/enum_acl.py+++ b/ares/modules/ad/enum_acl.py@@ -10,8 +10,21 @@ from ares.core.logger import get_loggerlogger = get_logger("ares.modules.ad.enum_acl")from ares.core.campaign import Finding, Severityfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_module+from ares.core.errors import ModuleValidationError+from ares.modules.params import DomainAuthParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ UntrustedTargetData,+ module_contract,+)# Active Directory extended rights GUIDsDCSYNC_RIGHTS = {@@ -19,7 +32,15 @@ DCSYNC_RIGHTS = {"1131f6ad-9c07-11d1-f79f-00c04fc2dcd2": "DS-Replication-Get-Changes-All",}-class ADEnumACLModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[389, 636], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=DomainAuthParams,+)+class ADEnumACLModule(BaseModule[DomainAuthParams, ModuleResult]):"""ad.enum_acl — Find WriteDACL, GenericAll, GenericWrite, DCSync delegation misconfigs@@ -32,10 +53,10 @@ class ADEnumACLModule(BaseModule):MODULE_AUTHOR = "ARES Team <[email protected]>"OPSEC_LEVEL=OpsecLevel.LOW; REQUIRES=[]; OUTPUTS=["acl_findings"]MITRE_TECHNIQUES=["T1222.001","T1003.006"]+ PARAMS_MODEL = DomainAuthParamsasync def validate(self, ctx: "Any") -> None:"""Enforce dc, domain, and credentials before any LDAP connection is made."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -57,6 +78,11 @@ class ADEnumACLModule(BaseModule):"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."""@@ -71,6 +97,27 @@ class ADEnumACLModule(BaseModule):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 finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"acl-{finding.title[:20].lower().replace(' ', '-')}",+ source_target=dc,+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "severity": str(finding.severity),+ "description": finding.description,+ "mitre": finding.mitre_technique,+ },+ tags=["ad", "acl", "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]+return ModuleResult(status="success" if (findings or raw) else "partial",findings=findings, raw=raw,diff --git a/ares/modules/ad/enum_computers.py b/ares/modules/ad/enum_computers.pyindex e230860..9b56f01 100644--- a/ares/modules/ad/enum_computers.py+++ b/ares/modules/ad/enum_computers.py@@ -12,7 +12,18 @@ from ares.core.logger import get_loggerlogger = get_logger("ares.modules.ad.enum_computers")from ares.core.campaign import Finding, Severityfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import DomainAuthParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ module_contract,+)from ares.core.tracing import trace_modulefrom ares.core.errors import AresError, ModuleValidationError, NetworkErrorfrom ares.modules.ad.dependencies import build_ad_bind_plan@@ -64,7 +75,15 @@ def _format_ldap_connection_failure(f"Reason: {_safe_ldap_exception_text(exc)}")-class ADEnumComputersModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[389, 636], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=DomainAuthParams,+)+class ADEnumComputersModule(BaseModule[DomainAuthParams, ModuleResult]):"""ad.enum_computers — Enumerate domain computers, OS versions, stale accounts, DCs@@ -77,10 +96,10 @@ class ADEnumComputersModule(BaseModule):MODULE_AUTHOR = "ARES Team <[email protected]>"OPSEC_LEVEL=OpsecLevel.LOW; REQUIRES=[]; OUTPUTS=["computer_list"]MITRE_TECHNIQUES=["T1018","T1087.002"]+ PARAMS_MODEL = DomainAuthParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight param checks before any network call."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -101,6 +120,11 @@ class ADEnumComputersModule(BaseModule):"ad.enum_computers requires domain credentials.",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."""@@ -117,6 +141,28 @@ class ADEnumComputersModule(BaseModule):dc=dc, username=username, password=password, domain=domain,use_ldaps=use_ldaps,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for comp in raw.get("computer_list", []):+ ev = EvidenceRecord(+ artifact_id=f"computer-{comp.get('name', 'unknown').lower()}",+ source_target=dc,+ collected_by=self.MODULE_ID,+ data={+ "name": comp.get("name"),+ "os": comp.get("os"),+ "os_version": comp.get("os_version"),+ "is_dc": comp.get("is_dc", False),+ "dns_name": comp.get("dns_name"),+ },+ tags=["ad", "computer", "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]+return ModuleResult(status="success" if (findings or raw) else "partial",findings=findings, raw=raw,diff --git a/ares/modules/ad/enum_spn.py b/ares/modules/ad/enum_spn.pyindex fd6a1dd..e3dcd84 100644--- a/ares/modules/ad/enum_spn.py+++ b/ares/modules/ad/enum_spn.py@@ -7,7 +7,18 @@ from ares.core.logger import get_loggerlogger = get_logger("ares.modules.ad.enum_spn")from ares.core.campaign import Finding, Severityfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import DomainAuthParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ module_contract,+)from ares.core.tracing import trace_modulefrom ares.core.errors import AresError, ModuleValidationErrorfrom ares.modules.ad.dependencies import (@@ -37,7 +48,15 @@ def classify_enum_spn_outcome(spn_count: int) -> tuple[str, str]:"LDAP completed successfully; no enabled user accounts with service principals were found.",)-class ADEnumSPNModule(BaseModule):+@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)@@ -50,10 +69,10 @@ class ADEnumSPNModule(BaseModule):MODULE_AUTHOR = "ARES Team <[email protected]>"OPSEC_LEVEL=OpsecLevel.LOW; REQUIRES=[]; OUTPUTS=["spn_list"]MITRE_TECHNIQUES=["T1558.003","T1087.002"]+ PARAMS_MODEL = DomainAuthParamsasync def validate(self, ctx: "Any") -> None:"""Enforce dc, domain, and credentials before any LDAP connection is made."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -75,6 +94,11 @@ class ADEnumSPNModule(BaseModule):"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."""@@ -94,6 +118,26 @@ class ADEnumSPNModule(BaseModule):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("spn_list", []):+ ev = EvidenceRecord(+ artifact_id=f"spn-{spn.get('samAccountName', 'unknown').lower()}",+ source_target=dc,+ collected_by=self.MODULE_ID,+ data={+ "samAccountName": spn.get("samAccountName"),+ "spns": spn.get("spns"),+ "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]+return ModuleResult(status="success" if (findings or raw) else "partial",findings=findings, raw=raw,diff --git a/ares/modules/ad/enum_users.py b/ares/modules/ad/enum_users.pyindex 1a9df73..1f469e0 100644--- a/ares/modules/ad/enum_users.py+++ b/ares/modules/ad/enum_users.py@@ -14,7 +14,18 @@ from ares.core.logger import get_loggerlogger = get_logger("ares.modules.ad.enum_users")from ares.core.campaign import Finding, Severityfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import DomainAuthParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ module_contract,+)from ares.core.tracing import trace_modulefrom ares.core.errors import AresError, ModuleValidationError, NetworkErrorfrom ares.modules.ad.dependencies import (@@ -42,7 +53,15 @@ def _days_since(dt: datetime.datetime | None) -> int | None:return Nonereturn max(0, (datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None) - dt).days)-class ADEnumUsersModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[389, 636], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=DomainAuthParams,+)+class ADEnumUsersModule(BaseModule[DomainAuthParams, ModuleResult]):"""ad.enum_users — Enumerate domain users, attributes, dormant accounts, password policy@@ -60,10 +79,10 @@ class ADEnumUsersModule(BaseModule):OUTPUTS = ["user_list"]MITRE_TECHNIQUES = ["T1087.002", "T1201"]MODULE_TIMEOUT_SECONDS: int | None = 90 # seconds+ PARAMS_MODEL = DomainAuthParamsasync def validate(self, ctx: "Any") -> None:"""Enforce dc, domain, and credentials before any LDAP connection is made."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -86,6 +105,11 @@ class ADEnumUsersModule(BaseModule):"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."""@@ -101,6 +125,30 @@ class ADEnumUsersModule(BaseModule):findings, raw = await self.run(dc=dc, username=username, password=password, domain=domain, use_ldaps=use_ldaps,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for user in raw.get("user_list", []):+ username_val = user.get("samAccountName", user.get("username", "unknown"))+ ev = EvidenceRecord(+ artifact_id=f"user-{str(username_val).lower()}",+ source_target=dc,+ collected_by=self.MODULE_ID,+ data={+ "username": username_val,+ "enabled": user.get("enabled", True),+ "admin_count": user.get("adminCount", 0),+ "spns": user.get("spns", []),+ "dont_expire_password": user.get("dontExpirePassword", False),+ "no_preauth": user.get("noPreauth", False),+ },+ tags=["ad", "user", "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]+return ModuleResult(status="success" if (findings or raw) else "partial",findings=findings, raw=raw,diff --git a/ares/modules/ad/kerberoast.py b/ares/modules/ad/kerberoast.pyindex 649e7a3..608c3f3 100644--- a/ares/modules/ad/kerberoast.py+++ b/ares/modules/ad/kerberoast.py@@ -12,9 +12,21 @@ from ares.core.logger import get_loggerlogger = get_logger("ares.modules.ad.kerberoast")from ares.core.campaign import Finding, Severity, NoiseProfilefrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_modulefrom ares.core.errors import AresError, ModuleValidationError+from ares.modules.params import KerberoastParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ UntrustedTargetData,+ module_contract,+)from ares.modules.ad.dependencies import (ad_bind_dry_run_metadata,ensure_ad_dependencies,@@ -229,7 +241,15 @@ def classify_kerberoast_outcome("LDAP completed successfully; no service principal candidates were found.",)-class KerberoastModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[88, 389, 636, 3268, 3269], protocols=["tcp", "udp"]),+ ProcessPermission(allow_subprocesses=True, allowed_binaries=["python", "python3"]),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=KerberoastParams,+)+class KerberoastModule(BaseModule[KerberoastParams, ModuleResult]):"""ad.kerberoast — Request TGS tickets for SPN accounts — hashcat-ready hashes@@ -247,6 +267,7 @@ class KerberoastModule(BaseModule):REQUIRES = ["domain_creds"]OUTPUTS = ["kerberos_hashes"]MITRE_TECHNIQUES = ["T1558.003"]+ PARAMS_MODEL = KerberoastParamsasync def assess_feasibility(self, ctx: "Any") -> Any:"""@@ -308,7 +329,6 @@ class KerberoastModule(BaseModule):Enforce dc, domain, and domain credentials.Also block early in STEALTH profile — each TGS request logs Event ID 4769."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorfrom ares.core.campaign import NoiseProfile@@ -340,6 +360,11 @@ class KerberoastModule(BaseModule):"detected by SIEM. Use NORMAL or AGGRESSIVE profile.",module_id=self.MODULE_ID, field="noise_profile",)+ 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."""@@ -361,6 +386,27 @@ class KerberoastModule(BaseModule):findings, raw = await self.run(dc=dc, username=username, password=password, domain=domain, target_user=target_user,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"kerb-{finding.title[:20].lower().replace(' ', '-')}",+ source_target=dc,+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "severity": str(finding.severity),+ "description": finding.description,+ "mitre": finding.mitre_technique,+ },+ tags=["ad", "kerberos", "kerberoast"],+ )+ 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]+return ModuleResult(status="success" if (findings or raw) else "partial",findings=findings, raw=raw,diff --git a/ares/modules/ad/laps_enum.py b/ares/modules/ad/laps_enum.pyindex c6fa1e7..3f79bad 100644--- a/ares/modules/ad/laps_enum.py+++ b/ares/modules/ad/laps_enum.py@@ -23,13 +23,32 @@ from typing import Anyfrom ares.core.campaign import Finding, Severityfrom ares.core.logger import audit, get_loggerfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import LAPSEnumParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ module_contract,+)from ares.core.tracing import trace_modulelogger = get_logger("ares.modules.ad.laps_enum")-class LAPSEnumModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[389, 636], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=LAPSEnumParams,+)+class LAPSEnumModule(BaseModule[LAPSEnumParams, ModuleResult]):"""ad.laps_enum — Read LAPS local admin passwords from Active Directory computer objects. Supports LAPS v1 (ms-Mcs@@ -51,9 +70,9 @@ class LAPSEnumModule(BaseModule):MITRE_TECHNIQUES = ["T1552.004"]MODULE_AUTHOR = "ARES Team <[email protected]>"MODULE_TIMEOUT_SECONDS: int | None = 60 # seconds+ PARAMS_MODEL = LAPSEnumParamsasync def validate(self, ctx: "Any") -> None:- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -75,6 +94,11 @@ class LAPSEnumModule(BaseModule):"on ms-Mcs-AdmPwd (identified by ad.enum_acl).",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+).@@ -90,6 +114,26 @@ class LAPSEnumModule(BaseModule):username=ad["username"], password=ad["password"],vault=getattr(ctx, "vault", None),)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for cred in raw.get("laps_passwords", []):+ ev = EvidenceRecord(+ artifact_id=f"laps-{cred.get('computer', 'unknown').lower()}",+ source_target=ad["dc"],+ collected_by=self.MODULE_ID,+ data={+ "computer": cred.get("computer"),+ "account": cred.get("account", "Administrator"),+ "version": cred.get("version", "LAPS"),+ },+ tags=["ad", "laps", "credentials"],+ )+ 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]+return ModuleResult(status="success" if findings else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/ad/sccm.py b/ares/modules/ad/sccm.pyindex 32a3551..d98ca8a 100644--- a/ares/modules/ad/sccm.py+++ b/ares/modules/ad/sccm.py@@ -38,13 +38,32 @@ from typing import Anyfrom ares.core.campaign import Finding, Severityfrom ares.core.logger import audit, get_loggerfrom ares.core.security import sanitize_hostname, sanitize_ldap-from ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import SCCMParams+from ares.sdk import (+ BaseModule,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ OpsecLevel,+ ProcessPermission,+ module_contract,+)from ares.core.tracing import trace_modulelogger = get_logger("ares.modules.ad.sccm")-class SCCMModule(BaseModule):+@module_contract(+ permissions=[+ NetworkPermission(ports=[80, 443, 135, 445, 389, 636, 8530, 8531], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=SCCMParams,+)+class SCCMModule(BaseModule[SCCMParams, ModuleResult]):"""ad.sccm — SCCM/MECM enumeration and credential extraction@@ -66,9 +85,9 @@ class SCCMModule(BaseModule):REQUIRES = ["domain_creds"]OUTPUTS = ["cleartext_credentials", "sccm_findings", "owned_hosts"]MITRE_TECHNIQUES = ["T1078.002", "T1021.006"]+ PARAMS_MODEL = SCCMParamsasync def validate(self, ctx: "Any") -> None:- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):@@ -84,6 +103,11 @@ class SCCMModule(BaseModule):"ad.sccm requires 'domain'.",module_id=self.MODULE_ID, field="domain",)+ 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":from ares.modules.base import ModuleResult@@ -97,6 +121,27 @@ class SCCMModule(BaseModule):sccm_server=ctx.params.get("sccm_server", ""),target=ctx.params.get("target", ""),)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"sccm-{finding.title[:20].lower().replace(' ', '-')}",+ source_target=ad["dc"],+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "severity": str(finding.severity),+ "description": finding.description,+ "mitre": finding.mitre_technique,+ },+ tags=["ad", "sccm", "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]+return ModuleResult(status="success" if findings else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/base.py b/ares/modules/base.pyindex 17c2600..f5c6aac 100644--- a/ares/modules/base.py+++ b/ares/modules/base.py@@ -632,8 +632,18 @@ class BaseModule(abc.ABC, Generic[P, R]):Safe to call even when ctx is a bare namespace (test mode)."""cred = getattr(ctx, "best_credential", lambda: None)()- username = ctx.params.get("username") or (cred.username if cred else "")- password = ctx.params.get("password", "")+ params = ctx.params if hasattr(ctx, "params") and ctx.params is not None else {}+ def _get_val(k: str, default: Any = "") -> Any:+ if hasattr(params, "get"):+ val = params.get(k, default)+ else:+ val = getattr(params, k, default)+ if hasattr(val, "get_secret_value"):+ return val.get_secret_value()+ return val++ username = _get_val("username") or (cred.username if cred else "")+ password = _get_val("password", "")if cred and not password:vault = getattr(ctx, "vault", None)if vault:@@ -642,8 +652,8 @@ class BaseModule(abc.ABC, Generic[P, R]):except Exception:passreturn {- "dc": ctx.params.get("dc") or getattr(ctx, "target", ""),- "domain": getattr(ctx, "domain", "") or ctx.params.get("domain", ""),+ "dc": _get_val("dc") or getattr(ctx, "target", ""),+ "domain": getattr(ctx, "domain", "") or _get_val("domain", ""),"username": username,"password": password,}diff --git a/ares/modules/params.py b/ares/modules/params.pyindex 0a3096d..0c66d2f 100644--- a/ares/modules/params.py+++ b/ares/modules/params.py@@ -112,6 +112,31 @@ class ModuleParams(BaseModel):str_strip_whitespace=True,)+ def get(self, key: str, default: Any = None) -> Any:+ try:+ val = getattr(self, key)+ if val is None:+ return default+ if hasattr(val, "get_secret_value"):+ return val.get_secret_value()+ return val+ except AttributeError:+ return default++ def __getitem__(self, key: str) -> Any:+ try:+ val = getattr(self, key)+ if hasattr(val, "get_secret_value"):+ return val.get_secret_value()+ return val+ except AttributeError:+ raise KeyError(key)++ def __contains__(self, key: object) -> bool:+ if not isinstance(key, str):+ return False+ return hasattr(self, key)+@classmethoddef validate_dict(cls, data: dict[str, Any]) -> ModuleParams:"""diff --git a/ares/sdk/resilience/circuit_breaker.py b/ares/sdk/resilience/circuit_breaker.pyindex 783e808..e1e02a8 100644--- a/ares/sdk/resilience/circuit_breaker.py+++ b/ares/sdk/resilience/circuit_breaker.py@@ -103,6 +103,11 @@ class LockoutCircuitBreaker(CircuitBreaker):super().__init__(name=name, failure_threshold=1, recovery_timeout_s=recovery_timeout_s)self.locked_accounts: set[str] = set()+ def record_failure(self, exc: Exception | None = None) -> None:+ """Record a failure event. Trips circuit ONLY if lockout indicators are detected."""+ if exc is not None:+ self.inspect_error(exc)+def inspect_error(self, exc: Exception, username: str = "") -> None:"""Inspects exception for lockout signatures and trips instantly if detected."""if isinstance(exc, AccountLocked):