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 7 data exfiltration modules to Next-Gen Sovereign SDK v2
Mafifrizi57e42f51666d
diff --git a/ares/modules/exfil/secrets_scan.py b/ares/modules/exfil/secrets_scan.pyindex 3196caa..9ef962b 100644--- a/ares/modules/exfil/secrets_scan.py+++ b/ares/modules/exfil/secrets_scan.py@@ -22,6 +22,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 SecretsScanParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.exfil.secrets_scan")@@ -167,6 +178,14 @@ def _wmi_scan(target: str, username: str, password: str = "",return hits+@module_contract(+ permissions=[+ NetworkPermission(ports=[22, 135, 445], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="exfil.secrets_scan", failure_threshold=5),+ params_model=SecretsScanParams,+)class SecretsScan(BaseModule):"""exfil.secrets_scan — Scan filesystem for hardcoded credentials, API keys, private keys, and connection strings@@ -184,6 +203,7 @@ class SecretsScan(BaseModule):REQUIRES = ["target"]OUTPUTS = ["credential_list", "sensitive_data_found"]MITRE_TECHNIQUES = ["T1552", "T1552.001", "T1083"]+ PARAMS_MODEL = SecretsScanParamsOPSEC_LEVEL = OpsecLevel.LOW@@ -207,9 +227,55 @@ class SecretsScan(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, SecretsScanParams):+ 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:+ hits = (+ finding.evidence.get("hits", [])+ if hasattr(finding, "evidence") and isinstance(finding.evidence, dict)+ else []+ )+ for hit in hits[:20]:+ ev = EvidenceRecord(+ artifact_id=f"secret-{str(hit.get('pattern', 'hit')).lower().replace('_', '-')}",+ source_target=getattr(ctx, "target", kwargs.get("target", "")),+ collected_by=self.MODULE_ID,+ data={+ "pattern": hit.get("pattern"),+ "file": hit.get("file"),+ "line": hit.get("line"),+ },+ tags=["exfil", "secrets_scan", "t1552"],+ )+ 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",+ status="success" if (findings or raw.get("credential_list")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,execution_id=getattr(ctx, "execution_id", ""),)diff --git a/ares/modules/exfil/smb_shares.py b/ares/modules/exfil/smb_shares.pyindex 0aa814b..0ff7b6e 100644--- a/ares/modules/exfil/smb_shares.py+++ b/ares/modules/exfil/smb_shares.py@@ -20,6 +20,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 SmbSharesParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.exfil.smb_shares")@@ -62,6 +73,14 @@ def _list_share_recursive(conn: Any, share: str, path: str = "*",return hits+@module_contract(+ permissions=[+ NetworkPermission(ports=[139, 445], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=SmbSharesParams,+)class SmbSharesExfil(BaseModule):"""exfil.smb_shares — Enumerate accessible SMB shares and scan for sensitive files including configs, keys, and credential@@ -79,6 +98,7 @@ class SmbSharesExfil(BaseModule):REQUIRES = ["target", "credential"]OUTPUTS = ["file_share_list", "sensitive_file_paths"]MITRE_TECHNIQUES = ["T1039", "T1021.002"]+ PARAMS_MODEL = SmbSharesParamsOPSEC_LEVEL = OpsecLevel.MEDIUM@@ -102,9 +122,49 @@ class SmbSharesExfil(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, SmbSharesParams):+ 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 file_path in raw.get("sensitive_file_paths", [])[:20]:+ file_name = file_path.rsplit("\\", 1)[-1]+ ev = EvidenceRecord(+ artifact_id=f"smb-file-{file_name.lower().replace('.', '-')}",+ source_target=getattr(ctx, "target", kwargs.get("target", "")),+ collected_by=self.MODULE_ID,+ data={+ "file_path": file_path,+ "target": getattr(ctx, "target", kwargs.get("target", "")),+ },+ tags=["exfil", "smb_shares", "t1039"],+ )+ 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",+ status="success" if (findings or raw.get("file_share_list")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,execution_id=getattr(ctx, "execution_id", ""),)diff --git a/ares/modules/exfil/staged_collection.py b/ares/modules/exfil/staged_collection.pyindex ffe805d..339434d 100644--- a/ares/modules/exfil/staged_collection.py+++ b/ares/modules/exfil/staged_collection.py@@ -16,6 +16,17 @@ 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 StagedCollectionParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.exfil.staged_collection")@@ -30,6 +41,14 @@ _COLLECTION_PATTERNS = ["*wallet.dat", "*.wallet",]+@module_contract(+ permissions=[+ NetworkPermission(ports=[22, 135, 445], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="exfil.staged_collection", failure_threshold=5),+ params_model=StagedCollectionParams,+)class StagedCollectionModule(BaseModule):"""exfil.staged_collection — "Search for high-value files (credentials, keys, configs, backups@@ -51,6 +70,7 @@ class StagedCollectionModule(BaseModule):OUTPUTS = ["sensitive_file_paths", "collection_inventory"]MITRE_TECHNIQUES = ["T1119", "T1039", "T1552"]MODULE_AUTHOR = "ARES Team <[email protected]>"+ PARAMS_MODEL = StagedCollectionParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight param checks before any network call."""@@ -79,18 +99,62 @@ class StagedCollectionModule(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", "")- key_path = ctx.params.get("key_path", "")- platform = ctx.params.get("platform", "linux")- search_paths = ctx.params.get("search_paths", ["/home", "/root", "/etc", "/var/www", "/opt"])- findings, raw = await self.run(target=target, username=username, password=password,- key_path=key_path, platform=platform,- search_paths=search_paths)- return ModuleResult(status="success" if findings else "partial",- findings=findings, raw=raw, module_id=self.MODULE_ID,- execution_id=getattr(ctx, "execution_id", ""))++ params = getattr(ctx, "params", {})+ if isinstance(params, StagedCollectionParams):+ 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 = ""+ key_path = pdict.get("key_path", "")+ platform = pdict.get("platform", "linux")+ search_paths = pdict.get("search_paths", ["/home", "/root", "/etc", "/var/www", "/opt"])+ destination = pdict.get("destination", "")+ max_files = int(pdict.get("max_files", 200))++ findings, raw = await self.run(+ target=target, username=username, password=password,+ key_path=key_path, platform=platform,+ search_paths=search_paths, max_files=max_files,+ destination=destination,+ )++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for file_info in raw.get("files_found", [])[:20]:+ file_name = file_info.get("path", "").rsplit("/", 1)[-1].rsplit("\\", 1)[-1]+ ev = EvidenceRecord(+ artifact_id=f"staged-{file_name.lower().replace('.', '-')}",+ source_target=getattr(ctx, "target", target),+ collected_by=self.MODULE_ID,+ data={+ "path": file_info.get("path"),+ "pattern": file_info.get("pattern"),+ "destination": destination,+ },+ tags=["exfil", "staged_collection", "t1119"],+ )+ 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.get("files_found")) else "partial",+ findings=findings, raw=raw, module_id=self.MODULE_ID,+ execution_id=getattr(ctx, "execution_id", ""),+ )@trace_module("exfil.staged_collection")async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:diff --git a/tests/unit/test_module_execute_adapters.py b/tests/unit/test_module_execute_adapters.pyindex 66c140d..b9b85ca 100644--- a/tests/unit/test_module_execute_adapters.py+++ b/tests/unit/test_module_execute_adapters.py@@ -218,6 +218,62 @@ def _ctx(params: dict[str, Any]) -> SimpleNamespace:"subscription_name": "AresMonitor",},),+ (+ "ares.modules.exfil.secrets_scan",+ "SecretsScan",+ {+ "target": "10.0.0.1",+ "username": "root",+ "password": "Password1!",+ "key_path": "/root/.ssh/id_rsa",+ "platform": "linux",+ },+ {+ "target": "10.0.0.1",+ "username": "root",+ "password": "Password1!",+ "key_path": "/root/.ssh/id_rsa",+ "platform": "linux",+ },+ ),+ (+ "ares.modules.exfil.smb_shares",+ "SmbSharesExfil",+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "domain": "corp.local",+ "max_depth": 2,+ },+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "domain": "corp.local",+ "max_depth": 2,+ },+ ),+ (+ "ares.modules.exfil.staged_collection",+ "StagedCollectionModule",+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "destination": "/tmp/staged",+ "platform": "linux",+ "max_files": 100,+ },+ {+ "target": "10.0.0.1",+ "username": "admin",+ "password": "Password1!",+ "destination": "/tmp/staged",+ "platform": "linux",+ "max_files": 100,+ },+ ),],)def test_execute_adapter_deduplicates_explicit_ctx_params(