infraweaver 0.1.0

package/src/mcp/terraform/types.ts

@@ -0,0 +1,382 @@
+import { createHash } from "node:crypto";
+import { toolSkip } from "#app/mcp/shared";
+import type { IacLanguage } from "#app/mcp/terraform/iacLanguages";
+
+/**
+ * A degrade-green skip result carrying the structured envelope
+ * (`ok: false` + machine `code` + human `detail`) PLUS the legacy alias the tool
+ * returned before it converged on the envelope — `ran`/`found` and
+ * `skipped_reason`/`reason` — so existing prompt + test contracts keep working.
+ * Additive, never breaking. `extra` folds in any tool-specific fields (e.g.
+ * read_findings' empty `concerns`/`groups`).
+ */
+export function skipResult(
+  code: string,
+  detail: string,
+  opts: {
+    key?: "ran" | "found";
+    reasonKey?: "skipped_reason" | "reason";
+    extra?: Record<string, any>;
+  } = {},
+): Record<string, any> {
+  const key = opts.key ?? "ran";
+  const reasonKey = opts.reasonKey ?? "skipped_reason";
+  return {
+    ...toolSkip(code, detail),
+    [key]: false,
+    [reasonKey]: detail,
+    ...(opts.extra ?? {}),
+  };
+}
+
+/**
+ * Internal "concern" model — the Remediator's ground truth for "what is not
+ * best practice". Produced by `terraform_scan` from the fork's own deterministic
+ * Terraform check tools (fmt / validate / tflint / trivy / checkov).
+ *
+ * This is a deliberate SUBSET of the reviewer's `findings.schema.json` v1.0
+ * (../terraform-reviewer/schemas/findings.schema.json). The reviewer's findings
+ * add `lens` / `standard` / `control_id` / `state` on top. Keeping the shape a
+ * subset means a future reviewer integration (read_findings) can emit the same
+ * Concern[] with no change to the modes or the rest of the tools — only the
+ * SOURCE of concerns swaps.
+ */
+export interface Concern {
+  /** stable content id: sha1(source|rule_id|file|line). idempotency key for branch/PR naming. */
+  id: string;
+  /** producing tool. `infraweaver` is the NATIVE rule pack ([[nativeRules]]) — the
+   * findings no upstream scanner can produce, re-derived on every scan so they stay
+   * ✗→✓ verifiable. `reviewer` marks a concern loaded from a terraform-reviewer
+   * findings.json whose original tool isn't one Infraweaver re-runs (tfsec / infracost
+   * / llm) — its provenance lives in `rule_id`. */
+  source:
+    | "terraform-fmt"
+    | "terraform-validate"
+    | "tflint"
+    | "trivy"
+    | "checkov"
+    | "infraweaver"
+    | "reviewer";
+  /** original namespaced rule, e.g. "trivy:AVD-AWS-0088" */
+  rule_id: string;
+  severity: Severity;
+  category: "security" | "style" | "correctness" | "cost";
+  /** the scanner message — what is wrong */
+  evidence: string;
+  location: { file: string; line: number | null };
+  /** the IaC language the flagged file is written in (from the scanner's own
+   * classification — trivy `Type` / checkov `check_type`). Absent on the
+   * Terraform-only scanners (fmt/validate/tflint) and reviewer-loaded concerns;
+   * scope filtering falls back to a path classification then terraform.
+   * NOT part of the content `id` — purely descriptive, additive. */
+  language?: IacLanguage;
+  /** the offending source line(s) the scanner flagged (trivy cause lines /
+   *  checkov code block), so a reader sees the exact code, not just file:line.
+   *  Absent when the scanner doesn't attach source context. */
+  code_snippet?: string | null;
+  remediation_hint: string | null;
+  suppression?: ConcernSuppression;
+  /** 2c taxonomy: the canonical resource+misconfig class this rule maps to (e.g.
+   *  "aws-s3-encryption"), set when cross-scanner normalisation recognises it. */
+  canonical_class?: string;
+  /** 2c taxonomy: the scanner(s) that flagged this canonical issue, after a
+   *  cross-scanner merge (e.g. ["checkov", "trivy"]). */
+  flagged_by?: string[];
+}
+
+export interface ConcernSuppression {
+  source: "inline" | "policy";
+  reason: string;
+  expires: string | null;
+}
+
+export const SEVERITIES = [
+  "critical",
+  "high",
+  "medium",
+  "low",
+  "info",
+] as const;
+export type Severity = (typeof SEVERITIES)[number];
+
+export const SEVERITY_RANK: Record<Severity, number> = {
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1,
+  info: 0,
+};
+
+export const SEVERITY_CVSS_SCORE: Record<Severity, number> = {
+  critical: 9.5,
+  high: 8.0,
+  medium: 5.0,
+  low: 2.0,
+  info: 0.0,
+};
+
+export const CVSS_SEVERITY_BANDS: ReadonlyArray<{
+  min: number;
+  severity: Severity;
+}> = [
+  { min: 9.0, severity: "critical" },
+  { min: 7.0, severity: "high" },
+  { min: 4.0, severity: "medium" },
+  { min: 0.1, severity: "low" },
+];
+
+export function severityFromCvss(score: number): Severity {
+  for (const band of CVSS_SEVERITY_BANDS) {
+    if (score >= band.min) return band.severity;
+  }
+  return "info";
+}
+
+export function cvssScoreForSeverity(severity: Severity): number {
+  return SEVERITY_CVSS_SCORE[severity];
+}
+
+export function concernId(
+  source: string,
+  ruleId: string,
+  file: string,
+  line: number | null,
+): string {
+  return createHash("sha1")
+    .update(`${source}|${ruleId}|${file}|${line ?? ""}`)
+    .digest("hex")
+    .slice(0, 12);
+}
+
+/**
+ * The single constructor every scanner parser uses to turn a raw finding into a
+ * `Concern`. It owns the one coupling that must never drift: the content `id`
+ * (`sha1(source|rule|file|line)`) and the namespaced `rule_id` (`source:rule`)
+ * are BOTH derived from the same bare `rule` here, so a parser can't accidentally
+ * hash one rule string while labelling the concern with another — which would
+ * silently break `remediate/<id>` branch naming and the ✗→✓ re-scan match.
+ *
+ * The per-scanner bits that genuinely differ (severity map, category, evidence
+ * text, remediation hint, whether a source snippet is attached) stay explicit at
+ * the call site — they're not uniform enough to hide behind a config object
+ * without obscuring each parser. `code_snippet` is only set when provided, so
+ * fmt/validate/tflint concerns keep their exact prior shape (no `code_snippet`
+ * key) and trivy/checkov keep theirs (`code_snippet` before `remediation_hint`).
+ */
+export function buildConcern(input: {
+  source: Concern["source"];
+  /** the BARE rule (e.g. `unformatted`, `AVD-AWS-0088`), NOT `source:rule`. */
+  rule: string;
+  file: string;
+  line: number | null;
+  severity: Severity;
+  category: Concern["category"];
+  evidence: string;
+  remediation_hint: string | null;
+  code_snippet?: string | null;
+  /** the scanner-reported IaC language (trivy `Type` / checkov `check_type`);
+   * omit for the Terraform-only scanners — descriptive only, never hashed. */
+  language?: IacLanguage | null;
+}): Concern {
+  const {
+    source,
+    rule,
+    file,
+    line,
+    severity,
+    category,
+    evidence,
+    remediation_hint,
+  } = input;
+  const base = {
+    id: concernId(source, rule, file, line),
+    source,
+    rule_id: `${source}:${rule}`,
+    severity,
+    category,
+    evidence,
+    location: { file, line },
+    ...(input.language ? { language: input.language } : {}),
+  };
+  return input.code_snippet !== undefined
+    ? { ...base, code_snippet: input.code_snippet, remediation_hint }
+    : { ...base, remediation_hint };
+}
+
+/**
+ * A LINE-INDEPENDENT identity for a concern — which rule fires in which file,
+ * ignoring the exact line. Two instances of the same rule in the same file at
+ * different lines share a key.
+ *
+ * The full content `id` keys on the line so it's unique per instance (right for
+ * SARIF alerts + branch naming), but that makes it UNSTABLE under a fix: almost
+ * every fix adds or removes lines, shifting every concern below it to a new line
+ * → a new id. If ✗→✓ verification compared raw ids, a shifted-but-unfixed concern
+ * would look RESOLVED (old id gone) and simultaneously look like a REGRESSION
+ * (new id appeared) — a false attestation either way. `terraform_verify_remediation`
+ * compares on this key instead, so a line shift can't fabricate a resolution or a
+ * regression. Derived identically to `id` minus the line (same bare-rule
+ * normalization) so keys match across the original scan and the re-scan.
+ */
+/** Strip a rule id's own `<source>:` namespace prefix, if present — the
+ *  normalization shared by `concernKeyOf` (per-file key) and the fix-memory
+ *  finding-TYPE key (`source|bareRule`, file-independent). One helper so the two
+ *  can never disagree on what "the same rule" means. */
+export function bareRuleOf(source: string, ruleId: string): string {
+  const prefix = `${source}:`;
+  return ruleId.startsWith(prefix) ? ruleId.slice(prefix.length) : ruleId;
+}
+
+export function concernKeyOf(
+  c: Pick<Concern, "source" | "rule_id" | "location">,
+): string {
+  return createHash("sha1")
+    .update(`${c.source}|${bareRuleOf(c.source, c.rule_id)}|${c.location.file}`)
+    .digest("hex")
+    .slice(0, 12);
+}
+
+export type ScannerOutcome = {
+  source: Concern["source"];
+  ran: boolean;
+  skipped_reason?: string;
+  concerns: Concern[];
+  /**
+   * For `terraform validate` only: count of roots where terraform RAN but its
+   * `-json` output could not be parsed (a real CLI-level failure, not a missing
+   * binary). Lets the validate tool report `passed` as fail-closed instead of
+   * silently treating an un-validated root as clean. Undefined/0 elsewhere.
+   */
+  unvalidated?: number;
+  /**
+   * A scanner that RAN but whose coverage was incomplete — one named check inside
+   * it could not execute. Distinct from `ran: false` (nothing ran) and from an
+   * empty `concerns` (everything ran and found nothing), which is exactly the
+   * distinction that stops a partially-blind scan reading as a clean one. Folded
+   * into the verification summary's INCONCLUSIVE list, never dropped.
+   */
+  partial?: { check: string; reason: string };
+  /**
+   * Set when this scanner executed under egress denial (supply-chain 0.2).
+   * Always the honest word "partial": the control is an env-level proxy
+   * contract, not a kernel boundary — a malicious binary can ignore it. The
+   * run summary records it so an assessor can see WHICH findings were produced
+   * under bounded egress; absence means the tool ran with open egress.
+   */
+  egress_isolation?: "partial";
+};
+
+export function skipped(
+  source: Concern["source"],
+  reason: string,
+): ScannerOutcome {
+  return { source, ran: false, skipped_reason: reason, concerns: [] };
+}
+
+/**
+ * Re-base a concern produced by a per-root command (its file is relative to the
+ * root dir) onto the scan `cwd` by prefixing the root's `relDir`, and recompute
+ * the content id so it stays consistent with the cwd-relative scanners (✗→✓).
+ * A no-op when `relDir` is "" (the root IS cwd).
+ */
+export function rebaseConcern(c: Concern, relDir: string): Concern {
+  if (!relDir) return c;
+  const file = `${relDir}/${c.location.file}`.replace(/\/+/g, "/");
+  const prefix = `${c.source}:`;
+  const bareRule = c.rule_id.startsWith(prefix)
+    ? c.rule_id.slice(prefix.length)
+    : c.rule_id;
+  return {
+    ...c,
+    location: { ...c.location, file },
+    id: concernId(c.source, bareRule, file, c.location.line),
+  };
+}
+
+/** true when a path is a Terraform source file Infraweaver may remediate. */
+export function isTerraformFile(file: string): boolean {
+  const f = file.toLowerCase();
+  return f.endsWith(".tf") || f.endsWith(".tfvars");
+}
+
+/**
+ * The FIX-LOOP filter: Remediate is Terraform-first. A concern in a
+ * non-`.tf`/`.tfvars` file can never be remediated (the `allowed_paths` push
+ * guardrail blocks the edit, and the `✗→✓` proof machinery is Terraform-specific).
+ * The single chokepoint that enforces this is `buildConcernResult`
+ * (concernResult.ts), through which EVERY fixer-feeding surface routes —
+ * `terraform_scan`, `read_findings`, `detect_plan_drift` and
+ * `ingest_external_findings` — so a non-Terraform concern can never reach grouping,
+ * a PR branch, or the verifier no matter which tool produced it.
+ * The READ-ONLY surfaces (Assess / SARIF / evidence) deliberately do NOT use this
+ * filter: they scope by detected IaC language instead (`inLanguageScope`), which is
+ * how multi-language Assess widens breadth without ever faking a fix proof for a
+ * format the machinery can't verify.
+ */
+export function isTerraformConcern(c: Concern): boolean {
+  return isTerraformFile(c.location.file);
+}
+
+export function dedupe(concerns: Concern[]): Concern[] {
+  const seen = new Set<string>();
+  const out: Concern[] = [];
+  for (const c of concerns) {
+    if (seen.has(c.id)) continue;
+    seen.add(c.id);
+    out.push(c);
+  }
+  return out;
+}
+
+export function sortConcerns(concerns: Concern[]): Concern[] {
+  return [...concerns].sort((a, b) => {
+    const sev = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (sev !== 0) return sev;
+    return a.id.localeCompare(b.id);
+  });
+}
+
+export function lowerSeverity(s: string | undefined): Severity {
+  const v = (s ?? "").toLowerCase();
+  return (SEVERITIES as readonly string[]).includes(v)
+    ? (v as Severity)
+    : "medium";
+}
+
+/**
+ * A scoped unit of work = all concerns in one file. Different scanners flag the
+ * same underlying defect under different rule ids (trivy ∩ checkov overlap
+ * heavily on e.g. S3 buckets), so per-concern PRs would spam many PRs for one
+ * bad file. Remediate acts on ONE group per PR (branch `remediate/<group.id>`),
+ * fixing every concern in the file together and proving them all cleared (✗→✓).
+ */
+export interface ConcernGroup {
+  /** stable id — the remediation branch/PR key (`remediate/<id>`). Derived from
+   * the file (by-file grouping) or the rule (by-rule grouping). */
+  id: string;
+  /** the group's primary file (by-file) or a human label like "3 files"
+   * (by-rule); `files` carries the full list for by-rule groups. */
+  file: string;
+  /** every file the group spans. one entry for a by-file group; the
+   * full set for a by-rule group (the agent must fix the rule in all of them). */
+  files?: string[];
+  /** how the group was formed — `file` (default) or `rule`. */
+  grouping?: "file" | "rule";
+  /** highest severity among the group's concerns. */
+  severity: Severity;
+  concern_count: number;
+  /** distinct rule ids in the group, for the PR body. */
+  rule_ids: string[];
+  /** the concern ids the re-scan must confirm are gone to call this ✓. */
+  concern_ids: string[];
+  /** `auto` (open a normal PR) or `needs-human` (escalate). attached by
+   * the scan tool from the group's concerns, not by `groupConcerns` (which has
+   * no autonomy threshold). undefined until the scan tool annotates it. */
+  autonomy?: Autonomy;
+  /** why the group was escalated (empty/absent for `auto`). */
+  autonomy_reasons?: string[];
+}
+
+export type Autonomy = "auto" | "needs-human";
+
+export type BlastTier = "low" | "medium" | "high";

