infraweaver 0.1.0

package/src/mcp/terraform/vex.ts

@@ -0,0 +1,367 @@
+/**
+ * CycloneDX 1.7 VEX emitter — the same read-only assessment as
+ * [[evidence]]/[[oscal]], rendered as a Vulnerability Exploitability eXchange
+ * document a downstream security scanner / SBOM consumer ingests directly.
+ *
+ * Honesty rules (matching the evidence bundle):
+ *   - Statuses derive from the five-status verdict: a code-verified violation
+ *     (`fail`) is `exploitable`; a human-decision control the engine can flag
+ *     but not prove (`not-code-verifiable`) is `in_triage`. We NEVER emit
+ *     `not_affected` — an unfired control is a coverage gap, not a clearance.
+ *   - Deterministic: name-based UUIDs (the v5-from-sha256 helper shared with
+ *     [[oscal]]), clock passed in — same inputs ⇒ byte-identical output.
+ *   - Scanner rule ids ride in `id`/`source`; file/line in the affected `file`
+ *     components + per-vulnerability properties.
+ *
+ * Signed via [[signing]] when INFRAWEAVER_SIGNING_KEY is present, exactly like
+ * the evidence bundle (detached `.sig` beside the file).
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { type } from "arktype";
+import { PRODUCT_NAME, TOOL_NAME, VEX_FILE } from "#app/brand";
+import { runAssessmentPipeline } from "#app/mcp/assess";
+import type { LocalToolContext } from "#app/mcp/localContext";
+import { resolveWithinCwd } from "#app/mcp/pathSafety";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import type { EvidenceSubject } from "#app/mcp/terraform/evidence";
+import {
+  buildInTotoStatement,
+  keylessBundlePath,
+  keylessSigningPossible,
+  keylessSignStatement,
+} from "#app/mcp/terraform/keyless";
+import { deterministicUuid } from "#app/mcp/terraform/oscal";
+import {
+  loadSigningKey,
+  type SignatureMetadata,
+  signatureMetadata,
+  signBytes,
+} from "#app/mcp/terraform/signing";
+import type { Concern, Severity } from "#app/mcp/terraform/types";
+import {
+  type ConcernVerificationStatus,
+  concernVerificationStatus,
+} from "#app/mcp/terraform/verification";
+import { log } from "#app/utils/cli";
+import { githubContext } from "#app/utils/env";
+import { redactSecrets } from "#app/utils/redact";
+import packageJson from "#package.json" with { type: "json" };
+
+/**
+ * The spec version emitted. CycloneDX 1.7 is ECMA-424 2nd edition — the version
+ * SBOM/VEX consumers standardise on, so emitting 1.6 would date the artefact.
+ *
+ * The document deliberately stays inside the 1.6 STRUCTURAL SUBSET: every field
+ * used here exists in both schemas, so a 1.6-only consumer still parses it.
+ * `vex.test.ts` validates the same bytes against both schema fixtures, which is
+ * what turns that from an intention into a guarantee.
+ *
+ * The signing path is untouched by this: signatures cover the exact bytes on
+ * disk, not the schema they conform to.
+ */
+export const CYCLONEDX_SPEC_VERSION = "1.7" as const;
+
+/** The older spec version the emitted document remains parseable as. */
+export const CYCLONEDX_COMPATIBLE_SPEC_VERSION = "1.6" as const;
+export const DEFAULT_VEX_PATH = `compliance/${VEX_FILE}`;
+
+/** CycloneDX impact-analysis states this emitter may produce. `not_affected`
+ * is deliberately NOT in this union: absence of a finding is not proof, so an
+ * unfired control never becomes a clearance. */
+export type VexAnalysisState = "exploitable" | "in_triage";
+
+interface VexProperty {
+  name: string;
+  value: string;
+}
+
+interface VexComponent {
+  type: "file";
+  "bom-ref": string;
+  name: string;
+}
+
+interface VexVulnerability {
+  "bom-ref": string;
+  /** the scanner's rule id (trivy AVD-*, checkov CKV_*, tflint rule…). */
+  id: string;
+  source: { name: string };
+  description: string;
+  ratings: { severity: Severity; method: "other" }[];
+  analysis: {
+    state: VexAnalysisState;
+    detail: string;
+  };
+  affects: { ref: string }[];
+  properties: VexProperty[];
+}
+
+export interface CycloneDxVexDocument {
+  bomFormat: "CycloneDX";
+  specVersion: typeof CYCLONEDX_SPEC_VERSION;
+  serialNumber: string;
+  version: number;
+  metadata: {
+    timestamp: string;
+    tools: {
+      components: {
+        type: "application";
+        name: typeof TOOL_NAME;
+        version: string;
+      }[];
+    };
+    component: { type: "application"; "bom-ref": string; name: string };
+    properties: VexProperty[];
+  };
+  components: VexComponent[];
+  vulnerabilities: VexVulnerability[];
+}
+
+const SUBJECT_REF = "infraweaver:workspace";
+
+const HONESTY_NOTE =
+  "Indicative, scanner-derived VEX from a deterministic rule-pack — statuses are code-verified " +
+  "only. `not_affected` is never emitted: an unfired control is a coverage gap, not a clearance.";
+
+/** the five-status verdict → CycloneDX impact-analysis state (honest subset). */
+export function vexAnalysisState(
+  status: ConcernVerificationStatus,
+): VexAnalysisState {
+  return status === "fail" ? "exploitable" : "in_triage";
+}
+
+function subjectName(s: EvidenceSubject): string {
+  return s.repo ? `${s.repo}${s.ref ? `@${s.ref}` : ""}` : s.scanned_dir;
+}
+
+/**
+ * Build the CycloneDX 1.7 VEX document from the assessment's OPEN concerns.
+ * Pure (clock/identity passed in); UUIDs are name-based, seeded like the OSCAL
+ * emitter — same inputs ⇒ identical bytes (the seed includes the generation
+ * timestamp, so ids are stable per generation, not across wall-clock re-runs).
+ * One vulnerability per concern; each affected file becomes a `file` component
+ * the vulnerability `affects` by bom-ref. When `signature` is supplied the
+ * public key + fingerprint are embedded in the document's metadata properties
+ * (inside the signed bytes), so a consumer holding only the artefact + `.sig`
+ * can verify it offline — the same self-contained contract as the evidence
+ * bundle.
+ */
+export function buildVexDocument(args: {
+  concerns: Concern[];
+  subject: EvidenceSubject;
+  generatedAt: string;
+  version?: string;
+  signature?: SignatureMetadata | null;
+}): CycloneDxVexDocument {
+  const { concerns, subject, generatedAt } = args;
+  const seed = `${subject.commit ?? subject.scanned_dir}|${generatedAt}`;
+
+  const fileRefs = new Map<string, VexComponent>();
+  const vulnerabilities: VexVulnerability[] = [];
+  for (const c of concerns) {
+    const file = c.location.file.replace(/\\/g, "/").replace(/^\.\//, "");
+    const fileRef = `file:${file}`;
+    if (!fileRefs.has(fileRef)) {
+      fileRefs.set(fileRef, { type: "file", "bom-ref": fileRef, name: file });
+    }
+    const { status, reason } = concernVerificationStatus(c);
+    const state = vexAnalysisState(status);
+    vulnerabilities.push({
+      "bom-ref": deterministicUuid(`vex|${seed}|${c.id}`),
+      id: c.rule_id,
+      source: { name: c.source },
+      // LLM02: evidence + suppression reason are repo/agent-derived — redact before
+      // they land in the signed, downstream-ingested VEX document.
+      description: redactSecrets(c.evidence),
+      ratings: [{ severity: c.severity, method: "other" }],
+      analysis: {
+        state,
+        detail: redactSecrets(
+          state === "exploitable"
+            ? `code-verified violation (five-status verdict: ${status})`
+            : `needs human/process evidence — IaC cannot prove it (five-status verdict: ${status}${reason ? `; ${reason}` : ""})`,
+        ),
+      },
+      affects: [{ ref: fileRef }],
+      properties: [
+        { name: "infraweaver:concern_id", value: c.id },
+        { name: "infraweaver:file", value: file },
+        { name: "infraweaver:line", value: String(c.location.line ?? "") },
+        { name: "infraweaver:verification_status", value: status },
+      ],
+    });
+  }
+
+  return {
+    bomFormat: "CycloneDX",
+    specVersion: CYCLONEDX_SPEC_VERSION,
+    serialNumber: `urn:uuid:${deterministicUuid(`vex-serial|${seed}`)}`,
+    version: 1,
+    metadata: {
+      timestamp: generatedAt,
+      tools: {
+        components: [
+          {
+            type: "application",
+            name: TOOL_NAME,
+            version: args.version ?? packageJson.version,
+          },
+        ],
+      },
+      component: {
+        type: "application",
+        "bom-ref": SUBJECT_REF,
+        name: subjectName(subject),
+      },
+      properties: [
+        { name: "infraweaver:honesty", value: HONESTY_NOTE },
+        ...(args.signature
+          ? [
+              {
+                name: "infraweaver:signature:algorithm",
+                value: args.signature.algorithm,
+              },
+              {
+                name: "infraweaver:signature:public_key",
+                value: args.signature.public_key,
+              },
+              {
+                name: "infraweaver:signature:fingerprint_sha256",
+                value: args.signature.fingerprint_sha256,
+              },
+              {
+                name: "infraweaver:signature:detached_signature",
+                value: args.signature.detached_signature,
+              },
+            ]
+          : []),
+      ],
+    },
+    components: [...fileRefs.values()].sort((a, b) =>
+      a.name.localeCompare(b.name),
+    ),
+    vulnerabilities,
+  };
+}
+
+export const TerraformEmitVexParams = type({
+  "output_path?": type.string.describe(
+    `where to write the CycloneDX VEX (default: ./${DEFAULT_VEX_PATH}). Commit it so the compliance/ path is the auditable trail.`,
+  ),
+  "severity_threshold?": type(
+    "'critical' | 'high' | 'medium' | 'low' | 'info'",
+  ).describe(
+    "minimum severity to include (default: the run's configured threshold, else low).",
+  ),
+});
+
+export function TerraformEmitVexTool(ctx: LocalToolContext) {
+  return tool({
+    name: "terraform_emit_vex",
+    description:
+      `Emit the read-only assessment as a CYCLONEDX ${CYCLONEDX_SPEC_VERSION} VEX document (default ` +
+      `\`${DEFAULT_VEX_PATH}\`) — the same open concerns as \`terraform_emit_evidence\`, in the ` +
+      "vulnerability-exchange format a downstream SBOM/security scanner ingests directly. Each concern " +
+      "becomes one `vulnerabilities[]` entry: the scanner rule id in `id`/`source`, file/line in the " +
+      "affected `file` component + properties, and an HONEST `analysis.state` from the five-status verdict " +
+      "(`exploitable` for a code-verified violation, `in_triage` for a human-decision control) — " +
+      "`not_affected` is NEVER emitted for an unfired control. UUIDs are name-based (deterministic for " +
+      "the same commit + generation time); when INFRAWEAVER_SIGNING_KEY is set the document is signed " +
+      "(detached Ed25519 `.sig` beside the file, public key + fingerprint embedded in the metadata " +
+      "properties so it verifies offline). It NEVER modifies Terraform or opens a PR. Pairs with " +
+      `\`terraform_emit_evidence\` (${PRODUCT_NAME}'s own schema) and \`terraform_emit_oscal\` (GRC import).`,
+    parameters: TerraformEmitVexParams,
+    execute: execute(async ({ output_path, severity_threshold }) => {
+      const configured = ctx.payload.severityThreshold as Severity | undefined;
+      const threshold: Severity = severity_threshold ?? configured ?? "low";
+      const { cwd, open } = runAssessmentPipeline(ctx, threshold);
+
+      // SECURITY: confine the agent-supplied path to the workspace (same guard
+      // as terraform_emit_evidence / terraform_emit_sarif).
+      const target = resolveWithinCwd(cwd, output_path ?? DEFAULT_VEX_PATH);
+      // load (and validate) the key BEFORE any bytes hit disk — a set-but-
+      // malformed key must fail the tool without leaving an unsigned artefact
+      // behind for a retry/later step to pick up (same order as evidence.ts).
+      const signingKey = loadSigningKey();
+      const sigPath = `${target}.sig`;
+      const gh = githubContext();
+      const doc = buildVexDocument({
+        concerns: open,
+        subject: {
+          scanned_dir: cwd,
+          repo: gh.repository,
+          ref: gh.refName,
+          commit: gh.sha,
+        },
+        generatedAt: new Date().toISOString(),
+        signature: signingKey
+          ? signatureMetadata(signingKey, basename(sigPath))
+          : null,
+      });
+      const bytes = `${JSON.stringify(doc, null, 2)}\n`;
+      // the default compliance/ dir may not exist yet on a first run.
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, bytes);
+      // same signing contract as the evidence bundle: detached signature over
+      // the exact bytes the artefact holds on disk.
+      if (signingKey)
+        writeFileSync(sigPath, `${signBytes(bytes, signingKey)}\n`);
+
+      // Second tier: keyless Sigstore attestation of the VEX (opt-in, CI-only,
+      // best-effort — same contract as terraform_emit_evidence). Binds the exact
+      // VEX bytes to the workflow OIDC identity, logged to Rekor.
+      let keylessBundleFile: string | undefined;
+      if (keylessSigningPossible()) {
+        try {
+          const statement = buildInTotoStatement({
+            subjectName: basename(target),
+            artifactBytes: bytes,
+            predicate: {
+              spec_version: CYCLONEDX_SPEC_VERSION,
+              vulnerabilities: doc.vulnerabilities.length,
+              generated_at: doc.metadata.timestamp,
+              subject: { repo: gh.repository, ref: gh.refName, commit: gh.sha },
+            },
+          });
+          const sigstoreBundle = await keylessSignStatement(statement);
+          keylessBundleFile = keylessBundlePath(target);
+          writeFileSync(
+            keylessBundleFile,
+            `${JSON.stringify(sigstoreBundle, null, 2)}\n`,
+          );
+          log.info(
+            `» terraform_emit_vex: keyless Sigstore attestation → ${keylessBundleFile}`,
+          );
+        } catch (e) {
+          log.warning(
+            `» terraform_emit_vex: keyless signing failed (VEX still emitted): ${e instanceof Error ? e.message : String(e)}`,
+          );
+        }
+      }
+      log.info(
+        `» terraform_emit_vex: ${doc.vulnerabilities.length} vulnerability statement(s) → ${target}` +
+          (signingKey
+            ? ` (signed ed25519, key ${signingKey.fingerprint.slice(0, 16)}…)`
+            : ""),
+      );
+      return toolOk({
+        output_path: target,
+        vulnerabilities: doc.vulnerabilities.length,
+        spec_version: CYCLONEDX_SPEC_VERSION,
+        signed: signingKey !== null,
+        ...(signingKey
+          ? {
+              signature_path: sigPath,
+              key_fingerprint_sha256: signingKey.fingerprint,
+            }
+          : {}),
+        keyless_signed: keylessBundleFile !== undefined,
+        ...(keylessBundleFile
+          ? { keyless_bundle_path: keylessBundleFile }
+          : {}),
+        note: `${basename(target)} is CycloneDX ${CYCLONEDX_SPEC_VERSION} (ECMA-424 2nd ed.), written inside the ${CYCLONEDX_COMPATIBLE_SPEC_VERSION} structural subset so older consumers still parse it — attach it to the compliance trail or feed it to an SBOM-aware scanner.`,
+      });
+    }),
+  });
+}

