attackmap 0.6.4__py3-none-any.whl

attackmap/cli.py

@@ -0,0 +1,1474 @@
+from __future__ import annotations
+
+import json
+import os
+from collections import Counter
+import shlex
+import sys
+from pathlib import Path
+
+import typer
+
+from .analyzer import summarize_architecture, summarize_attack_surface
+from .defensive_review import render_defensive_review
+from .analyzers import (
+    TRUSTED_ONLY_ENV,
+    MissingAnalyzersError,
+    analyze_repository,
+    analyzer_install_command,
+    get_available_modules,
+    get_available_repository_modules,
+    get_analyzer_metadata,
+    install_analyzer_module,
+    resolve_run_analyzers,
+    select_requested_analyzers,
+)
+from .cve import query_vulnerabilities
+from .anomalies import route_auth_signals
+from .contracts import link_contracts
+from .crossrepo import (
+    find_cross_boundary_flows,
+    find_cross_repo_anomalies,
+    find_trust_gaps,
+)
+from .fleet import (
+    FleetRepoResult,
+    FleetScan,
+    fleet_repo_ids,
+    fleet_summary_json,
+    render_fleet_graph_mermaid,
+    render_fleet_summary,
+)
+from .diff import (
+    FindingSnapshot,
+    diff_findings,
+    load_baseline,
+    render_diff_markdown,
+)
+from .graph import build_graph
+from .hunt_harness import run_majority_verify
+from .llm_review import LlmReviewError, generate_llm_review
+from .review_prompts import HUNT_LENSES
+from .triage import render_triage_fallback
+from .progress import PROGRESS_PROTOCOL_VERSION, create_progress
+from .recon_to_analysis import translate_recon
+from . import __version__
+from .md import sanitize_llm_markdown
+from .safe_fs import UnsafePathError, ensure_output_dir, safe_write_text
+from .report import OUTPUT_FORMATS, render_console_summary, render_pr_comment, write_reports
+from .suggest import detect_ecosystems
+from .gitref import GitRefError
+from .suppress import apply_suppressions, collect_suppressions
+from .gitref import untrusted_output_markers
+from .safe_fs import set_untrusted_output_markers
+from .scanner import EXCLUDED_DIR_LIMITATION
+
+app = typer.Typer(help="AttackMap: understand your system and map your attack surface.")
+
+
+def _select_modules(module: list[str], install_missing: bool) -> list:
+    """Resolve `-m` names (#237). Only official, lock-pinned plugins can be
+    installed by name, and only with --install-missing or an interactive
+    confirmation; otherwise the exact pinned pip command is printed."""
+    try:
+        return select_requested_analyzers(module, auto_install=False)
+    except MissingAnalyzersError as exc:
+        commands = [shlex.join(analyzer_install_command(name)) for name in exc.missing]
+        interactive = sys.stdin.isatty() and sys.stderr.isatty()
+        if install_missing or (
+            interactive
+            and typer.confirm(
+                "Install missing official analyzer(s) at their pinned commits?\n  "
+                + "\n  ".join(commands),
+                default=False,
+                err=True,
+            )
+        ):
+            try:
+                return select_requested_analyzers(module, auto_install=True)
+            except ValueError as install_exc:
+                raise typer.BadParameter(str(install_exc)) from install_exc
+        raise typer.BadParameter(
+            f"{exc} Install with:\n  " + "\n  ".join(commands) + "\nor re-run with --install-missing."
+        ) from exc
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _warn_if_nothing_scanned(scan) -> None:  # type: ignore[no-untyped-def]
+    """A run that scanned nothing is almost always a setup problem — say so
+    instead of reporting a clean "limited attack surface" (#215)."""
+    if scan.files_scanned:
+        return
+    root = Path(scan.root)
+    try:
+        has_files = any(p.is_file() for p in root.iterdir())
+    except OSError:
+        has_files = False
+    if has_files or any(root.glob("*/*")):
+        typer.echo(
+            "Warning: no source files were scanned. Check the path, and whether every file "
+            "is under a skipped directory (node_modules, dist, build, out, target, …) or in an "
+            "unsupported language.",
+            err=True,
+        )
+
+
+def _distrust_pr_markers(repo_path: Path, ref: str | None, output_dir: Path) -> None:
+    """Under --suppress-from-ref, an `.attackmap-output` marker that is not at
+    the ref was added by the PR: it must not exclude its directory from the
+    scan (GHSA-j544-8x8g-c3mw). The run's own output directory is trusted."""
+    if ref is None:
+        set_untrusted_output_markers(())
+        return
+    untrusted = untrusted_output_markers(repo_path, ref, keep_under=[output_dir])
+    for rel in untrusted:
+        typer.echo(
+            f"Scan warning: output marker {rel.as_posix()} was added since {ref}; "
+            "its directory is scanned anyway",
+            err=True,
+        )
+    set_untrusted_output_markers(repo_path / rel for rel in untrusted)
+
+
+def _excluded_dirs(scan) -> list[str]:  # noqa: ANN001
+    return [
+        note[len(EXCLUDED_DIR_LIMITATION):]
+        for note in getattr(scan, "limitations", [])
+        if note.startswith(EXCLUDED_DIR_LIMITATION)
+    ]
+
+
+def _ensure_output_dir(path: Path, *, mark: bool = False) -> Path:
+    try:
+        return ensure_output_dir(path, mark=mark)
+    except UnsafePathError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2) from exc
+
+
+def _write_text(path: Path, text: str) -> None:
+    """Write a CLI artifact without following symlinks (#228)."""
+    path = Path(path)
+    try:
+        safe_write_text(ensure_output_dir(path.parent), path, text)
+    except UnsafePathError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2) from exc
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"attackmap {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the AttackMap version and exit.",
+    ),
+) -> None:
+    """AttackMap: understand your system and map your attack surface."""
+
+# Prepended to vulnerability-hypotheses.md (#80) so the framing is unmissable
+# even if a reader skips straight to the file: these are leads, not detections.
+HUNT_BANNER = (
+    "> ⚠️ **These are HYPOTHESES to confirm, not confirmed vulnerabilities.**\n"
+    "> Generated by an LLM reasoning over AttackMap's static evidence as a red-team\n"
+    "> analyst. Each hypothesis cites the evidence it rests on and lists what a human\n"
+    "> must verify. Treat every item as a lead requiring code review before action —\n"
+    "> no CVE assignment, no exploitation instructions.\n\n"
+)
+
+# Prepended to remediation.md (#106): suggestions are review-first, not
+# auto-applied.
+REMEDIATION_BANNER = (
+    "> 🛠️ **Suggested fixes to review, not auto-applied.**\n"
+    "> LLM-proposed remediations grounded in AttackMap's static evidence. Each is\n"
+    "> the smallest change to remove a weakness class; review the diff, confirm the\n"
+    "> intent (e.g. whether a route should require auth), and run the verification\n"
+    "> step before applying. No exploit code.\n\n"
+)
+
+# Prepended to triage.md (#145): a prioritized view of the EXISTING findings,
+# not new discoveries.
+TRIAGE_BANNER = (
+    "> 🗂️ **Prioritized shortlist of existing findings — not new discoveries.**\n"
+    "> Triage clusters, de-duplicates, and ranks the heuristic findings AttackMap\n"
+    "> already produced so you can work them top-down. Each item cites a real\n"
+    "> finding id; no new findings are invented here.\n\n"
+)
+
+
+PROGRESS_FORMATS = ("auto", "tty", "json", "none")
+LLM_PROVIDERS = ("claude", "openai")
+LLM_SPEEDS = ("standard", "fast")
+LLM_EFFORTS = ("low", "medium", "high", "xhigh", "max")
+LLM_BACKENDS = ("auto", "api", "cli")
+
+
+def _given(ctx: typer.Context, name: str) -> bool:
+    """True when the user passed the option (not just its default)."""
+    source = ctx.get_parameter_source(name)
+    return source is not None and source.name not in {"DEFAULT", "DEFAULT_MAP"}
+
+
+def _validate_analyze_options(
+    ctx: typer.Context,
+    *,
+    progress_format: str,
+    output_format: str,
+    llm_provider: str,
+    llm_speed: str,
+    llm_effort: str | None,
+    llm_backend: str,
+    hunt: bool,
+    verify: bool,
+    verify_votes: int,
+    hunt_lenses: int,
+    hunt_rounds: int,
+    hunt_budget: int,
+    baseline: str | None,
+    diff_output: str | None,
+    secrets_history: int = 0,
+) -> None:
+    """Reject bad values and orphaned flags before any scanning starts (#229).
+
+    A typo in an LLM option used to surface only after the full scan, CVE
+    lookup and report writing; flags whose parent option was missing were
+    silently ignored with exit 0.
+    """
+
+    def _choice(flag: str, value: str | None, allowed: tuple[str, ...]) -> None:
+        if value is not None and value not in allowed:
+            raise typer.BadParameter(f"{flag} must be one of: {', '.join(allowed)} (got {value!r}).")
+
+    _choice("--progress-format", progress_format, PROGRESS_FORMATS)
+    _choice("--format", output_format, tuple(OUTPUT_FORMATS))
+    _choice("--llm-provider", llm_provider, LLM_PROVIDERS)
+    _choice("--llm-speed", llm_speed, LLM_SPEEDS)
+    _choice("--llm-effort", llm_effort, LLM_EFFORTS)
+    _choice("--llm-backend", llm_backend, LLM_BACKENDS)
+
+    hunt_only = ("verify", "verify_votes", "hunt_lenses", "hunt_rounds", "hunt_budget")
+    orphaned = [f"--{name.replace('_', '-')}" for name in hunt_only if _given(ctx, name)]
+    if orphaned and not hunt:
+        verb = "only applies" if len(orphaned) == 1 else "only apply"
+        raise typer.BadParameter(f"{', '.join(orphaned)} {verb} with --hunt.")
+    if _given(ctx, "diff_output") and diff_output is not None and baseline is None:
+        raise typer.BadParameter("--diff-output requires --baseline to be set.")
+
+    if not 0 <= secrets_history <= 5000:
+        raise typer.BadParameter(f"--secrets-history must be between 0 (off) and 5000 commits (got {secrets_history}).")
+    if verify_votes < 1:
+        raise typer.BadParameter(f"--verify-votes must be at least 1 (got {verify_votes}).")
+    if not 1 <= hunt_lenses <= len(HUNT_LENSES):
+        raise typer.BadParameter(f"--hunt-lenses must be between 1 and {len(HUNT_LENSES)} (got {hunt_lenses}).")
+    if hunt_rounds < 1:
+        raise typer.BadParameter(f"--hunt-rounds must be at least 1 (got {hunt_rounds}).")
+    if hunt_budget < 0:
+        raise typer.BadParameter(f"--hunt-budget must be 0 (no cap) or more (got {hunt_budget}).")
+
+
+def _echo_opt_in_hint(names: list[str]) -> None:
+    """Opt-in analyzers (enabled_by_default=False) that matched but didn't run
+    (#221), so their absence is visible rather than silent."""
+    if names:
+        typer.echo(
+            f"Opt-in analyzers match this repo but were not run: {', '.join(names)}. "
+            f"Enable with {' '.join(f'-m {n}' for n in names)}.",
+            err=True,
+        )
+
+
+def _run_fleet(
+    repo_paths: list[Path],
+    *,
+    output: str,
+    module: list[str] | None,
+    recall: bool,
+    cve: bool,
+    no_suppress: bool,
+    suppress_file: str | None,
+    progress_format: str,
+    no_progress: bool,
+    fleet_incompatible: dict[str, bool],
+    output_format: str = "all",
+    install_missing: bool = False,
+    suppress_from_ref: str | None = None,
+    strict_analyzers: bool = False,
+) -> None:
+    """Multi-repo fleet scan (#146a). Scans each repo independently — reusing the
+    same building blocks a single-repo run uses — writes per-repo reports into
+    ``output/<repo_id>/``, and assembles a fleet summary. No cross-repo detection
+    yet (that is #146b–#146d); this is the foundation."""
+    active_flags = [flag for flag, on in fleet_incompatible.items() if on]
+    if active_flags:
+        raise typer.BadParameter(
+            f"{', '.join(sorted(active_flags))} not yet supported in multi-repo mode — "
+            "run one repository at a time for these (fleet-aware wiring lands in #146b+)."
+        )
+
+    selected_analyzers = None
+    if module:
+        selected_analyzers = _select_modules(module, install_missing)
+
+    output_root = Path(output)
+    repo_ids = fleet_repo_ids(repo_paths)
+    fleet = FleetScan()
+
+    for repo_id, repo_path in zip(repo_ids, repo_paths):
+        typer.echo("")
+        typer.echo(f"── {repo_id}  ({repo_path}) ──")
+        try:
+            opt_in_matches: list[str] = []
+            active_analyzers = resolve_run_analyzers(
+                repo_path, analyzers=selected_analyzers, opt_in_matches=opt_in_matches
+            )
+            _echo_opt_in_hint(opt_in_matches)
+            scan_progress = create_progress(progress_format, no_progress=no_progress)
+            _distrust_pr_markers(repo_path, suppress_from_ref, output_root)
+            scan = analyze_repository(
+                repo_path,
+                analyzers=active_analyzers,
+                progress=scan_progress,
+                recall=recall,
+                strict=strict_analyzers,
+            )
+            if cve and scan.dependencies:
+                try:
+                    vulns, _cve_summary = query_vulnerabilities(
+                        scan.dependencies, progress=scan_progress
+                    )
+                finally:
+                    scan_progress.done()
+                scan.vulnerabilities = vulns
+
+            graph = build_graph(scan)
+            analysis = translate_recon(scan)
+            attack_surfaces = analysis.attack_surfaces
+            findings = analysis.findings
+            attack_paths = analysis.attack_paths
+            architecture_md = summarize_architecture(scan, graph)
+            attack_surface_md = summarize_attack_surface(scan, attack_surfaces)
+
+            suppressed_findings: list = []
+            if not no_suppress:
+                explicit = Path(suppress_file) if suppress_file else None
+                if explicit is not None and not explicit.exists():
+                    raise typer.BadParameter(f"Suppress file not found: {explicit}")
+                try:
+                    suppset, sup_warnings = collect_suppressions(
+                        repo_path, findings, explicit_file=explicit, trusted_ref=suppress_from_ref
+                    )
+                except GitRefError as exc:
+                    raise typer.BadParameter(str(exc)) from exc
+                for warning in sup_warnings:
+                    typer.echo(f"Suppression warning: {warning}", err=True)
+                outcome = apply_suppressions(findings, suppset)
+                for notice in outcome.notices:
+                    typer.echo(f"Suppression warning: {notice}", err=True)
+                findings = outcome.active
+                suppressed_findings = outcome.suppressed
+
+            defensive_review_md = render_defensive_review(scan, attack_surfaces, findings, attack_paths)
+            repo_out = output_root / repo_id
+            try:
+                write_reports(
+                    repo_out,
+                    scan,
+                    architecture_md,
+                    attack_surface_md,
+                    defensive_review_md,
+                    attack_surfaces,
+                    findings,
+                    attack_paths,
+                    analyzer_metadata=[
+                        {
+                            "name": metadata.name,
+                            "description": metadata.description,
+                            "scope": metadata.scope,
+                            "ecosystems": list(metadata.ecosystems),
+                        }
+                        for metadata in (get_analyzer_metadata(a) for a in active_analyzers)
+                    ],
+                    suppressed=suppressed_findings,
+                    output_format=output_format,
+                )
+            except UnsafePathError as exc:
+                typer.echo(f"Error: {exc}", err=True)
+                raise typer.Exit(2) from exc
+            typer.echo(render_console_summary(scan, findings, attack_paths))
+            _warn_if_nothing_scanned(scan)
+            fleet.results.append(
+                FleetRepoResult(
+                    repo_id=repo_id,
+                    root=str(repo_path),
+                    report_dir=str(repo_out.resolve()),
+                    scan=scan,
+                    findings=findings,
+                    attack_paths=attack_paths,
+                    suppressed_count=len(suppressed_findings),
+                )
+            )
+        except (typer.Exit, typer.Abort, typer.BadParameter):
+            raise  # usage / configuration errors stop the whole run
+        except Exception as exc:  # noqa: BLE001 — one bad repo must not sink the fleet (#217)
+            message = f"{type(exc).__name__}: {exc}"
+            typer.echo(f"Error: {repo_id} failed and was skipped — {message}", err=True)
+            fleet.failed.append({"repo_id": repo_id, "root": str(repo_path), "error": message})
+
+    # Cross-repo contract linking (#146b): match one repo's outbound calls to
+    # another repo's routes, over the assembled fleet.
+    repo_scans = [(r.repo_id, r.scan) for r in fleet.results]
+    fleet.links = link_contracts(repo_scans)
+    # Cross-boundary trust flows (#146c): confused-deputy leads over the links.
+    fleet.cross_boundary = find_cross_boundary_flows(fleet.links, repo_scans)
+    # Trust-assumption gaps + cross-repo anomalies (#146d / #149b). Per-route auth
+    # signals are resolved per repo (each with its own root).
+    auth_by_repo = {r.repo_id: route_auth_signals(r.scan, r.root) for r in fleet.results}
+    fleet.trust_gaps = find_trust_gaps(fleet.links, repo_scans, auth_by_repo)
+    fleet.cross_repo_anomalies = find_cross_repo_anomalies(repo_scans, auth_by_repo)
+
+    _ensure_output_dir(output_root, mark=True)
+    emit_markdown = output_format in {"all", "markdown"}
+    if emit_markdown:
+        _write_text(output_root / "fleet-summary.md", render_fleet_summary(fleet) + "\n")
+        _write_text(output_root / "fleet-graph.md", render_fleet_graph_mermaid(fleet) + "\n")
+    if output_format in {"all", "json"}:
+        _write_text(
+            output_root / "fleet-summary.json",
+            json.dumps(fleet_summary_json(fleet), indent=2) + "\n",
+        )
+    summary_name = "fleet-summary.md" if emit_markdown else "fleet-summary.json"
+    typer.echo("")
+    typer.echo(
+        f"Fleet: {fleet.repo_count} repositories, {fleet.total_findings()} finding(s), "
+        f"{len(fleet.links)} cross-repo link(s), "
+        f"{len(fleet.cross_boundary)} cross-boundary + {len(fleet.trust_gaps)} trust-gap + "
+        f"{len(fleet.cross_repo_anomalies)} anomaly (all speculative). "
+        f"Summary written to: {(output_root / summary_name).resolve()}"
+    )
+    if fleet.failed:
+        typer.echo(f"{len(fleet.failed)} repository scan(s) failed: "
+                   f"{', '.join(f['repo_id'] for f in fleet.failed)}", err=True)
+        raise typer.Exit(1)
+
+
+@app.command()
+def analyze(
+    ctx: typer.Context,
+    paths: list[str] | None = typer.Argument(
+        None,
+        help="Path(s) to the repository(ies) to analyze. Pass two or more for a "
+        "cross-repo fleet scan (#146a): each is scanned into its own report "
+        "subdirectory and a fleet summary is written alongside. Defaults to '.'.",
+    ),
+    output: str = typer.Option("reports", "--output", "-o", help="Directory for generated reports."),
+    format: str = typer.Option(
+        "all",
+        "--format",
+        help="Which report artifacts to write: 'all' (default), 'json' (machine-readable "
+        "*.json + SARIF), or 'markdown' (human-readable *.md + Graphviz *.dot). Opt-in "
+        "outputs (--baseline diff, --pr-comment, LLM passes) are always written.",
+    ),
+    module: list[str] | None = typer.Option(
+        None,
+        "--module",
+        "-m",
+        help="Analyzer module(s) to run. Repeat to select multiple. A missing official analyzer is installed (at its pinned commit) only with --install-missing or after an interactive confirmation.",
+    ),
+    install_missing: bool = typer.Option(
+        False,
+        "--install-missing",
+        help="Install missing official analyzers named by --module, pinned to the commits in attackmap's plugin lock.",
+    ),
+    trusted_analyzers_only: bool = typer.Option(
+        False,
+        "--trusted-analyzers-only",
+        help=f"Load only official AttackMap analyzer plugins; skip any other installed package that registers one (also via {TRUSTED_ONLY_ENV}=1).",
+    ),
+    llm: bool = typer.Option(
+        False,
+        "--llm",
+        help="Generate a narrative defensive review by calling Claude with the evidence pack. Auth resolves automatically: ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN → `claude` CLI (subscription auth). Force a backend with --llm-backend.",
+    ),
+    llm_provider: str = typer.Option(
+        "claude",
+        "--llm-provider",
+        help="LLM provider for --llm/--hunt/--remediate: 'claude' (default, Anthropic) or 'openai' (OpenAI/Codex).",
+    ),
+    llm_model: str | None = typer.Option(
+        None,
+        "--llm-model",
+        help="Model ID for --llm. Claude provider: e.g. claude-opus-4-8 (default), claude-fable-5, claude-sonnet-5, claude-opus-4-7. OpenAI provider: e.g. gpt-5-codex (default), gpt-5.5, gpt-5.4, gpt-5.4-mini — any model ID is passed through verbatim.",
+    ),
+    llm_effort: str | None = typer.Option(
+        None,
+        "--llm-effort",
+        help="Effort for --llm: low|medium|high|xhigh|max. Defaults to high. For OpenAI, xhigh/max clamp to high (Responses API reasoning effort tops out at high).",
+    ),
+    llm_backend: str = typer.Option(
+        "auto",
+        "--llm-backend",
+        help="Which backend --llm uses. Claude: 'auto' tries ANTHROPIC_API_KEY → ANTHROPIC_AUTH_TOKEN → `claude` CLI; 'api' forces the SDK; 'cli' forces the `claude` CLI. OpenAI: 'auto' tries OPENAI_API_KEY then the `codex` CLI; 'api' forces the OpenAI SDK; 'cli' forces `codex exec` (your `codex login` subscription).",
+    ),
+    llm_speed: str = typer.Option(
+        "standard",
+        "--llm-speed",
+        help="LLM output speed: 'standard' (default) or 'fast'. Fast mode (~2.5x output speed, premium price) applies only to Opus 4.8/4.7 via the API backend; other models/backends fall back to standard.",
+    ),
+    hunt: bool = typer.Option(
+        False,
+        "--hunt",
+        help="Vulnerability-hypothesis mode (#80): have Claude reason over the full evidence pack as a red-team analyst and propose ranked, human-verifiable exploit-chain HYPOTHESES (leads, not detections) to vulnerability-hypotheses.md. Uses the same LLM auth/backend as --llm.",
+    ),
+    verify: bool = typer.Option(
+        False,
+        "--verify",
+        help="With --hunt: adjudicate each hypothesis against the actual source at cited locations — CONFIRMED / REFUTED / NEEDS HUMAN REVIEW (#hunt-verify). AttackMap feeds the code excerpts to the model.",
+    ),
+    verify_votes: int = typer.Option(
+        3,
+        "--verify-votes",
+        help="With --hunt --verify: number of independent skeptic passes to adjudicate each hypothesis. A lead is CONFIRMED only on a strict majority (NEEDS_REVIEW only if a majority flags the evidence insufficient); ties/uncertainty are REFUTED (#147a). 1 = the classic single-pass verify.",
+    ),
+    hunt_lenses: int = typer.Option(
+        1,
+        "--hunt-lenses",
+        help="With --hunt --verify: run N independent generation passes, each specialised in a distinct failure mode (auth-bypass, TOCTOU, IDOR, deserialization, SSRF, secret-misuse), then dedupe across them before verifying (#147b). 1 = a single generalist pass. Costs one extra LLM call per lens.",
+    ),
+    hunt_rounds: int = typer.Option(
+        1,
+        "--hunt-rounds",
+        help="With --hunt --verify: loop generation for up to N rounds, accumulating new (deduped) leads while a completeness critic seeds each next round with untried angles; stops early once a round finds nothing new (#147c). 1 = a single round.",
+    ),
+    hunt_budget: int = typer.Option(
+        0,
+        "--hunt-budget",
+        help="With --hunt-rounds: stop launching new hunting rounds once this many output tokens have been spent (0 = no budget cap). A guardrail on multi-round cost.",
+    ),
+    remediate: bool = typer.Option(
+        False,
+        "--remediate",
+        help="Remediation mode (#106): have Claude propose concrete, review-first fixes per finding (suggested diffs / precise instructions, grounded in evidence) to remediation.md. Uses the same LLM auth/backend as --llm.",
+    ),
+    triage: bool = typer.Option(
+        False,
+        "--triage",
+        help="Triage mode (#145): cluster, de-duplicate, and rank the EXISTING heuristic findings into a prioritized shortlist (citing real finding IDs) at triage.md. LLM-backed when available; degrades to a deterministic score-ordered fallback when no backend is present.",
+    ),
+    recall: bool = typer.Option(
+        False,
+        "--recall",
+        help="Recall mode (#148a): widen taint discovery — deeper import-hop depth and surfacing reaches the default pass conservatively hides. The extra reach is marked SPECULATIVE and kept out of --fail-on-new-high; pair with --hunt --verify to adjudicate it. Off by default (higher recall, lower precision).",
+    ),
+    baseline: str | None = typer.Option(
+        None,
+        "--baseline",
+        help="Path to a prior `attackmap-report.json`. When set, emit a diff (new/persisted/resolved) alongside the fresh report.",
+    ),
+    diff_output: str | None = typer.Option(
+        None,
+        "--diff-output",
+        help="Path to write the Markdown diff. Defaults to <output>/attackmap-diff.md when --baseline is set.",
+    ),
+    fail_on_new_high: bool = typer.Option(
+        False,
+        "--fail-on-new-high",
+        help="Exit non-zero if the diff introduces any new HIGH-severity findings. Requires --baseline.",
+    ),
+    suppress_from_ref: str | None = typer.Option(
+        None,
+        "--suppress-from-ref",
+        help="Trust only suppressions that exist at this git ref (e.g. the PR's base branch). Suppress-file entries and inline directives added since are reported as pending and not applied.",
+    ),
+    allow_pr_suppressions: bool = typer.Option(
+        False,
+        "--allow-pr-suppressions",
+        help="With --suppress-from-ref, apply suppressions added since the ref anyway (they are still listed).",
+    ),
+    strict_suppressions: bool = typer.Option(
+        False,
+        "--strict-suppressions",
+        help="Exit 2 if any suppression has expired (past its `expires:` / `until=` date).",
+    ),
+    strict_analyzers: bool = typer.Option(
+        False,
+        "--strict-analyzers",
+        help="Fail fast if any analyzer raises or returns an invalid result, instead of skipping it and listing it under analyzer_errors (for plugin development and CI).",
+    ),
+    fail_on_new_suppression: bool = typer.Option(
+        False,
+        "--fail-on-new-suppression",
+        help="Exit non-zero if a finding active in the baseline is suppressed in this run (e.g. a suppression added by the PR), or excluded from it by an .attackmap-output marker. Requires --baseline.",
+    ),
+    secrets_history: int = typer.Option(
+        0,
+        "--secrets-history",
+        help="Also scan the patches of the last N commits (all refs) for hard-coded secrets, reporting the introducing commit and whether each is still in HEAD. Off by default (0); capped at 5000 commits and 64 MB of patch text. Git runs with hooks, pagers, external diff and textconv disabled.",
+    ),
+    cve: bool = typer.Option(
+        False,
+        "--cve",
+        help="Cross-reference SBOM entries against OSV.dev and surface vulnerable dependencies as findings. Cached under ~/.attackmap/cache/osv/ (24h TTL). Off by default because it does network I/O.",
+    ),
+    no_progress: bool = typer.Option(
+        False,
+        "--no-progress",
+        help="Disable the live progress bar / ETA during scanning. Progress auto-disables when stderr isn't a terminal (CI, piped output).",
+    ),
+    progress_format: str = typer.Option(
+        "auto",
+        "--progress-format",
+        help="Progress reporting: 'auto' (TTY bar when stderr is a terminal), 'tty' (always the bar), 'json' (newline-delimited JSON events on stderr, for GUI/tool front-ends), or 'none'. --no-progress is equivalent to 'none'.",
+    ),
+    pr_comment: str | None = typer.Option(
+        None,
+        "--pr-comment",
+        help="Write a Markdown PR summary comment to this path (for the GitHub Action / bot to post). Includes the baseline diff and top exploitability when available.",
+    ),
+    no_suppress: bool = typer.Option(
+        False,
+        "--no-suppress",
+        help="Ignore all suppressions — the .attackmap-suppress.yaml baseline and inline `attackmap:ignore` directives (#144). Use for a full, unfiltered audit.",
+    ),
+    suppress_file: str | None = typer.Option(
+        None,
+        "--suppress-file",
+        help="Path to a suppression baseline, overriding auto-discovery of .attackmap-suppress.yaml at the repo root (#144).",
+    ),
+) -> None:
+    repo_paths = [Path(p).resolve() for p in (paths or ["."])]
+    for rp in repo_paths:
+        if not rp.exists():
+            raise typer.BadParameter(f"Path does not exist: {rp}")
+
+    # Validate progress format before either branch, so the fleet path enforces
+    # the same option semantics as a single-repo run (#146a).
+    if trusted_analyzers_only and os.environ.get(TRUSTED_ONLY_ENV) != "1":
+        previous = os.environ.get(TRUSTED_ONLY_ENV)
+        os.environ[TRUSTED_ONLY_ENV] = "1"
+
+        def _restore_trust_env() -> None:
+            if previous is None:
+                os.environ.pop(TRUSTED_ONLY_ENV, None)
+            else:
+                os.environ[TRUSTED_ONLY_ENV] = previous
+
+        ctx.call_on_close(_restore_trust_env)
+    _validate_analyze_options(
+        ctx,
+        progress_format=progress_format,
+        output_format=format,
+        llm_provider=llm_provider,
+        llm_speed=llm_speed,
+        llm_effort=llm_effort,
+        llm_backend=llm_backend,
+        hunt=hunt,
+        verify=verify,
+        verify_votes=verify_votes,
+        hunt_lenses=hunt_lenses,
+        hunt_rounds=hunt_rounds,
+        hunt_budget=hunt_budget,
+        baseline=baseline,
+        diff_output=diff_output,
+        secrets_history=secrets_history,
+    )
+
+    # Multi-repo fleet mode (#146a): scan each repo independently and assemble a
+    # fleet view. Dispatched here so the single-repo path below is untouched.
+    if len(repo_paths) > 1:
+        _run_fleet(
+            repo_paths,
+            output=output,
+            module=module,
+            recall=recall,
+            cve=cve,
+            no_suppress=no_suppress,
+            suppress_file=suppress_file,
+            progress_format=progress_format,
+            no_progress=no_progress,
+            output_format=format,
+            install_missing=install_missing,
+            suppress_from_ref=suppress_from_ref,
+            strict_analyzers=strict_analyzers,
+            # Single-repo-only features aren't fleet-aware yet — reject rather
+            # than silently ignore, so the user isn't surprised (#146b+ wire them).
+            fleet_incompatible={
+                "--baseline": baseline is not None,
+                "--diff-output": diff_output is not None,
+                "--fail-on-new-high": fail_on_new_high,
+                "--fail-on-new-suppression": fail_on_new_suppression,
+                "--pr-comment": pr_comment is not None,
+                "--llm": llm,
+                "--hunt": hunt,
+                "--remediate": remediate,
+                "--triage": triage,
+                "--secrets-history": secrets_history > 0,
+            },
+        )
+        return
+
+    repo_path = repo_paths[0]
+    # Validate diff-mode flag combinations before doing any real work.
+    if fail_on_new_high and baseline is None:
+        raise typer.BadParameter("--fail-on-new-high requires --baseline to be set.")
+    if fail_on_new_suppression and baseline is None:
+        raise typer.BadParameter("--fail-on-new-suppression requires --baseline to be set.")
+    if baseline is not None:
+        baseline_path = Path(baseline)
+        if not baseline_path.exists():
+            raise typer.BadParameter(f"Baseline report not found: {baseline_path}")
+
+    selected_analyzers = None
+    if module:
+        selected_analyzers = _select_modules(module, install_missing)
+
+    # (Enum/range/dependency options are validated up front, #229.)
+    # Provider-aware label for the "via X" progress/echo strings.
+    llm_display = "Codex" if llm_provider == "openai" else "Claude"
+    if llm_provider == "openai" and llm_speed == "fast" and (llm or hunt or remediate):
+        typer.echo(
+            "Note: --llm-speed fast is Claude-only; ignoring it for the OpenAI provider.",
+            err=True,
+        )
+    opt_in_matches: list[str] = []
+    active_analyzers = resolve_run_analyzers(
+        repo_path, analyzers=selected_analyzers, opt_in_matches=opt_in_matches
+    )
+    _echo_opt_in_hint(opt_in_matches)
+    scan_progress = create_progress(progress_format, no_progress=no_progress)
+    _distrust_pr_markers(repo_path, suppress_from_ref, Path(output))
+    scan = analyze_repository(
+        repo_path,
+        analyzers=active_analyzers,
+        progress=scan_progress,
+        recall=recall,
+        strict=strict_analyzers,
+    )
+    if recall:
+        speculative = sum(1 for c in scan.taint_chains if c.speculative)
+        typer.echo(
+            f"Recall mode: widened taint discovery, {speculative} speculative "
+            "chain(s) surfaced (marked low-confidence; adjudicate with --hunt --verify)."
+        )
+    if secrets_history:
+        from .secrets_history import scan_secret_history
+
+        typer.echo(f"Scanning the last {secrets_history} commit(s) for secrets in git history…")
+        history_hits, history_notes = scan_secret_history(repo_path, secrets_history)
+        scan.secret_history = history_hits
+        scan.limitations.extend(history_notes)
+        removed = sum(1 for h in history_hits if not h.still_in_head)
+        typer.echo(
+            f"Secrets in history: {len(history_hits)} found, {removed} no longer in HEAD."
+        )
+    if cve and scan.dependencies:
+        typer.echo(f"Checking {len(scan.dependencies)} dependencies against OSV.dev…")
+        # query_vulnerabilities drives a determinate begin/advance bar itself
+        # (per unique package), so big lockfile trees show real progress + ETA
+        # instead of an indeterminate spinner.
+        try:
+            vulns, cve_summary = query_vulnerabilities(
+                scan.dependencies, progress=scan_progress
+            )
+        finally:
+            scan_progress.done()
+        scan.vulnerabilities = vulns
+        typer.echo(
+            f"CVE lookup: {len(vulns)} vulnerabilit"
+            f"{'y' if len(vulns) == 1 else 'ies'} across "
+            f"{cve_summary.queried} query(s), {cve_summary.cached} cache hit(s), "
+            f"{cve_summary.skipped_no_version} skipped (no queryable version), "
+            f"{cve_summary.network_errors} network error(s)."
+        )
+        if cve_summary.inventory_only:
+            listed = ", ".join(f"{n} {eco}" for eco, n in sorted(cve_summary.inventory_only.items()))
+            typer.echo(
+                f"Not CVE-checked (no OSV.dev database for the ecosystem; inventory only): {listed}."
+            )
+    graph = build_graph(scan)
+    analysis = translate_recon(scan)
+    attack_surfaces = analysis.attack_surfaces
+    architecture_md = summarize_architecture(scan, graph)
+    attack_surface_md = summarize_attack_surface(scan, attack_surfaces)
+    findings = analysis.findings
+    attack_paths = analysis.attack_paths
+
+    # Finding suppression (#144): the .attackmap-suppress.yaml baseline plus
+    # inline `attackmap:ignore` directives. Suppressed findings are partitioned
+    # out of the active set used for the review, console, and the diff gate —
+    # but retained (with reasons) in report.json and marked suppressed in SARIF.
+    suppressed_findings: list = []
+    suppression_governance: dict | None = None
+    if no_suppress:
+        if suppress_file is not None:
+            typer.echo("Note: --suppress-file is ignored because --no-suppress is set.", err=True)
+    else:
+        explicit = Path(suppress_file) if suppress_file else None
+        if explicit is not None and not explicit.exists():
+            raise typer.BadParameter(f"Suppress file not found: {explicit}")
+        try:
+            suppset, sup_warnings = collect_suppressions(
+                repo_path,
+                findings,
+                explicit_file=explicit,
+                trusted_ref=suppress_from_ref,
+                allow_pr_suppressions=allow_pr_suppressions,
+            )
+        except GitRefError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+        for warning in sup_warnings:
+            typer.echo(f"Suppression warning: {warning}", err=True)
+        outcome = apply_suppressions(findings, suppset)
+        for notice in outcome.notices:
+            typer.echo(f"Suppression warning: {notice}", err=True)
+        findings = outcome.active
+        suppressed_findings = outcome.suppressed
+        suppression_governance = {
+            "pending": [f"{sup.label()} — {sup.reason} ({sup.source})" for sup in suppset.pending],
+            "pending_applied": suppset.pending_applied,
+            "trusted_ref": suppress_from_ref,
+            "by_rule": dict(Counter(s.rule for s in suppressed_findings)),
+        }
+        if suppset.pending:
+            verb = "applied anyway (--allow-pr-suppressions)" if suppset.pending_applied else "NOT applied"
+            typer.echo(
+                f"{len(suppset.pending)} suppression(s) added since {suppress_from_ref} — {verb}:", err=True
+            )
+            for line in suppression_governance["pending"]:
+                typer.echo(f"  - {line}", err=True)
+        if strict_suppressions and suppset.expired:
+            typer.echo(
+                f"Error: {len(suppset.expired)} expired suppression(s) (--strict-suppressions).", err=True
+            )
+            raise typer.Exit(2)
+        if suppressed_findings:
+            typer.echo("")
+            typer.echo(f"Suppressed {len(suppressed_findings)} finding(s) (#144):")
+            for summary_line in outcome.summary_lines():
+                typer.echo(summary_line)
+
+    defensive_review_md = render_defensive_review(scan, attack_surfaces, findings, attack_paths)
+
+    try:
+        write_reports(
+            output,
+            scan,
+            architecture_md,
+            attack_surface_md,
+            defensive_review_md,
+            attack_surfaces,
+            findings,
+            attack_paths,
+            analyzer_metadata=[
+                {
+                    "name": metadata.name,
+                    "description": metadata.description,
+                    "scope": metadata.scope,
+                    "ecosystems": list(metadata.ecosystems),
+                }
+                for metadata in (get_analyzer_metadata(analyzer) for analyzer in active_analyzers)
+            ],
+            suppressed=suppressed_findings,
+            output_format=format,
+        )
+    except UnsafePathError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    typer.echo(render_console_summary(scan, findings, attack_paths))
+    _warn_if_nothing_scanned(scan)
+    typer.echo("")
+    typer.echo(f"Reports written to: {Path(output).resolve()}")
+
+    diff_exit_code = 0
+    diff = None
+    if baseline is not None:
+        baseline_path = Path(baseline)
+        try:
+            baseline_snapshots = load_baseline(baseline_path)
+        except (OSError, ValueError) as exc:
+            raise typer.BadParameter(f"Failed to read baseline: {exc}") from exc
+        current_snapshots = [FindingSnapshot.from_finding(f) for f in findings]
+        diff = diff_findings(
+            baseline_snapshots,
+            current_snapshots,
+            suppressed=[FindingSnapshot.from_finding(s.finding) for s in suppressed_findings],
+            excluded_dirs=_excluded_dirs(scan),
+        )
+        counts = diff.counts()
+        typer.echo("")
+        typer.echo(
+            f"Diff vs baseline: {counts['new']} new, "
+            f"{counts['new_instances']} new instance(s) of existing findings, "
+            f"{counts['persisted']} persisted, {counts['resolved']} resolved, "
+            f"{counts['newly_suppressed']} newly suppressed"
+            + (f", {counts['newly_excluded']} newly excluded from the scan." if diff.newly_excluded else ".")
+        )
+        if diff.baseline_without_instances:
+            typer.echo(
+                "Note: the baseline predates per-instance fingerprints (attackmap < 0.4.32); "
+                "new instances of existing findings can't be detected until it is regenerated.",
+                err=True,
+            )
+        diff_path = Path(diff_output) if diff_output else Path(output) / "attackmap-diff.md"
+        _write_text(diff_path, render_diff_markdown(diff))
+        typer.echo(f"Diff written to: {diff_path.resolve()}")
+        if fail_on_new_high and diff.has_new_high:
+            new_high_titles = [s.title for s in diff.new if s.severity == "high"] + [
+                f"{s.title} (new instance(s): {', '.join(labels[:5])})"
+                for s, labels in diff.new_instances
+                if s.severity == "high"
+            ]
+            typer.echo("", err=True)
+            typer.echo(
+                "New HIGH findings introduced (failing per --fail-on-new-high):",
+                err=True,
+            )
+            for t in new_high_titles:
+                typer.echo(f"  - {t}", err=True)
+            diff_exit_code = 1
+        if fail_on_new_suppression and diff.newly_suppressed:
+            typer.echo("", err=True)
+            typer.echo(
+                "Findings newly suppressed by this change (failing per --fail-on-new-suppression):",
+                err=True,
+            )
+            for s_ in diff.newly_suppressed:
+                typer.echo(f"  - [{s_.severity.upper()}] {s_.title}", err=True)
+            diff_exit_code = 1
+        if fail_on_new_suppression and diff.newly_excluded:
+            typer.echo("", err=True)
+            typer.echo(
+                "Findings newly excluded from the scan by an output marker "
+                "(failing per --fail-on-new-suppression):",
+                err=True,
+            )
+            for s_ in diff.newly_excluded:
+                typer.echo(f"  - [{s_.severity.upper()}] {s_.title}", err=True)
+            diff_exit_code = 1
+
+    if pr_comment is not None:
+        pr_path = Path(pr_comment)
+        _write_text(pr_path, render_pr_comment(findings, diff, suppressions=suppression_governance))
+        typer.echo(f"PR comment written to: {pr_path.resolve()}")
+
+    if llm:
+        try:
+            effort_value = llm_effort  # validated up front (#229)
+
+            typer.echo("")
+            typer.echo(
+                f"Generating narrative review via {llm_display} (backend={llm_backend}, may take a minute)..."
+            )
+            scan_progress.stage(
+                f"{llm_display} is writing the defensive review (backend={llm_backend})"
+            )
+            try:
+                result = generate_llm_review(
+                    scan,
+                    attack_surfaces,
+                    findings,
+                    attack_paths,
+                    model=llm_model,
+                    effort=effort_value,  # type: ignore[arg-type]
+                    backend=llm_backend,  # type: ignore[arg-type]
+                    speed=llm_speed,  # type: ignore[arg-type]
+                    provider=llm_provider,  # type: ignore[arg-type]
+                )
+            finally:
+                scan_progress.done()
+        except LlmReviewError as exc:
+            typer.echo(f"LLM review skipped: {exc}", err=True)
+        else:
+            output_path = Path(output)
+            llm_md_path = output_path / "defensive-review-llm.md"
+            _write_text(llm_md_path, sanitize_llm_markdown(result.markdown) + "\n")
+            llm_meta_path = output_path / "defensive-review-llm.meta.json"
+            _write_text(
+                llm_meta_path,
+                json.dumps(
+                    {
+                        "backend": result.backend,
+                        "model": result.model,
+                        "stop_reason": result.stop_reason,
+                        "usage": result.usage,
+                    },
+                    indent=2,
+                )
+                + "\n",
+            )
+            typer.echo(f"LLM review written to: {llm_md_path.resolve()} (backend={result.backend})")
+
+    if hunt:
+        hunt_effort_value = llm_effort  # validated up front (#229)
+        typer.echo("")
+        # Multi-pass hunt harness (#147a/#147b): opt in with --verify and either
+        # --verify-votes > 1 (jury) or --hunt-lenses > 1 (multi-lens generation).
+        # Ranges are validated up front (#229); no silent clamping.
+        lens_count = hunt_lenses
+        jury_votes = verify_votes
+        max_rounds = hunt_rounds
+        token_budget = hunt_budget if hunt_budget > 0 else None
+        use_jury = verify and (jury_votes > 1 or lens_count > 1 or max_rounds > 1)
+        lens_names = [name for name, _ in HUNT_LENSES][:lens_count] if lens_count > 1 else None
+
+        def _hunt_llm_call(mode: str, hypotheses=None, lens=None, avoid_titles=None, critic_hint=None):
+            return generate_llm_review(
+                scan,
+                attack_surfaces,
+                findings,
+                attack_paths,
+                model=llm_model,
+                effort=hunt_effort_value,  # type: ignore[arg-type]
+                backend=llm_backend,  # type: ignore[arg-type]
+                mode=mode,  # type: ignore[arg-type]
+                speed=llm_speed,  # type: ignore[arg-type]
+                provider=llm_provider,  # type: ignore[arg-type]
+                hypotheses=hypotheses,
+                lens=lens,
+                avoid_titles=avoid_titles,
+                critic_hint=critic_hint,
+            )
+
+        hunt_extra_meta: dict = {}
+        try:
+            if use_jury:
+                lens_note = f", {lens_count} lenses" if lens_names else ""
+                round_note = f", up to {max_rounds} rounds" if max_rounds > 1 else ""
+                typer.echo(
+                    f"Hunting + adjudicating via {llm_display} "
+                    f"({jury_votes} independent skeptics{lens_note}{round_note}, backend={llm_backend}, may take a few minutes)..."
+                )
+                scan_progress.stage(
+                    f"{llm_display} is hunting + majority-vote verifying "
+                    f"({jury_votes} skeptics{lens_note}{round_note}, backend={llm_backend})"
+                )
+                try:
+                    jury = run_majority_verify(
+                        scan, attack_surfaces, findings, attack_paths,
+                        votes=jury_votes, llm_call=_hunt_llm_call, lenses=lens_names,
+                        max_rounds=max_rounds, token_budget=token_budget,
+                    )
+                finally:
+                    scan_progress.done()
+                hunt_markdown = jury.report
+                hunt_backend, hunt_model = jury.backend, jury.model
+                hunt_stop, hunt_usage = None, jury.usage
+                hunt_extra_meta = {
+                    "verify_votes": jury.votes,
+                    "lenses": lens_names or [],
+                    "rounds_run": jury.rounds,
+                    "hypothesis_count": jury.hypothesis_count,
+                    "consensus": {
+                        "confirmed": sum(1 for c in jury.consensus if c.verdict == "confirmed"),
+                        "needs_review": sum(1 for c in jury.consensus if c.verdict == "needs_review"),
+                        "refuted": sum(1 for c in jury.consensus if c.verdict == "refuted"),
+                    },
+                }
+            else:
+                hunt_mode = "hunt_verify" if verify else "hunt"
+                typer.echo(
+                    f"Hunting for vulnerability hypotheses via {llm_display} "
+                    f"({'adjudicated against source, ' if verify else ''}backend={llm_backend}, may take a minute)..."
+                )
+                scan_progress.stage(
+                    f"{llm_display} is hunting exploit-chain hypotheses"
+                    f"{' + verifying against source' if verify else ''} (backend={llm_backend})"
+                )
+                try:
+                    hunt_result = _hunt_llm_call(hunt_mode)
+                finally:
+                    scan_progress.done()
+                hunt_markdown = hunt_result.markdown
+                hunt_backend, hunt_model = hunt_result.backend, hunt_result.model
+                hunt_stop, hunt_usage = hunt_result.stop_reason, hunt_result.usage
+        except LlmReviewError as exc:
+            typer.echo(f"Vulnerability hunt skipped: {exc}", err=True)
+        else:
+            output_path = Path(output)
+            hunt_md_path = output_path / "vulnerability-hypotheses.md"
+            _write_text(hunt_md_path, HUNT_BANNER + sanitize_llm_markdown(hunt_markdown) + "\n")
+            hunt_meta_path = output_path / "vulnerability-hypotheses.meta.json"
+            _write_text(
+                hunt_meta_path,
+                json.dumps(
+                    {
+                        "backend": hunt_backend,
+                        "model": hunt_model,
+                        "stop_reason": hunt_stop,
+                        "usage": hunt_usage,
+                        **hunt_extra_meta,
+                    },
+                    indent=2,
+                )
+                + "\n",
+            )
+            typer.echo(
+                f"Vulnerability hypotheses written to: {hunt_md_path.resolve()} "
+                f"(backend={hunt_backend})"
+            )
+
+    if remediate:
+        try:
+            rem_effort_value = llm_effort  # validated up front (#229)
+            typer.echo("")
+            typer.echo(
+                f"Generating remediation suggestions via {llm_display} (backend={llm_backend}, may take a minute)..."
+            )
+            scan_progress.stage(
+                f"{llm_display} is drafting remediation suggestions (backend={llm_backend})"
+            )
+            try:
+                rem_result = generate_llm_review(
+                    scan,
+                    attack_surfaces,
+                    findings,
+                    attack_paths,
+                    model=llm_model,
+                    effort=rem_effort_value,  # type: ignore[arg-type]
+                    backend=llm_backend,  # type: ignore[arg-type]
+                    mode="remediate",
+                    speed=llm_speed,  # type: ignore[arg-type]
+                    provider=llm_provider,  # type: ignore[arg-type]
+                )
+            finally:
+                scan_progress.done()
+        except LlmReviewError as exc:
+            typer.echo(f"Remediation skipped: {exc}", err=True)
+        else:
+            output_path = Path(output)
+            rem_md_path = output_path / "remediation.md"
+            _write_text(rem_md_path, REMEDIATION_BANNER + sanitize_llm_markdown(rem_result.markdown) + "\n")
+            rem_meta_path = output_path / "remediation.meta.json"
+            _write_text(
+                rem_meta_path,
+                json.dumps(
+                    {
+                        "backend": rem_result.backend,
+                        "model": rem_result.model,
+                        "stop_reason": rem_result.stop_reason,
+                        "usage": rem_result.usage,
+                    },
+                    indent=2,
+                )
+                + "\n",
+            )
+            typer.echo(
+                f"Remediation suggestions written to: {rem_md_path.resolve()} "
+                f"(backend={rem_result.backend})"
+            )
+
+    if triage:
+        tri_effort_value = llm_effort  # validated up front (#229)
+        output_path = Path(output)
+        tri_md_path = output_path / "triage.md"
+        tri_meta_path = output_path / "triage.meta.json"
+        tri_backend = "deterministic"
+        tri_model: str | None = None
+        tri_stop: str | None = None
+        tri_usage: dict = {}
+        try:
+            typer.echo("")
+            typer.echo(
+                f"Triaging findings via {llm_display} (backend={llm_backend})..."
+            )
+            scan_progress.stage(f"{llm_display} is triaging findings (backend={llm_backend})")
+            try:
+                tri_result = generate_llm_review(
+                    scan,
+                    attack_surfaces,
+                    findings,
+                    attack_paths,
+                    model=llm_model,
+                    effort=tri_effort_value,  # type: ignore[arg-type]
+                    backend=llm_backend,  # type: ignore[arg-type]
+                    mode="triage",
+                    speed=llm_speed,  # type: ignore[arg-type]
+                    provider=llm_provider,  # type: ignore[arg-type]
+                )
+            finally:
+                scan_progress.done()
+            markdown = TRIAGE_BANNER + tri_result.markdown + "\n"
+            tri_backend = tri_result.backend
+            tri_model = tri_result.model
+            tri_stop = tri_result.stop_reason
+            tri_usage = tri_result.usage
+        except LlmReviewError as exc:
+            # No LLM backend / call failed — degrade to the deterministic,
+            # reproducible score-ordered shortlist rather than erroring (#145).
+            typer.echo(f"Triage LLM unavailable ({exc}); using deterministic ordering.", err=True)
+            markdown = TRIAGE_BANNER + render_triage_fallback(scan, findings) + "\n"
+        _write_text(tri_md_path, sanitize_llm_markdown(markdown))
+        _write_text(
+            tri_meta_path,
+            json.dumps(
+                {
+                    "backend": tri_backend,
+                    "model": tri_model,
+                    "stop_reason": tri_stop,
+                    "usage": tri_usage,
+                },
+                indent=2,
+            )
+            + "\n",
+        )
+        typer.echo(f"Triage shortlist written to: {tri_md_path.resolve()} (backend={tri_backend})")
+
+    if diff_exit_code:
+        raise typer.Exit(code=diff_exit_code)
+
+
+CAPABILITIES_SCHEMA_VERSION = 1
+
+
+@app.command("capabilities")
+def capabilities() -> None:
+    """Describe what this CLI supports, for GUIs and wrappers.
+
+    Front-ends (e.g. the macOS app) used to scrape `analyze --help`, which
+    breaks when help wording or terminal width changes. This prints a stable
+    JSON document instead: the version, the subcommands, every long option
+    `analyze` accepts, and whether `analyze` takes multiple repo paths.
+    """
+    root = typer.main.get_command(app)
+    commands = getattr(root, "commands", {})
+    analyze_cmd = commands.get("analyze")
+    options: set[str] = set()
+    multi_repo = False
+    for param in getattr(analyze_cmd, "params", []):
+        for opt in [*getattr(param, "opts", []), *getattr(param, "secondary_opts", [])]:
+            if opt.startswith("--"):
+                options.add(opt)
+        if getattr(param, "param_type_name", "") == "argument" and getattr(param, "nargs", 1) == -1:
+            multi_repo = True
+    payload = {
+        "schema": CAPABILITIES_SCHEMA_VERSION,
+        "version": __version__,
+        "commands": sorted(commands),
+        "analyze": {"options": sorted(options), "multi_repo": multi_repo},
+        "progress_protocol": PROGRESS_PROTOCOL_VERSION,
+    }
+    typer.echo(json.dumps(payload, indent=2))
+
+
+@app.command("modules")
+def modules(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the installed analyzer modules as a JSON array "
+        "(name/display_name/description/scope/ecosystems/enabled_by_default). "
+        "Network-free — the remote module-repository section is omitted. "
+        "Intended for tool / GUI front-ends that offer analyzer selection.",
+    ),
+) -> None:
+    available_modules = get_available_modules()
+    if json_output:
+        payload = [
+            {
+                "name": meta.name,
+                "display_name": meta.display_name or meta.name,
+                "description": meta.description,
+                "scope": meta.scope,
+                "ecosystems": list(meta.ecosystems),
+                "enabled_by_default": meta.enabled_by_default,
+                "priority": meta.priority,
+                "experimental": meta.experimental,
+            }
+            for meta in available_modules
+        ]
+        typer.echo(json.dumps(payload, indent=2))
+        return
+
+    if not available_modules:
+        typer.echo("No analyzer modules are currently available.")
+    else:
+        typer.echo("Available analyzer modules (installed, in run order):")
+        for module_metadata in available_modules:
+            ecosystems = ", ".join(module_metadata.ecosystems) if module_metadata.ecosystems else "none"
+            mode = "default" if module_metadata.enabled_by_default else f"opt-in (-m {module_metadata.name})"
+            typer.echo(f"- {module_metadata.name}: {module_metadata.description}")
+            typer.echo(f"  scope: {module_metadata.scope}")
+            typer.echo(f"  ecosystems: {ecosystems}")
+            typer.echo(f"  priority: {module_metadata.priority}  runs: {mode}")
+            if module_metadata.experimental and module_metadata.enabled_by_default:
+                typer.echo("  note: experimental but enabled by default")
+
+    typer.echo("")
+    typer.echo("Available module repositories (mlaify GitHub org):")
+    try:
+        repository_modules = get_available_repository_modules()
+    except ValueError as exc:
+        typer.echo(f"- Unable to fetch remote module repositories: {exc}")
+        return
+
+    if not repository_modules:
+        typer.echo("- No module repositories were discovered.")
+        return
+
+    for module in repository_modules:
+        typer.echo(f"- {module.analyzer_name} ({module.repo_name})")
+        typer.echo(f"  repo: {module.web_url}")
+
+
+@app.command("suggest")
+def suggest(
+    path: str = typer.Argument(".", help="Path to the repository to inspect."),
+    install: bool = typer.Option(
+        False,
+        "--install",
+        help="After printing, offer to `pip install` the missing recommended plugins.",
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip the confirmation prompt when used with --install.",
+    ),
+    show_installed: bool = typer.Option(
+        False,
+        "--show-installed",
+        help="Include already-installed plugins in the output (marked accordingly).",
+    ),
+) -> None:
+    """Recommend analyzer plugins for the shape of the given repository."""
+    repo = Path(path).resolve()
+    if not repo.exists() or not repo.is_dir():
+        typer.echo(f"Path does not exist or is not a directory: {repo}")
+        raise typer.Exit(code=1)
+
+    suggestions = detect_ecosystems(repo)
+    missing = [s for s in suggestions if not s.installed]
+    installed = [s for s in suggestions if s.installed]
+
+    if not suggestions:
+        typer.echo(f"No AttackMap plugins matched the shape of {repo}.")
+        raise typer.Exit(code=0)
+
+    shown = suggestions if show_installed else missing
+    if not shown:
+        typer.echo("All recommended plugins are already installed:")
+        for s in installed:
+            typer.echo(f"  - {s.plugin} (installed)")
+        raise typer.Exit(code=0)
+
+    typer.echo(f"Recommended plugins for {repo}:")
+    for s in shown:
+        tag = " (installed)" if s.installed else ""
+        typer.echo(f"  - {s.plugin}{tag}")
+        typer.echo(f"      matches: {', '.join(s.matched_signals)}")
+        if not s.installed:
+            typer.echo(f"      install: {s.pip_install}")
+
+    if not install:
+        return
+    if not missing:
+        typer.echo("Nothing to install — all recommended plugins are already present.")
+        return
+
+    typer.echo("")
+    typer.echo("The following plugins will be installed via pip:")
+    for s in missing:
+        typer.echo(f"  - {s.plugin}")
+    if not yes and not typer.confirm("Proceed?", default=False):
+        typer.echo("Aborted.")
+        raise typer.Exit(code=1)
+
+    for s in missing:
+        typer.echo(f"Installing {s.plugin}…")
+        try:
+            install_analyzer_module(s.plugin)
+        except Exception as exc:  # noqa: BLE001 — surface pip failures verbatim
+            typer.echo(f"  Failed: {exc}")
+            raise typer.Exit(code=1) from exc
+    typer.echo("Done.")
+
+
+@app.command("rules")
+def rules(
+    as_json: bool = typer.Option(False, "--json", help="Emit the rule catalog as JSON."),
+) -> None:
+    """List every core detector's stable rule id (#223) — the SARIF ruleId and
+    the value for `rule:` suppressions and `attackmap:ignore[...]`."""
+    from .threat_model import rule_catalog
+
+    catalog = rule_catalog()
+    if as_json:
+        typer.echo(json.dumps([{"rule_id": r, "title": t, "severity": sev} for r, t, sev in catalog], indent=2))
+        return
+    width = max(len(r) for r, _, _ in catalog)
+    for rule_id, title, severity in catalog:
+        typer.echo(f"{rule_id.ljust(width)}  {severity:<7}  {title}")
+
+
+@app.command("bench")
+def bench(
+    benchmark: str = typer.Option(
+        "evals/benchmark/benchmark.json",
+        "--benchmark",
+        help="Path to the benchmark manifest (labeled ground-truth corpus).",
+    ),
+    root: str = typer.Option(
+        ".",
+        "--root",
+        help="Repository root the manifest's case paths are relative to.",
+    ),
+    output: str | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Directory to write benchmark-results.md + .json (also printed to stdout).",
+    ),
+    fail_under: float | None = typer.Option(
+        None,
+        "--fail-under",
+        help="Exit non-zero if any scored detector class falls below this precision/recall (0-1). For CI regression gating.",
+    ),
+) -> None:
+    """Score AttackMap findings against the labeled benchmark corpus (#197).
+
+    The 1.0 precision gate: reports precision/recall/F1 per detector class.
+    Contributor/CI tool — run from the repo root (the manifest ships in `evals/`,
+    not the installed wheel).
+    """
+    from .bench import bench_json, load_benchmark, min_scored_metric, render_markdown, run_benchmark
+
+    manifest = Path(benchmark)
+    if not manifest.exists():
+        typer.echo(f"Benchmark manifest not found: {manifest}")
+        typer.echo("Pass --benchmark <path>, or run from a checkout that has evals/benchmark/.")
+        raise typer.Exit(code=2)
+
+    results = run_benchmark(load_benchmark(manifest), root)
+    markdown = render_markdown(results)
+    typer.echo(markdown)
+
+    if output:
+        out = Path(output)
+        _ensure_output_dir(out)
+        _write_text(out / "benchmark-results.md", markdown + "\n")
+        _write_text(out / "benchmark-results.json", json.dumps(bench_json(results), indent=2) + "\n")
+        typer.echo(f"Written to: {out.resolve()}")
+
+    errored = [r.id for r in results if r.error]
+    if errored:
+        typer.echo(f"Cases that failed to scan: {', '.join(errored)}")
+        raise typer.Exit(code=1)
+
+    if fail_under is not None:
+        worst = min_scored_metric(results)
+        if worst < fail_under:
+            typer.echo(f"FAIL: lowest scored precision/recall {worst:.2f} < --fail-under {fail_under:.2f}")
+            raise typer.Exit(code=1)
+        typer.echo(f"OK: lowest scored precision/recall {worst:.2f} ≥ --fail-under {fail_under:.2f}")
+
+
+if __name__ == "__main__":
+    app()