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.

23.7 KB
Raw Blame
"""Read-only execution-chain guidance for the Modules experience."""

from __future__ import annotations

from copy import deepcopy
from typing import Any, Final, TypedDict


class ExecutionChainStage(TypedDict):
    order: int
    title: str
    module_ids: list[str]
    purpose: str
    required_inputs: list[str]
    uses_previous_output: bool
    produces: list[str]
    next_action: str
    final_goal: bool


class ExecutionChain(TypedDict):
    id: str
    title: str
    category: str
    description: str
    stages: list[ExecutionChainStage]


MODULE_EXECUTION_CHAINS: Final[tuple[ExecutionChain, ...]] = (
    {
        "id": "ad-kerberos-exposure-chain",
        "title": "AD Kerberos Exposure Chain",
        "category": "Active Directory",
        "description": "Move from account and SPN discovery to targeted Kerberos evidence and reporting.",
        "stages": [
            {
                "order": 1,
                "title": "Enumerate users and AS-REP exposure",
                "module_ids": ["ad.enum_users", "ad.asreproast"],
                "purpose": "Establish user context and identify accounts that may return AS-REP evidence.",
                "required_inputs": ["dc", "domain", "username", "password"],
                "uses_previous_output": False,
                "produces": ["domain user context", "AS-REP candidates or confirmed evidence"],
                "next_action": "Review the user results, then enumerate service principals.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Enumerate service principals",
                "module_ids": ["ad.enum_spn"],
                "purpose": "Find Kerberoastable service accounts and SPN candidates.",
                "required_inputs": ["dc", "domain", "username", "password"],
                "uses_previous_output": True,
                "produces": ["service account and SPN candidates"],
                "next_action": "Choose one discovered service account or SPN for the targeted step.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Request one targeted service ticket",
                "module_ids": ["ad.kerberoast"],
                "purpose": "Request evidence for a selected candidate without broad ticket collection.",
                "required_inputs": ["dc", "domain", "username", "password", "target_user"],
                "uses_previous_output": True,
                "produces": ["confirmed TGS hash evidence when capture succeeds"],
                "next_action": "Run ad.enum_spn first, then set target_user to a discovered account or SPN and run the module.",
                "final_goal": False,
            },
            {
                "order": 4,
                "title": "Export campaign evidence",
                "module_ids": [],
                "purpose": "Review confirmed findings, confidence, remediation, and redacted evidence.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["JSON, HTML, Markdown, or PDF report artifact"],
                "next_action": "Open Reports, generate the required format, and review the library.",
                "final_goal": True,
            },
        ],
    },
    {
        "id": "ad-domain-enumeration-chain",
        "title": "AD Domain Enumeration Chain",
        "category": "Active Directory",
        "description": "Build a scoped domain inventory, then review access-control and identity exposure evidence.",
        "stages": [
            {
                "order": 1,
                "title": "Build the domain inventory",
                "module_ids": ["ad.enum_users", "ad.enum_computers", "ad.enum_spn"],
                "purpose": "Collect the users, computers, and service principals needed for an initial inventory.",
                "required_inputs": ["dc", "domain", "username", "password"],
                "uses_previous_output": False,
                "produces": ["domain accounts, computers, and SPN inventory"],
                "next_action": "Review inventory coverage before selecting exposure checks.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Review access and identity exposure",
                "module_ids": ["ad.enum_acl", "ad.adcs", "ad.laps_enum"],
                "purpose": "Check delegated access, certificate services, and password-management exposure.",
                "required_inputs": ["dc", "domain", "username", "password"],
                "uses_previous_output": True,
                "produces": ["access-control and identity exposure evidence"],
                "next_action": "Validate any material exposure with the authorized campaign scope.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Validate domain abuse paths",
                "module_ids": ["ad.coerce", "ad.dcsync", "ad.delegation_abuse", "ad.sccm"],
                "purpose": "Use the inventory to assess explicitly authorized delegation, replication, coercion, or SCCM paths.",
                "required_inputs": ["dc", "domain", "username", "password"],
                "uses_previous_output": True,
                "produces": ["validated domain exposure evidence or controlled outcomes"],
                "next_action": "Review results and retain only confirmed, authorized findings.",
                "final_goal": False,
            },
            {
                "order": 4,
                "title": "Report the domain inventory",
                "module_ids": [],
                "purpose": "Package the inventory and confirmed exposure evidence for review.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["domain inventory report"],
                "next_action": "Generate a report from the Reports page.",
                "final_goal": True,
            },
        ],
    },
    {
        "id": "linux-ad-tradecraft-chain",
        "title": "Linux Active Directory Tradecraft Chain",
        "category": "Active Directory",
        "description": "Harvest cached credentials, tickets, and machine secrets from Linux domain members (RFC-ARES-2026-001).",
        "stages": [
            {
                "order": 1,
                "title": "Harvest cached credentials and machine secrets",
                "module_ids": ["linux.sssd_harvest", "linux.samba_secrets"],
                "purpose": "Extract offline salted SHA-512 hashes from SSSD LDB and machine account credentials from Samba secrets.tdb.",
                "required_inputs": ["target"],
                "uses_previous_output": False,
                "produces": ["cached user hashes", "machine account NTLM hash"],
                "next_action": "Review extracted credentials and scan for active Kerberos tickets and keytabs.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Hunt Kerberos credential caches and machine keytabs",
                "module_ids": ["linux.ccache_hunt", "linux.keytab_abuse"],
                "purpose": "Harvest unexpired TGTs from ccache/KCM and extract AES keys from /etc/krb5.keytab.",
                "required_inputs": ["target"],
                "uses_previous_output": True,
                "produces": ["Kerberos ccache TGTs", "Silver Ticket forging configuration"],
                "next_action": "Transcode captured Kerberos tickets to Windows .kirbi format if cross-platform lateral movement is needed.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Transcode Kerberos tickets for Windows lateral movement",
                "module_ids": ["credential.ticket_converter"],
                "purpose": "Convert Linux ccache v4 tickets to Windows .kirbi (KRB-CRED ASN.1) format in-memory.",
                "required_inputs": ["ticket_b64", "source_format", "target_format"],
                "uses_previous_output": True,
                "produces": ["converted Windows .kirbi ticket"],
                "next_action": "Deploy tickets or machine credentials against authorized domain resources.",
                "final_goal": False,
            },
            {
                "order": 4,
                "title": "Report Linux AD tradecraft findings",
                "module_ids": [],
                "purpose": "Package harvested credentials, tickets, and privilege escalation pathways for review.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["Linux AD engagement report"],
                "next_action": "Open Reports and generate the compliance artifact.",
                "final_goal": True,
            },
        ],
    },
    {
        "id": "web-api-exposure-chain",
        "title": "Web/API Exposure Chain",
        "category": "Web and Network",
        "description": "Identify reachable services, fingerprint exposed HTTP surfaces, and review confirmed evidence.",
        "stages": [
            {
                "order": 1,
                "title": "Fingerprint the target environment",
                "module_ids": ["recon.fingerprint"],
                "purpose": "Establish the target technology and environment context.",
                "required_inputs": ["target"],
                "uses_previous_output": False,
                "produces": ["target environment context"],
                "next_action": "Use the target context to scope network discovery.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Discover reachable services",
                "module_ids": ["network.dns_enum", "network.port_scan", "network.service_detect"],
                "purpose": "Resolve the target and identify services inside the campaign scope.",
                "required_inputs": ["target"],
                "uses_previous_output": True,
                "produces": ["resolved hosts, ports, and services"],
                "next_action": "Select authorized HTTP/API surfaces for focused validation.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Validate HTTP and API surfaces",
                "module_ids": ["network.http_fingerprint"],
                "purpose": "Fingerprint web responses and API exposure on discovered services.",
                "required_inputs": ["target"],
                "uses_previous_output": True,
                "produces": ["web/API evidence and service details"],
                "next_action": "Review findings and generate a campaign report.",
                "final_goal": False,
            },
            {
                "order": 4,
                "title": "Export confirmed evidence",
                "module_ids": [],
                "purpose": "Collect validated web/API observations in the campaign report.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["web/API exposure report"],
                "next_action": "Open Reports and generate the required format.",
                "final_goal": True,
            },
        ],
    },
    {
        "id": "cloud-exposure-chain",
        "title": "Cloud Exposure Chain",
        "category": "Cloud",
        "description": "Inventory cloud services, review identity paths, and package confirmed cloud exposure evidence.",
        "stages": [
            {
                "order": 1,
                "title": "Inventory cloud services",
                "module_ids": ["cloud.aws", "cloud.azure", "cloud.gcp", "cloud.azure_ad"],
                "purpose": "Collect the cloud account and identity context available to the authorized assessment.",
                "required_inputs": ["provider credentials or token", "scope"],
                "uses_previous_output": False,
                "produces": ["cloud account and service inventory"],
                "next_action": "Review the inventory and select identity paths for validation.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Review privilege and federation paths",
                "module_ids": ["cloud.aws_privesc", "cloud.identity_federation_abuse"],
                "purpose": "Assess explicitly authorized privilege and federation exposure using the collected context.",
                "required_inputs": ["provider credentials or token", "scope"],
                "uses_previous_output": True,
                "produces": ["cloud identity and privilege evidence"],
                "next_action": "Validate material observations and review remediation.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Report cloud exposure",
                "module_ids": [],
                "purpose": "Package confirmed cloud observations and remediation guidance.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["cloud exposure report"],
                "next_action": "Generate a report from the Reports page.",
                "final_goal": True,
            },
        ],
    },
    {
        "id": "credential-secret-exposure-chain",
        "title": "Credential / Secret Exposure Chain",
        "category": "Credentials",
        "description": "Review credential and secret exposure paths with explicit authorization and evidence handling.",
        "stages": [
            {
                "order": 1,
                "title": "Review credential reuse and strength",
                "module_ids": ["credential.reuse", "credential.crack"],
                "purpose": "Assess authorized credential material for reuse or recoverability.",
                "required_inputs": ["campaign scope", "authorized credential material"],
                "uses_previous_output": False,
                "produces": ["credential exposure observations"],
                "next_action": "Review results before any higher-impact credential operation.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Validate credential access paths",
                "module_ids": ["credential.pass_spray", "credential.ssh_spray", "credential.pass_the_hash", "credential.golden_ticket"],
                "purpose": "Assess only explicitly approved credential paths under the existing RBAC and OPSEC controls.",
                "required_inputs": ["campaign scope", "authorized credential material"],
                "uses_previous_output": True,
                "produces": ["controlled credential-path outcomes"],
                "next_action": "Stop on blocked or operator-error outcomes and review the evidence.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Review secret-bearing artifacts",
                "module_ids": ["exfil.secrets_scan", "windows.lsa_secrets", "windows.lsass_dump", "windows.registry_enum"],
                "purpose": "Inspect authorized artifacts for secret exposure while retaining redaction and cleanup controls.",
                "required_inputs": ["target", "authorized artifact context"],
                "uses_previous_output": True,
                "produces": ["redacted secret exposure evidence"],
                "next_action": "Review confirmed evidence and remediation without exporting raw secrets.",
                "final_goal": False,
            },
            {
                "order": 4,
                "title": "Report credential exposure",
                "module_ids": [],
                "purpose": "Export findings with sensitive evidence redacted by default.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["credential exposure report"],
                "next_action": "Generate and review the report library.",
                "final_goal": True,
            },
        ],
    },
    {
        "id": "opsec-safety-chain",
        "title": "OPSEC / Safety Chain",
        "category": "Safety",
        "description": "Review campaign coverage and planning context before authorized module execution.",
        "stages": [
            {
                "order": 1,
                "title": "Review OPSEC coverage",
                "module_ids": ["opsec.coverage_predictor"],
                "purpose": "Understand expected noise, coverage, and guardrail implications for the campaign.",
                "required_inputs": ["campaign", "selected modules"],
                "uses_previous_output": False,
                "produces": ["coverage and safety review"],
                "next_action": "Use the review to choose dry-run and authorized execution settings.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Review the execution plan",
                "module_ids": ["ai.autonomous_planner"],
                "purpose": "Review planning suggestions as operator context; execution remains manual and policy-controlled.",
                "required_inputs": ["campaign", "objective"],
                "uses_previous_output": True,
                "produces": ["operator-reviewed plan context"],
                "next_action": "Keep manual selection and approval at the Modules run panel.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Confirm safe evidence handling",
                "module_ids": [],
                "purpose": "Confirm scope, authorization, redaction, and report handling before closing the workflow.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["operator safety decision"],
                "next_action": "Run only the selected authorized modules and review their outcomes.",
                "final_goal": True,
            },
        ],
    },
    {
        "id": "reporting-evidence-chain",
        "title": "Reporting / Evidence Chain",
        "category": "Evidence",
        "description": "Review module outcomes, export campaign reports, and keep the artifact library intentional.",
        "stages": [
            {
                "order": 1,
                "title": "Review module results",
                "module_ids": [],
                "purpose": "Check outcome category, findings, confidence, remediation, and next steps.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["reviewed campaign evidence"],
                "next_action": "Select the report format that matches the engagement need.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Generate report artifacts",
                "module_ids": [],
                "purpose": "Create JSON, HTML, Markdown, or PDF output from persisted campaign findings.",
                "required_inputs": ["campaign", "report format"],
                "uses_previous_output": True,
                "produces": ["report artifact in the campaign library"],
                "next_action": "Open the Library tab and download or remove authorized artifacts.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Close the evidence record",
                "module_ids": [],
                "purpose": "Confirm the report contains the intended evidence and no raw secret material.",
                "required_inputs": ["campaign"],
                "uses_previous_output": True,
                "produces": ["final campaign report"],
                "next_action": "Retain only the artifacts required by the authorized engagement.",
                "final_goal": True,
            },
        ],
    },
    {
        "id": "standalone-utilities",
        "title": "Standalone Utilities",
        "category": "Utilities",
        "description": "Focused modules that do not belong to a single ordered family chain; select them manually with the normal safeguards.",
        "stages": [
            {
                "order": 1,
                "title": "Network and pivot utilities",
                "module_ids": ["network.pivot", "network.snmp_enum"],
                "purpose": "Use focused network utilities when the engagement requires a specific capability.",
                "required_inputs": ["target", "campaign scope"],
                "uses_previous_output": False,
                "produces": ["focused network observations"],
                "next_action": "Review the result and choose the next manual module.",
                "final_goal": False,
            },
            {
                "order": 2,
                "title": "Lateral movement utilities",
                "module_ids": ["lateral.dcom", "lateral.mssql", "lateral.ntlm_relay", "lateral.psexec", "lateral.rdp", "lateral.smb_relay", "lateral.ssh_pivot", "lateral.winrm", "lateral.wmiexec"],
                "purpose": "Run only a specifically authorized lateral capability from the manual catalog.",
                "required_inputs": ["target", "campaign scope", "authorized credentials"],
                "uses_previous_output": False,
                "produces": ["focused lateral outcome"],
                "next_action": "Review the result and return to the catalog for the next approved step.",
                "final_goal": False,
            },
            {
                "order": 3,
                "title": "Linux host utilities",
                "module_ids": ["linux.container", "linux.kernel_suggester", "linux.ld_preload", "linux.nfs_escape", "linux.privesc", "linux.service_hijack"],
                "purpose": "Use focused Linux host checks under the campaign scope and existing guardrails.",
                "required_inputs": ["target", "campaign scope"],
                "uses_previous_output": False,
                "produces": ["focused Linux host observations"],
                "next_action": "Review the result and select the next manual module if needed.",
                "final_goal": False,
            },
            {
                "order": 4,
                "title": "Windows and persistence utilities",
                "module_ids": ["persistence.registry_run", "persistence.scheduled_task", "persistence.wmi_subscription", "windows.applocker_bypass", "windows.scheduled_tasks_enum", "windows.uac_bypass"],
                "purpose": "Use focused Windows or persistence checks only when explicitly authorized.",
                "required_inputs": ["target", "campaign scope"],
                "uses_previous_output": False,
                "produces": ["focused Windows or persistence outcome"],
                "next_action": "Review the result and retain only confirmed evidence.",
                "final_goal": False,
            },
            {
                "order": 5,
                "title": "EDR and collection utilities",
                "module_ids": ["edr.bypass_adaptive", "exfil.smb_shares", "exfil.staged_collection"],
                "purpose": "Keep specialized EDR or collection modules available for approved manual use.",
                "required_inputs": ["target", "campaign scope", "authorization"],
                "uses_previous_output": False,
                "produces": ["focused specialized outcome"],
                "next_action": "Review the result, redaction, and campaign evidence handling.",
                "final_goal": True,
            },
        ],
    },
)


def list_execution_chains() -> list[dict[str, Any]]:
    """Return isolated chain metadata so callers cannot mutate definitions."""
    return deepcopy(list(MODULE_EXECUTION_CHAINS))