package/src/mcp/terraform/writeOnly.ts

@@ -0,0 +1,252 @@
+/**
+ * `secret-persisted-to-state` — the write-only / ephemeral-value finding class
+ * (Terraform 1.11+, OpenTofu 1.11+).
+ *
+ * THE DEFECT. Before write-only arguments, handing a provider a credential meant
+ * the credential landed in the state file in plain text — forever, in every
+ * historical state version, readable by everyone with state access, and copied
+ * into every backup. `terraform plan` could not avoid it: the value had to be in
+ * the plan to be sent to the provider. Write-only arguments (`password_wo` and
+ * its `password_wo_version` companion) fix this properly: the value is sent to
+ * the provider and then discarded, never serialised into state.
+ *
+ * WHY THE PROVIDER SCHEMA, NOT A RULE TABLE. Whether `password_wo` exists is a
+ * fact about the provider version the customer has pinned — providers adopted
+ * write-only arguments resource by resource, over several majors. A hardcoded
+ * catalogue of "resources that support write-only" would be wrong for somebody on
+ * the day it was written and wronger every month after, and it would propose
+ * `password_wo` on a provider where that argument does not exist — a "fix" that
+ * fails `terraform plan`. So the rule reads `terraform providers schema -json`
+ * (already loaded and cached by [[providerSchema]]) and fires ONLY when the
+ * installed provider genuinely declares the counterpart. No schema ⇒ no finding,
+ * reported as a coverage gap rather than guessed at.
+ *
+ * That also makes the remediation transform trivially correct: rename the
+ * argument to the counterpart the schema named, and add the `_wo_version` the
+ * schema named. Both sides come from the same source of truth, so the ✗→✓ re-scan
+ * clears the finding exactly when the edit is right.
+ *
+ * WHAT THIS RULE DELIBERATELY DOES NOT DO. The plan it came from paired it with a
+ * suppressor for stale UPSTREAM findings — a resource that has already migrated to
+ * `password_wo` can still trip "password stored in plaintext" rules in scanner
+ * packs that predate write-only arguments, and being punished for adopting the
+ * better pattern is a real incentive inversion. That suppressor is not here,
+ * because deciding another tool's finding is stale means pattern-matching its
+ * message text, and we have no verified example of such a message to match
+ * against. Guessing would risk waving away a real finding, which is a strictly
+ * worse failure than leaving a stale one visible. If a concrete offending rule id
+ * turns up, suppress that id — by evidence, not by regex.
+ *
+ * What IS handled here: this rule does not fire on a block that has already
+ * migrated (see the `assigned.has(wo)` check), so we never contradict ourselves.
+ *
+ * Pure except for `scanWriteOnlyFiles`, which consults the cached provider schema.
+ */
+import { loadProvidersSchema } from "#app/mcp/providerSchema";
+import {
+  isStringLiteral,
+  parseBlocks,
+  stripTrailingComment,
+  topLevelAssignments,
+} from "#app/mcp/terraform/hcl";
+import { NATIVE_SOURCE, SECRET_PERSISTED_TO_STATE } from "#app/mcp/terraform/nativeRules";
+import { buildConcern, type Concern } from "#app/mcp/terraform/types";
+
+/** Look up a resource type's attribute names in the installed provider schema.
+ *  Returns null when the type is unknown — the caller must then make NO claim. */
+export type ResourceAttributes = (resourceType: string) => ReadonlySet<string> | null;
+
+/** The write-only counterpart of an argument, by provider convention. */
+function writeOnlyNameFor(argument: string): string {
+  return `${argument}_wo`;
+}
+
+export interface WriteOnlySite {
+  resourceType: string;
+  resourceName: string;
+  /** the persisted argument as written, e.g. `password`. */
+  argument: string;
+  /** the counterpart the INSTALLED provider declares, e.g. `password_wo`. */
+  writeOnlyArgument: string;
+  /** the `_wo_version` companion, when the provider declares one. Null means the
+   *  provider takes the write-only argument without a version — do not invent it. */
+  versionArgument: string | null;
+  /** 1-based line of the offending assignment in the file. */
+  line: number;
+  /** true when the value is a bare string literal — a credential written into the
+   *  repo, not merely into state. Strictly worse, and not fixable by a rename. */
+  literal: boolean;
+  /** true when the value opens a heredoc, i.e. it continues past this line. The
+   *  finding is unaffected (the value is persisted either way) but a single-line
+   *  rewrite cannot express it, so none is offered. */
+  multiline: boolean;
+  /** the assignment as written. */
+  before: string;
+  /** the behaviour-equivalent write-only form. Empty for a `literal` or
+   *  `multiline` value: there is no correct one-line rewrite for either, and
+   *  offering one would imply the transform had solved a problem it hasn't. */
+  after: string;
+}
+
+/** Terraform meta-arguments never carry a provider value, so a `_wo` collision on
+ *  one could only be a coincidence of naming. Excluded so a future provider
+ *  attribute named e.g. `count_wo` can't make us rewrite a meta-argument. */
+const META_ARGUMENTS: ReadonlySet<string> = new Set([
+  "count",
+  "for_each",
+  "provider",
+  "depends_on",
+  "lifecycle",
+  "provisioner",
+  "connection",
+]);
+
+/**
+ * Every argument in `hcl` that is persisted to state while the installed provider
+ * offers a write-only counterpart.
+ *
+ * Skipped without a finding: a resource type the schema doesn't know (we cannot
+ * judge it), a block that already assigns the counterpart (mid-migration, or the
+ * author set both — a provider-level conflict `terraform validate` reports better
+ * than we could), and meta-arguments.
+ */
+export function findPersistedSecrets(
+  hcl: string,
+  attributesFor: ResourceAttributes,
+): WriteOnlySite[] {
+  const out: WriteOnlySite[] = [];
+  for (const block of parseBlocks(hcl, ["resource"])) {
+    const [resourceType = "", resourceName = ""] = block.labels;
+    const attributes = attributesFor(resourceType);
+    if (!attributes) continue; // unknown to the installed providers — make no claim
+    const assignments = topLevelAssignments(block.body);
+    const assigned = new Set(assignments.map((a) => a.name));
+    for (const a of assignments) {
+      if (META_ARGUMENTS.has(a.name) || a.name.endsWith("_wo")) continue;
+      const wo = writeOnlyNameFor(a.name);
+      if (!attributes.has(wo)) continue; // provider offers no write-only form
+      if (assigned.has(wo)) continue; // already migrated (or both set — not our call)
+      const versionArgument = attributes.has(`${wo}_version`) ? `${wo}_version` : null;
+      const value = stripTrailingComment(a.value);
+      const literal = isStringLiteral(a.value);
+      const multiline = value.startsWith("<<");
+      out.push({
+        resourceType,
+        resourceName,
+        argument: a.name,
+        writeOnlyArgument: wo,
+        versionArgument,
+        line: block.bodyLine + a.bodyLine - 1,
+        literal,
+        multiline,
+        before: `${a.name} = ${value}`,
+        after:
+          literal || multiline
+            ? ""
+            : [`${wo} = ${value}`, ...(versionArgument ? [`${versionArgument} = 1`] : [])].join(
+                "\n",
+              ),
+      });
+    }
+  }
+  return out;
+}
+
+/** The remediation hint for one site — the exact edit, or the reason there isn't
+ *  a mechanical one. */
+export function writeOnlyHint(site: WriteOnlySite): string {
+  if (site.literal) {
+    return (
+      `\`${site.argument}\` holds a literal value, so it is in the repository as well as in state. ` +
+      "Rotate it, move it to a secret manager or an ephemeral input, and only then switch to " +
+      `\`${site.writeOnlyArgument}\`` +
+      (site.versionArgument ? ` + \`${site.versionArgument} = 1\`` : "") +
+      " — renaming the argument alone would leave the secret committed."
+    );
+  }
+  if (site.multiline) {
+    return (
+      `Rename \`${site.argument}\` to \`${site.writeOnlyArgument}\`, keeping the heredoc body exactly as ` +
+      `it is` +
+      (site.versionArgument
+        ? `, and add \`${site.versionArgument} = 1\` after the closing delimiter`
+        : "") +
+      ". The value spans several lines, so no single-line rewrite is offered — the edit is the " +
+      "argument name, not the value."
+    );
+  }
+  return (
+    `Replace \`${site.before}\` with \`${site.writeOnlyArgument} = <the same expression>\`` +
+    (site.versionArgument
+      ? ` and add \`${site.versionArgument} = 1\` (bump it whenever the value changes — that is how the provider is told to re-send it)`
+      : "") +
+    ". The provider receives the value and discards it instead of writing it to state."
+  );
+}
+
+/**
+ * Turn detected sites into native concerns.
+ *
+ * Severity is the band floor (`medium`) for the mechanical case and `high` for a
+ * literal: a referenced secret in state is a real exposure with a one-line fix,
+ * whereas a committed literal needs rotation before anything else and should
+ * escalate. That split is also what keeps the mechanical case auto-remediable —
+ * `classifyAutonomy` routes high-severity security findings to a human, which is
+ * correct for the literal and wrong for the rename.
+ */
+export function persistedSecretsToConcerns(sites: WriteOnlySite[], file: string): Concern[] {
+  return sites.map((site) =>
+    buildConcern({
+      source: NATIVE_SOURCE,
+      rule: SECRET_PERSISTED_TO_STATE,
+      file,
+      line: site.line,
+      severity: site.literal ? "high" : "medium",
+      category: "security",
+      evidence:
+        `${site.resourceType}.${site.resourceName}: \`${site.argument}\` is written to Terraform state in ` +
+        `plain text — the installed provider declares \`${site.writeOnlyArgument}\`, which is not persisted` +
+        (site.literal ? ", and the value here is a hardcoded literal" : ""),
+      remediation_hint: writeOnlyHint(site),
+      // the offending line as written, so a reader sees the code and not just a line number.
+      code_snippet: site.before,
+    }),
+  );
+}
+
+// --- workspace scan (I/O composition) ----------------------------------------
+
+export interface WriteOnlyScan {
+  concerns: Concern[];
+  /** set when the provider schema was unavailable, so this rule did NOT run. An
+   *  honest coverage gap, never a silent pass. */
+  coverageGap: string | null;
+}
+
+/**
+ * The workspace-level entry point, over files ALREADY READ by the caller —
+ * `[repo-relative POSIX path, contents]` pairs. The native pack reads the tree
+ * once and passes the same text to every rule; re-reading each `.tf` per rule
+ * would double the I/O of every scan on exactly the monorepos where it hurts.
+ */
+export function scanWriteOnlyFiles(
+  cwd: string,
+  files: ReadonlyArray<readonly [string, string]>,
+): WriteOnlyScan {
+  const schema = loadProvidersSchema(cwd);
+  const attributesFor: ResourceAttributes = (t) => schema?.get(t)?.attributes ?? null;
+  const concerns: Concern[] = [];
+  if (schema) {
+    for (const [file, text] of files) {
+      concerns.push(...persistedSecretsToConcerns(findPersistedSecrets(text, attributesFor), file));
+    }
+  }
+  return {
+    concerns,
+    coverageGap: schema
+      ? null
+      : "provider schema unavailable (the directory is not `terraform init`-ed, or terraform is not " +
+        "installed) — whether a write-only counterpart exists is a fact about the INSTALLED provider, " +
+        "so no persisted-secret claim was made either way",
+  };
+}

