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 6 persistence modules to Next-Gen Sovereign SDK v2
Mafifrizi404733b21cf5
diff --git a/ares/modules/persistence/scheduled_task.py b/ares/modules/persistence/scheduled_task.pyindex 66a3875..9fd02f0 100644--- a/ares/modules/persistence/scheduled_task.py+++ b/ares/modules/persistence/scheduled_task.py@@ -24,6 +24,17 @@ from ares.core.campaign import Finding, Severityfrom ares.modules.base import BaseModule, OpsecLevelfrom ares.core.logger import get_logger, auditfrom ares.core.tracing import trace_module+from ares.modules.params import RegistryRunParams, ScheduledTaskParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.persistence")@@ -89,6 +100,14 @@ def _tsch_register_sync(target: str, username: str, password: str,pass+@module_contract(+ permissions=[+ NetworkPermission(ports=[135, 139, 445], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=ScheduledTaskParams,+)class ScheduledTaskPersistence(BaseModule):"""persistence.scheduled_task — Register a Windows scheduled task that executes at user logon via impacket tsch RPC (T1053.005)@@ -106,6 +125,7 @@ class ScheduledTaskPersistence(BaseModule):REQUIRES = ["target", "credential"]OUTPUTS = ["persistence_established", "task_name"]MITRE_TECHNIQUES = ["T1053.005"]+ PARAMS_MODEL = ScheduledTaskParamsOPSEC_LEVEL = OpsecLevel.MEDIUM@@ -197,7 +217,48 @@ class ScheduledTaskPersistence(BaseModule):if getattr(ctx, "dry_run", False):return ModuleResult(status="dry_run", module_id=self.MODULE_ID,raw={"dry_run": True})- findings, raw = await self.run(**ctx.params)++ params = getattr(ctx, "params", {})+ if isinstance(params, ScheduledTaskParams):+ kwargs = params.model_dump()+ elif isinstance(params, dict):+ kwargs = dict(params)+ else:+ kwargs = {}++ raw_pwd = kwargs.get("password") or getattr(ctx, "password", "")+ if hasattr(raw_pwd, "get_secret_value"):+ kwargs["password"] = raw_pwd.get_secret_value()+ elif raw_pwd is not None:+ kwargs["password"] = str(raw_pwd)+ else:+ kwargs["password"] = ""++ if not kwargs.get("target") and getattr(ctx, "target", ""):+ kwargs["target"] = ctx.target++ findings, raw = await self.run(**kwargs)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"schedtask-{str(finding.host or kwargs.get('target', 'host')).replace(':', '-').replace('/', '-')}",+ source_target=getattr(ctx, "target", kwargs.get("target", "")),+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "task_name": raw.get("task_name", kwargs.get("task_name", "")),+ "persistence_established": raw.get("persistence_established", False),+ "mitre": finding.mitre_technique,+ },+ tags=["persistence", "scheduled_task", "t1053_005"],+ )+ 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,@@ -322,6 +383,14 @@ def _rrp_set_run_key(target: str, username: str, password: str,dce.disconnect()+@module_contract(+ permissions=[+ NetworkPermission(ports=[135, 139, 445], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=RegistryRunParams,+)class RegistryRunKeyPersistence(BaseModule):"""persistence.registry_run — Add payload to HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run@@ -339,6 +408,7 @@ class RegistryRunKeyPersistence(BaseModule):REQUIRES = ["target", "credential"]OUTPUTS = ["persistence_established", "registry_key"]MITRE_TECHNIQUES = ["T1547.001"]+ PARAMS_MODEL = RegistryRunParamsOPSEC_LEVEL = OpsecLevel.MEDIUM@@ -367,7 +437,54 @@ class RegistryRunKeyPersistence(BaseModule):if getattr(ctx, "dry_run", False):return ModuleResult(status="dry_run", module_id=self.MODULE_ID,raw={"dry_run": True})- findings, raw = await self.run(**ctx.params)++ params = getattr(ctx, "params", {})+ if isinstance(params, RegistryRunParams):+ kwargs = params.model_dump()+ elif isinstance(params, dict):+ kwargs = dict(params)+ else:+ kwargs = {}++ raw_pwd = kwargs.get("password") or getattr(ctx, "password", "")+ if hasattr(raw_pwd, "get_secret_value"):+ kwargs["password"] = raw_pwd.get_secret_value()+ elif raw_pwd is not None:+ kwargs["password"] = str(raw_pwd)+ else:+ kwargs["password"] = ""++ if not kwargs.get("target") and getattr(ctx, "target", ""):+ kwargs["target"] = ctx.target++ # Map key_name / command to value_name / payload if needed+ if "key_name" in kwargs and "value_name" not in kwargs:+ kwargs["value_name"] = kwargs["key_name"]+ if "command" in kwargs and "payload" not in kwargs:+ kwargs["payload"] = kwargs["command"]++ findings, raw = await self.run(**kwargs)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"regrun-{str(finding.host or kwargs.get('target', 'host')).replace(':', '-').replace('/', '-')}",+ source_target=getattr(ctx, "target", kwargs.get("target", "")),+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "registry_key": raw.get("registry_key", ""),+ "persistence_established": raw.get("persistence_established", False),+ "mitre": finding.mitre_technique,+ },+ tags=["persistence", "registry_run", "t1547_001"],+ )+ 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/persistence/wmi_subscription.py b/ares/modules/persistence/wmi_subscription.pyindex ad8a551..8440ef9 100644--- a/ares/modules/persistence/wmi_subscription.py+++ b/ares/modules/persistence/wmi_subscription.py@@ -15,9 +15,28 @@ from ares.core.logger import get_logger, auditfrom ares.core.campaign import Finding, Severityfrom ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_module+from ares.modules.params import WMISubscriptionParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.persistence.wmi_subscription")+@module_contract(+ permissions=[+ NetworkPermission(ports=[135, 445], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=WMISubscriptionParams,+)class WMISubscriptionModule(BaseModule):"""persistence.wmi_subscription — Create a WMI FilterToConsumerBinding that executes a command on event trigger — highly stealthy@@ -39,6 +58,7 @@ class WMISubscriptionModule(BaseModule):REQUIRES = ["local_admin_creds"]OUTPUTS = ["persistence_established"]MITRE_TECHNIQUES = ["T1546.003"]+ PARAMS_MODEL = WMISubscriptionParamsasync def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":"""@@ -125,15 +145,51 @@ class WMISubscriptionModule(BaseModule):from ares.modules.base import ModuleResultif 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", "")- command = ctx.params.get("command", "")- sub_name = ctx.params.get("subscription_name", "WindowsUpdate")++ params = getattr(ctx, "params", {})+ if isinstance(params, WMISubscriptionParams):+ pdict = params.model_dump()+ elif isinstance(params, dict):+ pdict = dict(params)+ else:+ pdict = {}++ target = getattr(ctx, "target", pdict.get("target", ""))+ username = pdict.get("username", "")+ raw_pwd = pdict.get("password") or getattr(ctx, "password", "") or pdict.get("secret", "")+ if hasattr(raw_pwd, "get_secret_value"):+ password = raw_pwd.get_secret_value()+ elif raw_pwd is not None:+ password = str(raw_pwd)+ else:+ password = ""+ domain = getattr(ctx, "domain", "") or pdict.get("domain", "")+ command = pdict.get("command", "")+ sub_name = pdict.get("subscription_name", "WindowsUpdate")findings, raw = await self.run(target=target, username=username, password=password,domain=domain, command=command, subscription_name=sub_name)- return ModuleResult(status="success" if findings else "partial",++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"wmi-{str(finding.host or target).replace(':', '-').replace('/', '-')}",+ source_target=getattr(ctx, "target", target),+ collected_by=self.MODULE_ID,+ data={+ "title": finding.title,+ "subscription_name": sub_name,+ "persistence_established": raw.get("persistence_established", False),+ "mitre": finding.mitre_technique,+ },+ tags=["persistence", "wmi_subscription", "t1546_003"],+ )+ 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,execution_id=getattr(ctx, "execution_id", ""))diff --git a/tests/unit/test_module_execute_adapters.py b/tests/unit/test_module_execute_adapters.pyindex a954ae8..66c140d 100644--- a/tests/unit/test_module_execute_adapters.py+++ b/tests/unit/test_module_execute_adapters.py@@ -163,6 +163,61 @@ def _ctx(params: dict[str, Any]) -> SimpleNamespace:},{"target": "10.0.0.1", "domain": "corp.local", "users": ["alice"]},),+ (+ "ares.modules.persistence.scheduled_task",+ "ScheduledTaskPersistence",+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "domain": "corp.local",+ "task_name": "AresUpdater",+ "command": "powershell.exe -NoP -W Hidden",+ },+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "task_name": "AresUpdater",+ },+ ),+ (+ "ares.modules.persistence.scheduled_task",+ "RegistryRunKeyPersistence",+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "domain": "corp.local",+ "key_name": "AresUpdate",+ "command": r"C:\Windows\Temp\ares.exe",+ },+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "value_name": "AresUpdate",+ "payload": r"C:\Windows\Temp\ares.exe",+ },+ ),+ (+ "ares.modules.persistence.wmi_subscription",+ "WMISubscriptionModule",+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "domain": "corp.local",+ "subscription_name": "AresMonitor",+ "command": "powershell.exe -NoP -W Hidden",+ },+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "subscription_name": "AresMonitor",+ },+ ),],)def test_execute_adapter_deduplicates_explicit_ctx_params(