Attack Modules

tools/attack_modules/ is the plugin framework that gives the AI "known recipes" for common vulnerabilities, so it doesn't have to write every exploit from scratch (tools/attack_modules/__init__.py:1-6). A module is a pre-packaged, context-scored attack recipe: it declares which services, ports, and CVEs it targets, scores its own applicability against a target, and either generates an exploit script, emits a suggested command / MSF recipe, or returns a workflow that routes the agent through existing MCP tools.

What an attack module is

An AttackModule subclass (tools/attack_modules/base.py:144) is the unit of attack knowledge. It has two contracts:

• Metadata (class attributes): name, description, target_services, target_ports, required_cves, target_versions — used for scoring and display (base.py:163-168).
• Behavior: run(ctx) -> dict (abstract, base.py:208-211) plus optional generate_python_script(ctx) -> str (base.py:213-215) and generate_dynamic_script(ctx, mutator) (base.py:217-249, which routes script generation through the PayloadCrafter when a mutator is supplied).

ModuleContext (base.py:11-17) carries target_ip, target_os, services (list of {service, port, version} dicts), cves, and the workspace path. The capability upgrade added defaulted fields the orchestrator threads from AttackState: sessions, findings, hypotheses, evidence_refs, access_achieved, privilege_level, and phase — constructors that don't supply them keep the ABC defaults. ModuleResult (base.py:26-156) is the typed outcome shape the autonomous orchestrator and MCP renderer read; ModuleResult.to_result() adapts a legacy dict return so old modules keep working unchanged. It gained defaulted failure_class, retryable, confidence, produced_artifacts, follow_ups, and unlocked_capabilities fields (emitted by to_dict only when set, so the legacy contract is byte-identical).

Capability metadata (capability upgrade §1/§19)

Every AttackModule subclass declares five additional class attributes so the planner can do dynamic composition (find what produces a missing artifact) and prerequisite gating (find what a module requires):

find_producers(artifact_kind) (registry.py) returns the modules whose produces claims the kind — the dynamic-composition primitive for prerequisite-recovery scheduling. missing_prerequisites(mod, ctx) reports declared requires not satisfiable from a ModuleContext. capability_record() (base.py) is the superset metadata dict for discovery tools; to_json() stays byte-identical and does not leak the new attrs. applicability_explain(ctx) returns an ApplicabilityReport(score, reasons, penalties) while delegating the score to applicability(), so subclass overrides (ICS destructive zero-gate, ics_iot write flags) stay authoritative.

Applicability scoring

AttackModule.applicability(ctx) -> int (base.py:170-206) returns 0-100:

A score of 0 means the module is not applicable and is excluded from ranking (registry.py:236-239).

Registry mechanism

The registry lives in tools/attack_modules/registry.py. Registration is filesystem auto-discovery: the single source is the filesystem under tools/attack_modules/modules/, scanned with pkgutil.iter_modules (registry.py:21-67). There is no manual _MODULE_CLASSES literal to edit.

How modules register

1. Define an AttackModule subclass in the relevant category file under tools/attack_modules/modules/ (e.g. modules/web/sqli.py, modules/network_smb.py).
2. _discover_attack_modules() imports every module file and walks subpackages too: category families split into packages such as modules/web/ and modules/ics/ still register their classes, because a plain iter_modules loop skips packages and the walker explicitly queues each subpackage __path__ (registry.py:27-42). Discovery runs on import and is idempotent (registry.py:71).
3. Dedupe is by class identity and by module.name: a family mid-split that defines the same modules twice (e.g. modules/ics_iot.py alongside modules/ics/) registers only once, since module.name is the registry key for get_module / run_attack_module (registry.py:60-67).
4. tools/attack_modules/__init__.py re-exports the registry helpers and all module classes for tests that import them by name.

The @register_attack_module decorator remains as an explicit opt-in for out-of-tree or test modules: it appends the decorated class when absent and returns it unchanged (registry.py:96-106).

