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 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.py
index 8a74fd3..e3b5e05 100644
--- a/ares/modules/network/dns_enum.py
+++ b/ares/modules/network/dns_enum.py
@@ -15,7 +15,17 @@ from typing import Any
from ares.core.logger import get_logger
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import DNSEnumParams
from 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 hostnames
OPSEC: LOW
MITRE: "T1590.002"
@@ -63,20 +81,26 @@ class DnsEnumModule(BaseModule):
REQUIRES = []
OUTPUTS = ["dns_records", "subdomains"]
MITRE_TECHNIQUES = ["T1590.002"]
+ PARAMS_MODEL = DNSEnumParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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 ModuleResult
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", ""))
- 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.py
index 7ea2402..d9b88b6 100644
--- a/ares/modules/network/http_fingerprint.py
+++ b/ares/modules/network/http_fingerprint.py
@@ -14,7 +14,17 @@ from typing import Any
from ares.core.logger import get_logger
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import HTTPFingerprintParams
from 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 paths
OPSEC: LOW
MITRE: "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 = HTTPFingerprintParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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 ModuleResult
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", ""))
- 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.py
index 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, Severity
from ares.core.logger import audit, get_logger
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import PivotParams
from 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: LOW
MITRE: "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 = PivotParams
async def validate(self, ctx: "Any") -> None:
"""Enforce pivot host + credentials."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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 secret
if 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.py
index 3d2e159..324fb41 100644
--- a/ares/modules/network/port_scan.py
+++ b/ares/modules/network/port_scan.py
@@ -20,7 +20,17 @@ from typing import Any
from ares.core.logger import get_logger
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import PortScanParams
from 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 paths
OPSEC: MEDIUM
MITRE: "T1046"
@@ -100,20 +118,24 @@ class PortScanModule(BaseModule):
REQUIRES = []
OUTPUTS = ["open_ports", "service_map"]
MITRE_TECHNIQUES = ["T1046"]
+ PARAMS_MODEL = PortScanParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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_PORTS
dry_run = kwargs.get("dry_run", False)
timeout = float(kwargs.get("timeout", 2.0))
# Concurrency: stealth=10, normal=50, aggressive=200
diff --git a/ares/modules/network/service_detect.py b/ares/modules/network/service_detect.py
index 7bbf12c..b42d319 100644
--- a/ares/modules/network/service_detect.py
+++ b/ares/modules/network/service_detect.py
@@ -18,7 +18,17 @@ from typing import Any
from ares.core.logger import get_logger
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import ServiceDetectParams
from 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 services
OPSEC: LOW
MITRE: "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 = ServiceDetectParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index eb2f667..9a8834a 100644
--- a/ares/modules/network/snmp_enum.py
+++ b/ares/modules/network/snmp_enum.py
@@ -25,7 +25,17 @@ from typing import Any
from ares.core.logger import get_logger
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import SNMPEnumParams
from 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:
break
for 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:
+ break
if len(rows) >= max_rows:
break
return 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 processes
OPSEC: LOW
MITRE: "T1046", "T1590"
@@ -146,20 +164,24 @@ class SnmpEnumModule(BaseModule):
REQUIRES = []
OUTPUTS = ["snmp_findings", "system_info"]
MITRE_TECHNIQUES = ["T1046", "T1590"]
+ PARAMS_MODEL = SNMPEnumParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if 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.py
index 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.py
index 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",