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 8 strategic, EDR bypass & AI modules to Next-Gen Sovereign SDK v2
Mafifrizi2a6aa5265ebe
diff --git a/ares/modules/ai/autonomous_planner.py b/ares/modules/ai/autonomous_planner.pyindex 5b38aa0..374963e 100644--- a/ares/modules/ai/autonomous_planner.py+++ b/ares/modules/ai/autonomous_planner.py@@ -42,6 +42,15 @@ from ares.core.logger import get_logger, auditfrom ares.core.campaign import Severityfrom ares.modules.base import BaseModule, OpsecLevel, ModuleResultfrom ares.core.tracing import trace_module+from ares.modules.params import AIPlannerParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)if TYPE_CHECKING:from ares.core.engine import ExecutionPlan@@ -618,6 +627,14 @@ def _build_system_prompt_with_constitution(# ── Module ────────────────────────────────────────────────────────────────────+@module_contract(+ permissions=[+ NetworkPermission(ports=[443, 11434], protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="ai.autonomous_planner", failure_threshold=5),+ params_model=AIPlannerParams,+)class AIAutonomousPlannerModule(BaseModule):"""ai.autonomous_planner — LLM-powered attack chain orchestration.@@ -643,6 +660,7 @@ class AIAutonomousPlannerModule(BaseModule):OUTPUTS = ["execution_plan", "ai_reasoning", "confidence_score", "warnings"]MITRE_TECHNIQUES = ["T1591"]MODULE_TIMEOUT_SECONDS: int | None = 180+ PARAMS_MODEL = AIPlannerParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight: need active campaign and LLM API key."""@@ -652,7 +670,14 @@ class AIAutonomousPlannerModule(BaseModule):if not isinstance(ctx, ExecutionContext):returnimport os- backend = ctx.params.get("llm_backend", "claude")+ params = getattr(ctx, "params", {})+ if isinstance(params, AIPlannerParams):+ pdict = params.model_dump()+ elif isinstance(params, dict):+ pdict = dict(params)+ else:+ pdict = {}+ backend = pdict.get("llm_backend", "claude")if backend == "claude" and not os.environ.get("ANTHROPIC_API_KEY"):raise ModuleValidationError("ai.autonomous_planner with backend=claude requires ANTHROPIC_API_KEY env var. "@@ -674,16 +699,52 @@ class AIAutonomousPlannerModule(BaseModule):status="dry_run", module_id=self.MODULE_ID,raw={"dry_run": True, "note": "Would generate LLM attack plan from campaign context"},)+ params = getattr(ctx, "params", {})+ if isinstance(params, AIPlannerParams):+ pdict = params.model_dump()+ elif isinstance(params, dict):+ pdict = dict(params)+ else:+ pdict = {}++ goal = pdict.get("goal") or "domain_admin"+ llm_backend = pdict.get("llm_backend") or "claude"+ llm_model = pdict.get("llm_model") or ""+ auto_approve = pdict.get("auto_approve", False)+findings, raw = await self.run(- campaign=ctx.campaign,+ campaign=getattr(ctx, "campaign", None),vault=getattr(ctx, "vault", None),- goal=ctx.params.get("goal", "domain_admin"),- llm_backend=ctx.params.get("llm_backend", "claude"),- llm_model=ctx.params.get("llm_model", ""),- auto_approve=ctx.params.get("auto_approve", False),+ goal=goal,+ llm_backend=llm_backend,+ llm_model=llm_model,+ auto_approve=auto_approve,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ exec_plan = raw.get("execution_plan") or []+ for stage in exec_plan:+ stage_name = stage.get("name", "stage") if isinstance(stage, dict) else str(stage)+ ev = EvidenceRecord(+ artifact_id=f"ai-plan-stage-{stage_name}",+ source_target="campaign",+ collected_by=self.MODULE_ID,+ data={+ "stage_name": stage_name,+ "modules": stage.get("modules", []) if isinstance(stage, dict) else [],+ "goal": goal,+ "confidence": raw.get("confidence_score", 0.0),+ },+ tags=["ai", "autonomous_planner", "attack_chain"],+ )+ 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",+ status="success" if (findings or raw.get("execution_plan")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,execution_id=getattr(ctx, "execution_id", ""),)diff --git a/ares/modules/edr/bypass_adaptive.py b/ares/modules/edr/bypass_adaptive.pyindex 0ee6a93..5205cff 100644--- a/ares/modules/edr/bypass_adaptive.py+++ b/ares/modules/edr/bypass_adaptive.py@@ -38,6 +38,16 @@ from ares.core.campaign import Finding, Severityfrom ares.modules.base import BaseModule, OpsecLevel, ModuleResultfrom ares.core.tracing import trace_modulefrom ares.fingerprint.engine import EDRVendor+from ares.modules.params import EDRBypassParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)if TYPE_CHECKING:pass@@ -186,6 +196,13 @@ _EDR_BLIND_SPOTS: dict[str, list[dict[str, str]]] = {"unknown": [],}+@module_contract(+ permissions=[+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="edr.bypass_adaptive", failure_threshold=5),+ params_model=EDRBypassParams,+)class EDRAdaptiveBypassModule(BaseModule):"""edr.bypass_adaptive — Adaptive EDR evasion engine.@@ -212,6 +229,7 @@ class EDRAdaptiveBypassModule(BaseModule):OUTPUTS = ["viable_techniques", "recommended_approach", "edr_vendor", "bypass_plan"]MITRE_TECHNIQUES = ["T1562.001", "T1055", "T1027", "T1562.006"]MODULE_TIMEOUT_SECONDS: int | None = 120+ PARAMS_MODEL = EDRBypassParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight: need EDR detection results or explicit vendor."""@@ -220,9 +238,22 @@ class EDRAdaptiveBypassModule(BaseModule):from ares.core.errors import ModuleValidationErrorif not isinstance(ctx, ExecutionContext):return- has_fingerprint = bool(ctx.params.get("edr_vendor") or- ctx.params.get("fingerprint_result") or- getattr(ctx.campaign, "_artifact_store", None))+ params = getattr(ctx, "params", {})+ if isinstance(params, EDRBypassParams):+ explicit_vendor = "edr_vendor" in getattr(params, "__pydantic_fields_set__", set())+ has_fingerprint = bool(+ (explicit_vendor and params.edr_vendor) or+ getattr(ctx, "fingerprint_result", None) or+ (getattr(ctx.campaign, "_artifact_store", None) and getattr(ctx.campaign._artifact_store, "_artifacts", []))+ )+ else:+ pdict = dict(params) if isinstance(params, dict) else {}+ has_fingerprint = bool(+ pdict.get("edr_vendor") or+ pdict.get("fingerprint_result") or+ getattr(ctx, "fingerprint_result", None) or+ (getattr(ctx.campaign, "_artifact_store", None) and getattr(ctx.campaign._artifact_store, "_artifacts", []))+ )if not has_fingerprint:raise ModuleValidationError("edr.bypass_adaptive requires EDR detection results. "@@ -241,8 +272,17 @@ class EDRAdaptiveBypassModule(BaseModule):status="dry_run", module_id=self.MODULE_ID,raw={"dry_run": True, "note": "Would select evasion techniques based on detected EDR"},)++ params = getattr(ctx, "params", {})+ if isinstance(params, EDRBypassParams):+ pdict = params.model_dump()+ elif isinstance(params, dict):+ pdict = dict(params)+ else:+ pdict = {}+# Extract EDR vendor from params or artifact store- edr_vendor = ctx.params.get("edr_vendor", "")+ edr_vendor = pdict.get("edr_vendor", "")if not edr_vendor:edr_vendor = self._detect_vendor_from_artifacts(ctx)@@ -273,8 +313,28 @@ class EDRAdaptiveBypassModule(BaseModule):if hasattr(host_state, "update_defense_profile"):host_state.update_defense_profile(controls)+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for tech in raw.get("viable_techniques", [])[:20]:+ tech_id = tech.get("technique_id", "bypass") if isinstance(tech, dict) else str(tech)+ ev = EvidenceRecord(+ artifact_id=f"edr-bypass-{tech_id}",+ source_target=target or "local",+ collected_by=self.MODULE_ID,+ data={+ "technique_id": tech_id,+ "edr_vendor": raw.get("edr_vendor", edr_vendor),+ "recommended_approach": raw.get("recommended_approach", ""),+ },+ tags=["edr", "bypass", "evasion"],+ )+ 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",+ status="success" if (findings or raw.get("viable_techniques")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,execution_id=getattr(ctx, "execution_id", ""),)diff --git a/ares/modules/opsec/coverage_predictor.py b/ares/modules/opsec/coverage_predictor.pyindex 8b387fd..7b151e8 100644--- a/ares/modules/opsec/coverage_predictor.py+++ b/ares/modules/opsec/coverage_predictor.py@@ -33,6 +33,14 @@ from ares.core.logger import get_logger, auditfrom ares.core.campaign import Severityfrom ares.modules.base import BaseModule, OpsecLevel, ModuleResultfrom ares.core.tracing import trace_module+from ares.modules.params import CoveragePredictorParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ ProcessPermission,+ module_contract,+)if TYPE_CHECKING:pass@@ -637,6 +645,13 @@ class CoveragePredictor:# ── Module ─────────────────────────────────────────────────────────────────────+@module_contract(+ permissions=[+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="opsec.coverage_predictor", failure_threshold=5),+ params_model=CoveragePredictorParams,+)class CoveragePredictorModule(BaseModule):"""opsec.coverage_predictor — Real-time detection probability scoring@@ -656,6 +671,7 @@ class CoveragePredictorModule(BaseModule):OUTPUTS = ["detection_score", "action_risks", "wait_recommendation", "recommendations"]MITRE_TECHNIQUES = ["T1592"]MODULE_TIMEOUT_SECONDS: int | None = 30+ PARAMS_MODEL = CoveragePredictorParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight: campaign must be active."""@@ -677,13 +693,43 @@ class CoveragePredictorModule(BaseModule):status="dry_run", module_id=self.MODULE_ID,raw={"dry_run": True, "note": "Would analyze campaign execution history"},)- noise_profile = ctx.params.get("noise_profile", "normal")+ params = getattr(ctx, "params", {})+ if isinstance(params, CoveragePredictorParams):+ pdict = params.model_dump()+ elif isinstance(params, dict):+ pdict = dict(params)+ else:+ pdict = {}++ noise_profile = pdict.get("noise_profile") or "normal"findings, raw = await self.run(- campaign=ctx.campaign,+ campaign=getattr(ctx, "campaign", None),noise_profile=noise_profile,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for risk in raw.get("action_risks", [])[:20]:+ tech = risk.get("technique", "T1592")+ ev = EvidenceRecord(+ artifact_id=f"opsec-risk-{tech}-{risk.get('event', '')}",+ source_target="campaign",+ collected_by=self.MODULE_ID,+ data={+ "technique": tech,+ "event": risk.get("event"),+ "probability": risk.get("probability"),+ "description": risk.get("description"),+ },+ tags=["opsec", "coverage_predictor", "detection_risk"],+ )+ 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",+ status="success" if (findings or raw.get("detection_score", 0) >= 0) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,execution_id=getattr(ctx, "execution_id", ""),)diff --git a/ares/modules/recon/fingerprint.py b/ares/modules/recon/fingerprint.pyindex 4e3228a..5f74185 100644--- a/ares/modules/recon/fingerprint.py+++ b/ares/modules/recon/fingerprint.py@@ -24,6 +24,17 @@ from ares.core.logger import audit, get_loggerfrom ares.core.security import sanitize_hostnamefrom ares.modules.base import BaseModule, OpsecLevelfrom ares.core.tracing import trace_module+from ares.modules.params import FingerprintParams+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.recon.fingerprint")@@ -31,6 +42,14 @@ logger = get_logger("ares.modules.recon.fingerprint")_HIGH_RISK_EDR = {"crowdstrike", "sentinelone", "defender_atp"}+@module_contract(+ permissions=[+ NetworkPermission(protocols=["tcp", "udp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="recon.fingerprint", failure_threshold=5),+ params_model=FingerprintParams,+)class FingerprintModule(BaseModule):"""recon.fingerprint — Passive-first OS, domain role, and EDR/AV detection before any attack module. Detects CrowdStrik@@ -52,6 +71,7 @@ class FingerprintModule(BaseModule):REQUIRES = []OUTPUTS = ["fingerprint_result"]MITRE_TECHNIQUES = ["T1082", "T1518.001"]+ PARAMS_MODEL = FingerprintParamsasync def validate(self, ctx: "Any") -> None:"""Enforce target is set."""@@ -75,16 +95,52 @@ class FingerprintModule(BaseModule):if getattr(ctx, "dry_run", False):return ModuleResult(status="dry_run", module_id=self.MODULE_ID,raw={"dry_run": True})- target = getattr(ctx, "target", "") or ctx.params.get("target", "")- username = ctx.params.get("username", "")- domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")- secret = ctx.params.get("password", "") or ctx.params.get("secret", "")- timeout = float(ctx.params.get("timeout", 5.0))++ params = getattr(ctx, "params", {})+ if isinstance(params, FingerprintParams):+ pdict = params.model_dump()+ elif isinstance(params, dict):+ pdict = dict(params)+ else:+ pdict = {}++ target = getattr(ctx, "target", "") or pdict.get("target", "")+ username = pdict.get("username", "")+ domain = getattr(ctx, "domain", "") or pdict.get("domain", "")+ raw_sec = pdict.get("password") or pdict.get("secret") or getattr(ctx, "password", "")+ if hasattr(raw_sec, "get_secret_value"):+ secret = raw_sec.get_secret_value()+ elif raw_sec is not None:+ secret = str(raw_sec)+ else:+ secret = ""+ timeout = float(pdict.get("timeout", 5.0))findings, raw = await self.run(target=target, username=username, domain=domain,secret=secret, timeout=timeout,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for edr in raw.get("edr_vendors", []):+ ev = EvidenceRecord(+ artifact_id=f"edr-{str(edr).lower()}",+ source_target=getattr(ctx, "target", target),+ collected_by=self.MODULE_ID,+ data={+ "edr": edr,+ "target": target,+ "os": raw.get("os_type"),+ "detection_risk": raw.get("detection_risk"),+ },+ tags=["recon", "fingerprint", "edr"],+ )+ 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/sdk/taint/evidence.py b/ares/sdk/taint/evidence.pyindex c027890..6340e3e 100644--- a/ares/sdk/taint/evidence.py+++ b/ares/sdk/taint/evidence.py@@ -67,19 +67,31 @@ class EvidenceRecord:to the preceding evidence hash to establish an unbroken audit trail."""- evidence_id: str- source_target: str- payload: Any+ evidence_id: str = ""+ source_target: str = ""+ payload: Any = Nonetimestamp_ns: int = field(default_factory=time.time_ns)parent_hash: str = ""+ artifact_id: str = ""+ collected_by: str = ""+ data: Any = None+ tags: list[str] = field(default_factory=list)sha256_hash: str = field(init=False)chain_hash: str = field(init=False)def __post_init__(self) -> None:+ eff_id = self.evidence_id or self.artifact_id or "evidence"+ object.__setattr__(self, "evidence_id", eff_id)+ object.__setattr__(self, "artifact_id", eff_id)++ eff_payload = self.payload if self.payload is not None else (self.data if self.data is not None else {})+ object.__setattr__(self, "payload", eff_payload)+ object.__setattr__(self, "data", eff_payload)+# 1. Compute payload digest- serialized = json.dumps(self.payload, sort_keys=True, default=str)+ serialized = json.dumps(eff_payload, sort_keys=True, default=str)payload_digest = hashlib.sha256(- f"{self.evidence_id}:{self.source_target}:{self.timestamp_ns}:{serialized}".encode("utf-8")+ f"{eff_id}:{self.source_target}:{self.timestamp_ns}:{serialized}".encode("utf-8")).hexdigest()object.__setattr__(self, "sha256_hash", payload_digest)@@ -87,11 +99,17 @@ class EvidenceRecord:chain = hashlib.sha256(f"{self.parent_hash}:{payload_digest}".encode("utf-8")).hexdigest()object.__setattr__(self, "chain_hash", chain)+ @property+ def record_hash(self) -> str:+ return self.sha256_hash+def verify_integrity(self) -> bool:"""Verify that the evidence payload matches its cryptographic digest."""- serialized = json.dumps(self.payload, sort_keys=True, default=str)+ eff_id = self.evidence_id or self.artifact_id+ eff_payload = self.payload if self.payload is not None else (self.data if self.data is not None else {})+ serialized = json.dumps(eff_payload, sort_keys=True, default=str)recomputed = hashlib.sha256(- f"{self.evidence_id}:{self.source_target}:{self.timestamp_ns}:{serialized}".encode("utf-8")+ f"{eff_id}:{self.source_target}:{self.timestamp_ns}:{serialized}".encode("utf-8")).hexdigest()return hmac_equal(recomputed, self.sha256_hash)diff --git a/tests/unit/test_module_execute_adapters.py b/tests/unit/test_module_execute_adapters.pyindex b9b85ca..2fb29cd 100644--- a/tests/unit/test_module_execute_adapters.py+++ b/tests/unit/test_module_execute_adapters.py@@ -22,6 +22,7 @@ def _ctx(params: dict[str, Any]) -> SimpleNamespace:dry_run=False,execution_id="adapter-test",vault=params.get("vault"),+ campaign=params.get("campaign"),best_credential=lambda: None,)@@ -274,6 +275,64 @@ def _ctx(params: dict[str, Any]) -> SimpleNamespace:"max_files": 100,},),+ (+ "ares.modules.recon.fingerprint",+ "FingerprintModule",+ {+ "target": "10.0.0.1",+ "username": "admin",+ "domain": "corp.local",+ "secret": "Password1!",+ "timeout": 5.0,+ },+ {+ "target": "10.0.0.1",+ "username": "admin",+ "domain": "corp.local",+ "secret": "Password1!",+ "timeout": 5.0,+ },+ ),+ (+ "ares.modules.edr.bypass_adaptive",+ "EDRAdaptiveBypassModule",+ {+ "target": "10.0.0.1",+ "edr_vendor": "crowdstrike",+ "os_version": "Windows Server 2022",+ },+ {+ "target": "10.0.0.1",+ "edr_vendor": "crowdstrike",+ "os_version": "Windows Server 2022",+ },+ ),+ (+ "ares.modules.opsec.coverage_predictor",+ "CoveragePredictorModule",+ {+ "noise_profile": "stealth",+ },+ {+ "noise_profile": "stealth",+ },+ ),+ (+ "ares.modules.ai.autonomous_planner",+ "AIAutonomousPlannerModule",+ {+ "goal": "domain_admin",+ "llm_backend": "claude",+ "llm_model": "claude-3-7-sonnet",+ "auto_approve": False,+ },+ {+ "goal": "domain_admin",+ "llm_backend": "claude",+ "llm_model": "claude-3-7-sonnet",+ "auto_approve": False,+ },+ ),],)def test_execute_adapter_deduplicates_explicit_ctx_params(