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.

26.5 KB
Raw Blame

ARES Modules Guide

ARES ships with 66 active built-in modules (70 total registered in catalog, with 4 disabled per security audit). The modules are not meant to be random buttons. They are building blocks for an authorized engagement: create a campaign, define scope, run safe validation first, collect findings, then generate a report.

The core workflow is universal across module families: create a campaign, define targets and scope CIDRs, select a module from the backend catalog, fill the generated parameters, dry-run where supported, execute only inside authorized scope, review findings, and generate a report. AD/Kerberos, cloud, network, credential, Windows, Linux, and other modules differ only in optional extras/tools and parameter values.

Phase 5C.1 Descriptor Readiness (Audit Only)

Phase 5C.1 adds an immutable first-party descriptor sidecar at ares.modules.descriptors. It records one explicit contract for each of the 62 first-party module IDs and cross-checks those records against the existing registry and parameter models. The sidecar is audit metadata only. It is not called by the API, engine, plans, CLI, SDK, workers, Strategy, Goal, chains, or plugin loader during live execution.

Descriptor completeness is not execution safety. A descriptor can cover every required metadata dimension while remaining future-gateway-ineligible. The current inventory deliberately records blockers where cancellation ownership, result authority, dynamic destinations, ambient credentials, or adapters are not trustworthy enough for fail-closed execution. The P0/P1 execution defects identified by the Phase 5C.0 audit remain unfixed until later Phase 5C work.

Default metadata is value-free for nonpublic fields. The sidecar records only fixed absent, None, empty, nonempty-blocked, or unevaluated-factory states; it never stores or hashes a sensitive default. Nine nonpublic fields currently have a nonempty blocked state across eight modules. Lifecycle review records 61 idempotency contracts as unproven and the billable, nondeterministic AI planner as proven non-idempotent. Automatic retry is disabled for 30 mutating or conditionally mutating modules and blocked for lack of settled-attempt proof for the other 32. Compensation and timeout settlement remain unproven for all 62 modules; 12 timeout values are module-defined bounds and 50 are observations of the legacy engine default.

The canonical pre-side-effect gateway is deferred to Phase 5C.2. Until that gateway exists, the sidecar does not add role, approval, capability, destination, credential, retry, or outcome enforcement. External plugin metadata remains untrusted catalog data under the future contract and receives no fallback descriptor or gateway eligibility. Phase 5C.1 itself added no database table or migration. The later additive revision 0010 stores no module readiness override and does not connect descriptors to live execution.

Safety Model

Only run ARES in systems you own or have written permission to test.

Every serious workflow should start with:

  1. Create a campaign with an explicit scope.
  2. Keep dry_run enabled until the module parameters look correct.
  3. Use low-noise enumeration before medium or high-noise modules.
  4. Treat high-noise modules as approval-only actions.
  5. Generate a report and keep evidence inside the campaign.

The dashboard and API currently provide authentication, RBAC, scope, parameter-validation, rate-limit, and token-revocation checks. They are not yet one canonical execution gateway, and their existing ingress-parity defects are not corrected by the descriptor sidecar. The frontend remains a convenience layer; future execution enforcement must still be authoritative in the backend.

Execution Chains inside Modules

The Modules page includes an Execution Chains section alongside the manual module catalog. Chains are read-only execution guidance: they show an ordered relationship between existing modules, the inputs each step needs, the output that can feed the next step, and the final evidence goal. They do not auto-run modules or replace campaign, RBAC, scope, OPSEC, or parameter validation.

The chains cover AD/domain, web/API, cloud, credential/secret, OPSEC/safety, reporting/evidence, and standalone utility workflows. The AD Kerberos Exposure Chain is the reference example: run ad.enum_users or ad.asreproast, then ad.enum_spn, then select a discovered service account or SPN for targeted ad.kerberoast, and finish by reviewing a campaign report. Use a value such as svc-sql or MSSQLSvc/sql01.lab.local:1433 for target_user; an empty target is rejected before Kerberos work begins.

Manual module execution remains available for advanced operators. Selecting a module chip in a chain only opens that module in the existing Run Panel; the operator still supplies inputs, chooses dry-run or live execution, and submits each step explicitly.

