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.

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.py
index 7c0bb3d..8cbfc8a 100644
--- a/ares/modules/ad/adcs.py
+++ b/ares/modules/ad/adcs.py
@@ -26,8 +26,21 @@ from typing import Any
from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
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.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 = ADCSParams
async 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 ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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_logger
logger = get_logger("ares.modules.ad.asreproast")
from ares.core.campaign import Finding, Severity
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 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 = ASREPRoastParams
async def assess_feasibility(self, ctx: "Any") -> Any:
"""
@@ -269,12 +290,12 @@ class ASREPRoastModule(BaseModule):
domain = ctx.params.get("domain") or ctx.domain
if 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.py
index 3d741f3..19b7dfd 100644
--- a/ares/modules/ad/coerce.py
+++ b/ares/modules/ad/coerce.py
@@ -28,13 +28,34 @@ from typing import Any
from ares.core.campaign import Finding, Severity, NoiseProfile
from ares.core.logger import audit, get_logger
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.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 = CoerceParams
async def validate(self, ctx: "Any") -> None:
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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_logger
logger = get_logger("ares.modules.ad.dcsync")
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.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 = DCSyncParams
async 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 ExecutionContext
from ares.core.errors import ModuleValidationError
from 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.py
index e55518d..4456887 100644
--- a/ares/modules/ad/delegation_abuse.py
+++ b/ares/modules/ad/delegation_abuse.py
@@ -29,13 +29,34 @@ from typing import Any
from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
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.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 = DelegationAbuseParams
async def validate(self, ctx: "Any") -> None:
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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_logger
logger = get_logger("ares.modules.ad.enum_acl")
from ares.core.campaign import Finding, Severity
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.params import DomainAuthParams
+from ares.sdk import (
+ BaseModule,
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ OpsecLevel,
+ ProcessPermission,
+ UntrustedTargetData,
+ module_contract,
+)
# Active Directory extended rights GUIDs
DCSYNC_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 = DomainAuthParams
async 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 ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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_logger
logger = get_logger("ares.modules.ad.enum_computers")
from ares.core.campaign import Finding, Severity
from 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_module
from ares.core.errors import AresError, ModuleValidationError, NetworkError
from 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 = DomainAuthParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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_logger
logger = get_logger("ares.modules.ad.enum_spn")
from ares.core.campaign import Finding, Severity
from 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_module
from ares.core.errors import AresError, ModuleValidationError
from 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 = DomainAuthParams
async 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 ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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_logger
logger = get_logger("ares.modules.ad.enum_users")
from ares.core.campaign import Finding, Severity
from 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_module
from ares.core.errors import AresError, ModuleValidationError, NetworkError
from ares.modules.ad.dependencies import (
@@ -42,7 +53,15 @@ def _days_since(dt: datetime.datetime | None) -> int | None:
return None
return 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 = DomainAuthParams
async 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 ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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_logger
logger = get_logger("ares.modules.ad.kerberoast")
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 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 = KerberoastParams
async 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 ExecutionContext
from ares.core.errors import ModuleValidationError
from 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.py
index c6fa1e7..3f79bad 100644
--- a/ares/modules/ad/laps_enum.py
+++ b/ares/modules/ad/laps_enum.py
@@ -23,13 +23,32 @@ from typing import Any
from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
from 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_module
logger = 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 = LAPSEnumParams
async def validate(self, ctx: "Any") -> None:
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 32a3551..d98ca8a 100644
--- a/ares/modules/ad/sccm.py
+++ b/ares/modules/ad/sccm.py
@@ -38,13 +38,32 @@ from typing import Any
from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
from 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_module
logger = 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 = SCCMParams
async def validate(self, ctx: "Any") -> None:
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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:
pass
return {
- "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.py
index 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)
+
@classmethod
def validate_dict(cls, data: dict[str, Any]) -> ModuleParams:
"""
diff --git a/ares/sdk/resilience/circuit_breaker.py b/ares/sdk/resilience/circuit_breaker.py
index 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):