Out-of-tree modules register through the plugin system instead: registry._plugin_extra_module_classes() lazily consults tools.plugins.PLUGIN_REGISTRY.extra_module_classes (registry.py:74-85), and list_modules() / get_module() append those instances (registry.py:109-117, registry.py:292-302). See plugin-development.md §4a.

Registry metadata fields

The metadata schema is the class attributes on AttackModule (base.py:335-340), surfaced by to_json() (base.py:646-653):

There is no explicit risk field in the metadata. Risk is implicit in module behavior: read-only / detection / planning modules (detection, ICS/IoT, supply-chain families) never set shell_type/privilege_level and are low-risk; exploit and persistence modules are high-risk. The inventory table below marks this derived risk.

Registry API

Experience-aware ranking

find_modules blends static applicability with historical Bayesian confidence when an experience_store is provided (registry.py:120-159): the composite score is static + (confidence - 0.5) * 20, so experience swings the ordering by at most ±10 and can never include a module with 0 applicability. The write side (generate_dynamic_script, base.py:612-644) and the read side (_module_target_signature) share _module_primary_service so they can never disagree on which service:version:os signature an outcome was recorded against (registry.py:162-211).

Module inventory

All modules live in tools/attack_modules/modules/. Two families are split into subpackages: web probes live in modules/web/ (sqli.py, upload.py, xss.py, re-exported by modules/web/__init__.py) and ICS modules live in modules/ics/ (bacnet.py, modbus.py, s7.py, re-exported by modules/ics/__init__.py). The legacy modules/ics_iot.py still defines the same ICS classes; the registry dedupes by module.name, so each registers once (see Registry mechanism above).

Risk is derived from behavior, not a metadata field: low = read-only / detection / planning (never sets shell_type/privilege_level), high = active exploitation / credential attack / persistence.

Producer graph and artifact vocabulary

Producer graph (graph.py)

tools/attack_modules/graph.py is the producer/consumer graph over the closed artifact vocabulary. Its module docstring states it is shared by the campaign prerequisite scheduler and planner integration tests, and that all ranking is deterministic: cost order (low < medium < high), read-only preferred on ties, then name (graph.py:1-13). The campaign batch scheduler consults graph.rank_producers to order prerequisite-recovery candidates cheapest/read-only-first with ctx-satisfied prerequisites ahead (tools/campaign/batch.py:154-160). tests/test_artifact_graph.py is the contract test: closed vocabulary, every requires has a producer, no producer/consumer cycle, and dead ends are terminal or documented.

Two unsorted helpers sit alongside: producers_for(kind, modules=None) lists all modules producing kind and consumers_of(kind, modules=None) lists all modules requiring it (graph.py:69-84). graph.missing_prerequisites(mod, ctx) mirrors the registry helper against the closed vocabulary (graph.py:64-66).

from tools.attack_modules.graph import chain_to, rank_producers

# Cheapest producer of admin_priv whose own prerequisites are satisfiable first.
producers = rank_producers("admin_priv", ctx, exclude="DCSyncAttack")
# Full prerequisite chains yielding the artifact, up to 2 links deep.
chains = chain_to("admin_priv", ctx, depth=2)

Implementation note: orphan_requires docstring says "(excluding terminals)" but the code read filters only on the produced set with no terminal-kind exclusion; dead_end_produces is the one that excludes TERMINAL_ARTIFACTS.

Closed artifact vocabulary (artifacts.py)

tools/attack_modules/artifacts.py is the closed vocabulary for capability composition: requires/produces strings must come from ARTIFACT_VOCAB. Unknown kinds are absent (fail closed) and flagged by the contract test (artifacts.py:1-8). base._artifact_present delegates to this module (base.py:75-80).

Aliases resolve onto the canonical kinds: creds and password mean credentials, hash means hash_artifact, root_priv and system_priv mean admin_priv (artifacts.py:39-45). Terminal artifacts with no consumer expected are persistence, vuln_confirmed, high_priv, and webshell (artifacts.py:55-60).

