infraweaver 0.1.0

package/src/mcp/terraform/scanners.ts

@@ -0,0 +1,1134 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import {
+  MAX_TF_TOTAL_BYTES,
+  readTextCapped,
+  walkTfFiles,
+} from "#app/mcp/modules";
+import {
+  loadProvidersSchema,
+  unknownArgsForResource,
+} from "#app/mcp/providerSchema";
+import { matchBraceBody, skipNonCode } from "#app/mcp/terraform/hcl";
+import {
+  checkovTypeToLanguage,
+  trivyTypeToLanguage,
+} from "#app/mcp/terraform/iacLanguages";
+import { scanNative } from "#app/mcp/terraform/nativeScan";
+import {
+  type ResolvedRoot,
+  resolveBaseRef,
+  resolveRoots,
+  toRepoRelative,
+} from "#app/mcp/terraform/paths";
+import {
+  egressEnvFor,
+  type ToolsNetworkDirective,
+} from "#app/mcp/terraform/scannerEgress";
+import { parseScannerJson } from "#app/mcp/terraform/scannerJson";
+import { run, runTf } from "#app/mcp/terraform/subprocess";
+import { assertToolchainIntegrity } from "#app/mcp/terraform/toolchainIntegrity";
+import {
+  buildConcern,
+  type Concern,
+  dedupe,
+  lowerSeverity,
+  rebaseConcern,
+  type ScannerOutcome,
+  type Severity,
+  skipped,
+} from "#app/mcp/terraform/types";
+import { log } from "#app/utils/cli";
+import {
+  type ResolvedToolSelection,
+  scannerToolId,
+} from "#app/utils/toolSelection";
+
+// dirs already `terraform init`-ed this process, so repeated scans don't re-init.
+const initedDirs = new Set<string>();
+
+/**
+ * Run `terraform init -backend=false` once per dir so `terraform validate` has
+ * provider schemas to check against (Bug 3 / gap B). Without init, validate only
+ * emits "missing required provider" — which VALIDATE_NOISE drops — so it was
+ * effectively inert. `-backend=false` avoids needing real backend credentials;
+ * `-input=false` keeps it non-interactive. Network-dependent and best-effort: if
+ * it fails (offline, private module, etc.) validate still runs, just shallow.
+ */
+function ensureTerraformInit(
+  cwd: string,
+  extraEnv?: Record<string, string>,
+): void {
+  if (initedDirs.has(cwd)) return;
+  // `extraEnv` carries the optional module-fetch credential so init can
+  // resolve a private cross-repo `git::` module; absent for the common case.
+  // runTf falls back to `tofu` when `terraform` isn't installed.
+  const r = runTf(
+    ["init", "-backend=false", "-input=false", "-no-color"],
+    cwd,
+    extraEnv,
+  );
+  // mark done even on non-zero: a failed init won't succeed on retry within the
+  // same run, and we don't want to re-run it for every scanner call.
+  initedDirs.add(cwd);
+  if (r.status !== 0 && !r.missing) {
+    log.info(
+      `» terraform init (for validate) did not complete cleanly — validate may be shallow`,
+    );
+  }
+}
+
+// --- terraform fmt -------------------------------------------------------
+
+export function scanFmt(cwd: string): ScannerOutcome {
+  // `terraform` when installed, else `tofu` — OpenTofu-only runners keep fmt
+  // coverage (identical CLI surface; the source label stays "terraform-fmt" so
+  // rule ids and content hashes never fork on the binary name).
+  const r = runTf(["fmt", "-check", "-recursive", "-list=true"], cwd);
+  if (r.missing)
+    return skipped("terraform-fmt", "terraform (or tofu) not installed");
+  // exit 0 = all formatted; exit 3 = files need formatting (lists them on stdout);
+  // other non-zero = real error (e.g. parse failure) — surface nothing, validate covers it.
+  if (r.status === 0)
+    return { source: "terraform-fmt", ran: true, concerns: [] };
+  return {
+    source: "terraform-fmt",
+    ran: true,
+    concerns: parseFmtOutput(r.stdout, cwd),
+  };
+}
+
+/** `terraform fmt -check -list=true` prints one unformatted file path per line. */
+export function parseFmtOutput(stdout: string, cwd = ""): Concern[] {
+  const files = stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  return files.map<Concern>((raw) =>
+    buildConcern({
+      source: "terraform-fmt",
+      rule: "unformatted",
+      file: toRepoRelative(raw, cwd),
+      line: null,
+      severity: "low",
+      category: "style",
+      evidence: "File does not match `terraform fmt` canonical style.",
+      remediation_hint: "Run `terraform fmt` to apply canonical formatting.",
+    }),
+  );
+}
+
+// --- terraform validate ---------------------------------------------------
+
+// diagnostics that are environmental (the dir isn't initialized, or a provider
+// plugin failed to install/launch) rather than a real best-practice issue.
+// dropped so a scan can't emit false positives from toolchain hiccups — e.g.
+// after `terraform init` (Bug 3), a crashed provider plugin surfaces as
+// "Failed to load plugin schemas", which is noise, not a defect in the HCL.
+const VALIDATE_NOISE = [
+  "terraform init",
+  "missing required provider",
+  "module not installed",
+  "module is not yet installed",
+  "required plugins are not installed",
+  "uninitialized",
+  "failed to load plugin",
+  "plugin did not respond",
+  "could not load plugin",
+];
+
+/** run `terraform validate` in one root and return concerns re-based onto cwd. */
+function scanValidateRoot(
+  root: ResolvedRoot,
+  extraEnv?: Record<string, string>,
+): ScannerOutcome {
+  ensureTerraformInit(root.absDir, extraEnv);
+  const r = runTf(["validate", "-json"], root.absDir);
+  if (r.missing)
+    return skipped("terraform-validate", "terraform (or tofu) not installed");
+  try {
+    const concerns = parseValidateOutput(r.stdout, root.absDir).map((c) =>
+      rebaseConcern(c, root.relDir),
+    );
+    return { source: "terraform-validate", ran: true, concerns };
+  } catch {
+    // terraform ran but emitted output we couldn't parse — a real CLI-level
+    // failure (corrupted .terraform, a crash, an ancient terraform without
+    // `-json`), NOT a clean tree. Flag it as unvalidated so the tool fails
+    // closed rather than reporting this root as passing.
+    return {
+      ...skipped(
+        "terraform-validate",
+        "could not parse `terraform validate -json` output",
+      ),
+      unvalidated: 1,
+    };
+  }
+}
+
+/**
+ * Run `terraform validate` across EVERY root and aggregate. `validate` is the
+ * one scanner that's per-root (fmt/tflint/trivy/checkov are recursive over the
+ * whole tree), so a multi-root repo only catches subdir-root validate errors
+ * when we visit each root.
+ */
+export function scanValidate(
+  cwd: string,
+  extraEnv?: Record<string, string>,
+): ScannerOutcome {
+  const roots = resolveRoots(cwd);
+  const concerns: Concern[] = [];
+  let anyRan = false;
+  let sawMissing = false;
+  let unvalidated = 0;
+  for (const root of roots) {
+    const outcome = scanValidateRoot(root, extraEnv);
+    unvalidated += outcome.unvalidated ?? 0;
+    if (outcome.ran) {
+      anyRan = true;
+      concerns.push(...outcome.concerns);
+    } else if (outcome.skipped_reason?.includes("not installed")) {
+      sawMissing = true;
+    }
+  }
+  if (!anyRan) {
+    return sawMissing
+      ? skipped("terraform-validate", "terraform not installed")
+      : {
+          ...skipped(
+            "terraform-validate",
+            "could not parse `terraform validate -json` output",
+          ),
+          unvalidated,
+        };
+  }
+  return {
+    source: "terraform-validate",
+    ran: true,
+    concerns: dedupe(concerns),
+    unvalidated,
+  };
+}
+
+/** parse `terraform validate -json`; keeps real errors, drops uninitialized-dir noise. */
+export function parseValidateOutput(stdout: string, cwd = ""): Concern[] {
+  const parsed = parseScannerJson(ValidateOutput, stdout, "terraform validate");
+  const diags = (parsed.diagnostics ?? []).filter(
+    (d) => d.severity === "error",
+  );
+  const concerns: Concern[] = [];
+  for (const d of diags) {
+    const text = `${d.summary ?? ""} ${d.detail ?? ""}`.toLowerCase();
+    if (VALIDATE_NOISE.some((n) => text.includes(n))) continue;
+    concerns.push(
+      buildConcern({
+        source: "terraform-validate",
+        rule: d.summary ?? "error",
+        file: toRepoRelative(d.range?.filename, cwd),
+        line: d.range?.start?.line ?? null,
+        severity: "high",
+        category: "correctness",
+        evidence: [d.summary, d.detail].filter(Boolean).join(" — "),
+        remediation_hint: null,
+      }),
+    );
+  }
+  return concerns;
+}
+
+const ValidateDiagnostic = type({
+  "severity?": "string",
+  "summary?": "string",
+  "detail?": "string",
+  "range?": { "filename?": "string", "start?": { "line?": "number" } },
+});
+const ValidateOutput = type({
+  "diagnostics?": ValidateDiagnostic.array().or("null"),
+});
+
+// --- provider-version awareness ------------------------------------
+
+export interface ProviderRequirement {
+  /** local name, e.g. `aws`. */
+  name: string;
+  /** registry source, e.g. `hashicorp/aws`, or null (legacy string form). */
+  source: string | null;
+  /** raw version constraint, e.g. `~> 5.0`, or null when unconstrained. */
+  version: string | null;
+  /** the pinned MAJOR (the lower-bound major of the constraint) — the number a
+   * fix must target, since argument schemas differ across provider majors. */
+  major: number | null;
+}
+
+/** the lower-bound major version from a constraint string (`~> 5.0` → 5,
+ * `>= 3.1, < 4.0` → 3, `5` → 5). null when no number is present. */
+function majorOf(version: string | null): number | null {
+  if (!version) return null;
+  const m = version.match(/(\d+)\s*\.\s*\d+/) ?? version.match(/(\d+)/);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Parse every `required_providers { … }` block in some HCL text into the pinned
+ * provider requirements. Handles the modern object form
+ * (`aws = { source = "hashicorp/aws", version = "~> 5.0" }`) and the legacy
+ * string form (`aws = "~> 5.0"`). A repo's "correct" fix depends on the provider
+ * MAJOR — argument names and valid blocks differ across AWS/Azure majors — so
+ * surfacing the pinned major lets a fix target the right schema instead of
+ * breaking `plan`. Brace-matched (not a fragile single regex) so nested objects
+ * don't confuse it. First declaration of a name wins (dedup across files).
+ */
+export function parseRequiredProviders(hcl: string): ProviderRequirement[] {
+  const out: ProviderRequirement[] = [];
+  const seen = new Set<string>();
+  let searchFrom = 0;
+  for (;;) {
+    const idx = hcl.indexOf("required_providers", searchFrom);
+    if (idx === -1) break;
+    const braceStart = hcl.indexOf("{", idx);
+    if (braceStart === -1) break;
+    let depth = 0;
+    let end = -1;
+    for (let i = braceStart; i < hcl.length; i++) {
+      if (hcl[i] === "{") depth++;
+      else if (hcl[i] === "}") {
+        depth--;
+        if (depth === 0) {
+          end = i;
+          break;
+        }
+      }
+    }
+    if (end === -1) break;
+    const body = hcl.slice(braceStart + 1, end);
+    searchFrom = end + 1;
+
+    // object form: name = { source = "…", version = "…" }
+    const objRe = /([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*\{([^}]*)\}/g;
+    let m: RegExpExecArray | null;
+    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex-exec iteration
+    while ((m = objRe.exec(body)) !== null) {
+      // destructure with defaults — `name` is a required group, `inner` is `[^}]*`
+      // (may be empty); the "" defaults only stand in for a non-match that can't happen.
+      const [, name = "", inner = ""] = m;
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const source = inner.match(/source\s*=\s*"([^"]+)"/)?.[1] ?? null;
+      const version = inner.match(/version\s*=\s*"([^"]+)"/)?.[1] ?? null;
+      out.push({ name, source, version, major: majorOf(version) });
+    }
+    // legacy string form: name = "version" — run on the body with object blocks
+    // stripped so an object's inner `source =`/`version =` lines aren't matched.
+    const bodyNoObjects = body.replace(
+      /([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*\{[^}]*\}/g,
+      "",
+    );
+    const strRe = /([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*"([^"]+)"/g;
+    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex-exec iteration
+    while ((m = strRe.exec(bodyNoObjects)) !== null) {
+      const [, name = "", version = ""] = m;
+      if (seen.has(name)) continue;
+      seen.add(name);
+      out.push({ name, source: null, version, major: majorOf(version) });
+    }
+  }
+  return out;
+}
+
+/** read the repo's `*.tf` files (recursively — root + subdir roots + nested
+ * modules) and parse their pinned provider requirements (best-effort; an
+ * unreadable tree yields none). First declaration of a provider wins. */
+export function collectProviderRequirements(
+  cwd: string,
+): ProviderRequirement[] {
+  let text = "";
+  for (const f of walkTfFiles(cwd)) {
+    // byte-capped per file and in aggregate: a hostile repo with one multi-GB
+    // `.tf` would otherwise OOM the run near V8's string limit.
+    if (text.length >= MAX_TF_TOTAL_BYTES) break;
+    const t = readTextCapped(join(cwd, f));
+    if (t !== null) text += `${t}\n`;
+  }
+  return parseRequiredProviders(text);
+}
+
+// --- argument-vs-schema validation ------------------------------
+
+/** the top-level arguments of a single `resource` block. */
+export interface ResourceArguments {
+  resourceType: string;
+  /** the resource's local name (`resource "aws_s3_bucket" "<name>"`). */
+  name: string;
+  /** top-level attribute + nested-block names (meta-arguments excluded). */
+  args: string[];
+}
+
+// Terraform meta-arguments are valid on EVERY resource and never appear in a
+// provider's schema — exclude them so they're not flagged as unknown. `dynamic`
+// is handled specially (its quoted label is the real block name).
+const RESOURCE_META_ARGUMENTS: ReadonlySet<string> = new Set([
+  "count",
+  "for_each",
+  "provider",
+  "depends_on",
+  "lifecycle",
+  "provisioner",
+  "connection",
+]);
+
+/**
+ * Parse every `resource "<type>" "<name>" { … }` block's TOP-LEVEL argument
+ * names (attributes assigned with `=` and nested block labels) from some HCL.
+ * Conservative by design — it skips `"…"` strings and `#`/`//` line comments so
+ * an interpolation's braces or a commented line can't corrupt the brace depth or
+ * fabricate an argument, and only reports depth-0 names. A `dynamic "x"` block
+ * contributes `x` (the generated block type). Used to cross-check written
+ * arguments against the installed provider schema; pure.
+ */
+export function parseResourceArguments(hcl: string): ResourceArguments[] {
+  const out: ResourceArguments[] = [];
+  const re = /(?:^|\n)\s*resource\s+"([^"]+)"\s+"([^"]+)"\s*\{/g;
+  let m: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex-exec iteration
+  while ((m = re.exec(hcl)) !== null) {
+    const [, resourceType = "", name = ""] = m;
+    const braceStart = hcl.indexOf("{", m.index);
+    if (braceStart === -1) break;
+    const body = matchBraceBody(hcl, braceStart);
+    if (!body) break;
+    re.lastIndex = body.end + 1;
+    out.push({ resourceType, name, args: topLevelArgNames(body.text) });
+  }
+  return out;
+}
+
+/** extract the depth-0 argument names from a resource block body (string-,
+ * comment-, and heredoc-aware), excluding meta-arguments. */
+function topLevelArgNames(body: string): string[] {
+  const names = new Set<string>();
+  let depth = 0;
+  let atStmtStart = true;
+  for (let i = 0; i < body.length; i++) {
+    const span = skipNonCode(body, i);
+    if (span) {
+      i = span.end;
+      // a comment/heredoc ends a line (next token is a fresh statement); a
+      // string ends mid-line (still inside the current statement).
+      atStmtStart = span.endsLine;
+      continue;
+    }
+    const ch = body[i]!;
+    if (ch === "{") {
+      depth++;
+      atStmtStart = false;
+      continue;
+    }
+    if (ch === "}") {
+      depth--;
+      atStmtStart = false;
+      continue;
+    }
+    if (ch === "\n") {
+      atStmtStart = true;
+      continue;
+    }
+    if (ch === " " || ch === "\t" || ch === "\r") continue;
+    // a non-space char that starts a statement at depth 0 → read an identifier.
+    if (depth === 0 && atStmtStart && /[A-Za-z_]/.test(ch)) {
+      let j = i;
+      while (j < body.length && /[A-Za-z0-9_-]/.test(body[j]!)) j++;
+      const ident = body.slice(i, j);
+      // skip whitespace after the identifier to classify it.
+      let k = j;
+      while (k < body.length && (body[k] === " " || body[k] === "\t")) k++;
+      const next = body[k];
+      if (next === "=" && body[k + 1] !== "=") {
+        // attribute assignment: `name = …`
+        if (!RESOURCE_META_ARGUMENTS.has(ident)) names.add(ident);
+      } else if (next === "{") {
+        // nested block: `name { … }`
+        if (!RESOURCE_META_ARGUMENTS.has(ident)) names.add(ident);
+      } else if (next === '"') {
+        // labeled block: `dynamic "x" {` → the generated block is `x`;
+        // other labeled blocks (`provisioner "remote-exec"`) are meta.
+        if (ident === "dynamic") {
+          const labelEnd = body.indexOf('"', k + 1);
+          if (labelEnd !== -1) names.add(body.slice(k + 1, labelEnd));
+        }
+      }
+      i = j - 1;
+      atStmtStart = false;
+      continue;
+    }
+    atStmtStart = false;
+  }
+  return [...names];
+}
+
+export interface UnknownArgument {
+  resource_type: string;
+  /** the resource's local name. */
+  name: string;
+  /** repo-relative file the resource is declared in. */
+  file: string;
+  /** the argument names not present in the installed provider's schema. */
+  unknown: string[];
+}
+
+/**
+ * Cross-check every resource's written arguments against the
+ * INSTALLED provider's schema, so an argument that's invalid for the pinned
+ * provider major (a "correct" fix for the wrong version) is caught at validate
+ * time, not as a later `plan` failure. Degrades green: returns
+ * `{ checked: false }` when the schema is unavailable (terraform not installed /
+ * dir not init-ed). A resource type absent from the schema is skipped (can't
+ * judge), never flagged.
+ */
+export function checkArgumentsAgainstSchema(cwd: string): {
+  checked: boolean;
+  unknown_arguments: UnknownArgument[];
+} {
+  const schema = loadProvidersSchema(cwd);
+  if (!schema) return { checked: false, unknown_arguments: [] };
+  const out: UnknownArgument[] = [];
+  for (const f of walkTfFiles(cwd)) {
+    const text = readTextCapped(join(cwd, f));
+    if (text === null) continue;
+    for (const block of parseResourceArguments(text)) {
+      const verdict = unknownArgsForResource(
+        schema,
+        block.resourceType,
+        block.args,
+      );
+      if (!verdict.unknownResourceType && verdict.unknown.length > 0) {
+        out.push({
+          resource_type: block.resourceType,
+          name: block.name,
+          file: f,
+          unknown: verdict.unknown,
+        });
+      }
+    }
+  }
+  return { checked: true, unknown_arguments: out };
+}
+
+/** A parsed resource block plus the file it came from. `parseResourceArguments`
+ *  works on one file's text and so cannot carry a location; the transform-pack
+ *  matcher (TC-2.2) needs one to tell the agent WHERE to edit. */
+export interface LocatedResource extends ResourceArguments {
+  /** repo-relative file the resource is declared in. */
+  file: string;
+}
+
+/** Every `resource` block under `cwd`, with its file. Best-effort in the same
+ *  way as `collectProviderRequirements` — an unreadable file is skipped rather
+ *  than failing the walk. */
+export function collectResourceArguments(cwd: string): LocatedResource[] {
+  const out: LocatedResource[] = [];
+  for (const f of walkTfFiles(cwd)) {
+    const text = readTextCapped(join(cwd, f));
+    if (text === null) continue;
+    for (const block of parseResourceArguments(text))
+      out.push({ ...block, file: f });
+  }
+  return out;
+}
+
+// --- tflint ---------------------------------------------------------------
+
+function tflintSeverity(s: string | undefined): Severity {
+  switch ((s ?? "").toLowerCase()) {
+    case "error":
+      return "high";
+    case "warning":
+      return "medium";
+    default:
+      return "low";
+  }
+}
+
+// dirs we've already attempted `tflint --init` in, so repeated scans don't re-init.
+const tflintInitedDirs = new Set<string>();
+
+/**
+ * Install tflint's provider ruleset plugins via `tflint --init` when the dir has
+ * a `.tflint.hcl` declaring them. Core `tflint --recursive` runs only the
+ * built-in rules; the high-value provider rules (deprecated args, invalid
+ * instance types, missing-tag policies, etc.) live in the aws/azurerm/google
+ * plugins, which must be installed first. Opt-in by design — we only init when
+ * the repo ships a `.tflint.hcl`, so we don't force AWS rules onto an Azure/GCP
+ * repo. Best-effort and network-dependent: a failed init just leaves tflint
+ * running its core rules, exactly as before.
+ */
+function ensureTflintInit(
+  cwd: string,
+  extraEnv?: Record<string, string>,
+): void {
+  if (tflintInitedDirs.has(cwd)) return;
+  // mark first: a failed init won't succeed on retry within the same run, and
+  // we don't want to re-attempt the network fetch on every scanner call.
+  tflintInitedDirs.add(cwd);
+  if (!existsSync(join(cwd, ".tflint.hcl"))) return;
+  // under egress denial the overlay still admits GitHub's release hosts, so
+  // ruleset plugins install; everything else dies at the blackhole proxy.
+  const r = run("tflint", ["--init"], cwd, extraEnv);
+  if (r.status !== 0 && !r.missing) {
+    log.info(
+      "» tflint --init did not complete cleanly — provider ruleset plugins may be unavailable",
+    );
+  }
+}
+
+export function scanTflint(
+  cwd: string,
+  network?: ToolsNetworkDirective,
+): ScannerOutcome {
+  assertToolchainIntegrity("tflint", cwd);
+  const egress = egressEnvFor("tflint", network);
+  ensureTflintInit(cwd, egress ?? undefined);
+  const r = run(
+    "tflint",
+    ["--format", "json", "--recursive"],
+    cwd,
+    egress ?? undefined,
+  );
+  if (r.missing) return skipped("tflint", "tflint not installed");
+  try {
+    return {
+      source: "tflint",
+      ran: true,
+      concerns: parseTflintOutput(r.stdout, cwd),
+      ...(egress ? { egress_isolation: "partial" as const } : {}),
+    };
+  } catch {
+    return skipped("tflint", "could not parse tflint json output");
+  }
+}
+
+/** parse `tflint --format json` output into concerns. */
+export function parseTflintOutput(stdout: string, cwd = ""): Concern[] {
+  const parsed = parseScannerJson(TflintOutput, stdout, "tflint");
+  return (parsed.issues ?? []).map<Concern>((issue) => {
+    const rule = issue.rule?.name ?? "issue";
+    return buildConcern({
+      source: "tflint",
+      rule,
+      file: toRepoRelative(issue.range?.filename, cwd),
+      line: issue.range?.start?.line ?? null,
+      severity: tflintSeverity(issue.rule?.severity),
+      category: "style",
+      evidence: issue.message ?? rule,
+      remediation_hint: issue.rule?.link ?? null,
+    });
+  });
+}
+
+const TflintIssue = type({
+  "rule?": { "name?": "string", "severity?": "string", "link?": "string" },
+  "message?": "string",
+  "range?": { "filename?": "string", "start?": { "line?": "number" } },
+});
+const TflintOutput = type({ "issues?": TflintIssue.array().or("null") });
+
+// --- trivy ----------------------------------------------------------------
+
+// tfsec was archived by Aqua and folded into Trivy; `trivy config` is its
+// maintained successor with a larger ruleset (the AVD-* checks). `--quiet`
+// keeps Trivy's progress chatter off stdout so the JSON parses cleanly.
+function scanTrivy(
+  cwd: string,
+  network?: ToolsNetworkDirective,
+): ScannerOutcome {
+  // Supply-chain gate: refuse to execute a known-compromised trivy build
+  // (GHSA-69fq-xp46-6x23). Throws — a backdoored scanner is not a 'skip'.
+  assertToolchainIntegrity("trivy", cwd);
+  const egress = egressEnvFor("trivy", network);
+  const r = run(
+    "trivy",
+    ["config", "--format", "json", "--quiet", "."],
+    cwd,
+    egress ?? undefined,
+  );
+  if (r.missing) return skipped("trivy", "trivy not installed");
+  try {
+    return {
+      source: "trivy",
+      ran: true,
+      concerns: parseTrivyOutput(r.stdout, cwd),
+      ...(egress ? { egress_isolation: "partial" as const } : {}),
+    };
+  } catch {
+    return skipped("trivy", "could not parse trivy json output");
+  }
+}
+
+/**
+ * Parse `trivy config --format json` output into concerns. Trivy nests
+ * misconfigurations under `Results[].Misconfigurations[]`, keyed to the result's
+ * `Target` file. `trivy config` reports only failures by default, but we
+ * defensively drop any `Status: "PASS"` entry so an `--include-non-failures`
+ * run can't leak passing checks into the concern set. Each concern carries the
+ * IaC language from the result's `Type` (terraform / cloudformation / kubernetes
+ * / helm / dockerfile / azure-arm), which is what the read-only surfaces scope on
+ * — trivy scans every format it finds, and the language tag keeps that honest.
+ */
+export function parseTrivyOutput(stdout: string, cwd = ""): Concern[] {
+  const parsed = parseScannerJson(TrivyOutput, stdout, "trivy");
+  const concerns: Concern[] = [];
+  for (const result of parsed.Results ?? []) {
+    const file = toRepoRelative(result.Target, cwd);
+    const language = trivyTypeToLanguage(result.Type);
+    for (const m of result.Misconfigurations ?? []) {
+      if (m.Status === "PASS") continue;
+      const rule = m.AVDID || m.ID || "issue";
+      const start = m.CauseMetadata?.StartLine;
+      concerns.push(
+        buildConcern({
+          source: "trivy",
+          rule,
+          file,
+          line: typeof start === "number" && start > 0 ? start : null,
+          severity: lowerSeverity(m.Severity),
+          category: "security",
+          evidence: m.Message || m.Description || m.Title || rule,
+          code_snippet: trivyCodeSnippet(m.CauseMetadata?.Code?.Lines),
+          remediation_hint: m.Resolution || m.References?.[0] || null,
+          language,
+        }),
+      );
+    }
+  }
+  return concerns;
+}
+
+const TrivyCodeLine = type({
+  "Number?": "number",
+  "Content?": "string",
+  "IsCause?": "boolean",
+  "Truncated?": "boolean",
+});
+type TrivyCodeLine = typeof TrivyCodeLine.infer;
+
+const TrivyMisconfiguration = type({
+  "ID?": "string",
+  "AVDID?": "string",
+  "Title?": "string",
+  "Description?": "string",
+  "Message?": "string",
+  "Resolution?": "string",
+  "Severity?": "string",
+  "References?": "string[]",
+  "Status?": "string",
+  "CauseMetadata?": {
+    "StartLine?": "number",
+    "EndLine?": "number",
+    "Code?": { "Lines?": TrivyCodeLine.array().or("null") },
+  },
+});
+
+// Max source lines (and chars) we keep for a finding's snippet — enough to show
+// the offending block, bounded so a pathological scan can't bloat the report.
+const SNIPPET_MAX_LINES = 8;
+const SNIPPET_MAX_CHARS = 1000;
+
+/** The offending source from a trivy finding's `CauseMetadata.Code.Lines`:
+ *  prefer the lines trivy marked as the cause, else the whole shown window.
+ *  Returns null when trivy attached no code (older trivy / `--quiet` edge). */
+function trivyCodeSnippet(
+  lines: TrivyCodeLine[] | null | undefined,
+): string | null {
+  if (!lines?.length) return null;
+  const cause = lines.filter((l) => l.IsCause && !l.Truncated);
+  const picked = (
+    cause.length ? cause : lines.filter((l) => !l.Truncated)
+  ).slice(0, SNIPPET_MAX_LINES);
+  return tidySnippet(picked.map((l) => l.Content ?? ""));
+}
+
+/**
+ * Best-effort fallback so EVERY located finding shows its code, not only the
+ * trivy/checkov ones whose scanner emits a source window. For any concern that
+ * has a line but no scanner-attached snippet (terraform-validate, tflint, …),
+ * read the flagged line from disk. Files are read once and cached; a missing or
+ * unreadable file just leaves the snippet null. Pure-ish (read-only I/O).
+ */
+export function attachSourceSnippets(
+  concerns: Concern[],
+  cwd: string,
+): Concern[] {
+  const cache = new Map<string, string[] | null>();
+  const fileLines = (file: string): string[] | null => {
+    const cached = cache.get(file);
+    if (cached !== undefined) return cached;
+    let lines: string[] | null = null;
+    try {
+      const abs = join(cwd, file);
+      if (existsSync(abs)) lines = readTextCapped(abs)?.split(/\r?\n/) ?? null;
+    } catch {
+      lines = null;
+    }
+    cache.set(file, lines);
+    return lines;
+  };
+  return concerns.map((c) => {
+    if (c.code_snippet || c.location.line == null || !c.location.file) return c;
+    const raw = fileLines(c.location.file)?.[c.location.line - 1];
+    if (raw == null) return c;
+    const snippet = tidySnippet([raw]);
+    return snippet ? { ...c, code_snippet: snippet } : c;
+  });
+}
+
+/** Join source lines into a clipped snippet, dropping a common leading indent so
+ *  the code reads cleanly in the narrow finding panel. Returns null when empty. */
+function tidySnippet(rawLines: string[]): string | null {
+  const lines = rawLines.map((l) => l.replace(/\s+$/, ""));
+  while (lines.length && lines[0]?.trim() === "") lines.shift();
+  while (lines.length && lines[lines.length - 1]?.trim() === "") lines.pop();
+  if (!lines.length) return null;
+  const indent = Math.min(
+    ...lines
+      .filter((l) => l.trim() !== "")
+      .map((l) => l.length - l.trimStart().length),
+  );
+  const text = lines.map((l) => l.slice(indent)).join("\n");
+  return text.trim() ? text.slice(0, SNIPPET_MAX_CHARS) : null;
+}
+
+const TrivyResult = type({
+  "Target?": "string",
+  "Class?": "string",
+  "Type?": "string",
+  "Misconfigurations?": TrivyMisconfiguration.array(),
+});
+const TrivyOutput = type({ "Results?": TrivyResult.array().or("null") });
+
+// --- checkov --------------------------------------------------------------
+
+function scanCheckov(
+  cwd: string,
+  downloadExternalModules = false,
+  frameworks: string[] = ["terraform", "terraform_json"],
+  network?: ToolsNetworkDirective,
+): ScannerOutcome {
+  // `--framework` pins checkov to EXACTLY the languages this run scopes to
+  // (derived from `iac_languages` ∩ what the tree contains — see
+  // checkovFrameworksFor). The default stays Terraform-only so the fix loop's
+  // scan never widens; the read-only Assess path passes the detected set.
+  // Explicit is deliberate: checkov's own default is `all`, which also scans
+  // CI configs / secrets / SAST — noise the crosswalk isn't tuned for.
+  // NB: no `--compact` — it omits `code_block` from the JSON, which is exactly
+  // the offending source we attach to each finding (the detail's "flagged
+  // location"). `--quiet` already suppresses the progress banner.
+  //
+  // `--download-external-modules true` (off by default in checkov, and in
+  // Infraweaver) makes checkov resolve and scan INSIDE registry/git modules. The
+  // refactor `b.4` path (adopting a third-party module) MUST turn this on: a
+  // naive re-scan with it off stops looking inside the adopted module, so a pile
+  // of findings would vanish without being fixed — a false ✗→✓ ("finding-
+  // laundering"). Off by default keeps the normal scan fast and offline.
+  // Same integrity gate as trivy/tflint. No checkov advisory exists today, so
+  // this is a no-op denylist check — but it also probes the version, which the
+  // evidence bundle's provenance block records (A.3): the signed bundle names
+  // the exact scanner builds that produced its findings.
+  assertToolchainIntegrity("checkov", cwd);
+  const egress = egressEnvFor("checkov", network);
+  const args = [
+    "-d",
+    ".",
+    "--framework",
+    ...frameworks,
+    "-o",
+    "json",
+    "--quiet",
+  ];
+  if (downloadExternalModules) args.push("--download-external-modules", "true");
+  const r = run("checkov", args, cwd, egress ?? undefined);
+  if (r.missing) return skipped("checkov", "checkov not installed");
+  try {
+    return {
+      source: "checkov",
+      ran: true,
+      concerns: parseCheckovOutput(r.stdout, cwd),
+      ...(egress ? { egress_isolation: "partial" as const } : {}),
+    };
+  } catch {
+    return skipped("checkov", "could not parse checkov json output");
+  }
+}
+
+/** parse `checkov -o json` output (object for one framework, array for several).
+ *  Each block's `check_type` names the framework that produced it (terraform /
+ *  cloudformation / kubernetes / …) — carried onto every concern as its language. */
+export function parseCheckovOutput(stdout: string, cwd = ""): Concern[] {
+  const parsed = parseScannerJson(CheckovOutputs, stdout, "checkov");
+  const blocks = Array.isArray(parsed) ? parsed : [parsed];
+  const concerns: Concern[] = [];
+  for (const block of blocks) {
+    const language = checkovTypeToLanguage(block.check_type);
+    for (const check of block.results?.failed_checks ?? []) {
+      // checkov emits 0 for "no specific line"; normalize to null (matching the
+      // trivy parser and the reviewer's findings.json) so the content id is
+      // stable and a reviewer-loaded checkov concern re-verifies ✗→✓.
+      const startLine = check.file_line_range?.[0];
+      const rule = check.check_id ?? "issue";
+      concerns.push(
+        buildConcern({
+          source: "checkov",
+          rule,
+          file: toRepoRelative(check.file_path, cwd),
+          line:
+            typeof startLine === "number" && startLine > 0 ? startLine : null,
+          severity: lowerSeverity(check.severity ?? undefined),
+          category: "security",
+          evidence: check.check_name ?? rule,
+          code_snippet: checkovCodeSnippet(check.code_block),
+          remediation_hint: check.guideline ?? null,
+          language,
+        }),
+      );
+    }
+  }
+  return concerns;
+}
+
+/** The offending source from a checkov finding's `code_block` — an array of
+ *  `[lineNumber, content]` pairs for the flagged resource block. */
+function checkovCodeSnippet(
+  block: [number, string][] | null | undefined,
+): string | null {
+  if (!block?.length) return null;
+  return tidySnippet(
+    block.slice(0, SNIPPET_MAX_LINES).map(([, content]) => content ?? ""),
+  );
+}
+
+const CheckovFailedCheck = type({
+  "check_id?": "string",
+  "check_name?": "string",
+  "severity?": "string | null",
+  "file_path?": "string",
+  "file_line_range?": "number[]",
+  "code_block?": type(["number", "string"]).array(),
+  "guideline?": "string",
+});
+const CheckovOutput = type({
+  "check_type?": "string",
+  "results?": { "failed_checks?": CheckovFailedCheck.array() },
+});
+// object for one framework, array for several — see parseCheckovOutput.
+const CheckovOutputs = CheckovOutput.or(CheckovOutput.array());
+
+/**
+ * Terraform files changed on the current branch vs the base. Returns null when
+ * the base can't be determined (caller then falls back to a full scan).
+ */
+export function changedTerraformFiles(cwd: string): Set<string> | null {
+  const base = resolveBaseRef(cwd);
+  if (!base) return null;
+  const mergeBase = run("git", ["merge-base", base, "HEAD"], cwd);
+  const from =
+    mergeBase.status === 0 && mergeBase.stdout.trim()
+      ? mergeBase.stdout.trim()
+      : base;
+  const diff = run("git", ["diff", "--name-only", from, "HEAD"], cwd);
+  if (diff.status !== 0) return null;
+  // `git diff` reports paths relative to the repo ROOT, but a concern's
+  // `location.file` is relative to the scan `cwd` (toRepoRelative). When `cwd`
+  // is a repo SUBDIRECTORY (the `cwd` action input resolved under
+  // GITHUB_WORKSPACE) the two path spaces disagree — e.g. git says
+  // `infra/main.tf` while the concern says `main.tf` — and the in-scope check
+  // would silently drop every concern. Re-base the diff paths onto `cwd` by
+  // stripping the cwd→root prefix and discarding anything outside it, so both
+  // sides are cwd-relative.
+  const prefixResult = run("git", ["rev-parse", "--show-prefix"], cwd);
+  const prefix =
+    prefixResult.status === 0
+      ? prefixResult.stdout.trim().replace(/\\/g, "/")
+      : "";
+  const files: string[] = [];
+  for (const raw of diff.stdout.split("\n")) {
+    let f = raw.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+    if (!f) continue;
+    if (prefix) {
+      if (!f.startsWith(prefix)) continue; // changed file lives outside the scanned subdir
+      f = f.slice(prefix.length);
+    }
+    if (f.endsWith(".tf") || f.endsWith(".tfvars")) files.push(f);
+  }
+  return new Set(files);
+}
+
+export interface RunScannersOptions {
+  /** the resolved tool selection. A scanner whose tool is gated/disabled
+   * is reported as a `skipped` outcome (with the licence/disable reason) instead
+   * of running, so `terraform_scan` and the ✗→✓ verifier see the SAME toolchain. */
+  selection?: ResolvedToolSelection | undefined;
+  /** module-fetch credential env, threaded into `terraform validate`'s
+   * init so a private cross-repo `git::` module resolves during a scan. */
+  terraformEnv?: Record<string, string> | undefined;
+  /** when true, checkov resolves and scans INSIDE registry/git modules
+   * (`--download-external-modules true`). Required by the refactor b.4 path so
+   * adopting a third-party module can't launder its internal findings; off by
+   * default to keep the normal scan fast and offline. */
+  downloadExternalModules?: boolean | undefined;
+  /** checkov `--framework` values (see checkovFrameworksFor). Defaults to the
+   * Terraform-only pair — the fix loop never widens; the read-only Assess path
+   * passes the language-scope-derived set for multi-language breadth. */
+  checkovFrameworks?: string[] | undefined;
+  /** per-scanner egress policy (supply-chain 0.2, the `tools_network` input).
+   * A denied tool runs under the blackhole-proxy env overlay and its outcome
+   * records `egress_isolation: "partial"`. Absent ⇒ open egress (today's
+   * behaviour) — deny is opt-in. */
+  toolsNetwork?: ToolsNetworkDirective | undefined;
+}
+
+/** run every scanner once over `cwd`. shared by `terraform_scan` and the
+ * deterministic remediation verifier so both see the identical toolchain. A
+ * scanner the selection has turned off is emitted as `skipped` (never run), so
+ * the gate applies identically to the scan and its verification re-scan. */
+export function runScanners(
+  cwd: string,
+  opts: RunScannersOptions = {},
+): ScannerOutcome[] {
+  const {
+    selection,
+    terraformEnv,
+    downloadExternalModules,
+    checkovFrameworks,
+    toolsNetwork,
+  } = opts;
+  const gate = (
+    source: Concern["source"],
+    runner: () => ScannerOutcome,
+  ): ScannerOutcome => {
+    if (!selection) return runner();
+    const id = scannerToolId(source);
+    if (id && !selection.enabled(id)) {
+      return skipped(
+        source,
+        selection.offReason(id) ?? "disabled by tools_enabled",
+      );
+    }
+    return runner();
+  };
+  const upstream = [
+    // validate runs first so its `terraform init` has happened by the time the
+    // native pack asks for the provider schema — otherwise the persisted-secret
+    // rule would report a coverage gap on a tree that could in fact be judged.
+    gate("terraform-fmt", () => scanFmt(cwd)),
+    gate("terraform-validate", () => scanValidate(cwd, terraformEnv)),
+    gate("tflint", () => scanTflint(cwd, toolsNetwork)),
+    gate("trivy", () => scanTrivy(cwd, toolsNetwork)),
+    gate("checkov", () =>
+      scanCheckov(
+        cwd,
+        downloadExternalModules,
+        checkovFrameworks,
+        toolsNetwork,
+      ),
+    ),
+  ];
+  // The native pack is never gated: it is our own code, carries no third-party
+  // licence, and shells out to nothing (`scannerToolId` returns null for it).
+  return [...upstream, scanNative(cwd)];
+}
+
+export interface RemediationVerdict {
+  /** true only when every original concern id is absent from the re-scan. */
+  verified: boolean;
+  /** original ids no longer present (the fix cleared them). */
+  resolved: string[];
+  /** original ids still present (the fix did NOT clear them). */
+  remaining: string[];
+}
+
+/**
+ * Deterministic ✗→✓ check: partition the group's original `concern_ids` into
+ * those gone from a fresh scan (`resolved`) and those still present
+ * (`remaining`). Concern ids are content hashes (`sha1(source|rule|file|line)`),
+ * so a missing id means that exact concern is gone — the correct primitive for
+ * "did the fix clear it", independent of severity/scope filtering. This is the
+ * code-level replacement for the agent eyeballing a re-scan and self-reporting.
+ */
+export function computeRemediationVerdict(
+  originalConcernIds: string[],
+  currentConcernIds: Set<string>,
+): RemediationVerdict {
+  const resolved: string[] = [];
+  const remaining: string[] = [];
+  for (const id of originalConcernIds) {
+    if (currentConcernIds.has(id)) remaining.push(id);
+    else resolved.push(id);
+  }
+  return { verified: remaining.length === 0, resolved, remaining };
+}
+
+/**
+ * Regression guard. The full re-scan (`terraform_verify_remediation`)
+ * already sees the whole workspace, so a concern the fix *introduced* shows up
+ * in the current scan. Regressions are exactly the content ids present after the
+ * fix that were not in the pre-fix baseline — `current − baseline`. A non-empty
+ * result means the fix traded one defect for another (e.g. an encryption block
+ * that trips a different tflint rule) and must downgrade the PR to needs-human.
+ *
+ * Both id sets are computed the same way (the deduped union of every scanner's
+ * concern ids, unfiltered by severity) so the diff is apples-to-apples — a
+ * regression at ANY severity is caught, not just ones above the run threshold.
+ * Returns sorted ids for a stable PR body.
+ */
+export function computeRegressions(
+  baselineConcernIds: Iterable<string>,
+  currentConcernIds: Iterable<string>,
+): string[] {
+  const baseline = new Set(baselineConcernIds);
+  const regressions = new Set<string>();
+  for (const id of currentConcernIds) {
+    if (!baseline.has(id)) regressions.add(id);
+  }
+  return [...regressions].sort();
+}
+
+/**
+ * Line-INDEPENDENT ✗→✓ partition (the integrity-preserving replacement for the
+ * raw-id `computeRemediationVerdict` when scan context is available). Each
+ * requested entry carries its display `id` and its `key` (see `concernKeyOf`);
+ * a concern is `remaining` iff its KEY still appears in the re-scan, else
+ * `resolved`. Because a fix that shifts lines keeps the same (source|rule|file)
+ * key, an unfixed concern can no longer be mis-reported as resolved. Pure.
+ */
+export function partitionByKey(
+  requested: { id: string; key: string }[],
+  currentKeys: Set<string>,
+): RemediationVerdict {
+  const resolved: string[] = [];
+  const remaining: string[] = [];
+  for (const r of requested) {
+    if (currentKeys.has(r.key)) remaining.push(r.id);
+    else resolved.push(r.id);
+  }
+  return { verified: remaining.length === 0, resolved, remaining };
+}
+
+/**
+ * Line-INDEPENDENT regression set: one representative current concern id per KEY
+ * present in the re-scan but absent from the pre-fix baseline keys. A pre-existing
+ * concern that merely shifted to a new line (same key) is NOT a regression — only
+ * a genuinely new (rule, file) defect is. Replaces the raw-id `computeRegressions`
+ * for the integrity path. Pure; returns sorted ids for a stable PR body.
+ */
+export function regressionIdsByKey(
+  current: { id: string; key: string }[],
+  baselineKeys: Set<string>,
+): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const c of current) {
+    if (baselineKeys.has(c.key) || seen.has(c.key)) continue;
+    seen.add(c.key);
+    out.push(c.id);
+  }
+  return out.sort();
+}