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 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.py
index 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, audit
from ares.core.campaign import Severity
from ares.modules.base import BaseModule, OpsecLevel, ModuleResult
from 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 = AIPlannerParams
async 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):
return
import 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.py
index 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, Severity
from ares.modules.base import BaseModule, OpsecLevel, ModuleResult
from ares.core.tracing import trace_module
from 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 = EDRBypassParams
async 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 ModuleValidationError
if 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.py
index 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, audit
from ares.core.campaign import Severity
from ares.modules.base import BaseModule, OpsecLevel, ModuleResult
from 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 = CoveragePredictorParams
async 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.py
index 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_logger
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
from 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 = FingerprintParams
async 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.py
index 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 = None
timestamp_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.py
index 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(