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 3 credential & lateral movement to Next-Gen Sovereign SDK v2

Mafifrizi459a7011c03c
diff --git a/ares/core/campaign.py b/ares/core/campaign.py
index 4e3db23..f099379 100644
--- a/ares/core/campaign.py
+++ b/ares/core/campaign.py
@@ -212,7 +212,7 @@ class Campaign(BaseModel):
target = ip.strip().lower()
explicit_hosts = {
entry.strip().lower()
- for entry in [*self.targets, self.dc]
+ for entry in [*self.targets, self.dc, self.domain]
if entry and entry.strip()
}
if target and target in explicit_hosts:
@@ -254,7 +254,7 @@ class Campaign(BaseModel):
else:
_log.debug("scope_check_hostname_resolved: %r → %s (in scope)", ip, resolved_ip)
return in_scope
- except _socket.gaierror as dns_exc:
+ except (_socket.gaierror, TimeoutError, Exception) as dns_exc:
_log.warning(
"scope_check_dns_failed: hostname %r could not be resolved (%s) — BLOCKING "
"(add explicit IP to scope or ensure DNS is available)",
diff --git a/ares/modules/credential/crack.py b/ares/modules/credential/crack.py
index 09e2737..e4583ad 100644
--- a/ares/modules/credential/crack.py
+++ b/ares/modules/credential/crack.py
@@ -22,7 +22,18 @@ from typing import Any
from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
-from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import CredentialCrackParams
+from ares.sdk import (
+ BaseModule,
+ CircuitBreaker,
+ EvidenceRecord,
+ ExecutionContext,
+ ModuleResult,
+ NetworkPermission,
+ OpsecLevel,
+ ProcessPermission,
+ module_contract,
+)
from ares.core.tracing import trace_module
logger = get_logger("ares.modules.credential.crack")
@@ -52,7 +63,15 @@ _CRACK_PRIORITY: dict[str, int] = {
}
-class CrackModule(BaseModule):
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[]),
+ ProcessPermission(allow_subprocesses=True, allowed_binaries=["hashcat", "john", "hashcat.exe", "john.exe"]),
+ ],
+ circuit_breaker=CircuitBreaker(name="credential_crack", failure_threshold=5, recovery_timeout_s=60.0),
+ params_model=CredentialCrackParams,
+)
+class CrackModule(BaseModule[CredentialCrackParams, ModuleResult]):
"""
credential.crack — "Crack hashes in CredentialVault using hashcat (GPU
@@ -74,10 +93,10 @@ class CrackModule(BaseModule):
MITRE_TECHNIQUES = ["T1110.002"]
MODULE_AUTHOR = "ARES Team <[email protected]>"
MODULE_TIMEOUT_SECONDS: int | None = 3600 # seconds
+ PARAMS_MODEL = CredentialCrackParams
async def validate(self, ctx: "Any") -> None:
"""Enforce vault has hash credentials to crack."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
@@ -102,6 +121,7 @@ class CrackModule(BaseModule):
"or all hashes have already been cracked.",
module_id=self.MODULE_ID, field="vault",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -119,6 +139,26 @@ class CrackModule(BaseModule):
findings, raw = await self.run(
vault=vault, timeout_s=timeout_s, use_gpu=use_gpu, wordlist=wordlist,
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for cred in raw.get("cracked_credentials", []):
+ ev = EvidenceRecord(
+ artifact_id=f"crack-{cred.get('username', 'unknown').lower()}",
+ source_target="localhost",
+ collected_by=self.MODULE_ID,
+ data={
+ "username": cred.get("username"),
+ "domain": cred.get("domain"),
+ "hash_type": cred.get("hash_type"),
+ },
+ tags=["credential", "crack", "hashcat"],
+ )
+ 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/credential/golden_ticket.py b/ares/modules/credential/golden_ticket.py
index 1c84c9c..ca7a719 100644
--- a/ares/modules/credential/golden_ticket.py
+++ b/ares/modules/credential/golden_ticket.py
@@ -17,13 +17,32 @@ from typing import Any
from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
-from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import GoldenTicketParams
+from ares.sdk import (
+ BaseModule,
+ EvidenceRecord,
+ ExecutionContext,
+ FilesystemPermission,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ OpsecLevel,
+ ProcessPermission,
+ module_contract,
+)
from ares.core.tracing import trace_module
logger = get_logger("ares.modules.credential.golden_ticket")
-class GoldenTicketModule(BaseModule):
+@module_contract(
+ permissions=[
+ FilesystemPermission(read_only=False),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=GoldenTicketParams,
+)
+class GoldenTicketModule(BaseModule[GoldenTicketParams, ModuleResult]):
"""
credential.golden_ticket — Forge a Kerberos TGT using the krbtgt hash — provides persistent domain access that survives pas
@@ -44,6 +63,7 @@ class GoldenTicketModule(BaseModule):
REQUIRES = ["ntlm_hashes", "domain_admin_creds"]
OUTPUTS = ["golden_ticket", "kerberos_ticket"]
MITRE_TECHNIQUES = ["T1558.001"]
+ PARAMS_MODEL = GoldenTicketParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -121,12 +141,13 @@ class GoldenTicketModule(BaseModule):
async def validate(self, ctx: "Any") -> None:
"""Enforce domain, krbtgt hash, and domain SID before ticket forge."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
import re as _re
if not isinstance(ctx, ExecutionContext):
return
+ if isinstance(ctx.params, dict) and not ctx.params.get("domain") and getattr(ctx, "domain", None):
+ ctx.params["domain"] = ctx.domain
domain = getattr(ctx, "domain", "") or ctx.params.get("domain", "")
krbtgt_hash = ctx.params.get("krbtgt_hash", "")
domain_sid = ctx.params.get("domain_sid", "")
@@ -161,6 +182,7 @@ class GoldenTicketModule(BaseModule):
"Expected: S-1-5-21-<sub1>-<sub2>-<sub3>",
module_id=self.MODULE_ID, field="domain_sid",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -175,6 +197,27 @@ class GoldenTicketModule(BaseModule):
**params,
target=getattr(ctx, "target", ctx.params.get("target", "")),
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ if raw.get("ccache_path") or raw.get("ticket_b64"):
+ ev = EvidenceRecord(
+ artifact_id=f"golden-ticket-{str(params.get('username', 'admin')).lower()}",
+ source_target=params.get("domain", "domain"),
+ collected_by=self.MODULE_ID,
+ data={
+ "domain": params.get("domain"),
+ "username": params.get("username"),
+ "domain_sid": params.get("domain_sid"),
+ "ccache_path": raw.get("ccache_path"),
+ },
+ tags=["credential", "kerberos", "golden_ticket"],
+ )
+ 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/credential/pass_spray.py b/ares/modules/credential/pass_spray.py
index 2e8d742..783e77a 100644
--- a/ares/modules/credential/pass_spray.py
+++ b/ares/modules/credential/pass_spray.py
@@ -16,7 +16,18 @@ from typing import Any
from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
-from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import PassSprayParams
+from ares.sdk import (
+ BaseModule,
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ OpsecLevel,
+ ProcessPermission,
+ module_contract,
+)
from ares.core.tracing import trace_module
logger = get_logger("ares.modules.credential.pass_spray")
@@ -208,7 +219,15 @@ def generate_smart_wordlist(
return unique
-class PassSprayModule(BaseModule):
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[389, 636, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=PassSprayParams,
+)
+class PassSprayModule(BaseModule[PassSprayParams, ModuleResult]):
"""
credential.pass_spray — Low-and-slow password spray against domain accounts — built-in lockout protection, one password
@@ -229,6 +248,7 @@ class PassSprayModule(BaseModule):
REQUIRES = ["user_list"]
OUTPUTS = ["valid_credentials"]
MITRE_TECHNIQUES = ["T1110.003"]
+ PARAMS_MODEL = PassSprayParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -305,11 +325,15 @@ class PassSprayModule(BaseModule):
async def validate(self, ctx: "Any") -> None:
"""Enforce target, user list, and password list before spray."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
+ 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", "")
users = ctx.params.get("users", [])
passwords = ctx.params.get("passwords", [])
@@ -329,6 +353,7 @@ class PassSprayModule(BaseModule):
"credential.pass_spray requires 'passwords' list.",
module_id=self.MODULE_ID, field="passwords",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -347,6 +372,26 @@ class PassSprayModule(BaseModule):
findings, raw = await self.run(
target=target, domain=domain, users=users, passwords=passwords, **params
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for cred in raw.get("valid_credentials", []):
+ ev = EvidenceRecord(
+ artifact_id=f"spray-{cred.get('username', 'unknown').lower()}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "username": cred.get("username"),
+ "domain": cred.get("domain", domain),
+ "protocol": cred.get("protocol", "smb"),
+ },
+ tags=["credential", "password_spray", "valid_account"],
+ )
+ 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/credential/pass_the_hash.py b/ares/modules/credential/pass_the_hash.py
index e8a209e..cb84728 100644
--- a/ares/modules/credential/pass_the_hash.py
+++ b/ares/modules/credential/pass_the_hash.py
@@ -14,13 +14,32 @@ from typing import Any
from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
-from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import PassTheHashParams
+from ares.sdk import (
+ BaseModule,
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ OpsecLevel,
+ ProcessPermission,
+ module_contract,
+)
from ares.core.tracing import trace_module
logger = get_logger("ares.modules.credential.pass_the_hash")
-class PassTheHashModule(BaseModule):
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[135, 139, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=PassTheHashParams,
+)
+class PassTheHashModule(BaseModule[PassTheHashParams, ModuleResult]):
"""
credential.pass_the_hash — Authenticate to target using NTLM hash — no plaintext password required"
@@ -41,6 +60,7 @@ class PassTheHashModule(BaseModule):
REQUIRES = ["ntlm_hashes"]
OUTPUTS = ["valid_credentials", "owned_hosts"]
MITRE_TECHNIQUES = ["T1550.002"]
+ PARAMS_MODEL = PassTheHashParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -104,11 +124,19 @@ class PassTheHashModule(BaseModule):
async def validate(self, ctx: "Any") -> None:
"""Enforce target and NTLM hash before any SMB connection."""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
+ 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
+ if not ctx.params.get("username"):
+ ctx.params["username"] = "Administrator"
+ if not ctx.params.get("nt_hash") and ctx.params.get("hash"):
+ ctx.params["nt_hash"] = ctx.params["hash"]
target = getattr(ctx, "target", "") or ctx.params.get("target", "")
nt_hash = ctx.params.get("nt_hash", "") or ctx.params.get("hash", "")
if not target:
@@ -123,6 +151,7 @@ class PassTheHashModule(BaseModule):
"the 32-character NT hash from ad.dcsync output.",
module_id=self.MODULE_ID, field="nt_hash",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+).
@@ -141,6 +170,27 @@ class PassTheHashModule(BaseModule):
target=target, username=username, nt_hash=nt_hash,
lm_hash=lm_hash, domain=domain, command=command
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for cred in raw.get("valid_credentials", []):
+ ev = EvidenceRecord(
+ artifact_id=f"pth-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "username": username,
+ "domain": domain,
+ "owned": bool(raw.get("owned_hosts")),
+ },
+ tags=["credential", "pass_the_hash", "lateral_movement"],
+ )
+ 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/credential/reuse.py b/ares/modules/credential/reuse.py
index dcf0f31..d9c961b 100644
--- a/ares/modules/credential/reuse.py
+++ b/ares/modules/credential/reuse.py
@@ -13,14 +13,33 @@ from __future__ import annotations
from typing import Any
from ares.core.campaign import Finding, Severity
-from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import CredentialReuseParams
+from ares.sdk import (
+ BaseModule,
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ OpsecLevel,
+ ProcessPermission,
+ module_contract,
+)
from ares.core.logger import get_logger, audit
from ares.core.tracing import trace_module
logger = get_logger("ares.modules.credential.reuse")
-class CredentialReuseModule(BaseModule):
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[22, 389, 445, 636, 3389, 5985, 5986], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=CredentialReuseParams,
+)
+class CredentialReuseModule(BaseModule[CredentialReuseParams, ModuleResult]):
"""
Try each captured credential against one or more targets.
@@ -38,14 +57,16 @@ class CredentialReuseModule(BaseModule):
MITRE_TECHNIQUES = ["T1078", "T1550.002"]
OPSEC_LEVEL = OpsecLevel.MEDIUM
+ PARAMS_MODEL = CredentialReuseParams
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
+ if isinstance(ctx.params, dict) and 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 not target:
raise ModuleValidationError(
@@ -59,6 +80,7 @@ class CredentialReuseModule(BaseModule):
"run ad.kerberoast/dcsync/pass_the_hash first.",
module_id=self.MODULE_ID, field="vault",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""ExecutionContext-based entry point (v0.9.0+)."""
@@ -75,6 +97,26 @@ class CredentialReuseModule(BaseModule):
vault=getattr(ctx, "vault", None),
target=getattr(ctx, "target", ctx.params.get("target", "")),
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for cred in raw.get("valid_credentials", []):
+ ev = EvidenceRecord(
+ artifact_id=f"reuse-{str(cred.get('username', 'cred')).lower()}",
+ source_target=getattr(ctx, "target", ctx.params.get("target", "")),
+ collected_by=self.MODULE_ID,
+ data={
+ "username": cred.get("username"),
+ "domain": cred.get("domain"),
+ "service": cred.get("service"),
+ },
+ tags=["credential", "reuse", "spray"],
+ )
+ 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/modules/lateral/dcom.py b/ares/modules/lateral/dcom.py
index 479d254..7978989 100644
--- a/ares/modules/lateral/dcom.py
+++ b/ares/modules/lateral/dcom.py
@@ -32,10 +32,28 @@ from ares.modules.lateral.modules import (
BaseLateralModule, LateralResult, LateralTechnique,
)
from ares.modules.base import OpsecLevel
+from ares.modules.params import DCOMParams
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.lateral.dcom")
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[135, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=DCOMParams,
+)
class DCOMLateral(BaseLateralModule):
"""
DCOM-based lateral movement via MMC20.Application,
@@ -59,6 +77,7 @@ class DCOMLateral(BaseLateralModule):
MITRE_TECHNIQUES = ["T1021.003"]
MODULE_AUTHOR = "ARES Team <[email protected]>"
MIN_NOISE_PROFILE = "normal" # blocked in stealth — creates remote process
+ PARAMS_MODEL = DCOMParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -106,11 +125,19 @@ class DCOMLateral(BaseLateralModule):
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
+ 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
+ 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 not target:
raise ModuleValidationError(
@@ -122,6 +149,7 @@ class DCOMLateral(BaseLateralModule):
"lateral.dcom requires 'username' with local_admin_creds.",
module_id=self.MODULE_ID, field="username",
)
+ await super().validate(ctx)
async def move(
self,
diff --git a/ares/modules/lateral/modules.py b/ares/modules/lateral/modules.py
index 7ff7e4f..dcdea02 100644
--- a/ares/modules/lateral/modules.py
+++ b/ares/modules/lateral/modules.py
@@ -27,6 +27,22 @@ from typing import Any, TYPE_CHECKING
from ares.core.campaign import Campaign, Finding, Severity
from ares.core.logger import audit, get_logger
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import (
+ PsExecParams,
+ WmiExecParams,
+ WinRMParams,
+ SSHPivotParams,
+ RDPLateralParams,
+)
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
if TYPE_CHECKING:
from ares.credential.vault import CredentialVault, Credential
@@ -139,11 +155,19 @@ class BaseLateralModule(BaseModule):
Enforce target and credentials before any network connection.
Applied to all lateral modules: psexec, wmiexec, dcom, winrm, rdp, ssh.
"""
- await super().validate(ctx)
from ares.core.context import ExecutionContext
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
+ 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
+ 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 not target:
raise ModuleValidationError(
@@ -164,6 +188,7 @@ class BaseLateralModule(BaseModule):
"pass 'password', 'nt_hash' (NTLM), or provide a vault credential.",
module_id=self.MODULE_ID, field="password",
)
+ await super().validate(ctx)
async def execute(self, ctx: "Any") -> "ModuleResult":
"""
@@ -199,6 +224,27 @@ class BaseLateralModule(BaseModule):
target=target, username=username, domain=domain,
secret=secret, command=command, **params,
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"lateral-{self.MODULE_ID.replace('.', '-')}-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "username": username,
+ "domain": domain,
+ "title": finding.title,
+ },
+ tags=["lateral", self.MODULE_ID.split(".")[-1]],
+ )
+ 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,
@@ -272,6 +318,14 @@ class BaseLateralModule(BaseModule):
# ── PsExec ─────────────────────────────────────────────────────────────────────
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[139, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=PsExecParams,
+)
class PsExecLateral(BaseLateralModule):
"""
PsExec-style lateral movement via SMB + Service Control Manager.
@@ -286,6 +340,7 @@ class PsExecLateral(BaseLateralModule):
REQUIRES = ["smb_access", "local_admin_creds"]
OUTPUTS = ["lateral_session", "command_output"]
MITRE_TECHNIQUES = ["T1569.002", "T1021.002"]
+ PARAMS_MODEL = PsExecParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -505,6 +560,14 @@ class PsExecLateral(BaseLateralModule):
# ── WmiExec ────────────────────────────────────────────────────────────────────
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[135, 445], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=WmiExecParams,
+)
class WmiExecLateral(BaseLateralModule):
"""
WMI-based lateral movement via Win32_Process.Create.
@@ -519,6 +582,7 @@ class WmiExecLateral(BaseLateralModule):
REQUIRES = ["wmi_access", "domain_creds"]
OUTPUTS = ["lateral_session", "command_output"]
MITRE_TECHNIQUES = ["T1047", "T1021.002"]
+ PARAMS_MODEL = WmiExecParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -706,6 +770,14 @@ class WmiExecLateral(BaseLateralModule):
# ── WinRM ──────────────────────────────────────────────────────────────────────
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[5985, 5986], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=WinRMParams,
+)
class WinRMLateral(BaseLateralModule):
"""
WinRM / PowerShell Remoting lateral movement.
@@ -720,6 +792,7 @@ class WinRMLateral(BaseLateralModule):
REQUIRES = ["winrm_access", "domain_creds"]
OUTPUTS = ["lateral_session", "command_output", "powershell_session"]
MITRE_TECHNIQUES = ["T1021.006", "T1059.001"]
+ PARAMS_MODEL = WinRMParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
@@ -820,6 +893,14 @@ class WinRMLateral(BaseLateralModule):
# ── SSH Pivot ──────────────────────────────────────────────────────────────────
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[22], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=SSHPivotParams,
+)
class SSHPivot(BaseLateralModule):
"""
SSH lateral movement and pivot tunnel establishment.
@@ -837,6 +918,7 @@ class SSHPivot(BaseLateralModule):
REQUIRES = ["ssh_access", "ssh_credentials"]
OUTPUTS = ["lateral_session", "socks5_proxy", "command_output"]
MITRE_TECHNIQUES = ["T1021.004", "T1090.001"]
+ PARAMS_MODEL = SSHPivotParams
async def move(self, target, username, domain, secret, command="id", **kwargs) -> LateralResult:
import time
@@ -987,6 +1069,14 @@ class SSHPivot(BaseLateralModule):
# ── RDP Lateral ────────────────────────────────────────────────────────────────
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[3389], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=RDPLateralParams,
+)
class RDPLateral(BaseLateralModule):
"""
RDP-based lateral movement.
@@ -1002,6 +1092,7 @@ class RDPLateral(BaseLateralModule):
OUTPUTS = ["lateral_session"]
MITRE_TECHNIQUES = ["T1021.001"]
MIN_NOISE_PROFILE = "normal"
+ PARAMS_MODEL = RDPLateralParams
async def assess_feasibility(self, ctx: "Any") -> "FeasibilityReport":
"""
diff --git a/ares/modules/lateral/mssql.py b/ares/modules/lateral/mssql.py
index c97c6b9..990ffc0 100644
--- a/ares/modules/lateral/mssql.py
+++ b/ares/modules/lateral/mssql.py
@@ -23,11 +23,29 @@ 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 MSSQLParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.lateral.mssql")
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[1433], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=MSSQLParams,
+)
class MSSQLModule(BaseModule):
"""
lateral.mssql — MSSQL lateral movement via xp_cmdshell, linked servers, EXECUTE AS LOGIN, and UNC path NTLM coer
@@ -48,6 +66,7 @@ class MSSQLModule(BaseModule):
REQUIRES = []
OUTPUTS = ["command_output", "lateral_session"]
MITRE_TECHNIQUES = ["T1505.001"]
+ PARAMS_MODEL = MSSQLParams
async def validate(self, ctx: "Any") -> None:
await super().validate(ctx)
@@ -94,6 +113,27 @@ class MSSQLModule(BaseModule):
port=port, command=command, technique=technique,
linked=linked, listener=listener,
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"lateral-mssql-{target.replace('.', '-')}",
+ source_target=target,
+ collected_by=self.MODULE_ID,
+ data={
+ "target": target,
+ "username": username,
+ "technique": technique,
+ "title": finding.title,
+ },
+ tags=["lateral", "mssql"],
+ )
+ 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/lateral/ntlm_relay.py b/ares/modules/lateral/ntlm_relay.py
index 148b6ba..20a07ad 100644
--- a/ares/modules/lateral/ntlm_relay.py
+++ b/ares/modules/lateral/ntlm_relay.py
@@ -32,7 +32,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 NTLMRelayParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.lateral.ntlm_relay")
@@ -72,6 +82,14 @@ class RBCDResult:
error: str = ""
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[88, 135, 389, 445, 636], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=NTLMRelayParams,
+)
class NTLMRelayModule(BaseModule):
"""
lateral.ntlm_relay — Full NTLM relay attack automation
@@ -96,6 +114,7 @@ class NTLMRelayModule(BaseModule):
REQUIRES = ["domain_creds"]
OUTPUTS = ["relay_targets", "machine_account", "kerberos_ticket", "owned_hosts"]
MITRE_TECHNIQUES = ["T1557.001", "T1134.001"]
+ PARAMS_MODEL = NTLMRelayParams
async def validate(self, ctx: "Any") -> None:
await super().validate(ctx)
@@ -137,6 +156,26 @@ class NTLMRelayModule(BaseModule):
target_user=ctx.params.get("target_user", "administrator"),
mode=ctx.params.get("mode", "full"),
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"lateral-ntlm-relay-{ad['dc'].replace('.', '-')}",
+ source_target=ad["dc"],
+ collected_by=self.MODULE_ID,
+ data={
+ "dc": ad["dc"],
+ "domain": ad["domain"],
+ "title": finding.title,
+ },
+ tags=["lateral", "ntlm_relay"],
+ )
+ 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/lateral/smb_relay.py b/ares/modules/lateral/smb_relay.py
index 8982907..30b43bf 100644
--- a/ares/modules/lateral/smb_relay.py
+++ b/ares/modules/lateral/smb_relay.py
@@ -39,7 +39,17 @@ from ares.core.logger import get_logger, audit
from ares.core.campaign import Finding, Severity
from ares.core.security import sanitize_hostname
from ares.modules.base import BaseModule, OpsecLevel
+from ares.modules.params import SMBRelayParams
from ares.core.tracing import trace_module
+from ares.sdk import (
+ EvidenceRecord,
+ ExecutionContext,
+ LockoutCircuitBreaker,
+ ModuleResult,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.lateral.smb_relay")
@@ -161,6 +171,14 @@ async def _check_smb_signing(target: str, port: int = 445, timeout: float = 8.0)
return result
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[139, 389, 445, 636], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=LockoutCircuitBreaker(),
+ params_model=SMBRelayParams,
+)
class SMBRelayAuditModule(BaseModule):
"""
Checks SMB signing configuration on one or more targets.
@@ -179,6 +197,7 @@ class SMBRelayAuditModule(BaseModule):
REQUIRES = []
OUTPUTS = ["smb_signing_config", "relay_candidates"]
MITRE_TECHNIQUES = ["T1557.001", "T1082"]
+ PARAMS_MODEL = SMBRelayParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
@@ -212,6 +231,26 @@ class SMBRelayAuditModule(BaseModule):
check_ldap = ctx.params.get("check_ldap", False)
findings, raw = await self.run(targets=targets, check_ldap=check_ldap)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"lateral-smb-relay-audit-{str(targets[0] if targets else 'audit').replace('.', '-')}",
+ source_target=targets[0] if targets else "audit",
+ collected_by=self.MODULE_ID,
+ data={
+ "targets": targets,
+ "check_ldap": check_ldap,
+ "title": finding.title,
+ },
+ tags=["lateral", "smb_relay"],
+ )
+ 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/params.py b/ares/modules/params.py
index 0c66d2f..5129802 100644
--- a/ares/modules/params.py
+++ b/ares/modules/params.py
@@ -137,6 +137,13 @@ class ModuleParams(BaseModel):
return False
return hasattr(self, key)
+ def __iter__(self) -> Any:
+ for k, v in super().__iter__():
+ if hasattr(v, "get_secret_value"):
+ yield k, v.get_secret_value()
+ else:
+ yield k, v
+
@classmethod
def validate_dict(cls, data: dict[str, Any]) -> ModuleParams:
"""
diff --git a/ares/sdk/pipeline/interceptors.py b/ares/sdk/pipeline/interceptors.py
index 6d570bc..5ede088 100644
--- a/ares/sdk/pipeline/interceptors.py
+++ b/ares/sdk/pipeline/interceptors.py
@@ -41,6 +41,14 @@ class ScopeEnforcementInterceptor(BaseExecutionInterceptor):
if not target:
return # Targetless modules (cloud/recon metadata) handled by validation
+ # Skip network scope validation for local/offline modules that do not declare network capabilities
+ perms = getattr(module, "PERMISSIONS", [])
+ if perms:
+ from ares.sdk.security.permissions import NetworkPermission
+ has_net = any(isinstance(p, NetworkPermission) or getattr(p, "name", "") == "network" for p in perms)
+ if not has_net:
+ return
+
# 1. Check direct ScopeGuard if attached to context
if hasattr(ctx, "scope_guard") and ctx.scope_guard is not None:
ctx.scope_guard.assert_in_scope(target, action=getattr(module, "MODULE_ID", "module"))
diff --git a/tests/unit/test_api_endpoints.py b/tests/unit/test_api_endpoints.py
index 3092c97..fb0034a 100644
--- a/tests/unit/test_api_endpoints.py
+++ b/tests/unit/test_api_endpoints.py
@@ -398,7 +398,7 @@ def test_module_outcome_success_mapping(outcome: str, expected: bool) -> None:
assert _is_successful_module_outcome(outcome) is expected
[email protected](scope="module")
[email protected](scope="module", autouse=True)
def _app_mock_db():
global _PRODUCTION_C_LIVE_DESCRIPTOR_GATE
# Clear lru_cache so unit tests always use UNIT env vars,