Orchestrator phases

The autonomous orchestrator (tools/autonomous_orchestrator.py) drives modules through a fixed campaign. Phase order and module selection:

The phase modules in orchestrator_phases.py exist because the orchestrator previously referenced names that were not registered — get_module(name) returned None and every privesc/lateral/validation task FAILED (orchestrator_phases.py:1-25). LateralMovement and ValidateFinding declare target_services=[] so they are never service-matched; the orchestrator instantiates them by name (orchestrator_phases.py:126-131, 155-160).

How the planner picks modules

tools/attack_planner.py is the LLM-driven planning layer, distinct from the deterministic orchestrator. It defines the AttackPhase enum (RECON → ENUMERATE → EXPLOIT → ESCALATE → LOOT → PIVOT → DONE, attack_planner.py:20-27), AttackPlan/AttackStep dataclasses (attack_planner.py:30-155), and prompt builders that ask the AI to emit JSON steps (build_planning_prompt, attack_planner.py:158-203; adaptive build_replanning_prompt, attack_planner.py:206-238). Steps reference MCP tool names (including the attack_module family tools), not module classes directly; AttackPlanner manages plan lifecycle and persists plans as JSON under <workspace>/plans/ (attack_planner.py:304-363). The MCP tool layer (tools/mcp_tools/attack_modules.py) exposes list_attack_modules, run_attack_module, craft_exploit, mutate_exploit, and the campaign planner tools (CLAUDE.md:214).

How the eval harness drives them

tools/eval_harness.py (--eval) runs a single attack-mode exploit session against --target and derives EvalMetrics from the run_exploit_agent final-result dict (eval_harness.py:1-19, 130-204). It does not call find_modules directly — modules are selected inside the exploit session by the agent loop. The harness:

1. Loads validated config, builds the model router, and probes the MCP exploit server with open_exploit_mcp_session(soft_fail=True) (eval_harness.py:369-467).
2. Runs run_exploit_session in attack mode with ExploitPermission.FULL_ACCESS and the initial_access goal (eval_harness.py:416-484).
3. Computes metrics (compromises / cred dumps / partials / failures, success rate, verdict) from the outcome summary and audit records (eval_harness.py:64-204), then writes eval_report.json / .md / .html under reports/eval/<run_id>/ (eval_harness.py:328-355).

The attack path is target-locked at the MCP tool layer (allowlist unions the runtime --target); the harness adds no further gate (eval_harness.py:15-18).

OPSEC / detection-coverage integration

tools/detection_coverage.py is the read-only helper backing the detection family modules (detection_coverage.py:1-18):

• detection_probe_plan(target_ip) builds a 4-item canary plan (auth / file / exec / network) the operator deploys against their own target to validate SIEM/IDS/FIM coverage; nothing executes (detection_coverage.py:86-124). Consumed by DetectionCoverageProbe.run (detection.py:66-80).
• footprint_summary(audit_records) reduces exploit_audit.jsonl records into counts (total/noisy/commands/targets/tools/egress) without mutating the append-only audit trail (detection_coverage.py:127-179). Consumed by OPSECPostureReport.run (detection.py:154-200).
• LogSourceEnum lists candidate log sources per OS family (detection.py:83-137).

The detection modules are deliberately read-only: they never set shell_type/privilege_level (so access_achieved is never flipped), never clear logs or defeat EDR/SIEM, and are target-locked to ctx.target_ip (detection.py:1-21). DetectionCoverageProbe and OPSECPostureReport override applicability to fixed low scores (15 / 10) so they are always selectable but never outrank real exploit modules (detection.py:62-64, 150-152). The OPSEC posture itself (pacing, UA rotation, DoH, quiet-command rewriting) is enforced elsewhere — tools/opsec.py and the AttackModuleExecutor — not by these modules (CLAUDE.md:123).

Add a module

Minimal module (matching docs/extension-guide.md:78-102):

