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 Quickstart & Scaffolding Guide
Version: 1.0.0
Quick Start
Generate a module scaffold using the CLI:
ares module create ad.my_attack \
--author [email protected] \
--category ad \
--description "Find something interesting"
This creates two files:
my_attack.py- module implementationtest_my_attack.py- test scaffold
Module Anatomy
Every ARES module is a Python class that inherits from BaseModule:
from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
ModuleParams, param, SecretParam,
OpsecLevel, Severity, ares_module,
)
# 1. Parameter schema with strict validation & auto UI forms
class MyAttackParams(ModuleParams):
target: str = param("Target domain controller or IP", min_length=1)
domain: str = param("AD domain name, e.g. CORP.LOCAL", min_length=1)
username: str = param("Domain username", required=False)
password: SecretParam = param("User password", secret=True, required=False)
# 2. Modern generic BaseModule[Params, Result]
class MyAttackModule(BaseModule[MyAttackParams, ModuleResult]):
MODULE_ID = "ad.my_attack" # unique dot-notation ID
MODULE_NAME = "My Attack"
MODULE_CATEGORY = "ad" # ad | linux | cloud | lateral | exfil | credential
MODULE_DESCRIPTION = "Find something interesting"
MODULE_AUTHOR = "[email protected]"
PARAMS_MODEL = MyAttackParams
OPSEC_LEVEL = OpsecLevel.LOW # silent | low | medium | high_noise
REQUIRES = ["domain_creds"] # capabilities this module needs
OUTPUTS = ["credential_list"] # capabilities this module produces
MITRE_TECHNIQUES = ["T1558.003"] # MITRE ATT&CK technique IDs
async def execute(self, ctx: ExecutionContext[MyAttackParams]) -> ModuleResult:
if ctx.dry_run:
return ModuleResult.ok("Dry-run check validated: target in scope.", module_id=self.MODULE_ID)
# Full type safety on parameters
target = ctx.params.target
await self.before_request(target, "ldap") # scope + noise check
# Emit findings using fluent context helper
ctx.emit_finding(
title = "Kerberoastable account found",
description = "Service account has SPN set",
severity = Severity.HIGH,
mitre_technique = "T1558.003",
host = target,
evidence = {"spn": "MSSQLSvc/db01"},
remediation = "Use gMSA instead",
)
return ModuleResult(
status = "success",
findings = ctx.findings,
module_id = self.MODULE_ID,
raw = {"spns": [...]},
)
REQUIRES and OUTPUTS
These are the two most important metadata fields for the capability-based planner.
| Field | Type | Purpose |
|---|---|---|
REQUIRES |
list[str] |
Capabilities this module needs to run |
OUTPUTS |
list[str] |
Capabilities this module produces on success |
The CapabilityGraph uses these to automatically determine execution order when running a goal. If you set them correctly, your module will be discovered and used automatically by the planner.
Core capability identifiers:
| Capability | Description |
|---|---|
domain_creds |
Any valid domain user credential |
domain_admin_creds |
Domain Admin credential |
local_admin_cred |
Local admin on a specific host |
user_list |
List of domain users |
spn_list |
List of SPN accounts |
kerberos_hashes |
Kerberos TGS/AS-REP hashes |
ntlm_hashes |
NTLM hashes from DCSync |
acl_findings |
Dangerous ACL grants |
computer_list |
Domain computers |
lateral_session |
Active session on remote host |
persistence_established |
Persistence mechanism in place |
file_share_list |
Accessible SMB shares |
credential_list |
List of credentials |
sensitive_data_found |
Sensitive data located |
OpsecLevel
Controls whether the planner includes your module in stealth profiles:
| Level | Description | Example |
|---|---|---|
OpsecLevel.SILENT |
No network noise, read-only | Reading local files |
OpsecLevel.LOW |
Minimal network, no auth events | LDAP anonymous query |
OpsecLevel.MEDIUM |
Some auth events expected | Kerberoast (normal TGS) |
OpsecLevel.HIGH_NOISE |
Very noisy, creates many events | DCSync, brute force |
Finding Severity
from ares.sdk import Severity
Severity.CRITICAL # CVSS 9.0–10.0
Severity.HIGH # CVSS 7.0–8.9
Severity.MEDIUM # CVSS 4.0–6.9
Severity.LOW # CVSS 0.1–3.9
Severity.INFO # Informational
Testing Your Module
The scaffold generates a test file with two baseline tests. Add more:
from ares.sdk import ModuleTestHarness, Severity
import pytest
@pytest.mark.asyncio
async def test_finds_kerberoastable_user():
"""Simulate attack module in hermetic test harness."""
harness = ModuleTestHarness(MyAttackModule)
result = await harness.simulate(
params={"target": "10.0.0.1", "domain": "CORP.LOCAL"},
dry_run=False,
)
result.assert_success()
result.assert_no_errors()
finding = result.assert_finding(severity=Severity.HIGH, mitre="T1558.003")
assert "Kerberoastable" in finding.title
@pytest.mark.asyncio
async def test_dry_run_simulation():
"""Verify dry-run returns success without side-effects."""
harness = ModuleTestHarness(MyAttackModule)
result = await harness.simulate(
params={"target": "10.0.0.1", "domain": "CORP.LOCAL"},
dry_run=True,
)
result.assert_success()
result.assert_no_errors()
Run tests:
pytest test_my_attack.py -v
Installing Your Module
# Sign the module (required for non-builtin)
ares signing generate-key --author [email protected]
ares signing sign my_attack.py
# Install from local file
ares module install ./my_attack.py
# Verify it loaded
ares module list | grep my_attack
ares module info ad.my_attack
Module Categories
| Category | Purpose | Examples |
|---|---|---|
ad |
Active Directory attacks | kerberoast, dcsync, enum_users |
linux |
Linux/Unix attacks | privesc, container escape |
cloud |
Cloud provider attacks | aws, azure, gcp |
lateral |
Lateral movement | psexec, wmiexec, winrm, ssh |
exfil |
Data exfiltration | smb_shares, secrets_scan |
credential |
Credential operations | reuse, cracking |
persistence |
Persistence mechanisms | scheduled_task, registry_run |
reporting |
Report generation | report_gen |