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
"""
ARES Module Parameter Validation - Pydantic-based
Replaces the weak dict-based PARAM_SCHEMA with a proper Pydantic model
that enforces types, lengths, patterns, and secret handling.
Usage in modules:
from ares.modules.params import param, SecretParam, ModuleParams
class KerberoastParams(ModuleParams):
dc: str = param(description="DC IP or FQDN", min_length=3)
domain: str = param(description="e.g. CORP.LOCAL", min_length=3),
username: str = param(description="Authenticating username")
password: SecretParam = param(description="Password", secret=True)
target_user: str = param(description="Target specific user", required=False, default="")
class KerberoastModule(BaseModule):
PARAMS = KerberoastParams
async def run(self, **kwargs):
p = KerberoastParams.model_validate(kwargs) # raises ValidationError on bad input
# Use p.dc, p.domain, etc.
Integrates with API:
POST /modules/{id}/run validates body.params against module's PARAMS model.
Returns 422 with field-level error detail on validation failure.
"""
from __future__ import annotations
from typing import Any
from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator, model_validator
# ── Type aliases ──────────────────────────────────────────────────────────────
SecretParam = SecretStr
_PARAM_REQUIRED_UNSET = object()
def param(
description: str = "",
required: bool | Any = _PARAM_REQUIRED_UNSET,
default: Any = None,
min_length: int | None = None,
max_length: int | None = None,
ge: float | None = None,
le: float | None = None,
pattern: str | None = None,
secret: bool = False,
) -> Any:
"""
Factory for module parameter field definitions.
Wraps pydantic Field() with ARES-specific metadata.
Example:
dc: str = param("DC IP or FQDN", min_length=7),
password: SecretStr = param("Password", secret=True)
timeout: int = param("Timeout seconds", required=False, default=30, ge=1, le=300)
"""
if required is _PARAM_REQUIRED_UNSET:
is_required = default is None
else:
is_required = bool(required)
kwargs: dict[str, Any] = {
"description": description,
"json_schema_extra": {"secret": secret, "required": is_required},
}
if not is_required and default is not None:
kwargs["default"] = default
elif not is_required:
kwargs["default"] = None
# else: is_required=True, no default → pydantic marks as required
if min_length is not None:
kwargs["min_length"] = min_length
if max_length is not None:
kwargs["max_length"] = max_length
if ge is not None:
kwargs["ge"] = ge
if le is not None:
kwargs["le"] = le
if pattern is not None:
kwargs["pattern"] = pattern
return Field(**kwargs)
# ── Base class for all module params ─────────────────────────────────────────
class ModuleParams(BaseModel):
"""
Base class for module parameter models.
Subclass this in each module to define typed, validated params.
Example:
class DCParams(ModuleParams):
dc: str = param("DC IP or FQDN", min_length=3)
username: str = param("Username")
password: SecretParam = param("Password", secret=True)
domain: str = param("FQDN domain, e.g. CORP.LOCAL")
"""
model_config = ConfigDict(
extra="allow", # Allow extra params (ignore unknown keys)
populate_by_name=True,
str_strip_whitespace=True,
)
def get(self, key: str, default: Any = None) -> Any:
try:
val = getattr(self, key)
if val is None:
return default
if hasattr(val, "get_secret_value"):
return val.get_secret_value()
return val
except AttributeError:
return default
def __getitem__(self, key: str) -> Any:
try:
val = getattr(self, key)
if hasattr(val, "get_secret_value"):
return val.get_secret_value()
return val
except AttributeError:
raise KeyError(key) # noqa: B904
def __contains__(self, key: object) -> bool:
if not isinstance(key, str):
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:
"""
Validate a raw param dict and return a populated model.
Raises pydantic.ValidationError with field-level errors on failure.
"""
return cls.model_validate(data)
@classmethod
def schema_for_api(cls) -> dict[str, Any]:
"""Return a simplified schema dict for API documentation."""
schema = cls.model_json_schema()
result: dict[str, Any] = {}
props = schema.get("properties", {})
required = schema.get("required", [])
for name, field_schema in props.items():
result[name] = {
"type": field_schema.get("type", "string"),
"description": field_schema.get("description", ""),
"required": name in required,
"secret": field_schema.get(
"secret",
field_schema.get("json_schema_extra", {}).get("secret", False),
),
}
if "default" in field_schema:
result[name]["default"] = field_schema["default"]
if "minimum" in field_schema:
result[name]["min"] = field_schema["minimum"]
if "maximum" in field_schema:
result[name]["max"] = field_schema["maximum"]
if "minLength" in field_schema:
result[name]["min_len"] = field_schema["minLength"]
if "maxLength" in field_schema:
result[name]["max_len"] = field_schema["maxLength"]
if "pattern" in field_schema:
result[name]["pattern"] = field_schema["pattern"]
if "items" in field_schema:
result[name]["items"] = field_schema["items"]
return result
def safe_dict(self) -> dict[str, Any]:
"""Export params dict, replacing SecretStr values with '***'."""
result = {}
for name, field_info in self.__class__.model_fields.items():
val = getattr(self, name, None)
if isinstance(val, SecretStr):
result[name] = "***"
else:
result[name] = val
return result
# ── Common reusable parameter models ─────────────────────────────────────────
_HOST_PATTERN = r"^[\w.-]+$"
_DOMAIN_PATTERN = r"^[\w.-]+$"
_USER_PATTERN = r"^[\w.\\@-]+$"
_CIDR_PATTERN = r"^(\d{1,3}\.){3}\d{1,3}(/\d{1,2})?$"
class DomainAuthParams(ModuleParams):
"""Shared params for AD modules requiring DC + credentials."""
dc: str = param("DC IP or FQDN", min_length=3, pattern=_HOST_PATTERN)
domain: str = param(
"FQDN domain (CORP.LOCAL)", min_length=3, pattern=_DOMAIN_PATTERN
)
username: str = param(
"Authenticating username", min_length=1, pattern=_USER_PATTERN
)
password: SecretParam = param("Password", secret=True)
use_ldaps: bool = param("Use LDAPS (port 636)", required=False, default=True)
class KerberoastParams(DomainAuthParams):
target_user: str = param(
"Required target user or SPN; run ad.enum_spn first",
required=False,
default="",
max_length=256,
)
class ASREPRoastParams(ModuleParams):
dc: str = param("DC IP or FQDN", min_length=3, pattern=_HOST_PATTERN)
domain: str = param("Domain FQDN", min_length=3, pattern=_DOMAIN_PATTERN)
username: str | None = param(
"Authenticated username for LDAP discovery", required=False, default=None
)
password: SecretParam | None = param(
"Password (for authenticated mode)", required=False, default=None, secret=True
)
userfile: str | None = param(
"Path to username wordlist (unauthenticated mode)",
required=False,
default=None,
max_length=512,
)
@model_validator(mode="after")
def require_auth_or_wordlist(self) -> ASREPRoastParams:
if not self.username and not self.userfile:
raise ValueError(
"Either 'username' (authenticated LDAP) or 'userfile' (wordlist mode) is required"
)
return self
class DCSyncParams(DomainAuthParams):
target_user: str = param(
"Target user (default: krbtgt)",
required=False,
default="krbtgt",
max_length=256,
)
class AWSParams(ModuleParams):
profile: str | None = param("AWS named profile", required=False, default=None)
access_key: str | None = param(
"AWS Access Key ID", required=False, default=None, max_length=128
)
secret_key: SecretParam | None = param(
"AWS Secret Key", required=False, default=None, secret=True
)
session_token: SecretParam | None = param(
"Session token", required=False, default=None, secret=True
)
region: str = param(
"AWS region",
required=False,
default="us-east-1",
pattern=r"^[a-z]{2}-[a-z]+-\d$",
)
@model_validator(mode="before")
@classmethod
def _normalize_aws_keys(cls, data: Any) -> Any:
if isinstance(data, dict):
if "aws_access_key" in data and not data.get("access_key"):
data["access_key"] = data["aws_access_key"]
if "aws_secret_key" in data and not data.get("secret_key"):
data["secret_key"] = data["aws_secret_key"]
if "aws_session_token" in data and not data.get("session_token"):
data["session_token"] = data["aws_session_token"]
if "aws_region" in data and not data.get("region"):
data["region"] = data["aws_region"]
if "aws_profile" in data and not data.get("profile"):
data["profile"] = data["aws_profile"]
return data
class LinuxPrivescParams(ModuleParams):
host: str = param(
"Target host (localhost for local)", required=False, default="localhost"
)
ssh_user: str | None = param(
"SSH username (remote mode)", required=False, default=None
)
ssh_key: str | None = param("Path to SSH private key", required=False, default=None)
ssh_pass: SecretParam | None = param(
"SSH password", required=False, default=None, secret=True
)
ssh_port: int = param("SSH port", required=False, default=22, ge=1, le=65535)
class SssdHarvestParams(ModuleParams):
"""Parameters for linux.sssd_harvest - SSSD cache and offline hash extractor."""
db_path: str = param(
"Directory containing SSSD LDB databases.",
required=False,
default="/var/lib/sss/db",
min_length=1,
)
extract_offline_hashes: bool = param(
"Extract salted offline password hashes for password cracking.",
required=False,
default=True,
)
target_domain: str | None = param(
"Specific AD domain name to target. If None, targets all domains.",
required=False,
default=None,
)
class CcacheHuntParams(ModuleParams):
"""Parameters for linux.ccache_hunt - Kerberos ticket cache hunter."""
search_dirs: list[str] = param(
"Filesystem locations to scan for Kerberos ccache files.",
required=False,
default=["/tmp", "/run/user"],
)
scan_kernel_keyring: bool = param(
"Attempt retrieval of tickets stored in Linux Kernel Keyring.",
required=False,
default=True,
)
scan_kcm_socket: bool = param(
"Attempt retrieval from Kerberos Credential Manager (KCM) IPC socket.",
required=False,
default=True,
)
include_expired: bool = param(
"Whether to return expired Kerberos tickets.",
required=False,
default=False,
)
class KeytabAbuseParams(ModuleParams):
"""Parameters for linux.keytab_abuse - Host keytab harvester and Silver Ticket generator."""
keytab_path: str = param(
"Path to the Kerberos keytab file.",
required=False,
default="/etc/krb5.keytab",
min_length=1,
)
forge_silver_ticket: bool = param(
"Attempt offline generation of local service Silver Ticket.",
required=False,
default=False,
)
service_name: str = param(
"Target service principal for Silver Ticket (e.g. host, cifs, http).",
required=False,
default="host",
)
class SambaSecretsParams(ModuleParams):
"""Parameters for linux.samba_secrets - Samba/Winbind machine password and NTLM extractor."""
secrets_tdb_path: str = param(
"Path to Samba secrets.tdb database.",
required=False,
default="/var/lib/samba/private/secrets.tdb",
min_length=1,
)
class TicketConverterParams(ModuleParams):
"""Parameters for credential.ticket_converter - Bi-directional ccache <-> kirbi converter."""
source_format: str = param(
"Format of input ticket: 'ccache' or 'kirbi'.",
required=False,
default="ccache",
)
ticket_b64: str = param(
"Base64-encoded source ticket bytes.",
required=True,
min_length=4,
)
target_format: str = param(
"Desired target format: 'ccache' or 'kirbi'.",
required=False,
default="kirbi",
)
# ── AD modules ────────────────────────────────────────────────────────────────
class ADCSParams(DomainAuthParams):
"""ad.adcs - ADCS ESC1-ESC8 enumeration and exploitation."""
exploit_esc1: bool = param(
"Attempt ESC1 certificate request if vulnerable",
required=False,
default=False,
)
target_user: str = param(
"User to request a certificate for when exploiting ESC1",
required=False,
default="Administrator",
max_length=256,
)
class GhostForgeParams(DomainAuthParams):
"""ad.ghost_forge - Autonomous ADCS Cryptographic Identity & Kerberos PKINIT Takeover."""
ca_server: str = param(
"Certificate Authority (CA) server hostname or IP",
min_length=3,
max_length=253,
)
ca_name: str = param(
"Target Enterprise CA name (e.g. CORP-ENTERPRISE-CA)",
min_length=2,
max_length=253,
)
template: str = param(
"Vulnerable Certificate Template name with enrollee-supplied SAN",
required=False,
default="ESC1-Template",
max_length=128,
)
impersonate_user: str = param(
"Target privileged account to impersonate via SAN injection",
required=False,
default="Administrator",
max_length=256,
)
perform_pkinit: bool = param(
"Execute Kerberos PKINIT exchange and UnPAC-the-hash to extract TGT and NTLM hash",
required=False,
default=True,
)
target_technique: str = param(
"Adversary validation vector: auto, esc1, esc6, esc13, shadow_cred",
required=False,
default="auto",
max_length=64,
)
enforcement_mode_check: bool = param(
"Inspect KDC StrongCertificateBindingEnforcement status (KB5014754)",
required=False,
default=True,
)
policy_oid: str | None = param(
"Certificate Policy OID for ESC13 Issuance Policy to privileged group mapping",
required=False,
default=None,
max_length=128,
)
generate_detection_rules: bool = param(
"Automatically synthesize Microsoft Sentinel KQL and Sigma detection rules in loot",
required=False,
default=True,
)
class CoerceParams(DomainAuthParams):
"""ad.coerce - PetitPotam/PrinterBug/DFSCoerce NTLM coercion."""
listener_ip: str = param(
"Attacker IP to receive NTLM auth", min_length=7, max_length=45
)
method: str = param(
"Method: auto|petitpotam|printerbug|dfscoerce",
required=False,
default="auto",
pattern=r"^(auto|petitpotam|printerbug|dfscoerce)$",
)
class SCCMParams(DomainAuthParams):
"""ad.sccm - SCCM/MECM enumeration and credential extraction."""
sccm_server: str = param(
"SCCM site server hostname (auto-discover if empty)",
required=False,
default="",
max_length=253,
)
target: str = param(
"Target SCCM client for NAA extraction (requires local admin)",
required=False,
default="",
max_length=253,
)
class NTLMRelayParams(DomainAuthParams):
"""lateral.ntlm_relay - Full NTLM relay attack chain."""
targets: list[str] = param(
"Target hosts to check for relay (auto-discover if empty)",
required=False,
default=[],
)
coerce_source: str = param(
"Host to coerce authentication from (default: DC)",
required=False,
default="",
max_length=253,
)
target_user: str = param(
"User to impersonate via RBCD (default: administrator)",
required=False,
default="administrator",
max_length=256,
)
mode: str = param(
"Mode: discover|coerce|full",
required=False,
default="full",
pattern=r"^(discover|coerce|full)$",
)
class DelegationAbuseParams(DomainAuthParams):
"""ad.delegation_abuse - Unconstrained/constrained/RBCD delegation abuse."""
mode: str = param(
"Mode: enumerate|unconstrained|constrained|rbcd",
required=False,
default="enumerate",
pattern=r"^(enumerate|unconstrained|constrained|rbcd)$",
)
target_computer: str = param(
"Target computer object for RBCD delegation abuse",
required=False,
default="",
max_length=253,
)
impersonate_user: str = param(
"User to impersonate via S4U",
required=False,
default="Administrator",
max_length=256,
)
target_service: str = param(
"Service SPN prefix to request",
required=False,
default="cifs",
max_length=64,
)
class LAPSEnumParams(DomainAuthParams):
"""ad.laps_enum - LAPS v1/v2 password retrieval."""
computer_filter: str = param(
"LDAP filter for target computers", required=False, default="", max_length=512
)
# ── Cloud modules ─────────────────────────────────────────────────────────────
class AWSPrivescParams(ModuleParams):
"""cloud.aws_privesc - AWS IAM privilege escalation."""
access_key: str | None = param(
"AWS Access Key ID", required=False, default=None, max_length=128
)
secret_key: SecretParam | None = param(
"AWS Secret Key", required=False, default=None, secret=True
)
session_token: SecretParam | None = param(
"Session token", required=False, default=None, secret=True
)
region: str = param(
"AWS region",
required=False,
default="us-east-1",
pattern=r"^[a-z]{2}-[a-z]+-\d+$",
)
@model_validator(mode="before")
@classmethod
def _normalize_aws_keys(cls, data: Any) -> Any:
if isinstance(data, dict):
if "aws_access_key" in data and not data.get("access_key"):
data["access_key"] = data["aws_access_key"]
if "aws_secret_key" in data and not data.get("secret_key"):
data["secret_key"] = data["aws_secret_key"]
if "aws_session_token" in data and not data.get("session_token"):
data["session_token"] = data["aws_session_token"]
if "aws_region" in data and not data.get("region"):
data["region"] = data["aws_region"]
return data
class AzureParams(ModuleParams):
"""cloud.azure - Azure resource enumeration."""
subscription_id: str | None = param(
"Azure subscription ID", required=False, default=None
)
tenant_id: str | None = param("Azure tenant ID", required=False, default=None)
client_id: str | None = param(
"Service principal client ID", required=False, default=None
)
client_secret: SecretParam | None = param(
"Service principal secret", required=False, default=None, secret=True
)
class AzureADParams(ModuleParams):
"""cloud.azure_ad - Azure AD enumeration via Graph API."""
tenant_id: str | None = param("Azure tenant ID", required=False, default=None)
client_id: str | None = param("App client ID", required=False, default=None)
client_secret: SecretParam | None = param(
"App client secret", required=False, default=None, secret=True
)
access_token: SecretParam | None = param(
"Existing Microsoft Graph access token",
required=False,
default=None,
secret=True,
)
technique: str = param(
"Technique: enumerate|device_code|sp_audit",
required=False,
default="enumerate",
pattern=r"^(enumerate|device_code|sp_audit)$",
)
class GCPParams(ModuleParams):
"""cloud.gcp - GCP resource enumeration."""
project_id: str | None = param(
"GCP project ID (lowercase letters, digits, hyphens)",
required=False,
default=None,
max_length=30,
pattern=r"^[a-z][a-z0-9\-]{4,28}[a-z0-9]$",
)
credentials_file: str | None = param(
"Path to service account JSON", required=False, default=None, max_length=512
)
# ── Credential modules ────────────────────────────────────────────────────────
class CredentialCrackParams(ModuleParams):
"""credential.crack - Offline hash cracking via hashcat/john."""
hashcat_path: str = param(
"Path to hashcat binary", required=False, default="hashcat", max_length=512
)
wordlist: str = param(
"Path to wordlist", required=False, default="", max_length=512
)
rules: str = param(
"Hashcat rules file", required=False, default="best64.rule", max_length=256
)
class GoldenTicketParams(ModuleParams):
"""credential.golden_ticket - Kerberos golden ticket forging."""
domain: str = param("Target domain FQDN", min_length=3, pattern=r"^[\w.-]+$")
domain_sid: str = param(
"Domain SID (S-1-5-21-...)", pattern=r"^S-1-5-21-\d+-\d+-\d+$"
)
krbtgt_hash: SecretParam = param(
"krbtgt NT hash (32 hex chars)", secret=True, min_length=32, max_length=32
)
username: str = param(
"Identity to forge", required=False, default="Administrator", max_length=256
)
target: str = param("Target host", required=False, default="", max_length=253)
class PassSprayParams(ModuleParams):
"""credential.pass_spray - Password spraying against LDAP/SMB."""
target: str = param("DC or target IP/hostname", min_length=3, max_length=253)
domain: str = param("Domain FQDN", required=False, default="", max_length=253)
users: list[str] = param("List of usernames to spray")
passwords: list[str] = param("List of passwords to spray")
delay_s: float = param(
"Delay between attempts (seconds)", required=False, default=1.0, ge=0.0, le=60.0
)
max_per_user: int = param(
"Max attempts per user (lockout protection)",
required=False,
default=1,
ge=1,
le=5,
)
class SSHSprayParams(ModuleParams):
"""credential.ssh_spray - SSH authentication audit and credential spray."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
port: int = param("SSH port", required=False, default=22, ge=1, le=65535)
users: list[str] = param(
"List of usernames to spray",
required=False,
default=["root", "admin", "kali", "ubuntu", "user", "kraii"],
)
passwords: list[str] = param(
"List of passwords to test",
required=False,
default=["Password123!", "admin", "root", "toor", "ubuntu", "kali", "password", "123456"],
)
username: str | None = param("Single username to test", required=False, default=None)
password: SecretParam | None = param("Single password to test", required=False, default=None, secret=True)
delay_s: float = param(
"Delay between attempts (seconds)", required=False, default=0.5, ge=0.0, le=60.0
)
timeout_s: float = param(
"Connection timeout (seconds)", required=False, default=5.0, ge=0.5, le=30.0
)
max_attempts: int = param(
"Max total attempts (lockout protection)", required=False, default=20, ge=1, le=200
)
class PassTheHashParams(ModuleParams):
"""credential.pass_the_hash - SMB pass-the-hash authentication."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param("Username", min_length=1, max_length=256)
nt_hash: SecretParam = param(
"NT hash (32 hex chars)", secret=True, min_length=32, max_length=32
)
lm_hash: str = param(
"LM hash",
required=False,
default="aad3b435b51404eeaad3b435b51404ee",
min_length=32,
max_length=32,
)
domain: str = param("Domain", required=False, default="", max_length=253)
command: str = param(
"Verification command", required=False, default="whoami", max_length=500
)
class CredentialReuseParams(ModuleParams):
"""credential.reuse - Test captured credentials against a target."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
protocol: str = param(
"Protocol: smb|winrm|ssh|ldap",
required=False,
default="smb",
pattern=r"^(smb|winrm|ssh|ldap)$",
)
# ── Exfil modules ─────────────────────────────────────────────────────────────
class SecretsScanParams(ModuleParams):
"""exfil.secrets_scan - SSH remote scan for credential patterns."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param("SSH username", min_length=1, max_length=256)
password: SecretParam | None = param(
"SSH password", required=False, default=None, secret=True
)
key_path: str | None = param(
"SSH private key path", required=False, default=None, max_length=512
)
platform: str = param(
"Target OS: linux|windows",
required=False,
default="linux",
pattern=r"^(linux|windows)$",
)
class SmbSharesParams(ModuleParams):
"""exfil.smb_shares - Enumerate SMB shares and search for sensitive files."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param("Username", min_length=1, max_length=256)
password: SecretParam | None = param(
"Password", required=False, default=None, secret=True
)
domain: str = param("Domain", required=False, default="", max_length=253)
max_depth: int = param(
"Max directory traversal depth", required=False, default=3, ge=1, le=10
)
class StagedCollectionParams(ModuleParams):
"""exfil.staged_collection - Collect files matching patterns via SSH."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param("SSH username", min_length=1, max_length=256)
password: SecretParam | None = param(
"SSH password", required=False, default=None, secret=True
)
destination: str = param("Staging destination path or share", max_length=512)
platform: str = param(
"Target OS: linux|windows",
required=False,
default="linux",
pattern=r"^(linux|windows)$",
)
max_files: int = param(
"Max files to collect", required=False, default=200, ge=1, le=1000
)
# ── Lateral movement modules ──────────────────────────────────────────────────
class LateralBaseParams(ModuleParams):
"""Shared params for lateral movement modules (remote execution - command runs on target)."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param("Username", min_length=1, max_length=256)
password: SecretParam | None = param(
"Password", required=False, default=None, secret=True
)
domain: str = param("Domain", required=False, default="", max_length=253)
command: str = param(
"Command to execute on remote target",
required=False,
default="whoami /all",
max_length=2048,
)
class DCOMParams(LateralBaseParams):
"""lateral.dcom - DCOM lateral movement via MMC20/ShellWindows."""
method: str = param(
"DCOM method: auto|mmc20|shellwindows|shellbrowserwindow",
required=False,
default="auto",
pattern=r"^(auto|mmc20|shellwindows|shellbrowserwindow)$",
)
class PsExecParams(LateralBaseParams):
"""lateral.psexec - PsExec-style lateral movement via SMB + SCM."""
service_name: str = param(
"Temporary service name", required=False, default="", max_length=256
)
class WmiExecParams(LateralBaseParams):
"""lateral.wmiexec - WMI remote execution."""
pass
class WinRMParams(LateralBaseParams):
"""lateral.winrm - WinRM PowerShell remote execution."""
pass
class RDPLateralParams(LateralBaseParams):
"""lateral.rdp - RDP lateral movement (HIGH_NOISE)."""
pass
class SSHPivotParams(ModuleParams):
"""lateral.ssh_pivot - SSH tunnel SOCKS5 pivot."""
target: str = param("SSH server IP or hostname", min_length=3, max_length=253)
username: str = param("SSH username", min_length=1, max_length=256)
password: SecretParam | None = param(
"SSH password", required=False, default=None, secret=True
)
key_path: str | None = param(
"SSH private key path", required=False, default=None, max_length=512
)
ssh_port: int = param("SSH port", required=False, default=22, ge=1, le=65535)
socks_port: int = param(
"Local SOCKS5 port", required=False, default=1080, ge=1024, le=65535
)
class SMBRelayParams(ModuleParams):
"""lateral.smb_relay - SMB signing audit and relay candidate detection."""
target: str | None = param(
"Single target to check", required=False, default=None, max_length=253
)
targets: list[str] = param("List of targets to audit", required=False, default=[])
check_ldap: bool = param("Also check LDAP signing", required=False, default=False)
# ── Linux modules ─────────────────────────────────────────────────────────────
class LinuxSSHParams(ModuleParams):
"""Shared SSH params for Linux post-exploitation modules."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param("SSH username", min_length=1, max_length=256)
password: SecretParam | None = param(
"SSH password", required=False, default=None, secret=True
)
key_path: str | None = param(
"SSH private key path", required=False, default=None, max_length=512
)
ssh_port: int = param("SSH port", required=False, default=22, ge=1, le=65535)
class ContainerEscapeParams(LinuxSSHParams):
"""linux.container - Docker/K8s container escape techniques."""
pass
class KernelSuggesterParams(LinuxSSHParams):
"""linux.kernel_suggester - Kernel exploit suggester via uname."""
pass
class LDPreloadParams(LinuxSSHParams):
"""linux.ld_preload - LD_PRELOAD privilege escalation."""
pass
class NFSEscapeParams(LinuxSSHParams):
"""linux.nfs_escape - NFS no_root_squash escape."""
pass
class ServiceHijackParams(LinuxSSHParams):
"""linux.service_hijack - Writable systemd service hijack."""
pass
# ── Network modules ───────────────────────────────────────────────────────────
class PortScanParams(ModuleParams):
"""network.port_scan - TCP port scan."""
target: str = param("Target IP, hostname, or CIDR", min_length=3, max_length=253)
ports: str = param(
"Port spec: top1000|all|22,80,443,8080-8090",
required=False,
default="top1000",
max_length=512,
)
timeout: float = param(
"Per-port timeout (seconds)", required=False, default=1.0, ge=0.1, le=10.0
)
threads: int = param(
"Concurrent scan threads", required=False, default=100, ge=1, le=500
)
class DNSEnumParams(ModuleParams):
"""network.dns_enum - DNS enumeration and zone transfer attempt."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
domain: str = param(
"Domain to enumerate", required=False, default="", max_length=253
)
brute: bool = param("Brute-force subdomains", required=False, default=True)
def _coerce_ports_list(v: Any) -> list[int]:
"""Accept integer, comma-separated string, or list/tuple of ports and normalize to list[int]."""
if v is None or v == "":
return []
if isinstance(v, int):
return [v]
if isinstance(v, str):
if not v.strip():
return []
result = []
for p in v.split(","):
p_clean = p.strip()
if p_clean.isdigit():
result.append(int(p_clean))
return result
if isinstance(v, (list, tuple, set)):
result = []
for item in v:
if isinstance(item, int):
result.append(item)
elif isinstance(item, str) and item.strip().isdigit():
result.append(int(item.strip()))
return result
return v
class HTTPFingerprintParams(ModuleParams):
"""network.http_fingerprint - HTTP service and tech fingerprinting."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
ports: list[int] = param(
"Ports to fingerprint. Leave blank for common web ports: 80, 443, 8080, 8443, 8888",
required=False,
default=[80, 443, 8080, 8443, 8888],
)
timeout: float = param(
"HTTP timeout (seconds)", required=False, default=5.0, ge=0.5, le=30.0
)
@field_validator("ports", mode="before")
@classmethod
def coerce_ports(cls, v: Any) -> list[int]:
return _coerce_ports_list(v)
class SNMPEnumParams(ModuleParams):
"""network.snmp_enum - SNMP community brute-force and OID walk."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
port: int = param("SNMP UDP port", required=False, default=161, ge=1, le=65535)
communities: list[str] = param(
"Community strings to try",
required=False,
default=["public", "private", "manager"],
)
class ServiceDetectParams(ModuleParams):
"""network.service_detect - Banner-grab service version detection."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
ports: list[int] = param("Ports to check", required=False, default=[])
timeout: float = param(
"Per-port timeout (seconds)", required=False, default=3.0, ge=0.5, le=30.0
)
@field_validator("ports", mode="before")
@classmethod
def coerce_ports(cls, v: Any) -> list[int]:
return _coerce_ports_list(v)
class PivotParams(ModuleParams):
"""network.pivot - SSH tunnel SOCKS5 pivot infrastructure."""
target: str = param("Pivot host IP or hostname", min_length=3, max_length=253)
username: str = param("SSH username", min_length=1, max_length=256)
password: SecretParam | None = param(
"SSH password", required=False, default=None, secret=True
)
key_path: str | None = param(
"SSH private key path", required=False, default=None, max_length=512
)
local_port: int = param(
"Local SOCKS5 port", required=False, default=1080, ge=0, le=65535
)
# ── Persistence modules ───────────────────────────────────────────────────────
class PersistenceBaseParams(ModuleParams):
"""Shared params for persistence modules."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param(
"Username with local admin rights", min_length=1, max_length=256
)
password: SecretParam | None = param(
"Password", required=False, default=None, secret=True
)
domain: str = param("Domain", required=False, default="", max_length=253)
class ScheduledTaskParams(PersistenceBaseParams):
"""persistence.scheduled_task - Windows scheduled task persistence."""
task_name: str = param(
"Scheduled task name",
required=False,
default="AresUpdater",
max_length=256,
pattern=r"^[\w\s\-.]+$",
)
command: str = param(
"Command to persist (runs as SYSTEM)",
required=False,
max_length=2048,
default="powershell.exe -NoP -W Hidden -Enc BASE64",
)
class RegistryRunParams(PersistenceBaseParams):
"""persistence.registry_run - Registry Run key persistence."""
key_name: str = param(
"Run key value name",
required=False,
default="AresUpdate",
max_length=256,
pattern=r"^[\w\s\-.]+$",
)
command: str = param(
"Command to persist",
required=False,
max_length=2048,
default="powershell.exe -NoP -W Hidden -Enc BASE64",
)
class WMISubscriptionParams(PersistenceBaseParams):
"""persistence.wmi_subscription - WMI event subscription persistence."""
subscription_name: str = param(
"WMI subscription name",
required=False,
default="AresMonitor",
max_length=256,
pattern=r"^[\w\s\-.]+$",
)
command: str = param(
"Command to persist",
required=False,
max_length=2048,
default="powershell.exe -NoP -W Hidden -Enc BASE64",
)
# ── Recon modules ─────────────────────────────────────────────────────────────
class FingerprintParams(ModuleParams):
"""recon.fingerprint - Environment fingerprinting (EDR, OS, domain)."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
timeout: float = param(
"Timeout per check (seconds)", required=False, default=5.0, ge=0.5, le=30.0
)
# ── Windows post-exploitation modules ────────────────────────────────────────
class WindowsBaseParams(ModuleParams):
"""Shared params for Windows post-exploitation modules."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param(
"Username with local admin rights", min_length=1, max_length=256
)
password: SecretParam | None = param(
"Password", required=False, default=None, secret=True
)
nt_hash: SecretParam | None = param(
"NT hash for PTH (32 hex chars)",
required=False,
default=None,
secret=True,
min_length=32,
max_length=32,
)
domain: str = param("Domain", required=False, default="", max_length=253)
class AppLockerBypassParams(WindowsBaseParams):
"""windows.applocker_bypass - AppLocker policy enumeration and bypass."""
command: str = param(
"Command to execute if bypass found",
required=False,
default="whoami /all",
max_length=2048,
)
class DPAPIParams(WindowsBaseParams):
"""windows.dpapi - DPAPI credential and browser password decryption."""
targets: list[str] = param(
"DPAPI target types: chrome|wifi|rdp|credentials",
required=False,
default=["chrome", "wifi", "credentials"],
)
class LSASecretsParams(WindowsBaseParams):
"""windows.lsa_secrets - LSA secrets and cached credential extraction."""
pass
class LsassDumpParams(WindowsBaseParams):
"""windows.lsass_dump - LSASS process memory dump and parsing."""
technique: str = param(
"Dump technique: comsvcs|secretsdump",
required=False,
default="comsvcs",
pattern=r"^(comsvcs|secretsdump)$",
)
class RegistryEnumParams(WindowsBaseParams):
"""windows.registry_enum - Registry credential hunting."""
pass
class ScheduledTasksEnumParams(WindowsBaseParams):
"""windows.scheduled_tasks_enum - Scheduled task enumeration for privesc."""
pass
class TokenImpersonationParams(ModuleParams):
"""windows.token_impersonation - Token impersonation via named pipe."""
target: str = param("Target IP or hostname", min_length=3, max_length=253)
username: str = param("Username", min_length=1, max_length=256)
password: SecretParam | None = param(
"Password", required=False, default=None, secret=True
)
domain: str = param("Domain", required=False, default="", max_length=253)
class UACBypassParams(WindowsBaseParams):
"""windows.uac_bypass - UAC configuration check and bypass."""
technique: str = param(
"Bypass technique: auto|fodhelper|eventvwr",
required=False,
default="auto",
pattern=r"^(auto|fodhelper|eventvwr)$",
)
class CoveragePredictorParams(ModuleParams):
"""opsec.coverage_predictor - Detection probability scoring."""
noise_profile: str = param(
"Campaign noise profile for scoring",
required=False,
default="normal",
pattern=r"^(stealth|normal|aggressive)$",
)
class CloudFederationParams(ModuleParams):
"""cloud.identity_federation_abuse - Cross-cloud SAML/OIDC federation abuse."""
tenant_id: str | None = param("Azure tenant ID", required=False, default=None)
client_id: str | None = param("Azure client ID", required=False, default=None)
client_secret: SecretParam | None = param(
"Azure client secret", required=False, default=None, secret=True
)
access_key: str | None = param("AWS Access Key ID", required=False, default=None)
secret_key: SecretParam | None = param(
"AWS Secret Key", required=False, default=None, secret=True
)
adfs_url: str | None = param(
"ADFS base URL", required=False, default=None, max_length=512
)
krbtgt_hash: SecretParam | None = param(
"krbtgt NT hash (for Golden SAML path check)",
required=False,
default=None,
secret=True,
min_length=32,
max_length=32,
)
domain: str = param("Target domain", required=False, default="", max_length=253)
mode: str = param(
"Mode: enumerate|golden_saml|oauth_abuse",
required=False,
default="enumerate",
pattern=r"^(enumerate|golden_saml|oauth_abuse)$",
)
class PhantomTokenParams(ModuleParams):
"""cloud.phantom_token - Hybrid Entra ID & Primary Refresh Token (PRT) Hijack."""
tenant_id: str = param(
"Target Azure AD / Entra ID Tenant ID or domain name (e.g. corp.onmicrosoft.com)",
min_length=3,
max_length=253,
)
client_id: str = param(
"OAuth2 Client ID for application context (default: Microsoft Office / Teams client)",
required=False,
default="1fec8e78-bce4-4aaf-abb1-b1b232c79215",
max_length=128,
)
scope: str = param(
"Target OAuth2 resource scope",
required=False,
default="https://graph.microsoft.com/.default",
max_length=256,
)
session_cookie: SecretParam | None = param(
"Harvested x-ms-RefreshTokenCredential or ESTSAUTHPERSISTENT cookie context",
required=False,
default=None,
secret=True,
)
evaluate_cap_bypass: bool = param(
"Evaluate Conditional Access Policy (CAP) and MFA bypass feasibility",
required=False,
default=True,
)
assessment_mode: str = param(
"Evaluation vector: auto, workload_identity, prt_enclave, cae_probe",
required=False,
default="auto",
max_length=64,
)
federation_issuer: str | None = param(
"OIDC federation issuer for Workload Identity testing (e.g. https://token.actions.githubusercontent.com)",
required=False,
default=None,
max_length=256,
)
dpop_enforced: bool = param(
"Verify RFC 9449 Demonstrating Proof-of-Possession asymmetric key constraints",
required=False,
default=False,
)
generate_detection_rules: bool = param(
"Automatically synthesize Microsoft Sentinel KQL and Sigma detection rules in loot",
required=False,
default=True,
)
class EDRBypassParams(ModuleParams):
"""edr.bypass_adaptive - Adaptive EDR evasion."""
edr_vendor: str = param(
"EDR vendor: crowdstrike|sentinelone|defender_atp|defender_av|carbon_black|cylance|unknown",
required=False,
default="unknown",
pattern=r"^(crowdstrike|sentinelone|defender_atp|defender_av|carbon_black|cylance|unknown)$",
)
target: str = param("Target host", required=False, default="", max_length=253)
os_version: str = param(
"Target OS version", required=False, default="", max_length=256
)
class AIPlannerParams(ModuleParams):
"""ai.autonomous_planner - LLM-powered attack chain planning."""
goal: str = param(
"Attack goal: domain_admin|cloud_admin|data_exfil|persistence|full_compromise",
required=False,
default="domain_admin",
pattern=r"^(domain_admin|enterprise_admin|cloud_admin|data_exfil|persistence|full_compromise)$",
)
llm_backend: str = param(
"LLM backend: claude|openai|local",
required=False,
default="claude",
pattern=r"^(claude|openai|local)$",
)
llm_model: str = param(
"Specific LLM model (optional, uses default if empty)",
required=False,
default="",
max_length=128,
)
auto_approve: bool = param(
"Skip operator review and execute plan automatically (use with caution)",
required=False,
default=False,
)
# ── Module → Params class registry ───────────────────────────────────────────
class MSSQLParams(ModuleParams):
"""Parameters for lateral.mssql - validated before execution."""
target: str = Field(
..., min_length=1, max_length=253, description="MSSQL server IP or hostname"
)
username: str = Field(..., min_length=1, max_length=128)
password: str = Field(default="", max_length=256)
port: int = Field(default=1433, ge=1, le=65535)
technique: str = Field(
default="xp_cmdshell", pattern=r"^(xp_cmdshell|linked|unc_coerce)$"
)
command: str = Field(
default="whoami",
max_length=500,
# Allow alphanumeric, spaces, and common cmd chars - block quotes and semicolons
pattern=r"^[a-zA-Z0-9 /\.\-_=@:,\(\)\[\]\*\?]+$",
description="OS command to execute (no quotes or semicolons)",
)
linked: str = Field(
default="",
max_length=128,
pattern=r"^[a-zA-Z0-9\.\-_]*$",
description="Linked server name (alphanumeric only)",
)
listener: str = Field(
default="",
max_length=253,
pattern=r"^[a-zA-Z0-9.\-:]*$",
description="Attacker IP/hostname for NTLM capture (no special chars)",
)
MODULE_PARAMS: dict[str, type[ModuleParams]] = {
# ── Active Directory ──────────────────────────────────────────────────────
"ad.enum_users": DomainAuthParams,
"ad.enum_spn": DomainAuthParams,
"ad.enum_acl": DomainAuthParams,
"ad.enum_computers": DomainAuthParams,
"ad.kerberoast": KerberoastParams,
"ad.asreproast": ASREPRoastParams,
"ad.dcsync": DCSyncParams,
"ad.adcs": ADCSParams,
"ad.ghost_forge": GhostForgeParams,
"ad.coerce": CoerceParams,
"ad.delegation_abuse": DelegationAbuseParams,
"ad.laps_enum": LAPSEnumParams,
"ad.sccm": SCCMParams,
# ── Cloud ─────────────────────────────────────────────────────────────────
"cloud.aws": AWSParams,
"cloud.aws_privesc": AWSPrivescParams,
"cloud.azure": AzureParams,
"cloud.azure_ad": AzureADParams,
"cloud.gcp": GCPParams,
"cloud.phantom_token": PhantomTokenParams,
# ── Credential ────────────────────────────────────────────────────────────
"credential.crack": CredentialCrackParams,
"credential.golden_ticket": GoldenTicketParams,
"credential.pass_spray": PassSprayParams,
"credential.ssh_spray": SSHSprayParams,
"credential.pass_the_hash": PassTheHashParams,
"credential.reuse": CredentialReuseParams,
# ── Exfil ─────────────────────────────────────────────────────────────────
"exfil.secrets_scan": SecretsScanParams,
"exfil.smb_shares": SmbSharesParams,
"exfil.staged_collection": StagedCollectionParams,
# ── Lateral ───────────────────────────────────────────────────────────────
"lateral.dcom": DCOMParams,
"lateral.psexec": PsExecParams,
"lateral.wmiexec": WmiExecParams,
"lateral.winrm": WinRMParams,
"lateral.rdp": RDPLateralParams,
"lateral.ssh_pivot": SSHPivotParams,
"lateral.smb_relay": SMBRelayParams,
"lateral.ntlm_relay": NTLMRelayParams,
"lateral.mssql": MSSQLParams,
# ── Linux ─────────────────────────────────────────────────────────────────
"linux.privesc": LinuxPrivescParams,
"linux.container": ContainerEscapeParams,
"linux.kernel_suggester": KernelSuggesterParams,
"linux.ld_preload": LDPreloadParams,
"linux.nfs_escape": NFSEscapeParams,
"linux.service_hijack": ServiceHijackParams,
"linux.sssd_harvest": SssdHarvestParams,
"linux.ccache_hunt": CcacheHuntParams,
"linux.keytab_abuse": KeytabAbuseParams,
"linux.samba_secrets": SambaSecretsParams,
"credential.ticket_converter": TicketConverterParams,
# ── Network ───────────────────────────────────────────────────────────────
"network.port_scan": PortScanParams,
"network.dns_enum": DNSEnumParams,
"network.http_fingerprint": HTTPFingerprintParams,
"network.snmp_enum": SNMPEnumParams,
"network.service_detect": ServiceDetectParams,
"network.pivot": PivotParams,
# ── Persistence ───────────────────────────────────────────────────────────
"persistence.scheduled_task": ScheduledTaskParams,
"persistence.registry_run": RegistryRunParams,
"persistence.wmi_subscription": WMISubscriptionParams,
# ── Recon ─────────────────────────────────────────────────────────────────
"recon.fingerprint": FingerprintParams,
# ── OPSEC ─────────────────────────────────────────────────────────────────
"opsec.coverage_predictor": CoveragePredictorParams,
# ── EDR ───────────────────────────────────────────────────────────────────
"edr.bypass_adaptive": EDRBypassParams,
# ── AI ────────────────────────────────────────────────────────────────────
"ai.autonomous_planner": AIPlannerParams,
# ── Cloud (new) ───────────────────────────────────────────────────────────
"cloud.identity_federation_abuse": CloudFederationParams,
# ── Windows ───────────────────────────────────────────────────────────────
"windows.applocker_bypass": AppLockerBypassParams,
"windows.dpapi": DPAPIParams,
"windows.lsa_secrets": LSASecretsParams,
"windows.lsass_dump": LsassDumpParams,
"windows.registry_enum": RegistryEnumParams,
"windows.scheduled_tasks_enum": ScheduledTasksEnumParams,
"windows.token_impersonation": TokenImpersonationParams,
"windows.uac_bypass": UACBypassParams,
}
def validate_module_params(
module_id: str, raw_params: dict[str, Any]
) -> dict[str, Any]:
"""
Validate raw_params against the module's Pydantic schema.
Returns validated dict (with SecretStr values accessible via .get_secret_value()).
Raises pydantic.ValidationError with field-level errors on failure.
Raises KeyError if module_id has no registered params model.
"""
model_cls = MODULE_PARAMS.get(module_id)
if not model_cls:
return raw_params # No schema registered → pass through
validated = model_cls.validate_dict(raw_params)
# Convert back to dict, keeping SecretStr objects intact for modules
result: dict[str, Any] = {}
for name in validated.model_fields:
val = getattr(validated, name, None)
if val is None and name not in (validated.model_fields_set or set()):
continue
result[name] = val
# Include extra fields (allowed by model_config extra="allow")
for name, val in (
validated.__pydantic_extra__.items() if validated.__pydantic_extra__ else []
):
result[name] = val
return result