ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
ARES Module & Developer SDK
Version: 2.0.0 (Next-Gen Sovereign Architecture) | Backward Compatible with v1.0.0
Complete guide for ARES module authors and automation engineers. Everything needed to build type-safe modules, simulate attacks in isolation, and automate ARES via Python.
ares.sdk is the canonical public import path. It provides:
- Type-Safe Module Authoring: Generic
BaseModule[P, R], Pydantic v2ModuleParams, and declarative@ares_module. - Enterprise Security & Governance: Declarative
@module_contract,ScopeEnforcementInterceptor,AdaptiveNoiseInterceptor,SecretSanitizationInterceptor, andAuditProvenanceInterceptor. - Capability-Based Sandboxing:
NetworkPermission,VaultPermission,FilesystemPermission, andProcessPermission. - Intelligent Resilience & Circuit Breakers:
CircuitBreakerandLockoutCircuitBreakerfor zero-collateral safety. - Taint Tracking & Provenance:
UntrustedTargetData[T](anti-prompt injection) andEvidenceRecord(SHA-256 Merkle chain). - Isolated Testing & Simulation:
ModuleTestHarnesswith fluent assertions (result.assert_success(),result.assert_provenance_verified()). - Programmatic API Client:
AresClientfor asynchronous REST and WebSocket automation.
Quick Start (Next-Gen Architecture)
# my_module.py
from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
ModuleParams, param, SecretParam,
OpsecLevel, Severity, ares_module,
)
# 1. Declare validated parameter schema with Pydantic v2
class AttackParams(ModuleParams):
dc: str = param(description="Target DC IP or FQDN", min_length=3)
domain: str = param(description="AD domain name", min_length=3)
password: SecretParam = param(description="Password", secret=True, required=False)
port: int = param(description="Target port", default=389, ge=1, le=65535)
# 2. Modern Class-Based Module
class MyModule(BaseModule[AttackParams, ModuleResult]):
MODULE_ID = "myorg.my_attack"
MODULE_NAME = "My Attack Module"
MODULE_CATEGORY = "ad"
PARAMS_MODEL = AttackParams
OPSEC_LEVEL = OpsecLevel.LOW
MITRE_TECHNIQUES = ["T1087.002"]
async def execute(self, ctx: ExecutionContext[AttackParams]) -> ModuleResult:
# ctx.params has 100% type safety and autocomplete!
target_dc = ctx.params.dc
# Fluent finding emission
ctx.emit_finding(
title=f"Discovered Service on {target_dc}",
severity=Severity.HIGH,
mitre_technique="T1087.002",
)
return ModuleResult(status="success", module_id=self.MODULE_ID)
# 3. Or Declarative Functional Module
@ares_module(
id="myorg.quick_probe",
name="Quick Probe",
category="recon",
params_model=AttackParams,
mitre="T1046",
)
async def quick_probe(ctx: ExecutionContext[AttackParams]) -> ModuleResult:
ctx.emit_finding("Port Active", Severity.INFO, mitre_technique="T1046")
return ModuleResult(status="success", module_id="myorg.quick_probe")
Enterprise Security & Governance Contracts (@module_contract)
For production environments and autonomous operations, ARES enforces code-level capabilities, zero-trust scope verification, and circuit breaking via @module_contract:
from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
ModuleParams, param, SecretParam,
NetworkPermission, VaultPermission,
LockoutCircuitBreaker, UntrustedTargetData, EvidenceRecord,
module_contract, OpsecLevel, Severity,
)
class KerberoastParams(ModuleParams):
dc: str = param("Target DC IP or FQDN", min_length=3)
domain: str = param("AD domain name", min_length=3)
@module_contract(
permissions=[
NetworkPermission(ports=[88, 389], protocols=["tcp", "udp"]),
VaultPermission(read_types=["domain_creds"], write_types=["kerberos_hash"]),
],
circuit_breaker=LockoutCircuitBreaker(),
params_model=KerberoastParams,
)
class EnterpriseKerberoastModule(BaseModule[KerberoastParams, ModuleResult]):
MODULE_ID = "ad.enterprise_kerberoast"
MODULE_NAME = "Enterprise Kerberoast"
MODULE_CATEGORY = "ad"
OPSEC_LEVEL = OpsecLevel.LOW
async def execute(self, ctx: ExecutionContext[KerberoastParams]) -> ModuleResult:
# 1. Scope and Noise budget are enforced automatically by interceptor pipeline!
target_dc = ctx.params.dc
# 2. Taint Tracking: wrap untrusted target data to prevent prompt injection
untrusted_banner = UntrustedTargetData("DC01 Windows Server 2022", source=target_dc)
# 3. Cryptographic Chain-of-Custody Evidence Record
evidence = EvidenceRecord(
evidence_id="ev-krb-001",
source_target=target_dc,
payload={"spn": "MSSQLSvc/sql01.corp.local", "etype": 23},
)
finding = ctx.emit_finding(
title=f"Kerberoastable SPN on {target_dc}",
severity=Severity.HIGH,
evidence={"hash": evidence.sha256_hash},
)
return ModuleResult.ok("Execution completed", module_id=self.MODULE_ID, findings=[finding])
Isolated Testing & Simulation (ares.sdk.testing)
Test modules locally in complete isolation without starting the engine or databases:
from ares.sdk import ModuleTestHarness, Severity
async def test_my_module():
harness = ModuleTestHarness(MyModule)
result = await harness.simulate(
params={"dc": "10.0.0.1", "domain": "CORP.LOCAL"},
dry_run=True,
)
result.assert_success()
result.assert_no_errors()
finding = result.assert_finding(severity=Severity.HIGH, mitre="T1087.002")
assert "Discovered Service" in finding.title
Programmatic Automation (AresClient)
Control and automate ARES from external Python scripts, SOAR playbooks, or CI/CD pipelines:
from ares.sdk import AresClient
async with AresClient(base_url="http://127.0.0.1:8080", api_key="ares_pat_...") as client:
campaign = await client.campaigns.create(name="Op-Titan", scope=["10.10.0.0/24"])
print(f"Created Campaign: {campaign['id']}")
dispatch = await client.modules.run("ad.kerberoast", target="dc01.corp.local", campaign_id=campaign["id"])
findings = await client.campaigns.findings(campaign["id"])
Legacy Quick Start (v1.0.0 - Fully Preserved)
# my_module.py
from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
OpsecLevel, Severity, Finding,
module_metadata, get_logger,
AuthenticationFailed, HostUnreachable,
)
from ares.core.capabilities import Capability
logger = get_logger("myorg.my_module")
@module_metadata(
module_id = "myorg.my_attack",
name = "My Attack Module",
category = "ad",
description = "Does something interesting against AD",
author = "[email protected]",
opsec = OpsecLevel.LOW,
requires = ["domain_creds"],
outputs = ["user_list"],
mitre = ["T1087.002"],
)
class MyModule(BaseModule):
CAPABILITIES = {Capability.CAP_NET, Capability.CAP_DB}
async def validate(self, ctx: ExecutionContext) -> None:
ctx.require("target", "domain")
if not ctx.params.get("dc"):
from ares.core.errors import ModuleValidationError
raise ModuleValidationError("Missing 'dc' param", field="dc")
async def execute(self, ctx: ExecutionContext) -> ModuleResult:
if ctx.dry_run:
return ModuleResult(status="dry_run", module_id=self.MODULE_ID)
await self.before_request(ctx.target) # scope + rate limit + jitter
# ... do work ...
finding = self.finding(
title = "Something found",
description = "Details here",
severity = Severity.HIGH,
mitre_technique = "T1087.002",
host = ctx.target,
)
return ModuleResult(
status = "success",
findings = [finding],
module_id = self.MODULE_ID,
)
async def run(self, **kwargs):
# Legacy interface - engine calls execute(ctx) instead
ctx = ExecutionContext.for_test(**kwargs)
result = await self.execute(ctx)
return result.findings, result.raw
Module Contract (v1.0.0)
Every module must implement 3 methods:
validate(ctx: ExecutionContext) → None
Called before execution. Check that all required params and context fields are present.
Raise ModuleValidationError if context is insufficient - engine aborts immediately.
async def validate(self, ctx: ExecutionContext) -> None:
# Assert required context fields
ctx.require("target", "domain")
# Validate module params
dc = ctx.params.get("dc")
if not dc:
raise ModuleValidationError("Missing 'dc'", module_id=self.MODULE_ID, field="dc")
# Check opsec profile allows this module
if ctx.opsec_profile == "stealth" and self.OPSEC_LEVEL == OpsecLevel.HIGH_NOISE:
raise ModuleValidationError("Module blocked in stealth profile")
execute(ctx: ExecutionContext) → ModuleResult
Main execution. Receives typed context, returns structured result.
async def execute(self, ctx: ExecutionContext) -> ModuleResult:
if ctx.dry_run:
# Always support dry_run - no real network calls
return ModuleResult(status="dry_run", module_id=self.MODULE_ID)
# Use before_request hook (scope check + rate limit + opsec jitter)
await self.before_request(ctx.target, action="ldap_query")
try:
# ... network operations ...
findings = [self.finding(...)]
return ModuleResult(
status = "success",
findings = findings,
new_credentials = [], # Credential objects if harvested
discovered_hosts = ["10.0.0.5"], # IPs if lateral discovery
raw = {"count": 3}, # free-form extra data
module_id = self.MODULE_ID,
)
except HostUnreachable as e:
raise # let engine handle (will skip target)
except AuthenticationFailed as e:
raise # let engine try next credential
report(result: ModuleResult) → dict
Format result for the report engine. Default implementation works fine for most modules. Override to add custom narrative, MITRE context, or remediation text.
def report(self, result: ModuleResult) -> dict:
base = super().report(result)
base["narrative"] = (
f"The {self.MODULE_NAME} found {len(result.findings)} "
f"exploitable accounts. Immediate remediation required."
)
return base
Required Metadata
MODULE_ID = "myorg.my_attack" # dotted: category.name (REQUIRED)
MODULE_NAME = "My Attack Module" # human name (REQUIRED)
MODULE_CATEGORY = "ad" # ad | linux | cloud | reporting (REQUIRED)
MODULE_DESCRIPTION = "Does X against Y" # one-liner (REQUIRED)
MODULE_AUTHOR = "[email protected]" # optional but recommended
MODULE_ID rules:
- Must use dotted format:
category.nameororg.category.name - Lowercase, alphanumeric +
.+_only - Must be globally unique - prefix with your org name
Optional Metadata
OPSEC_LEVEL = OpsecLevel.LOW # silent | low | medium | high_noise
REQUIRES = ["domain_creds"] # what the module needs as input
OUTPUTS = ["spn_list"] # what the module produces
MITRE_TECHNIQUES = ["T1558.003"] # ATT&CK technique IDs
MIN_NOISE_PROFILE = "normal" # "stealth" | "normal" | "aggressive"
CAPABILITIES = {Capability.CAP_NET} # resource access declaration
REQUIRES / OUTPUTS wire into the GoalEngine's dependency resolver and AttackPlanner's scoring:
# Example: your module needs kerberoastable accounts (produced by ad.enum_spn)
# and produces cracked credentials
REQUIRES = ["spn_list"]
OUTPUTS = ["credential"]
# The engine will automatically:
# 1. Run ad.enum_spn first (produces spn_list)
# 2. Then run your module (needs spn_list, produces credential)
Capability Declaration
Declare exactly what system resources your module needs:
from ares.core.capabilities import Capability
class MyModule(BaseModule):
# Network-only module (most AD/cloud modules)
CAPABILITIES = {Capability.CAP_NET, Capability.CAP_DB}
# Module that spawns subprocesses (lateral movement)
CAPABILITIES = {Capability.CAP_NET, Capability.CAP_EXEC, Capability.CAP_DB}
# Module that reads/writes local files (reporting, evidence)
CAPABILITIES = {Capability.CAP_DB, Capability.CAP_FS}
Community module limits:
CAP_NET,CAP_DB,CAP_FS- allowedCAP_EXEC,CAP_PROCESS,CAP_UNSAFE- not allowed for community modules- If you declare forbidden caps, module is rejected at load time
Error Handling
Always raise typed SDK errors - engine uses the type to decide retry/fallback/abort:
from ares.sdk import (
AuthenticationFailed, # try next credential
AccountLocked, # ABORT all auth attempts
HostUnreachable, # skip this target
ConnectionRefused, # fallback to alternative module
DetectionSignal, # pause + escalate opsec
HoneypotDetected, # abort campaign
InsufficientPrivilege, # suggest privesc
)
async def execute(self, ctx):
try:
result = ldap_connect(ctx.target, ctx.best_credential())
except ldap3.core.exceptions.LDAPInvalidCredentialsResult:
raise AuthenticationFailed(
f"LDAP auth failed on {ctx.target}",
username=ctx.best_credential().username if ctx.best_credential() else "",
module_id=self.MODULE_ID, target=ctx.target,
)
except ConnectionError as e:
if "refused" in str(e).lower():
raise ConnectionRefused(f"Port 389 refused on {ctx.target}", port=389)
raise HostUnreachable(f"{ctx.target} unreachable: {e}")
Using ExecutionContext
# Access target and params
dc = ctx.params.get("dc") or ctx.target
domain = ctx.domain or ctx.params.get("domain", "")
# Get best available credential
cred = ctx.best_credential()
if cred:
username = cred.username
password = cred.secret # plaintext if cracked, else hash
# Check opsec profile
if ctx.opsec_profile == "stealth":
# Use more cautious technique
use_ldaps = True
# Dry run mode (simulation)
if ctx.dry_run:
return ModuleResult(status="dry_run", ...)
# Check optional fields
if ctx.has("session"):
host_state = ctx.host_state()
if host_state and host_state.is_dc:
logger.info("Target is a DC - running full enumeration")
Creating Findings
finding = self.finding(
title = "Kerberoastable SPN account: svc_sql",
description = (
"Account svc_sql has SPN MSSQLSvc/db01:1433 registered. "
"Any domain user can request a TGS ticket and attempt offline cracking."
),
severity = Severity.HIGH, # CRITICAL | HIGH | MEDIUM | LOW | INFO
mitre_technique = "T1558.003", # Kerberoasting
mitre_tactic = "Credential Access",
host = ctx.target,
confidence = 0.95, # 0.0–1.0
evidence = {
"username": "svc_sql",
"spns": ["MSSQLSvc/db01:1433"],
"domain": ctx.domain,
},
remediation = (
"Use Group Managed Service Accounts (gMSA) for service accounts. "
"Require AES-256 Kerberos encryption."
),
)
Severity guidelines:
| Severity | Examples |
|---|---|
| CRITICAL | DA credential harvested, DCSync successful |
| HIGH | Kerberoastable SPN, AS-REP roastable, ACL abuse |
| MEDIUM | Misconfigured SMB shares, weak password policy |
| LOW | Information disclosure, non-critical misconfigs |
| INFO | Enumeration results (user list, host discovery) |
Preview-only module validation
Use ModuleTestHelper to validate metadata, parameters, and the shape of a
dry-run preview. These examples do not execute validate, run, or execute
on the module class:
# tests/test_my_module.py
import pytest
from ares.sdk import ModuleTestHelper
from my_module import MyModule
class TestMyModule:
@pytest.fixture
def helper(self):
return ModuleTestHelper(MyModule)
def test_metadata_valid(self, helper):
errors = helper.validate_class()
assert len(errors) == 0
@pytest.mark.asyncio
async def test_dry_run(self, helper):
result = await helper.run_full(
target="10.0.0.1",
domain="CORP",
params={"dc": "10.0.0.1"},
dry_run=True,
)
assert result.status == "preview_only"
@pytest.mark.asyncio
async def test_validate_missing_dc(self, helper):
from ares.core.errors import ModuleValidationError
ctx = helper.make_context(target="10.0.0.1", domain="CORP", params={})
with pytest.raises(ModuleValidationError):
await helper.validate(ctx)
def test_report_structure(self, helper):
from ares.sdk import ModuleResult
result = ModuleResult(status="success", module_id="myorg.my_attack")
report = helper.report(result)
assert "module_id" in report
assert "findings" in report
Run: pytest tests/ -v
Signing Your Module
Before publishing:
# 1. Generate key pair (once per author)
ares signing generate-key --author [email protected] --out ~/.ares/keys/
# 2. Sign your module
ares signing sign my_module.py \
--key ~/.ares/keys/<key_id>.key \
--author [email protected] \
--module-id myorg.my_attack \
--version 1.0.0
# 3. Verify signature
ares signing verify my_module.py
# ✓ my_module.py: COMMUNITY (author: '[email protected]')
# 4. Publish public key to ARES registry
ares signing add-key <key_id> ~/.ares/keys/<key_id>.pub \
--author [email protected]
Include both my_module.py and my_module.py.sig in your release.
Publishing
Option 1: pip package
# pyproject.toml
[project.entry-points."ares.modules"]
myorg_my_attack = "myorg_ares_modules.my_module:MyModule"
Users install with: pip install myorg-ares-modules
Option 2: Drop-in file
Copy my_module.py + my_module.py.sig to ~/.ares/plugins/.
ARES auto-discovers on next startup.
Checklist
Before submitting a module to the ARES marketplace:
- All required metadata set (
MODULE_ID,MODULE_NAME,MODULE_CATEGORY,MODULE_DESCRIPTION) -
validate(ctx)checks all required params -
execute(ctx)supportsdry_run=True - Typed errors raised (never bare
Exception) -
CAPABILITIESdeclared (no undeclaredCAP_EXEC/CAP_PROCESS) -
MITRE_TECHNIQUESset -
OPSEC_LEVELset accurately - Unit tests with
ModuleTestHelper -
@module_metadatadecorator validates clean (no errors) - Module signed with Ed25519 key
C-LIVE-v1 SDK status
ModuleTestHelper is preview-only. Its run and run_full surfaces validate
and describe a module but do not invoke module validate, run, or execute
methods. Public engine calls also reject an absent, fabricated, stale,
transferred, or reused coordinator seal.
All production descriptors remain disabled/ineligible in C-LIVE-v1. Tests may use a private deterministic plan/admission seam, but production cannot import or configure that seam and the SDK never advertises it as executable capability.