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 5 network reconnaissance & infrastructure to Next-Gen Sovereign SDK v2
Mafifrizi789287cf65bd
diff --git a/ares/modules/network/dns_enum.py b/ares/modules/network/dns_enum.pyindex 8a74fd3..e3b5e05 100644--- a/ares/modules/network/dns_enum.py+++ b/ares/modules/network/dns_enum.py@@ -15,7 +15,17 @@ from typing import Anyfrom ares.core.logger import get_loggerfrom ares.core.campaign import Finding, Severityfrom ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import DNSEnumParamsfrom ares.core.tracing import trace_module+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.network.dns_enum")@@ -43,9 +53,17 @@ _COMMON_SUBDOMAINS: list[str] = [_RECORD_TYPES: list[str] = ["A", "AAAA", "MX", "NS", "TXT", "SOA", "CNAME", "PTR"]+@module_contract(+ permissions=[+ NetworkPermission(ports=[53], protocols=["udp", "tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="network.dns_enum", failure_threshold=10),+ params_model=DNSEnumParams,+)class DnsEnumModule(BaseModule):"""- network.dns_enum — DNS zone transfer attempt, subdomain brute force, and record enumeration — maps DNS infrastructu+ network.dns_enum — DNS zone transfer attempt, subdomain brute force, and record enumeration — maps DNS infrastructure and finds internal hostnamesOPSEC: LOWMITRE: "T1590.002"@@ -63,20 +81,26 @@ class DnsEnumModule(BaseModule):REQUIRES = []OUTPUTS = ["dns_records", "subdomains"]MITRE_TECHNIQUES = ["T1590.002"]+ PARAMS_MODEL = DNSEnumParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight param checks before any network call."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif 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+ 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+).@@ -84,13 +108,50 @@ class DnsEnumModule(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", ""))- domain = ctx.params.get("domain") or target- params = dict(ctx.params)- params.pop("target", None)- params.pop("domain", None)- findings, raw = await self.run(target=target, domain=domain, **params)+ return ModuleResult(+ status="dry_run", module_id=self.MODULE_ID,+ raw={"dry_run": True},+ )+ target = getattr(ctx, "target", "")+ domain = getattr(ctx, "domain", "")+ brute = True+ extra_params: dict[str, Any] = {}++ params = getattr(ctx, "params", {})+ if isinstance(params, DNSEnumParams):+ target = params.target or target+ domain = params.domain or domain or target+ brute = getattr(params, "brute", True)+ elif isinstance(params, dict):+ target = params.get("target") or target+ domain = params.get("domain") or domain or target+ brute = params.get("brute_force", params.get("brute", True))+ extra_params = {k: v for k, v in params.items() if k not in ("target", "domain", "brute", "brute_force")}++ findings, raw = await self.run(+ target=target, domain=domain, brute_force=brute, brute=brute, **extra_params,+ )++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"dns-{target.replace('.', '-')}",+ source_target=target,+ collected_by=self.MODULE_ID,+ data={+ "target": target,+ "domain": domain,+ "title": finding.title,+ "severity": str(finding.severity),+ },+ tags=["network", "dns_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 or raw.get("dns_records")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/network/http_fingerprint.py b/ares/modules/network/http_fingerprint.pyindex 7ea2402..d9b88b6 100644--- a/ares/modules/network/http_fingerprint.py+++ b/ares/modules/network/http_fingerprint.py@@ -14,7 +14,17 @@ from typing import Anyfrom ares.core.logger import get_loggerfrom ares.core.campaign import Finding, Severityfrom ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import HTTPFingerprintParamsfrom ares.core.tracing import trace_module+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.network.http_fingerprint")@@ -60,9 +70,17 @@ _HEADER_FINGERPRINTS: list[tuple[str, str, str]] = []+@module_contract(+ permissions=[+ NetworkPermission(protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="network.http_fingerprint", failure_threshold=10),+ params_model=HTTPFingerprintParams,+)class HttpFingerprintModule(BaseModule):"""- network.http_fingerprint — Fingerprint web servers and applications — detect server software, frameworks, CMS, admin interf+ network.http_fingerprint — Fingerprint web servers and applications — detect server software, frameworks, CMS, admin interfaces, and exposed sensitive pathsOPSEC: LOWMITRE: "T1592.002", T1046 := "T1046"@@ -80,20 +98,24 @@ class HttpFingerprintModule(BaseModule):REQUIRES = []OUTPUTS = ["web_fingerprint", "admin_interfaces"]MITRE_TECHNIQUES = ["T1592.002", T1046 := "T1046"]+ PARAMS_MODEL = HTTPFingerprintParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight param checks before any network call."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif 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+ 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+).@@ -102,10 +124,45 @@ class HttpFingerprintModule(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", ""))- params = dict(ctx.params)- params.pop("target", None)- findings, raw = await self.run(target=target, **params)+ target = getattr(ctx, "target", "")+ ports = [80, 443, 8080, 8443, 8888]+ timeout = 5.0+ extra_params: dict[str, Any] = {}++ params = getattr(ctx, "params", {})+ if isinstance(params, HTTPFingerprintParams):+ target = params.target or target+ ports = params.ports or ports+ timeout = params.timeout or timeout+ elif isinstance(params, dict):+ target = params.get("target") or target+ ports = params.get("ports") or params.get("http_ports") or ports+ timeout = params.get("timeout") or timeout+ extra_params = {k: v for k, v in params.items() if k not in ("target", "ports", "http_ports", "timeout")}++ findings, raw = await self.run(+ target=target, ports=ports, timeout=timeout, **extra_params,+ )++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"http-{target.replace('.', '-')}",+ source_target=target,+ collected_by=self.MODULE_ID,+ data={+ "target": target,+ "title": finding.title,+ "severity": str(finding.severity),+ },+ tags=["network", "http_fingerprint"],+ )+ 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("web_fingerprint")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/network/pivot.py b/ares/modules/network/pivot.pyindex 6555ff5..f4d5be3 100644--- a/ares/modules/network/pivot.py+++ b/ares/modules/network/pivot.py@@ -28,7 +28,17 @@ from ares.core.campaign import Finding, Severityfrom ares.core.logger import audit, get_loggerfrom ares.core.security import sanitize_hostnamefrom ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import PivotParamsfrom ares.core.tracing import trace_module+from ares.sdk import (+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.network.pivot")@@ -36,9 +46,17 @@ logger = get_logger("ares.modules.network.pivot")_PIVOT_MANAGERS: dict[str, "Any"] = {} # campaign_id → PivotManager+@module_contract(+ permissions=[+ NetworkPermission(protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=PivotParams,+)class PivotModule(BaseModule):"""- network.pivot — Create SOCKS5/SSH tunnels through compromised hosts. All subsequent modules route through tunnel+ network.pivot — Create SOCKS5/SSH tunnels through compromised hosts. All subsequent modules route through tunnel automatically. Generates proxychains.conf. Supports chained pivots.OPSEC: LOWMITRE: "T1090.001", "T1021.004"@@ -59,37 +77,51 @@ class PivotModule(BaseModule):OUTPUTS = ["pivot_tunnel", "proxy_url", "proxychains_config"]MITRE_TECHNIQUES = ["T1090.001", "T1021.004"]MODULE_TIMEOUT_SECONDS: int | None = 60 # seconds+ PARAMS_MODEL = PivotParamsasync def validate(self, ctx: "Any") -> None:"""Enforce pivot host + credentials."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif 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("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("network.pivot requires 'target' — IP or hostname of the pivot host ""(a host where you have SSH access).",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("network.pivot requires 'username' for SSH authentication.",module_id=self.MODULE_ID, field="username",)- has_secret = bool(ctx.params.get("password") or ctx.params.get("key_path") or- ctx.params.get("secret") or- (getattr(ctx, "vault", None) and- getattr(getattr(ctx, "vault", None), "_store", None)))+ has_secret = False+ if isinstance(ctx.params, dict):+ has_secret = bool(ctx.params.get("password") or ctx.params.get("key_path") or+ ctx.params.get("secret") or+ (getattr(ctx, "vault", None) and+ getattr(getattr(ctx, "vault", None), "_store", None)))+ elif isinstance(ctx.params, PivotParams):+ has_secret = bool(ctx.params.password or ctx.params.key_path or+ (getattr(ctx, "vault", None) and+ getattr(getattr(ctx, "vault", None), "_store", None)))if not has_secret:raise ModuleValidationError("network.pivot requires SSH credentials — ""pass 'password', 'key_path', or provide a vault credential.",module_id=self.MODULE_ID, field="password",)+ await super().validate(ctx)async def execute(self, ctx: "Any") -> "ModuleResult":"""ExecutionContext-based entry point (v0.9.0+).@@ -100,16 +132,34 @@ class PivotModule(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", "")- secret = ctx.params.get("password", "") or ctx.params.get("secret", "")- key_path = ctx.params.get("key_path", "")- ssh_port = int(ctx.params.get("ssh_port", 22))- local_port = int(ctx.params.get("local_port", 0))- reachable_nets = ctx.params.get("reachable_subnets", [])- campaign_id = getattr(getattr(self, "campaign", None), "id", "default")+ target = getattr(ctx, "target", "")+ username = ""+ secret = ""+ key_path = ""+ ssh_port = 22+ local_port = 0+ reachable_nets: list[str] = []+ campaign_id = getattr(getattr(self, "campaign", None), "id", "default")++ params = getattr(ctx, "params", {})+ if isinstance(params, PivotParams):+ target = params.target or target+ username = params.username or ""+ raw_pass = params.password+ secret = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")+ key_path = params.key_path or ""+ local_port = params.local_port or 0+ elif isinstance(params, dict):+ target = params.get("target") or target+ username = params.get("username", "")+ raw_pass = params.get("password") or params.get("secret", "")+ secret = raw_pass.get_secret_value() if hasattr(raw_pass, "get_secret_value") else (raw_pass or "")+ key_path = params.get("key_path", "")+ ssh_port = int(params.get("ssh_port", 22))+ local_port = int(params.get("local_port", 0))+ reachable_nets = params.get("reachable_subnets", [])++ target = sanitize_hostname(target)# Reveal from vault if no plaintext secretif not secret and not key_path:@@ -126,6 +176,26 @@ class PivotModule(BaseModule):key_path=key_path, ssh_port=ssh_port, local_port=local_port,reachable_subnets=reachable_nets, 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"pivot-{target.replace('.', '-')}",+ source_target=target,+ collected_by=self.MODULE_ID,+ data={+ "target": target,+ "title": finding.title,+ "severity": str(finding.severity),+ },+ tags=["network", "pivot"],+ )+ 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/network/port_scan.py b/ares/modules/network/port_scan.pyindex 3d2e159..324fb41 100644--- a/ares/modules/network/port_scan.py+++ b/ares/modules/network/port_scan.py@@ -20,7 +20,17 @@ from typing import Anyfrom ares.core.logger import get_loggerfrom ares.core.campaign import Finding, Severityfrom ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import PortScanParamsfrom ares.core.tracing import trace_module+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.network.port_scan")@@ -80,9 +90,17 @@ async def _tcp_connect(host: str, port: int, timeout: float = 2.0) -> bool:return False+@module_contract(+ permissions=[+ NetworkPermission(protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="network.port_scan", failure_threshold=15),+ params_model=PortScanParams,+)class PortScanModule(BaseModule):"""- network.port_scan — Async TCP connect scan — identifies open ports and maps them to services and recommended attack+ network.port_scan — Async TCP connect scan — identifies open ports and maps them to services and recommended attack pathsOPSEC: MEDIUMMITRE: "T1046"@@ -100,20 +118,24 @@ class PortScanModule(BaseModule):REQUIRES = []OUTPUTS = ["open_ports", "service_map"]MITRE_TECHNIQUES = ["T1046"]+ PARAMS_MODEL = PortScanParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight param checks before any network call."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif 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+ target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))if not target:raise ModuleValidationError("network.port_scan requires 'target' — IP or CIDR to scan.",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+).@@ -123,12 +145,64 @@ class PortScanModule(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", "")})- params = dict(ctx.params)- params.pop("target", None)+ target = getattr(ctx, "target", "")+ ports = _DEFAULT_PORTS+ timeout = 2.0+ extra_params: dict[str, Any] = {}++ params = getattr(ctx, "params", {})+ if isinstance(params, PortScanParams):+ target = params.target or target+ timeout = params.timeout or timeout+ if isinstance(params.ports, str):+ if params.ports in ("top1000", "all", ""):+ ports = _DEFAULT_PORTS+ else:+ try:+ ports = [int(p.strip()) for p in params.ports.split(",") if p.strip().isdigit()]+ except Exception:+ ports = _DEFAULT_PORTS+ elif isinstance(params.ports, list):+ ports = params.ports+ elif isinstance(params, dict):+ target = params.get("target") or target+ timeout = float(params.get("timeout", 2.0))+ raw_ports = params.get("ports")+ if isinstance(raw_ports, list):+ ports = raw_ports+ elif isinstance(raw_ports, str):+ if raw_ports in ("top1000", "all", ""):+ ports = _DEFAULT_PORTS+ else:+ try:+ ports = [int(p.strip()) for p in raw_ports.split(",") if p.strip().isdigit()]+ except Exception:+ ports = _DEFAULT_PORTS+ extra_params = {k: v for k, v in params.items() if k not in ("target", "ports", "timeout")}+findings, raw = await self.run(- **params,- target=getattr(ctx, "target", ctx.params.get("target", "")),+ target=target, ports=ports, timeout=timeout, **extra_params,)++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"portscan-{target.replace('.', '-')}",+ source_target=target,+ collected_by=self.MODULE_ID,+ data={+ "target": target,+ "title": finding.title,+ "severity": str(finding.severity),+ },+ tags=["network", "port_scan"],+ )+ 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("open_ports")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,@@ -138,7 +212,17 @@ class PortScanModule(BaseModule):@trace_module("network.port_scan")async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:target = kwargs.get("target", "")- ports = kwargs.get("ports", _DEFAULT_PORTS)+ raw_ports = kwargs.get("ports", _DEFAULT_PORTS)+ if isinstance(raw_ports, str):+ if raw_ports in ("top1000", "all", ""):+ ports = _DEFAULT_PORTS+ else:+ try:+ ports = [int(p.strip()) for p in raw_ports.split(",") if p.strip().isdigit()]+ except Exception:+ ports = _DEFAULT_PORTS+ else:+ ports = raw_ports or _DEFAULT_PORTSdry_run = kwargs.get("dry_run", False)timeout = float(kwargs.get("timeout", 2.0))# Concurrency: stealth=10, normal=50, aggressive=200diff --git a/ares/modules/network/service_detect.py b/ares/modules/network/service_detect.pyindex 7bbf12c..b42d319 100644--- a/ares/modules/network/service_detect.py+++ b/ares/modules/network/service_detect.py@@ -18,7 +18,17 @@ from typing import Anyfrom ares.core.logger import get_loggerfrom ares.core.campaign import Finding, Severityfrom ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import ServiceDetectParamsfrom ares.core.tracing import trace_module+from ares.sdk import (+ CircuitBreaker,+ EvidenceRecord,+ ExecutionContext,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.network.service_detect")@@ -87,13 +97,20 @@ async def _grab_banner(host: str, port: int, timeout: float = 4.0,return ""+@module_contract(+ permissions=[+ NetworkPermission(protocols=["tcp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=CircuitBreaker(name="network.service_detect", failure_threshold=10),+ params_model=ServiceDetectParams,+)class ServiceDetectModule(BaseModule):"""- network.service_detect — Banner grabbing and version fingerprinting on open ports — identifies service versions and flags+ network.service_detect — Banner grabbing and version fingerprinting on open ports — identifies service versions and flags potentially vulnerable servicesOPSEC: LOWMITRE: "T1046", "T1590.004"- REQUIRES: "open_ports"OUTPUTS: "service_versions", "vulnerable_services""""MODULE_ID = "network.service_detect"@@ -108,20 +125,24 @@ class ServiceDetectModule(BaseModule):REQUIRES = ["open_ports"]OUTPUTS = ["service_versions", "vulnerable_services"]MITRE_TECHNIQUES = ["T1046", "T1590.004"]+ PARAMS_MODEL = ServiceDetectParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight param checks before any network call."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif 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+ 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+).@@ -131,12 +152,45 @@ class ServiceDetectModule(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", ctx.params.get("target", ""))- ports = ctx.params.get("ports", [])- params = dict(ctx.params)- params.pop("target", None)- params.pop("ports", None)- findings, raw = await self.run(target=target, ports=ports, **params)+ target = getattr(ctx, "target", "")+ ports = []+ timeout = 3.0+ extra_params: dict[str, Any] = {}++ params = getattr(ctx, "params", {})+ if isinstance(params, ServiceDetectParams):+ target = params.target or target+ ports = params.ports or []+ timeout = params.timeout or timeout+ elif isinstance(params, dict):+ target = params.get("target") or target+ ports = params.get("ports", [])+ timeout = float(params.get("timeout", 3.0))+ extra_params = {k: v for k, v in params.items() if k not in ("target", "ports", "timeout")}++ findings, raw = await self.run(+ target=target, ports=ports, timeout=timeout, **extra_params,+ )++ # Cryptographic Evidence Records with SHA-256 Merkle Provenance+ evidence_chain: list[EvidenceRecord] = []+ for finding in findings:+ ev = EvidenceRecord(+ artifact_id=f"service-detect-{target.replace('.', '-')}",+ source_target=target,+ collected_by=self.MODULE_ID,+ data={+ "target": target,+ "title": finding.title,+ "severity": str(finding.severity),+ },+ tags=["network", "service_detect"],+ )+ 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("service_versions")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/network/snmp_enum.py b/ares/modules/network/snmp_enum.pyindex eb2f667..9a8834a 100644--- a/ares/modules/network/snmp_enum.py+++ b/ares/modules/network/snmp_enum.py@@ -25,7 +25,17 @@ from typing import Anyfrom ares.core.logger import get_loggerfrom ares.core.campaign import Finding, Severityfrom ares.modules.base import BaseModule, OpsecLevel+from ares.modules.params import SNMPEnumParamsfrom ares.core.tracing import trace_module+from ares.sdk import (+ EvidenceRecord,+ ExecutionContext,+ LockoutCircuitBreaker,+ ModuleResult,+ NetworkPermission,+ ProcessPermission,+ module_contract,+)logger = get_logger("ares.modules.network.snmp_enum")@@ -103,7 +113,7 @@ def _snmp_walk_sync(host: str, community: str, port: int,ContextData, ObjectType, ObjectIdentity,)except ImportError:- return []+ return ["_error: pysnmp not installed"]rows: list[str] = []engine = SnmpEngine()@@ -118,17 +128,25 @@ def _snmp_walk_sync(host: str, community: str, port: int,if error_indication or error_status:breakfor var_bind in var_binds:- val = str(var_bind[1]).strip()- if val and val not in rows:- rows.append(val)+ rows.append(str(var_bind[1]))+ if len(rows) >= max_rows:+ breakif len(rows) >= max_rows:breakreturn rows+@module_contract(+ permissions=[+ NetworkPermission(ports=[161, 162], protocols=["udp"]),+ ProcessPermission(allow_subprocesses=False),+ ],+ circuit_breaker=LockoutCircuitBreaker(),+ params_model=SNMPEnumParams,+)class SnmpEnumModule(BaseModule):"""- network.snmp_enum — Test common SNMP community strings and enumerate system info via OID walk — identifies default c+ network.snmp_enum — Test common SNMP community strings and enumerate system info via OID walk — identifies default credentials, system details, interfaces, and running processesOPSEC: LOWMITRE: "T1046", "T1590"@@ -146,20 +164,24 @@ class SnmpEnumModule(BaseModule):REQUIRES = []OUTPUTS = ["snmp_findings", "system_info"]MITRE_TECHNIQUES = ["T1046", "T1590"]+ PARAMS_MODEL = SNMPEnumParamsasync def validate(self, ctx: "Any") -> None:"""Pre-flight param checks before any network call."""- await super().validate(ctx)from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationErrorif 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+ 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+).@@ -170,10 +192,47 @@ class SnmpEnumModule(BaseModule):return ModuleResult(status="dry_run", module_id=self.MODULE_ID,raw={"dry_run": True,"target": getattr(ctx, "target", "")})- target = getattr(ctx, "target", ctx.params.get("target", ""))- params = dict(ctx.params)- params.pop("target", None)- findings, raw = await self.run(target=target, **params)+ target = getattr(ctx, "target", "")+ port = 161+ communities = None+ extra_params: dict[str, Any] = {}++ params = getattr(ctx, "params", {})+ if isinstance(params, SNMPEnumParams):+ target = params.target or target+ port = params.port or port+ communities = params.communities+ elif isinstance(params, dict):+ target = params.get("target") or target+ port = int(params.get("port") or params.get("snmp_port", 161))+ communities = params.get("communities")+ extra_params = {k: v for k, v in params.items() if k not in ("target", "port", "snmp_port", "communities")}++ kwargs: dict[str, Any] = {"target": target, "port": port, **extra_params}+ if communities is not None:+ kwargs["communities"] = communities++ 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"snmp-{target.replace('.', '-')}",+ source_target=target,+ collected_by=self.MODULE_ID,+ data={+ "target": target,+ "title": finding.title,+ "severity": str(finding.severity),+ },+ tags=["network", "snmp_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 or raw.get("valid_communities")) else "partial",findings=findings, raw=raw, module_id=self.MODULE_ID,diff --git a/ares/modules/params.py b/ares/modules/params.pyindex 5129802..846bed1 100644--- a/ares/modules/params.py+++ b/ares/modules/params.py@@ -836,7 +836,7 @@ class PivotParams(ModuleParams):"SSH private key path", required=False, default=None, max_length=512)local_port: int = param(- "Local SOCKS5 port", required=False, default=1080, ge=1024, le=65535+ "Local SOCKS5 port", required=False, default=1080, ge=0, le=65535)diff --git a/tests/unit/test_module_execute_adapters.py b/tests/unit/test_module_execute_adapters.pyindex 3aae094..a954ae8 100644--- a/tests/unit/test_module_execute_adapters.py+++ b/tests/unit/test_module_execute_adapters.py@@ -38,8 +38,8 @@ def _ctx(params: dict[str, Any]) -> SimpleNamespace:("ares.modules.network.dns_enum","DnsEnumModule",- {"target": "example.com", "domain": "example.com"},- {"target": "example.com", "domain": "example.com"},+ {"target": "10.0.0.1", "domain": "example.com"},+ {"target": "10.0.0.1", "domain": "example.com"},),("ares.modules.network.port_scan",@@ -59,6 +59,12 @@ def _ctx(params: dict[str, Any]) -> SimpleNamespace:{"target": "10.0.0.1", "port": 161, "communities": ["public"]},{"target": "10.0.0.1", "port": 161},),+ (+ "ares.modules.network.pivot",+ "PivotModule",+ {"target": "10.0.0.1", "username": "admin", "password": "pw", "local_port": 1080},+ {"target": "10.0.0.1", "username": "admin", "local_port": 1080},+ ),("ares.modules.cloud.identity_federation","CloudIdentityFederationModule",