package/src/mcp/terraform/verification.ts

@@ -0,0 +1,150 @@
+import { classifyRefusal } from "#app/mcp/terraform/decisions";
+import { bandVerdictReason, nativeRuleOf } from "#app/mcp/terraform/nativeRules";
+import type { Concern, ScannerOutcome } from "#app/mcp/terraform/types";
+
+/**
+ * Five-status verification taxonomy (the auditor-credibility win the evidence
+ * pack + crosswalk both lean on). The point is HONESTY: never let "no finding"
+ * read as "compliant", and never claim the engine proved something it cannot see
+ * from code. Every assessment statement carries exactly one of these:
+ *
+ *   - `pass`                — a check ran and code-verified compliance.
+ *   - `fail`                — a check ran and code-verified a violation.
+ *   - `not-applicable`      — the control does not apply to the resources present.
+ *   - `inconclusive`        — a relevant check did NOT run (gated / not installed /
+ *                             unparseable). A coverage gap, never silently a pass.
+ *   - `not-code-verifiable` — the control needs human / process evidence
+ *                             (governance, training, a key-policy decision); IaC
+ *                             scanning structurally cannot prove it either way.
+ *
+ * What this engine asserts today: `fail` and `not-code-verifiable` per concern,
+ * and `inconclusive` per scanner that didn't run. It deliberately does NOT
+ * fabricate `pass` / `not-applicable` for controls nothing fired on — absence of
+ * a finding is not proof, and over-claiming is exactly what costs credibility
+ * with an assessor. The two reserved statuses are part of the shared vocabulary
+ * for the evidence consumer (and a future full-framework crosswalk). Pure.
+ */
+
+export const VERIFICATION_STATUSES = [
+  "pass",
+  "fail",
+  "not-applicable",
+  "inconclusive",
+  "not-code-verifiable",
+] as const;
+export type VerificationStatus = (typeof VERIFICATION_STATUSES)[number];
+
+/** one-line legend per status — for the report / evidence bundle. */
+export const VERIFICATION_STATUS_LABEL: Record<VerificationStatus, string> = {
+  pass: "a check ran and code-verified compliance",
+  fail: "a check ran and code-verified a violation",
+  "not-applicable": "the control does not apply to the resources present",
+  inconclusive: "a relevant check did not run — a coverage gap, not a pass",
+  "not-code-verifiable": "needs human / process evidence — IaC cannot prove it",
+};
+
+/** the statuses the engine asserts per concern (a concern is always one or the
+ * other — it fired, the only question is whether code can prove the fix). */
+export type ConcernVerificationStatus = Extract<VerificationStatus, "fail" | "not-code-verifiable">;
+
+/**
+ * Classify one concern: a code-verified violation (`fail`) — UNLESS its
+ * remediation is a human decision the engine can flag but not prove from code
+ * (IAM least-privilege, a KMS key policy, a real CIDR — the refusal set), in
+ * which case it is `not-code-verifiable`. Pure.
+ *
+ * A NATIVE rule ([[nativeRules]]) is decided by its declared band FIRST, and the
+ * band is checked before the keyword-matching refusal set on purpose: a
+ * governance rule's own text (which names what it deliberately does not assert)
+ * must never be able to trip a refusal regex into a different reason, and a
+ * `verified` native rule must never be downgraded because its evidence happens
+ * to contain a word like "policy".
+ */
+export function concernVerificationStatus(concern: Pick<Concern, "rule_id" | "evidence">): {
+  status: ConcernVerificationStatus;
+  reason?: string;
+} {
+  const native = nativeRuleOf(concern.rule_id);
+  if (native) {
+    const reason = bandVerdictReason(native);
+    return reason ? { status: "not-code-verifiable", reason } : { status: "fail" };
+  }
+  const refusal = classifyRefusal(concern);
+  if (refusal.refuse) {
+    return refusal.reason
+      ? { status: "not-code-verifiable", reason: refusal.reason }
+      : { status: "not-code-verifiable" };
+  }
+  return { status: "fail" };
+}
+
+export interface VerifiedConcern {
+  id: string;
+  status: ConcernVerificationStatus;
+  reason?: string;
+}
+
+export interface VerificationSummary {
+  /** per-concern verification status. */
+  concerns: VerifiedConcern[];
+  counts: {
+    fail: number;
+    not_code_verifiable: number;
+    /** scanners that did not run (each is a coverage gap). */
+    inconclusive: number;
+  };
+  coverage: {
+    /** scanners that ran — their checks are code-verified for what they cover. */
+    verified: string[];
+    /** scanners that did NOT run — their checks are INCONCLUSIVE, never a pass. */
+    inconclusive: { source: string; reason: string }[];
+  };
+  /** the honesty caveat an assessor should read alongside the statuses. */
+  note: string;
+}
+
+const HONESTY_NOTE =
+  "Statuses are code-verified only. A scanner that did not run leaves its checks " +
+  "INCONCLUSIVE (a coverage gap, not a pass); controls needing human/process " +
+  "evidence are NOT-CODE-VERIFIABLE. Absence of a finding is not proof of compliance.";
+
+/**
+ * Roll a scan up into a verification summary: every concern classified
+ * (fail / not-code-verifiable) and every scanner partitioned into verified (ran)
+ * vs inconclusive (skipped — gated, not installed, or unparseable). Pure;
+ * `outcomes` is the raw `runScanners` result, `concerns` the deduped,
+ * Terraform-only set the assessment reports on.
+ */
+export function buildVerificationSummary(
+  concerns: Pick<Concern, "id" | "rule_id" | "evidence">[],
+  outcomes: ScannerOutcome[],
+): VerificationSummary {
+  const verified: VerifiedConcern[] = concerns.map((c) => {
+    const v = concernVerificationStatus(c);
+    return v.reason
+      ? { id: c.id, status: v.status, reason: v.reason }
+      : { id: c.id, status: v.status };
+  });
+
+  const verifiedTools: string[] = [];
+  const inconclusiveTools: { source: string; reason: string }[] = [];
+  for (const o of outcomes) {
+    if (o.ran) verifiedTools.push(o.source);
+    else inconclusiveTools.push({ source: o.source, reason: o.skipped_reason ?? "did not run" });
+    // A scanner can run AND still be partially blind. That named sub-check is a
+    // coverage gap in its own right — listing it alongside the scanners that
+    // didn't run at all is the only way "verified" stays a truthful word.
+    if (o.partial) inconclusiveTools.push({ source: o.partial.check, reason: o.partial.reason });
+  }
+
+  return {
+    concerns: verified,
+    counts: {
+      fail: verified.filter((c) => c.status === "fail").length,
+      not_code_verifiable: verified.filter((c) => c.status === "not-code-verifiable").length,
+      inconclusive: inconclusiveTools.length,
+    },
+    coverage: { verified: verifiedTools, inconclusive: inconclusiveTools },
+    note: HONESTY_NOTE,
+  };
+}