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.

6.6 KB
Raw Blame

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 implementation
  • test_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