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 4 Windows host modules to Next-Gen Sovereign SDK v2

Mafifrizi3cf9d6e2f28d
diff --git a/ares/modules/windows/applocker_bypass.py b/ares/modules/windows/applocker_bypass.py
index 3b1258e..07adc02 100644
--- a/ares/modules/windows/applocker_bypass.py
+++ b/ares/modules/windows/applocker_bypass.py
@@ -25,7 +25,17 @@ from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import AppLockerBypassParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.windows.applocker_bypass")
@@ -58,20 +68,26 @@ _LOLBINS: list[dict[str, str]] = [
# Commonly writable paths inside trusted Windows locations
_TRUSTED_WRITABLE_CANDIDATES: list[str] = [
"%windir%\\Tasks",
- "%windir%\\Tracing",
- "%windir%\\System32\\spool\\drivers\\color",
+ "%windir%\\Temp",
+ "%windir%\\System32\\Spool\\Drivers\\Color",
+ "%windir%\\System32\\Microsoft\\Crypto\\RSA\\MachineKeys",
"%windir%\\System32\\Tasks",
- "%windir%\\SysWOW64\\Tasks",
- "%temp%",
- "%localappdata%\\Temp",
- "%appdata%\\Microsoft\\Windows\\Start Menu\\Programs\\Startup",
- "%programdata%\\Microsoft\\Windows\\Start Menu\\Programs\\Startup",
+ "%windir%\\Tracing",
+ "%windir%\\Registration\\CRMLog",
]
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[135, 139, 445, 5985], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=AppLockerBypassParams,
+)
class AppLockerBypassModule(BaseModule):
"""
- windows.applocker_bypass — Enumerate AppLocker rules from registry, identify enforcement mode, and detect writable trusted
+ windows.applocker_bypass — Enumerate AppLocker policy from registry, identify enforcement mode, and detect writable trusted
OPSEC: LOW
MITRE: "T1218", "T1574.001", "T1082"
@@ -90,20 +106,30 @@ class AppLockerBypassModule(BaseModule):
REQUIRES = ["local_admin_creds"]
OUTPUTS = ["applocker_config", "privesc_vectors"]
MITRE_TECHNIQUES = ["T1218", "T1574.001", "T1082"]
+ PARAMS_MODEL = AppLockerBypassParams
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):
return
- target = getattr(ctx, "target", "") or ctx.params.get("target", "")
+ if isinstance(ctx.params, dict):
+ if not ctx.params.get("target") and getattr(ctx, "target", None):
+ ctx.params["target"] = ctx.target
+ if not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
+ if not ctx.params.get("username") and hasattr(ctx, "best_credential"):
+ cred = ctx.best_credential()
+ if cred and cred.username:
+ ctx.params["username"] = cred.username
+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
if not target:
raise ModuleValidationError(
f"{self.MODULE_ID} requires 'target' — IP or hostname.",
module_id=self.MODULE_ID, field="target",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -115,13 +141,47 @@ class AppLockerBypassModule(BaseModule):
status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True},
)
- target = getattr(ctx, "target", ctx.params.get("target", ""))
- username = ctx.params.get("username", "")
- password = ctx.params.get("password", "") or ctx.params.get("secret", "")
- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
+ target = getattr(ctx, "target", "")
+ username = ""
+ password = ""
+ domain = getattr(ctx, "domain", "")
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AppLockerBypassParams):
+ target = params.target or target
+ username = params.username or ""
+ password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
+ domain = params.domain or domain
+ elif isinstance(params, dict):
+ target = params.get("target") or target
+ username = params.get("username", "")
+ raw_pass = params.get("password") or params.get("secret", "")
+ password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
+ domain = params.get("domain") or domain
+
findings, raw = await self.run(
target=target, 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"windows-applocker-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "title": finding.title,
+ "severity": str(finding.severity),
+ },
+ tags=["windows", "applocker_bypass"],
+ )
+ 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/windows/dpapi.py b/ares/modules/windows/dpapi.py
index 07379b7..b30d4db 100644
--- a/ares/modules/windows/dpapi.py
+++ b/ares/modules/windows/dpapi.py
@@ -28,11 +28,29 @@ from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
from ares.core.security import sanitize_hostname, secure_mkstemp
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import DPAPIParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.windows.dpapi")
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[135, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=DPAPIParams,
+)
class DPAPIModule(BaseModule):
"""
windows.dpapi — Extract DPAPI-protected credentials: Chrome passwords, WiFi PSK, Windows Credential Manager, RDP
@@ -55,6 +73,7 @@ class DPAPIModule(BaseModule):
OUTPUTS = ["cleartext_credentials", "browser_passwords"]
MITRE_TECHNIQUES = ["T1555.004", "T1555.003"]
MODULE_TIMEOUT_SECONDS: int | None = 180 # seconds
+ PARAMS_MODEL = DPAPIParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -138,23 +157,32 @@ class DPAPIModule(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):
return
- target = getattr(ctx, "target", "") or ctx.params.get("target", "")
+ if isinstance(ctx.params, dict):
+ if not ctx.params.get("target") and getattr(ctx, "target", None):
+ ctx.params["target"] = ctx.target
+ if not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
+ if not ctx.params.get("username") and hasattr(ctx, "best_credential"):
+ cred = ctx.best_credential()
+ if cred and cred.username:
+ ctx.params["username"] = cred.username
+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
if not target:
raise ModuleValidationError(
"windows.dpapi requires 'target' — IP of target Windows host.",
module_id=self.MODULE_ID, field="target",
)
- username = ctx.params.get("username", "")
+ username = (ctx.params.get("username", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "username", ""))
if not username:
raise ModuleValidationError(
"windows.dpapi requires 'username' — target user whose DPAPI blobs to decrypt.",
module_id=self.MODULE_ID, field="username",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -165,18 +193,41 @@ class DPAPIModule(BaseModule):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True})
- target = sanitize_hostname(
- getattr(ctx, "target", "") or ctx.params.get("target", "")
- )
- username = ctx.params.get("username", "")
- password = ctx.params.get("password", "") or ctx.params.get("secret", "")
- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
- target_user = ctx.params.get("target_user", username) # whose blobs to decrypt
- nt_hash = ctx.params.get("nt_hash", "") # for offline decryption
- backup_key = ctx.params.get("backup_key", "") # domain backup key PEM
- mode = ctx.params.get("mode", "auto") # auto|user|backup|offline
+ target = getattr(ctx, "target", "")
+ username = ""
+ password = ""
+ domain = getattr(ctx, "domain", "")
+ target_user = ""
+ nt_hash = ""
+ backup_key = ""
+ mode = "auto"
campaign_id = getattr(ctx, "campaign_id", "")
+ params = getattr(ctx, "params", {})
+ if isinstance(params, DPAPIParams):
+ target = params.target or target
+ username = params.username or ""
+ password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
+ domain = params.domain or domain
+ target_user = getattr(params, "target_user", username) or username
+ nt_hash = getattr(params, "nt_hash", "") or ""
+ backup_key = getattr(params, "backup_key", "") or ""
+ mode = getattr(params, "mode", "auto") or "auto"
+ elif isinstance(params, dict):
+ target = params.get("target") or target
+ username = params.get("username", "")
+ raw_pass = params.get("password") or params.get("secret", "")
+ password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
+ domain = params.get("domain") or domain
+ target_user = params.get("target_user", username) or username
+ nt_hash = params.get("nt_hash", "")
+ backup_key = params.get("backup_key", "")
+ mode = params.get("mode", "auto")
+
+ target = sanitize_hostname(target)
+ if not target_user:
+ target_user = username
+
# Parse NTLM hash if password looks like one
lmhash, nthash_login = "", ""
if password and (len(password) == 32 or (len(password) == 65 and ":" in password)):
@@ -193,6 +244,26 @@ class DPAPIModule(BaseModule):
target_user=target_user, nt_hash=nt_hash,
backup_key=backup_key, mode=mode, campaign_id=campaign_id,
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"windows-dpapi-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "title": finding.title,
+ "severity": str(finding.severity),
+ },
+ tags=["windows", "dpapi"],
+ )
+ 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/windows/lsa_secrets.py b/ares/modules/windows/lsa_secrets.py
index c89411e..407cbb7 100644
--- a/ares/modules/windows/lsa_secrets.py
+++ b/ares/modules/windows/lsa_secrets.py
@@ -20,11 +20,29 @@ from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import LSASecretsParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.windows.lsa_secrets")
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[135, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=LSASecretsParams,
+)
class LSASecretsModule(BaseModule):
"""
windows.lsa_secrets — "Extract local account hashes (SAM
@@ -47,6 +65,7 @@ class LSASecretsModule(BaseModule):
MITRE_TECHNIQUES = ["T1003.002", "T1003.004"]
MODULE_AUTHOR = "ARES Team <[email protected]>"
MIN_NOISE_PROFILE = "normal" # blocked in stealth
+ PARAMS_MODEL = LSASecretsParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -119,12 +138,26 @@ class LSASecretsModule(BaseModule):
async def validate(self, ctx: "Any") -> None:
"""LSA secrets dump blocked in STEALTH — registry access triggers Sysmon."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
from ares.core.campaign import NoiseProfile
if not isinstance(ctx, ExecutionContext):
return
+ if isinstance(ctx.params, dict):
+ if not ctx.params.get("target") and getattr(ctx, "target", None):
+ ctx.params["target"] = ctx.target
+ if not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
+ if not ctx.params.get("username") and hasattr(ctx, "best_credential"):
+ cred = ctx.best_credential()
+ if cred and cred.username:
+ ctx.params["username"] = cred.username
+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
+ if not target:
+ raise ModuleValidationError(
+ "windows.lsa_secrets requires 'target' — IP of target Windows host.",
+ module_id=self.MODULE_ID, field="target",
+ )
noise = getattr(getattr(ctx, "campaign", None), "noise_profile", None)
if noise == NoiseProfile.STEALTH:
raise ModuleValidationError(
@@ -133,6 +166,7 @@ class LSASecretsModule(BaseModule):
"Use NORMAL or AGGRESSIVE profile.",
module_id=self.MODULE_ID, field="noise_profile",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -141,16 +175,49 @@ class LSASecretsModule(BaseModule):
from ares.modules.base import ModuleResult
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID, raw={"dry_run": True})
- target = getattr(ctx, "target", ctx.params.get("target", ""))
- username = ctx.params.get("username", "")
- password = ctx.params.get("password", "") or ctx.params.get("secret", "")
- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
- params = dict(ctx.params)
- for key in ("target", "username", "password", "domain"):
- params.pop(key, None)
+ target = getattr(ctx, "target", "")
+ username = ""
+ password = ""
+ domain = getattr(ctx, "domain", "")
+ extra_params: dict[str, Any] = {}
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, LSASecretsParams):
+ target = params.target or target
+ username = params.username or ""
+ password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
+ domain = params.domain or domain
+ elif isinstance(params, dict):
+ target = params.get("target") or target
+ username = params.get("username", "")
+ raw_pass = params.get("password") or params.get("secret", "")
+ password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
+ domain = params.get("domain") or domain
+ extra_params = {k: v for k, v in params.items() if k not in ("target", "username", "password", "secret", "domain")}
+
findings, raw = await self.run(
- target=target, username=username, password=password, domain=domain, **params
+ target=target, username=username, password=password, domain=domain, **extra_params
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"windows-lsa-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "title": finding.title,
+ "severity": str(finding.severity),
+ },
+ tags=["windows", "lsa_secrets"],
+ )
+ 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/windows/lsass_dump.py b/ares/modules/windows/lsass_dump.py
index 9587803..b634a8e 100644
--- a/ares/modules/windows/lsass_dump.py
+++ b/ares/modules/windows/lsass_dump.py
@@ -30,11 +30,29 @@ from ares.core.campaign import Finding, Severity, NoiseProfile
from ares.core.logger import audit, get_logger
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import LsassDumpParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.windows.lsass_dump")
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[135, 445, 5985], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=LsassDumpParams,
+)
class LsassDumpModule(BaseModule):
"""
windows.lsass_dump — Extract NTLM hashes + Kerberos tickets from LSASS via COMSVCS.DLL MiniDump. Remote execution via
@@ -59,6 +77,7 @@ class LsassDumpModule(BaseModule):
OUTPUTS = ["ntlm_hashes", "kerberos_tickets"]
MITRE_TECHNIQUES = ["T1003.001"]
MODULE_TIMEOUT_SECONDS: int | None = 300 # seconds
+ PARAMS_MODEL = LsassDumpParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -151,7 +170,6 @@ class LsassDumpModule(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):
@@ -165,18 +183,28 @@ class LsassDumpModule(BaseModule):
"Use NORMAL or AGGRESSIVE profile.",
module_id=self.MODULE_ID, field="noise_profile",
)
- target = getattr(ctx, "target", "") or ctx.params.get("target", "")
+ if isinstance(ctx.params, dict):
+ if not ctx.params.get("target") and getattr(ctx, "target", None):
+ ctx.params["target"] = ctx.target
+ if not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
+ if not ctx.params.get("username") and hasattr(ctx, "best_credential"):
+ cred = ctx.best_credential()
+ if cred and cred.username:
+ ctx.params["username"] = cred.username
+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
if not target:
raise ModuleValidationError(
"windows.lsass_dump requires 'target' — IP of target Windows host.",
module_id=self.MODULE_ID, field="target",
)
- username = ctx.params.get("username", "")
+ username = (ctx.params.get("username", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "username", ""))
if not username:
raise ModuleValidationError(
"windows.lsass_dump requires local admin credentials.",
module_id=self.MODULE_ID, field="username",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -187,13 +215,28 @@ class LsassDumpModule(BaseModule):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True})
- target = sanitize_hostname(
- getattr(ctx, "target", "") or ctx.params.get("target", "")
- )
- username = ctx.params.get("username", "")
- password = ctx.params.get("password", "") or ctx.params.get("secret", "")
- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
- technique = ctx.params.get("technique", "comsvcs") # comsvcs|secretsdump
+ target = getattr(ctx, "target", "")
+ username = ""
+ password = ""
+ domain = getattr(ctx, "domain", "")
+ technique = "comsvcs"
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, LsassDumpParams):
+ target = params.target or target
+ username = params.username or ""
+ password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
+ domain = params.domain or domain
+ technique = params.technique or "comsvcs"
+ elif isinstance(params, dict):
+ target = params.get("target") or target
+ username = params.get("username", "")
+ raw_pass = params.get("password") or params.get("secret", "")
+ password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
+ domain = params.get("domain") or domain
+ technique = params.get("technique", "comsvcs")
+
+ target = sanitize_hostname(target)
# Reveal NTLM hash if provided instead of cleartext
lmhash, nthash = "", ""
@@ -209,6 +252,26 @@ class LsassDumpModule(BaseModule):
target=target, username=username, password=password,
domain=domain, lmhash=lmhash, nthash=nthash, technique=technique,
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"windows-lsass-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "title": finding.title,
+ "severity": str(finding.severity),
+ },
+ tags=["windows", "lsass_dump"],
+ )
+ 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/windows/registry_enum.py b/ares/modules/windows/registry_enum.py
index 73a4ab0..7df934f 100644
--- a/ares/modules/windows/registry_enum.py
+++ b/ares/modules/windows/registry_enum.py
@@ -39,7 +39,17 @@ from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import RegistryEnumParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.windows.registry_enum")
@@ -144,6 +154,14 @@ _SEV_MAP = {
}
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[139, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=RegistryEnumParams,
+)
class RegistryEnumModule(BaseModule):
"""
windows.registry_enum — Read-only enumeration of well-known registry keys that store credentials — AutoLogon, VNC passwo
@@ -169,20 +187,30 @@ class RegistryEnumModule(BaseModule):
"credential_hints",
]
MITRE_TECHNIQUES = ["T1552.002", "T1082"]
+ PARAMS_MODEL = RegistryEnumParams
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):
return
- target = getattr(ctx, "target", "") or ctx.params.get("target", "")
+ if isinstance(ctx.params, dict):
+ if not ctx.params.get("target") and getattr(ctx, "target", None):
+ ctx.params["target"] = ctx.target
+ if not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
+ if not ctx.params.get("username") and hasattr(ctx, "best_credential"):
+ cred = ctx.best_credential()
+ if cred and cred.username:
+ ctx.params["username"] = cred.username
+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
if not target:
raise ModuleValidationError(
f"{self.MODULE_ID} requires 'target' — IP or hostname.",
module_id=self.MODULE_ID, field="target",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -194,13 +222,47 @@ class RegistryEnumModule(BaseModule):
status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True},
)
- target = getattr(ctx, "target", ctx.params.get("target", ""))
- username = ctx.params.get("username", "")
- password = ctx.params.get("password", "") or ctx.params.get("secret", "")
- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
+ target = getattr(ctx, "target", "")
+ username = ""
+ password = ""
+ domain = getattr(ctx, "domain", "")
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, RegistryEnumParams):
+ target = params.target or target
+ username = params.username or ""
+ password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
+ domain = params.domain or domain
+ elif isinstance(params, dict):
+ target = params.get("target") or target
+ username = params.get("username", "")
+ raw_pass = params.get("password") or params.get("secret", "")
+ password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
+ domain = params.get("domain") or domain
+
findings, raw = await self.run(
target=target, 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"windows-registry-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "title": finding.title,
+ "severity": str(finding.severity),
+ },
+ tags=["windows", "registry_enum"],
+ )
+ 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/windows/scheduled_tasks_enum.py b/ares/modules/windows/scheduled_tasks_enum.py
index b92d68c..cbe14a6 100644
--- a/ares/modules/windows/scheduled_tasks_enum.py
+++ b/ares/modules/windows/scheduled_tasks_enum.py
@@ -27,7 +27,17 @@ from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import ScheduledTasksEnumParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.windows.scheduled_tasks_enum")
@@ -130,6 +140,14 @@ def _parse_task_xml(xml_str: str) -> dict[str, Any]:
return info
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[139, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=ScheduledTasksEnumParams,
+)
class ScheduledTasksEnumModule(BaseModule):
"""
windows.scheduled_tasks_enum — Enumerate scheduled tasks via TSCH RPC and identify high-privilege tasks with writable binary pa
@@ -151,20 +169,30 @@ class ScheduledTasksEnumModule(BaseModule):
REQUIRES = ["local_admin_creds"]
OUTPUTS = ["scheduled_tasks", "privesc_vectors"]
MITRE_TECHNIQUES = ["T1053.005", "T1082"]
+ PARAMS_MODEL = ScheduledTasksEnumParams
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):
return
- target = getattr(ctx, "target", "") or ctx.params.get("target", "")
+ if isinstance(ctx.params, dict):
+ if not ctx.params.get("target") and getattr(ctx, "target", None):
+ ctx.params["target"] = ctx.target
+ if not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
+ if not ctx.params.get("username") and hasattr(ctx, "best_credential"):
+ cred = ctx.best_credential()
+ if cred and cred.username:
+ ctx.params["username"] = cred.username
+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
if not target:
raise ModuleValidationError(
f"{self.MODULE_ID} requires 'target' — IP or hostname.",
module_id=self.MODULE_ID, field="target",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -176,13 +204,47 @@ class ScheduledTasksEnumModule(BaseModule):
status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True},
)
- target = getattr(ctx, "target", ctx.params.get("target", ""))
- username = ctx.params.get("username", "")
- password = ctx.params.get("password", "") or ctx.params.get("secret", "")
- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
+ target = getattr(ctx, "target", "")
+ username = ""
+ password = ""
+ domain = getattr(ctx, "domain", "")
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, ScheduledTasksEnumParams):
+ target = params.target or target
+ username = params.username or ""
+ password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
+ domain = params.domain or domain
+ elif isinstance(params, dict):
+ target = params.get("target") or target
+ username = params.get("username", "")
+ raw_pass = params.get("password") or params.get("secret", "")
+ password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
+ domain = params.get("domain") or domain
+
findings, raw = await self.run(
target=target, 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"windows-tasks-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "title": finding.title,
+ "severity": str(finding.severity),
+ },
+ tags=["windows", "scheduled_tasks_enum"],
+ )
+ 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/windows/token_impersonation.py b/ares/modules/windows/token_impersonation.py
index 8dd5598..d161d65 100644
--- a/ares/modules/windows/token_impersonation.py
+++ b/ares/modules/windows/token_impersonation.py
@@ -15,11 +15,29 @@ from ares.core.logger import get_logger
from ares.core.campaign import Finding, Severity
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import TokenImpersonationParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.windows.token_impersonation")
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[135, 445, 5985], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=TokenImpersonationParams,
+)
class TokenImpersonationModule(BaseModule):
"""
windows.token_impersonation — Detect SeImpersonatePrivilege on current session — prerequisite check for Potato-family privileg
@@ -41,6 +59,7 @@ class TokenImpersonationModule(BaseModule):
REQUIRES = ["lateral_session"]
OUTPUTS = ["privesc_vectors"]
MITRE_TECHNIQUES = ["T1134.001", "T1134.002"]
+ PARAMS_MODEL = TokenImpersonationParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -83,17 +102,26 @@ class TokenImpersonationModule(BaseModule):
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):
return
- target = getattr(ctx, "target", "") or ctx.params.get("target", "")
+ if isinstance(ctx.params, dict):
+ if not ctx.params.get("target") and getattr(ctx, "target", None):
+ ctx.params["target"] = ctx.target
+ if not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
+ if not ctx.params.get("username") and hasattr(ctx, "best_credential"):
+ cred = ctx.best_credential()
+ if cred and cred.username:
+ ctx.params["username"] = cred.username
+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
if not target:
raise ModuleValidationError(
"windows.token_impersonation requires 'target'.",
module_id=self.MODULE_ID, field="target",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -102,17 +130,50 @@ class TokenImpersonationModule(BaseModule):
from ares.modules.base import ModuleResult
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID, raw={"dry_run": True})
- target = getattr(ctx, "target", ctx.params.get("target", ""))
- username = ctx.params.get("username", "")
- password = ctx.params.get("password", "") or ctx.params.get("secret", "")
- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
- params = dict(ctx.params)
- for key in ("target", "username", "password", "domain"):
- params.pop(key, None)
+ target = getattr(ctx, "target", "")
+ username = ""
+ password = ""
+ domain = getattr(ctx, "domain", "")
+ extra_params: dict[str, Any] = {}
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, TokenImpersonationParams):
+ target = params.target or target
+ username = params.username or ""
+ password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
+ domain = params.domain or domain
+ elif isinstance(params, dict):
+ target = params.get("target") or target
+ username = params.get("username", "")
+ raw_pass = params.get("password") or params.get("secret", "")
+ password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
+ domain = params.get("domain") or domain
+ extra_params = {k: v for k, v in params.items() if k not in ("target", "username", "password", "secret", "domain")}
+
findings, raw = await self.run(
target=target, username=username, password=password, domain=domain,
- **params
+ **extra_params
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"windows-token-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "title": finding.title,
+ "severity": str(finding.severity),
+ },
+ tags=["windows", "token_impersonation"],
+ )
+ 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/windows/uac_bypass.py b/ares/modules/windows/uac_bypass.py
index f56e015..6864be6 100644
--- a/ares/modules/windows/uac_bypass.py
+++ b/ares/modules/windows/uac_bypass.py
@@ -27,7 +27,17 @@ from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import UACBypassParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.windows.uac_bypass")
@@ -90,6 +100,14 @@ _BYPASS_TECHNIQUES: list[dict[str, Any]] = [
]
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[139, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=UACBypassParams,
+)
class UACBypassModule(BaseModule):
"""
windows.uac_bypass — Read UAC configuration via remote registry and enumerate applicable bypass techniques — detectio
@@ -111,20 +129,30 @@ class UACBypassModule(BaseModule):
REQUIRES = ["local_admin_creds"]
OUTPUTS = ["uac_config", "privesc_vectors"]
MITRE_TECHNIQUES = ["T1548.002", "T1082"]
+ PARAMS_MODEL = UACBypassParams
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):
return
- target = getattr(ctx, "target", "") or ctx.params.get("target", "")
+ if isinstance(ctx.params, dict):
+ if not ctx.params.get("target") and getattr(ctx, "target", None):
+ ctx.params["target"] = ctx.target
+ if not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
+ if not ctx.params.get("username") and hasattr(ctx, "best_credential"):
+ cred = ctx.best_credential()
+ if cred and cred.username:
+ ctx.params["username"] = cred.username
+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
if not target:
raise ModuleValidationError(
f"{self.MODULE_ID} requires 'target' — IP or hostname.",
module_id=self.MODULE_ID, field="target",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -136,13 +164,47 @@ class UACBypassModule(BaseModule):
status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True},
)
- target = getattr(ctx, "target", ctx.params.get("target", ""))
- username = ctx.params.get("username", "")
- password = ctx.params.get("password", "") or ctx.params.get("secret", "")
- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
+ target = getattr(ctx, "target", "")
+ username = ""
+ password = ""
+ domain = getattr(ctx, "domain", "")
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, UACBypassParams):
+ target = params.target or target
+ username = params.username or ""
+ password = params.password.get_secret_value() if hasattr(params.password, "get_secret_value") else (params.password or "")
+ domain = params.domain or domain
+ elif isinstance(params, dict):
+ target = params.get("target") or target
+ username = params.get("username", "")
+ raw_pass = params.get("password") or params.get("secret", "")
+ password = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")
+ domain = params.get("domain") or domain
+
findings, raw = await self.run(
target=target, 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"windows-uac-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "title": finding.title,
+ "severity": str(finding.severity),
+ },
+ tags=["windows", "uac_bypass"],
+ )
+ 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/tests/unit/test_module_execute_adapters.py b/tests/unit/test_module_execute_adapters.py
index 812202b..3aae094 100644
--- a/tests/unit/test_module_execute_adapters.py
+++ b/tests/unit/test_module_execute_adapters.py
@@ -81,12 +81,48 @@ def _ctx(params: dict[str, Any]) -> SimpleNamespace:
{"target": "10.0.0.1", "username": "user", "password": "pw", "key_path": ""},
{"target": "10.0.0.1", "username": "user", "password": "pw"},
),
+ (
+ "ares.modules.windows.applocker_bypass",
+ "AppLockerBypassModule",
+ {"target": "10.0.0.1", "username": "user", "password": "pw", "domain": "corp"},
+ {"target": "10.0.0.1", "username": "user", "domain": "corp"},
+ ),
+ (
+ "ares.modules.windows.dpapi",
+ "DPAPIModule",
+ {"target": "10.0.0.1", "username": "user", "password": "pw", "domain": "corp"},
+ {"target": "10.0.0.1", "username": "user", "domain": "corp"},
+ ),
+ (
+ "ares.modules.windows.lsass_dump",
+ "LsassDumpModule",
+ {"target": "10.0.0.1", "username": "user", "password": "pw", "domain": "corp"},
+ {"target": "10.0.0.1", "username": "user", "domain": "corp"},
+ ),
+ (
+ "ares.modules.windows.registry_enum",
+ "RegistryEnumModule",
+ {"target": "10.0.0.1", "username": "user", "password": "pw", "domain": "corp"},
+ {"target": "10.0.0.1", "username": "user", "domain": "corp"},
+ ),
+ (
+ "ares.modules.windows.scheduled_tasks_enum",
+ "ScheduledTasksEnumModule",
+ {"target": "10.0.0.1", "username": "user", "password": "pw", "domain": "corp"},
+ {"target": "10.0.0.1", "username": "user", "domain": "corp"},
+ ),
(
"ares.modules.windows.token_impersonation",
"TokenImpersonationModule",
{"target": "10.0.0.1", "username": "user", "password": "pw", "domain": "corp"},
{"target": "10.0.0.1", "username": "user", "domain": "corp"},
),
+ (
+ "ares.modules.windows.uac_bypass",
+ "UACBypassModule",
+ {"target": "10.0.0.1", "username": "user", "password": "pw", "domain": "corp"},
+ {"target": "10.0.0.1", "username": "user", "domain": "corp"},
+ ),
(
"ares.modules.windows.lsa_secrets",
"LSASecretsModule",