package/src/mcp/terraform.ts

@@ -0,0 +1,52 @@
+/**
+ * Facade for the Terraform MCP toolchain. The implementation lives in the
+ * per-concern modules under `./terraform/`; this file re-exports every symbol so
+ * existing importers (`#app/mcp/terraform`) keep resolving unchanged.
+ *
+ *   types     — Concern + shared types/helpers (ids, paths, roots, severity)
+ *   scanners  — fmt / validate / tflint / trivy / checkov + provider/arg schema
+ *   decisions — grouping, autonomy, confidence, refusal, prevention, co-location
+ *   cost      — infracost breakdown / delta / escalation
+ *   currency  — registry version currency (provider + module upgrade intel)
+ *   registry  — published-module lookup/search (public + private registries)
+ *   findings  — reviewer findings + SARIF ingest/emit
+ *   plan      — plan parsing + destroy/blast/stability/aggregation
+ *   tools     — the MCP Tool factories + their *Params schemas
+ *   verification — the five-status taxonomy (fail / not-code-verifiable / …)
+ *   evidence  — the backend-free compliance evidence bundle + emitter
+ *   signing   — detached Ed25519 signing for the compliance artefacts
+ *   vex       — the CycloneDX 1.7 VEX emitter
+ *   nativeRules  — the native rule pack's registry (ids, bands, honesty pairs)
+ *   writeOnly    — secret-persisted-to-state + its FP suppression
+ *   governance   — action triggers + dynamic destroy protection
+ *   tfquery      — *.tfquery.hcl discovery inventory (never remediation input)
+ *   hcl          — the shared, tolerant HCL block scanner every rule reads through
+ */
+
+export * from "#app/mcp/terraform/cost";
+export * from "#app/mcp/terraform/currency";
+export * from "#app/mcp/terraform/decisions";
+export * from "#app/mcp/terraform/evidence";
+export * from "#app/mcp/terraform/findings";
+export * from "#app/mcp/terraform/governance";
+export * from "#app/mcp/terraform/hcl";
+export * from "#app/mcp/terraform/moduleDocs";
+export * from "#app/mcp/terraform/nativeRules";
+export * from "#app/mcp/terraform/nativeScan";
+export * from "#app/mcp/terraform/normalization";
+export * from "#app/mcp/terraform/oscal";
+export * from "#app/mcp/terraform/paths";
+export * from "#app/mcp/terraform/plan";
+export * from "#app/mcp/terraform/policyAuthor";
+export * from "#app/mcp/terraform/refactor";
+export * from "#app/mcp/terraform/registry";
+export * from "#app/mcp/terraform/risk";
+export * from "#app/mcp/terraform/scanners";
+export * from "#app/mcp/terraform/signing";
+export * from "#app/mcp/terraform/subprocess";
+export * from "#app/mcp/terraform/tfquery";
+export * from "#app/mcp/terraform/tools";
+export * from "#app/mcp/terraform/types";
+export * from "#app/mcp/terraform/verification";
+export * from "#app/mcp/terraform/vex";
+export * from "#app/mcp/terraform/writeOnly";