Dry-Run and Outcomes

The live module catalog currently exposes required and optional parameters, defaults, capability labels, supported modes, dependency notes, and its declared dry-run flag. Phase 5C.1 independently records the audited contract; it does not make those legacy declarations authoritative. The audit binds 56 module-native dry-run guards and six lateral modules to the shared BaseLateralModule.execute guard using stable normalized provenance. Guard removal, inversion, fall-through, pre-guard effects, flag poisoning, and provenance drift are readiness failures. Existing dry-run routes return dry_run_ok, dry_run_blocked, or dry_run_unsupported with a redacted parameter summary, missing inputs, warnings, and next steps, but the sidecar does not invoke a module or enforce dry-run at a live ingress.

Live results use these outcome labels:

  • confirmed_findings: confirmed observations were returned.
  • completed_no_findings: execution completed, but no exploitable condition was confirmed. This is different from a failed run.
  • operator_error: review inputs, authorization, credentials, or scope.
  • dependency_error: an optional runtime dependency is unavailable.
  • network_error: the target or network could not be reached or completed.
  • unsupported: the module or requested mode is blocked or unavailable.
  • module_error: the module failed unexpectedly; preserve the displayed error when troubleshooting.

For AD modules, an LDAP-success result can still be completed_no_findings: ad.asreproast explains whether candidates were found without AS-REP material, ad.enum_spn reports when no SPN candidates matched, and ad.kerberoast distinguishes no SPNs, no TGS material, and TGS collection failures. On Windows with a source/local Impacket install, use .[ad-support] for the direct AD support libraries and follow the doctor/setup guidance for Python 3.12.x.

How Modules Are Used

Dashboard Flow

  1. For local development, run ares dashboard dev --no-reload from the repository root and open http://127.0.0.1:5173/dashboard/. On Windows, use .\.venv\Scripts\ares.exe dashboard dev --no-reload. In production/static mode, FastAPI serves the built dashboard at /dashboard after frontend assets are built.
  2. Log in as an authorized operator.
  3. Go to Campaigns.
  4. Create or select a campaign.
  5. Go to Modules.
  6. Select a campaign and a module.
  7. Fill the generated parameter form.
  8. Run in dry_run first.
  9. Review the result, then run only if the engagement allows it.
  10. Generate a report from Reports.

The module form is generated from backend metadata. That means new or updated modules can expose their own parameters without hardcoding fields in React. The dashboard catalog uses the backend loader output for built-in module IDs, names, categories, OPSEC labels, and parameter schemas. High-noise or sensitive modules remain guarded by RBAC, scope checks, and explicit confirmation. Do not run destructive, credential theft, lateral movement, exfiltration, persistence, EDR bypass, or other noisy workflows without written authorization and a scoped campaign.

API Flow

$headers = @{ "X-API-Key" = $env:ARES_API_KEY }

Invoke-RestMethod `
  -Method Get `
  -Uri http://127.0.0.1:8080/modules `
  -Headers $headers

API keys are the supported automation credential. Browser authentication is same-origin only: it begins with GET /auth/csrf, keeps the refresh authority in an HttpOnly cookie, and keeps access tokens in memory. POST /auth/refresh has an empty body and query and accepts no refresh-token header or JSON fallback. WebSocket tickets continue to be issued from an access bearer or API key and ignore ambient refresh cookies.