# tools/attack_modules/modules/web/sqli.py
from tools.attack_modules.base import AttackModule, ModuleContext
from typing import Any

class MyProbe(AttackModule):
    name = "MyProbe"
    description = "Probe for a specific misconfiguration"
    target_services = ["http", "https"]
    target_ports = [80, 443]
    required_cves = []
    # Capability metadata (required for find_producers composition + gating):
    requires = ["credentials"]   # artifacts needed before this can run
    produces = ["high_priv"]     # artifacts yielded on success
    read_only = True             # False if it writes to the target
    cost = "low"
    phase_hint = "enumerate"

    def run(self, ctx: ModuleContext) -> dict[str, Any]:
        script = self.generate_python_script(ctx)
        return {
            "status": "script_generated",
            "module": self.name,
            "script": script,
            "note": "What this probe does.",
        }

    def generate_python_script(self, ctx: ModuleContext) -> str:
        return f"""import sys
host = sys.argv[1] if len(sys.argv) > 1 else "{ctx.target_ip}"
print(f"probing {{host}}")
"""

Checklist

1. Subclass AttackModule in the relevant category file under tools/attack_modules/modules/ (docs/extension-guide.md:84).
2. Set metadata: name (stable — tests and orchestrators reference it), description, target_services, target_ports, required_cves, and target_versions if version-aware scoring is needed.
3. Declare capability metadata: requires (artifacts the module needs), produces (artifacts it yields — use the shared vocabulary: credentials / foothold / shell / user_list / hash_artifact / admin_priv / high_priv / persistence / webshell), read_only (False only when it actually writes to the target), cost, and an explicit phase_hint (recon/enumerate/exploit/escalate/loot/persist/validate/pivot). tests/test_module_capability_metadata_{a,b}.py assert these are set.
4. Implement run(ctx) -> dict; override applicability(ctx) only if the base scoring is not enough (docs/extension-guide.md:85-86).
5. Return structured data: status, script text, suggested commands, or workflow instructions as dict keys; never embed credentials in plain output (docs/extension-guide.md:98-100).
6. Re-export the class from tools/attack_modules/modules/__init__.py (modules/__init__.py:3-105) and add it to __all__ (modules/__init__.py:106-183).
7. No registry edit needed — filesystem auto-discovery picks up the new file on import (see Registry mechanism above). Out-of-tree: use registry.register_attack_module(cls) via the plugin system instead (docs/extension-guide.md:102, docs/plugin-development.md:153-188).
8. Add tests to tests/test_attack_modules.py covering registry registration, applicability, run output, and edge cases (docs/extension-guide.md:88).
9. Run the suite: python -m pytest tests/ -v and ruff check . (AGENTS.md §Commands).

Read-only / detection modules should follow the detection-family conventions: no shell_type/privilege_level in results, target-locked to ctx.target_ip, and a fixed low applicability override if they should always be selectable (detection.py:1-21).

Related documentation

• extension-guide.md — authoring a new module
• plugin-development.md — out-of-tree registration via register_attack_module
• campaign.md — campaign prerequisite-recovery scheduling
• safety-model.md — ICS write dual gate and allowlist lock

Source map

• tools/attack_modules/registry.py
• tools/attack_modules/graph.py
• tools/attack_modules/artifacts.py
• tools/attack_modules/base.py
• tools/attack_modules/__init__.py
• tools/attack_modules/modules/__init__.py
• tools/attack_modules/modules/web/__init__.py
• tools/attack_modules/modules/web/sqli.py
• tools/attack_modules/modules/web/upload.py
• tools/attack_modules/modules/web/xss.py
• tools/attack_modules/modules/ics/__init__.py
• tools/attack_modules/modules/ics/bacnet.py
• tools/attack_modules/modules/ics/modbus.py
• tools/attack_modules/modules/ics/s7.py
• tools/attack_modules/modules/ics_iot.py
• tools/campaign/batch.py
• tests/test_artifact_graph.py