Run a module in dry-run mode:

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8080/modules/recon.fingerprint/run `
  -Headers $headers `
  -ContentType "application/json" `
  -Body '{
    "campaign_id": "CAMPAIGN_ID",
    "target": "127.0.0.1",
    "params": {},
    "dry_run": true
  }'

Optional extras and native tools depend on the module family. The base dashboard/reporting workflow uses the dev,pdf baseline; install .[ad], .[cloud], .[windows], or .[full] only when those modules are needed. For AD modules, .[ad] is the normal full install. If ares doctor already shows Impacket as importable from a source/local install, use .[ad-support] to install the direct AD support libraries (pyasn1, pyasn1_modules, ldap3, and httpx_ntlm) without forcing another Impacket wheel install. On Windows, if .[ad] fails while importing Impacket example scripts such as GetNPUsers.py, restore the known-good source/local Impacket checkout and use .[ad-support] for the direct support libraries. For dashboard module parameters, prefer UPN usernames such as [email protected]; use LAB\alice only when NTLM/MD4 support is known to work in the active Python/OpenSSL environment.

Module Categories

Category Purpose Typical Use
recon Target/environment fingerprinting Start here to understand a host or domain.
network DNS, HTTP, service and port discovery Build basic target context.
ad Active Directory enumeration and abuse checks Domain assessment, Kerberos, ACLs, ADCS, SCCM.
credential Credential testing, vault use, cracking workflows Offline validation and authorized credential checks.
lateral Lateral movement validation Medium/high-noise actions; use with care.
windows Windows host checks and local privilege paths Endpoint-focused validation.
linux Linux privilege and container checks Linux/container assessment.
cloud AWS, Azure, GCP posture and identity paths Cloud control-plane review.
edr EDR/OPSEC decision support Adaptive bypass planning and telemetry.
opsec Detection-risk modeling Coverage prediction before running noisy actions.
ai Autonomous planning Suggest chains and next steps from current state.
exfil Authorized data exposure checks Secrets and share exposure validation.
persistence Persistence exposure checks Scheduled task, WMI, registry run-key review.

Built-In Catalog

This is the operator-facing catalog. Exact availability depends on installed optional dependencies such as AD, cloud, container, Windows, and PDF extras.

Active Directory

Module Use
ad.enum_users Enumerate domain users, dormant accounts, and password policy.
ad.enum_spn Find service principal accounts that may be Kerberoast candidates.
ad.enum_computers Enumerate computers, OS versions, stale accounts, and DCs.
ad.enum_acl Find ACL paths such as WriteDACL, GenericAll, and DCSync rights.
ad.kerberoast Request service tickets for authorized Kerberoast validation.
ad.asreproast Check accounts without Kerberos pre-authentication.
ad.adcs Assess ADCS template and enrollment misconfigurations.
ad.delegation_abuse Review unconstrained, constrained, and resource-based delegation paths.
ad.laps_enum Enumerate LAPS-managed local admin password exposure.
ad.sccm Review SCCM/MECM abuse paths.
ad.coerce High-noise coercion validation; use only with approval.
ad.dcsync High-noise replication-rights validation; requires explicit authorization.
ad.ghost_forge (Disabled per security audit: MOD-005) Forge golden certificates via compromised ADCS CA private keys (ESC1-ESC8).

Credential

Module Use
credential.crack Offline hash cracking workflow from campaign artifacts.
credential.pass_spray Password-spray validation with rate-limit awareness.
credential.ssh_spray Automated SSH credential testing against scoped hosts with rate limiting and lockout backoff.
credential.golden_ticket Golden ticket validation in approved lab/engagement contexts.
credential.pass_the_hash Authorized NTLM hash reuse validation.
credential.reuse Credential reuse checks across discovered services.
credential.ticket_converter In-memory bidirectional transcoding between Linux Kerberos ccache and Windows .kirbi (KRB-CRED).

Lateral Movement

Module Use
lateral.smb_relay SMB signing and relay-prerequisite audit.
lateral.ntlm_relay High-noise NTLM relay automation path.
lateral.mssql MSSQL linked-server and command execution path review.
lateral.dcom DCOM lateral movement validation.
lateral.wmiexec WMI process creation validation.
lateral.winrm PowerShell Remoting validation.
lateral.ssh_pivot SSH pivot and SOCKS/forwarding workflow.
lateral.psexec High-noise service-control validation.
lateral.rdp RDP access validation.

Windows

Module Use
windows.registry_enum Registry credential and configuration review.
windows.scheduled_tasks_enum Scheduled task enumeration and exposure review.
windows.uac_bypass UAC configuration audit.
windows.token_impersonation (Disabled per security audit: MOD-030) Token impersonation exposure validation.
windows.lsass_dump LSASS exposure validation in approved contexts.
windows.dpapi (Disabled per security audit: MOD-029) DPAPI artifact review.
windows.applocker_bypass AppLocker bypass posture review.
windows.lsa_secrets LSA secrets exposure review.

Linux and Containers

Module Use
linux.sssd_harvest SSSD cache parser; extracts offline SHA-512 crypt hashes and identifies Domain Admin escalation paths.
linux.ccache_hunt Pure-Python Kerberos credential cache hunter (/tmp, /run/user, KCM Unix socket IPC); extracts unexpired TGTs.
linux.keytab_abuse Parses binary keytabs (/etc/krb5.keytab, RFC 0x0502); extracts machine AES-256 keys and generates Silver Ticket configs.
linux.samba_secrets Extracts machine account cleartext passwords and computes NTLM hashes from Samba/Winbind secrets.tdb.
linux.kernel_suggester Kernel version and known local privilege path review.
linux.container Docker/Kubernetes/container escape posture checks.
linux.privesc Linux privilege escalation posture review.
linux.ld_preload LD_PRELOAD misconfiguration validation.
linux.service_hijack Service hijack exposure review.
linux.nfs_escape NFS/container escape path review.

Cloud

Module Use
cloud.aws AWS IAM, S3, IMDS, and security group review.
cloud.aws_privesc AWS IAM privilege escalation path analysis.
cloud.azure Azure resource, storage, RBAC, and Key Vault review.
cloud.azure_ad Azure AD service principal, device code, and guest review.
cloud.gcp GCP IAM, GCS, and service account review.
cloud.identity_federation_abuse SAML/OIDC and cross-cloud identity path review.
cloud.phantom_token (Disabled per security audit: MOD-049) Abuse Entra ID / Hybrid Azure AD Primary Refresh Tokens (PRT) and session tokens.

Network, Recon, Exfil, Persistence, OPSEC, AI

Module Use
recon.fingerprint Target OS, role, and EDR/environment fingerprinting.
network.dns_enum DNS enumeration.
network.http_fingerprint HTTP service fingerprinting.
network.port_scan Port discovery inside campaign scope.
network.service_detect Service identification.
network.snmp_enum SNMP exposure review.
network.pivot Pivot path modeling.
exfil.secrets_scan Secrets and sensitive-file exposure review.
exfil.smb_shares SMB share exposure review.
exfil.staged_collection Authorized staged collection workflow.
persistence.scheduled_task Scheduled task persistence exposure.
persistence.wmi_subscription WMI subscription persistence exposure.
persistence.registry_run Registry run-key persistence exposure.
edr.bypass_adaptive EDR vendor-aware OPSEC recommendations and outcome tracking.
opsec.coverage_predictor Predict detection probability and recommended wait windows.
ai.autonomous_planner Plan an engagement chain from campaign state and goals.

AI Planner Module

ai.autonomous_planner is the LLM-backed planning module. It is different from template planning and from the internal module scorer:

Planner surface LLM required? Primary use
Templates dashboard page No Produce predictable template-based plans for review.
ai.autonomous_planner module Yes, unless using local Ollama Ask Claude, OpenAI, or Ollama to propose a plan from campaign context.
Strategy dashboard page Usually yes Start a background goal-based engagement loop with strategy events.
Internal AttackPlanner scorer No Rank possible next modules using local state and scoring weights.

Parameters:

Parameter Values Meaning
goal domain_admin, enterprise_admin, cloud_admin, data_exfil, persistence, full_compromise The desired high-level outcome for the proposed plan.
llm_backend claude, openai, local Which planner backend to use.
llm_model Optional string Overrides the backend default model.
auto_approve false recommended When false, ARES returns a proposed plan for operator review.

Provider setup:

  • llm_backend=claude requires ANTHROPIC_API_KEY.
  • llm_backend=openai requires OPENAI_API_KEY.
  • llm_backend=local expects Ollama at http://localhost:11434.

Expected output:

  • execution_plan: proposed stages and module IDs.
  • ai_reasoning: why the planner selected the path.
  • confidence_score: confidence from the planner response.
  • warnings: OPSEC or safety notes to review before execution.

The module is OPSEC LOCAL: the planning call goes to the selected LLM backend and does not contact the target network by itself. Treat the result as a plan proposal, not as automatic authorization to execute it.

Recommended Workflows

Local Validation

Use this after a code or UI change:

$env:ARES_LAB_PASSWORD="your-current-admin-password"
.\scripts\run_validation_lab.ps1

The validation lab logs in, checks auth, creates a local campaign, validates input handling, generates a report, creates/deletes an API key, and deletes the temporary campaign when done.

Safe First Campaign

  1. Create a campaign with one loopback or lab target.
  2. Run recon.fingerprint in dry-run.
  3. Run network.http_fingerprint or network.dns_enum in dry-run.
  4. Generate an HTML report.
  5. Confirm the report and dashboard views behave correctly.

Active Directory Review

  1. Start with ad.enum_users, ad.enum_computers, and ad.enum_spn.
  2. Review findings and scope.
  3. Use ad.kerberoast only when explicitly authorized.
  4. Use credential.crack for offline analysis.
  5. Keep high-noise modules such as ad.dcsync, ad.coerce, and lateral.psexec approval-gated.

OPSEC Review

  1. Run or review recon.fingerprint.
  2. Use edr.bypass_adaptive to understand defensive product assumptions.
  3. Use opsec.coverage_predictor before noisy chains.
  4. Prefer low-noise enumeration when uncertainty is high.

Linux Active Directory Post-Exploitation Suite (RFC-ARES-2026-001)

The Linux Active Directory suite addresses the modern hybrid enterprise attack surface: critical Linux systems (Kubernetes worker nodes, CI/CD runners, database servers) joined to Active Directory via SSSD, Winbind, or Kerberos PAM.

1. Engineering Principles & Technical Honesty (Anti-Hype Policy)

In strict accordance with the ARES Engineering Standards:

  • Pure User-Space Execution: All parsers (TDBParser, CcacheParser, KeytabParser, KirbiASN1Codec, KCMClient, and pure_md4) execute entirely within Python user space using standard-library primitives (struct, hashlib, socket, io).
  • Zero Kernel Overclaims: These modules do not claim or utilize kernel-mode hooks. They read existing disk databases and IPC sockets accessible under standard POSIX file permissions.
  • Subprocess Evasion (execve Bypass): Standard offensive scripts invoke external binaries (strings, tdbdump, klist, kinit, secretsdump.py), producing auditd SYSCALL 59 (execve) telemetry alerts. ARES executes zero subprocesses, parsing raw binary structures directly in-memory.
  • Graceful Unprivileged Fallback: When run without elevated permissions (root), modules verify read access, cleanly classify missing access as dry_run_blocked or permission_denied, and never raise unhandled exceptions or disrupt target system operations.
  • Automated AEAD Vault Integration: Recovered credentials, machine account NTLM hashes, and Kerberos TGTs are encrypted at rest using AES-256-GCM authenticated encryption in AresVault, preventing cleartext exposure in engagement logs.

2. Module Specifications

linux.sssd_harvest

  • Module ID: linux.sssd_harvest
  • MITRE ATT&CK: T1003.008 (OS Credential Dumping: /etc/passwd and /etc/shadow), T1558 (Steal or Forge Kerberos Tickets)
  • OPSEC Rating: SILENT (Reads local files; 0 network packets transmitted).
  • Parameters:
    • target (str, required): Target IP address or hostname.
    • db_path (str, optional, default /var/lib/sss/db/cache_default.ldb): Path to SSSD LDB cache database.
    • extract_offline_hashes (bool, default True): Extracts salted SHA-512 crypt hashes for offline cracking.
    • check_domain_admins (bool, default True): Parses LDAP memberOf attributes to highlight Domain Admin accounts.
  • Permissions: FilesystemPermission(read_only=True), ProcessPermission(allow_subprocesses=False), VaultPermission(read_types=[], write_types=["password", "hash"]).
  • Closed-Loop Telemetry:
    • Sigma Rule: detection.selection: name|contains: 'cache_', filter: exe|startswith: '/usr/sbin/sssd'
    • Microsoft Sentinel (KQL):
      DeviceFileEvents
      | where ActionType in ('FileRead', 'FileModified')
      | where FolderPath has_any ('/var/lib/sss/db', '/var/lib/sss/secrets')
      | where InitiatingProcessFileName !in ('sssd', 'sssd_be', 'sssd_nss', 'sssd_pam')
      | project Timestamp, DeviceName, InitiatingProcessAccountName, InitiatingProcessFileName, FolderPath
      

linux.ccache_hunt

  • Module ID: linux.ccache_hunt
  • MITRE ATT&CK: T1558 (Steal or Forge Kerberos Tickets), T1550.003 (Pass the Ticket)
  • OPSEC Rating: SILENT (Scans user-space ticket caches; 0 network packets transmitted).
  • Parameters:
    • target (str, required): Target IP address or hostname.
    • search_paths (list[str], default ["/tmp", "/run/user"]): Directories to hunt for Kerberos ccache files (krb5cc_*).
    • include_expired (bool, default False): Filter out expired credentials by inspecting ticket lifetime timestamps.
    • query_kcm (bool, default True): Query the local SSSD KCM Unix domain socket (/var/run/sss/pipes/kcm).
  • Permissions: FilesystemPermission(read_only=True), ProcessPermission(allow_subprocesses=False), VaultPermission(read_types=[], write_types=["ticket", "kerberos"]).
  • Harvested Artefacts: Extracted TGTs are tagged with is_tgt=True, granting immediate lateral movement or Pass-the-Ticket capabilities.

linux.keytab_abuse

  • Module ID: linux.keytab_abuse
  • MITRE ATT&CK: T1558.003 (Kerberoasting), T1078.002 (Domain Accounts)
  • OPSEC Rating: LOW (Local keytab read; optional Silver Ticket configuration derivation).
  • Parameters:
    • target (str, required): Target IP address or hostname.
    • keytab_path (str, default /etc/krb5.keytab): Path to Kerberos keytab binary file.
    • generate_silver_ticket_config (bool, default True): Derives service ticket forging parameters (SPN, encryption type, symmetric key).
    • target_service (str, default cifs): Target service name for Silver Ticket configuration template.
  • Supported Enctypes: Enctype 18 (AES256-CTS-HMAC-SHA1-96), Enctype 17 (AES128-CTS-HMAC-SHA1-96), Enctype 23 (RC4-HMAC).
  • Permissions: FilesystemPermission(read_only=True), ProcessPermission(allow_subprocesses=False), VaultPermission(read_types=[], write_types=["key", "password"]).

linux.samba_secrets

  • Module ID: linux.samba_secrets
  • MITRE ATT&CK: T1003 (OS Credential Dumping), T1550.002 (Pass the Hash)
  • OPSEC Rating: SILENT (Parses Samba database; 0 network packets transmitted).
  • Parameters:
    • target (str, required): Target IP address or hostname.
    • secrets_tdb_path (str, default /var/lib/samba/private/secrets.tdb): Path to Samba secrets database.
  • Capabilities: Parses TDB records to extract SECRETS/MACHINE_PASSWORD/<DOMAIN>. Automatically derives the machine account NTLM hash via cross-platform RFC 1320 MD4, enabling instant Pass-the-Hash lateral movement as the computer account (DOMAIN$).
  • Permissions: FilesystemPermission(read_only=True), ProcessPermission(allow_subprocesses=False), VaultPermission(read_types=[], write_types=["password", "hash"]).

credential.ticket_converter

  • Module ID: credential.ticket_converter
  • MITRE ATT&CK: T1558 (Steal or Forge Kerberos Tickets)
  • OPSEC Rating: SILENT (100% in-memory data transformation; zero file writes or network transmission).
  • Parameters:
    • ticket_b64 (str, required): Base64-encoded Kerberos ticket.
    • source_format (str, ccache | kirbi): Input format.
    • target_format (str, kirbi | ccache): Desired output format.
    • target (str, default 127.0.0.1): Host identifier for provenance tracking.
  • Capabilities: Transcodes Linux Kerberos ccache v4 binary structures to Windows .kirbi (KRB-CRED ASN.1 Application 22 DER) and vice versa, allowing tickets captured on Linux domain members to be deployed directly against Windows targets without external dependencies.