terramend 0.2.0

package/src/mcp/commitInfo.test.ts

@@ -0,0 +1,127 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { CommitInfoTool } from "#app/mcp/commitInfo";
+import type { ToolContext } from "#app/mcp/server";
+
+type ToolResultShape = { content: [{ type: "text"; text: string }]; isError?: boolean };
+
+async function runTool(t: { execute?: unknown }, params: unknown): Promise<ToolResultShape> {
+  const exec = t.execute as (p: unknown, c: unknown) => Promise<ToolResultShape>;
+  return exec(params, {});
+}
+
+const fullCommit = {
+  sha: "abc1234def5678",
+  html_url: "https://gh/commit/abc1234",
+  commit: {
+    message: "fix: tighten bucket policy",
+    author: { date: "2026-01-01T00:00:00Z" },
+    committer: { date: "2026-01-02T00:00:00Z" },
+  },
+  author: { login: "alice" },
+  committer: null,
+  parents: [{ sha: "p1" }, { sha: "p2" }],
+  stats: { additions: 3, deletions: 1, total: 4 },
+  files: [
+    {
+      filename: "main.tf",
+      patch: "@@ -1,2 +1,3 @@\n resource\n+  versioning = true\n }",
+    },
+  ],
+};
+
+function makeCtx(commitData: Record<string, unknown>) {
+  const getCommit = vi.fn(async (_p: unknown) => ({ data: commitData }));
+  const ctx = {
+    octokit: { rest: { repos: { getCommit } } },
+    repo: { owner: "octo", name: "repo" },
+  } as unknown as ToolContext;
+  return { ctx, getCommit };
+}
+
+describe("CommitInfoTool", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "terramend-commitinfo-"));
+    vi.stubEnv("TERRAMEND_TEMP_DIR", tempDir);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("returns commit metadata and writes the formatted diff to disk", async () => {
+    const { ctx, getCommit } = makeCtx(fullCommit);
+    const result = await runTool(CommitInfoTool(ctx), { sha: "abc1234def5678" });
+
+    expect(result.isError).toBeUndefined();
+    expect(getCommit).toHaveBeenCalledWith({ owner: "octo", repo: "repo", ref: "abc1234def5678" });
+
+    const text = result.content[0].text;
+    expect(text).toContain("fix: tighten bucket policy");
+    expect(text).toContain("alice");
+    expect(text).toContain("2026-01-01T00:00:00Z");
+    expect(text).toContain("fileCount: 1");
+    expect(text).toContain("commit-abc1234.diff");
+
+    const diff = readFileSync(join(tempDir, "commit-abc1234.diff"), "utf-8");
+    expect(diff).toContain("main.tf");
+    expect(diff).toContain("versioning = true");
+  });
+
+  it("falls back to committer date and zeroed stats when fields are missing", async () => {
+    const { ctx } = makeCtx({
+      ...fullCommit,
+      author: undefined,
+      committer: { login: "bot" },
+      commit: { message: "chore", committer: { date: "2026-02-02T00:00:00Z" } },
+      stats: undefined,
+      files: undefined,
+      parents: [],
+    });
+    const result = await runTool(CommitInfoTool(ctx), { sha: "abc1234def5678" });
+
+    expect(result.isError).toBeUndefined();
+    const text = result.content[0].text;
+    expect(text).toContain("author: null");
+    expect(text).toContain("bot");
+    expect(text).toContain("2026-02-02T00:00:00Z");
+    expect(text).toContain("fileCount: 0");
+    expect(text).toContain("additions: 0");
+  });
+
+  it("renders an empty date when neither author nor committer dates exist", async () => {
+    const { ctx } = makeCtx({
+      ...fullCommit,
+      commit: { message: "chore" },
+      files: [{ filename: "image.png" }],
+    });
+    const result = await runTool(CommitInfoTool(ctx), { sha: "abc1234def5678" });
+
+    expect(result.isError).toBeUndefined();
+    const diff = readFileSync(join(tempDir, "commit-abc1234.diff"), "utf-8");
+    expect(diff).toContain("(binary file or no changes)");
+  });
+
+  it("errors when TERRAMEND_TEMP_DIR is not set", async () => {
+    vi.stubEnv("TERRAMEND_TEMP_DIR", "");
+    const { ctx } = makeCtx(fullCommit);
+    const result = await runTool(CommitInfoTool(ctx), { sha: "abc1234def5678" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("TERRAMEND_TEMP_DIR not set");
+  });
+
+  it("surfaces API failures as tool errors", async () => {
+    const { ctx, getCommit } = makeCtx(fullCommit);
+    getCommit.mockRejectedValueOnce(new Error("No commit found"));
+    const result = await runTool(CommitInfoTool(ctx), { sha: "deadbeef" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("No commit found");
+  });
+});

package/src/mcp/commitInfo.ts

@@ -0,0 +1,61 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { type } from "arktype";
+import { formatFilesWithLineNumbers } from "#app/mcp/checkout";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+
+export const CommitInfo = type({
+  sha: type.string.describe("the commit SHA (full or abbreviated) to fetch"),
+});
+
+export function CommitInfoTool(ctx: ToolContext) {
+  return tool({
+    name: "get_commit_info",
+    description:
+      "Retrieve commit metadata and diff via GitHub API. Use this instead of git show for reviewing commits - " +
+      "it works with shallow clones and shows the actual changes in the commit. Returns diffPath pointing to formatted diff file. " +
+      'Example: `get_commit_info({ sha: "2a6ab5d" })`.',
+    parameters: CommitInfo,
+    execute: execute(async ({ sha }) => {
+      const response = await ctx.octokit.rest.repos.getCommit({
+        owner: ctx.repo.owner,
+        repo: ctx.repo.name,
+        ref: sha,
+      });
+
+      const data = response.data;
+      const files = data.files ?? [];
+
+      // format diff with line numbers and write to file
+      const formatResult = formatFilesWithLineNumbers(files);
+      const tempDir = process.env.TERRAMEND_TEMP_DIR;
+      if (!tempDir) {
+        throw new Error(
+          "TERRAMEND_TEMP_DIR not set - get_commit_info must run in terramend action context",
+        );
+      }
+      const diffFile = join(tempDir, `commit-${sha.slice(0, 7)}.diff`);
+      writeFileSync(diffFile, formatResult.content);
+      log.debug(`wrote commit diff to ${diffFile} (${formatResult.content.length} bytes)`);
+
+      return {
+        sha: data.sha,
+        message: data.commit.message,
+        author: data.author?.login ?? null,
+        committer: data.committer?.login ?? null,
+        date: data.commit.author?.date ?? data.commit.committer?.date ?? "",
+        url: data.html_url,
+        parents: data.parents.map((p) => p.sha),
+        stats: {
+          additions: data.stats?.additions ?? 0,
+          deletions: data.stats?.deletions ?? 0,
+          total: data.stats?.total ?? 0,
+        },
+        fileCount: files.length,
+        diffFile,
+      };
+    }),
+  });
+}

package/src/mcp/crosswalk.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildCrosswalkReport,
+  ComplianceCrosswalkTool,
+  mapConcernToControls,
+} from "#app/mcp/crosswalk";
+import type { ToolContext } from "#app/mcp/server";
+
+describe("mapConcernToControls", () => {
+  it("maps an encryption concern to encryption controls", () => {
+    const { themes, controls } = mapConcernToControls({
+      rule_id: "trivy:AVD-AWS-0088",
+      evidence: "S3 bucket does not have server-side encryption enabled",
+    });
+    expect(themes).toContain("encryption-at-rest");
+    expect(controls.some((c) => c.framework === "CIS Controls v8")).toBe(true);
+    expect(controls.some((c) => c.framework === "NHS DSPT")).toBe(true);
+  });
+
+  it("maps a public-access concern to firewall/network controls", () => {
+    const { themes, controls } = mapConcernToControls({
+      rule_id: "checkov:CKV_AWS_260",
+      evidence: "Security group allows ingress from 0.0.0.0/0 to port 22",
+    });
+    expect(themes).toContain("public-exposure");
+    expect(controls.some((c) => c.framework === "Cyber Essentials")).toBe(true);
+  });
+
+  it("dedupes identical control refs across matched themes", () => {
+    // matches both encryption-in-transit (tls) and public-exposure (public)
+    const { controls } = mapConcernToControls({
+      rule_id: "x",
+      evidence: "public endpoint without TLS",
+    });
+    const keys = controls.map((c) => `${c.framework}|${c.control}`);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it("returns empty for an unmappable concern (honest, not forced)", () => {
+    const { themes, controls } = mapConcernToControls({
+      rule_id: "terraform-fmt:format",
+      evidence: "file is not canonically formatted",
+    });
+    expect(themes).toEqual([]);
+    expect(controls).toEqual([]);
+  });
+});
+
+describe("buildCrosswalkReport", () => {
+  it("builds per-concern entries, a by-framework index, and an unmapped list", () => {
+    const report = buildCrosswalkReport([
+      { id: "aaa", rule_id: "trivy:AVD-AWS-0088", evidence: "bucket not encrypted at rest" },
+      { id: "bbb", rule_id: "terraform-fmt:format", evidence: "not formatted" },
+    ]);
+    expect(report.entries.map((e) => e.concern_id)).toEqual(["aaa"]);
+    expect(report.unmapped_concern_ids).toEqual(["bbb"]);
+    expect(Object.keys(report.by_framework).length).toBeGreaterThan(0);
+    // version + review date are carried for reproducibility.
+    expect(report.version).toMatch(/^\d+\.\d+\.\d+$/);
+    expect(report.reviewed).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  it("by_framework controls are deduped and sorted", () => {
+    const report = buildCrosswalkReport([
+      { id: "a", rule_id: "r1", evidence: "encrypt at rest" },
+      { id: "b", rule_id: "r2", evidence: "encryption kms missing" },
+    ]);
+    for (const controls of Object.values(report.by_framework)) {
+      const ids = controls.map((c) => c.control);
+      expect(new Set(ids).size).toBe(ids.length);
+      expect([...ids]).toEqual([...ids].sort());
+    }
+  });
+
+  it("is deterministic for the same input", () => {
+    const input = [{ id: "a", rule_id: "r", evidence: "public ingress without encryption" }];
+    expect(buildCrosswalkReport(input)).toEqual(buildCrosswalkReport(input));
+  });
+});
+
+describe("ComplianceCrosswalkTool", () => {
+  it("wraps the report in the ok envelope with the indicative-crosswalk note", async () => {
+    const tool = ComplianceCrosswalkTool({} as unknown as ToolContext);
+    const exec = tool.execute as (
+      p: unknown,
+      c: unknown,
+    ) => Promise<{ content: [{ type: "text"; text: string }]; isError?: boolean }>;
+    const result = await exec(
+      {
+        concerns: [
+          { id: "a", rule_id: "trivy:AVD-AWS-0088", evidence: "bucket lacks encryption" },
+          { id: "z", rule_id: "none", evidence: "completely unrelated text" },
+        ],
+      },
+      {},
+    );
+
+    const text = result.content[0].text;
+    expect(result.isError).toBeUndefined();
+    expect(text).toContain("ok: true");
+    expect(text).toContain("concern_id: a");
+    expect(text).toContain("unmapped_concern_ids[1]: z");
+    expect(text).toContain("Indicative crosswalk");
+    expect(text).toContain("not an audit verdict");
+  });
+});

package/src/mcp/crosswalk.ts

@@ -0,0 +1,339 @@
+import { type } from "arktype";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool, toolOk } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+
+/**
+ * Compliance crosswalk (§differentiator 23 — "explain like I'm the auditor", the
+ * seed of the Part-6 moat). Maps a best-practice concern → the control families
+ * it touches across UK public-sector + general frameworks, so a remediation can
+ * be narrated to an assessor in their own language ("this closes NCSC Cloud
+ * Principle 2 / Cyber Essentials Secure Configuration") rather than as a raw
+ * scanner rule id.
+ *
+ * SCOPE / HONESTY: this is a deterministic STARTER rule-pack keyed on the
+ * defect's THEME (encryption, public exposure, least-privilege, logging, …),
+ * not a certified control-by-control mapping. The durable product is a
+ * versioned, framework-revision-pinned crosswalk (Part 6) — so every mapping
+ * carries the pack version + date and is labelled indicative, never an audit
+ * verdict. No open crosswalk to UK frameworks exists; this is the wedge.
+ */
+
+export const CROSSWALK_VERSION = "0.1.0";
+/** the date this rule-pack's framework references were last reviewed (absolute). */
+export const CROSSWALK_REVIEWED = "2026-06-07";
+
+export interface ControlRef {
+  /** the framework, e.g. "NCSC Cloud Security Principles". */
+  framework: string;
+  /** the control id within that framework, e.g. "Principle 2". */
+  control: string;
+  /** the control's short title. */
+  title: string;
+}
+
+/** a theme of defect, the signals that identify it, and the controls it maps to. */
+interface CrosswalkRule {
+  theme: string;
+  /** lowercased substrings that, if any appears in the rule_id/evidence, match. */
+  signals: string[];
+  controls: ControlRef[];
+}
+
+// The starter rule-pack. Themes are matched against the concern's rule_id +
+// evidence (lowercased). Ordered most-specific first; a concern can match
+// several themes (their controls are unioned). Kept deliberately small and
+// auditable — each control ref is a real, citable control family.
+const CROSSWALK: CrosswalkRule[] = [
+  {
+    theme: "encryption-at-rest",
+    // NB avoid the bare token "sse" — it's a substring of "essential"/"asset"
+    // and would false-match; use the explicit phrases instead.
+    signals: [
+      "encrypt",
+      "kms",
+      "server-side encryption",
+      "server_side_encryption",
+      "sse_algorithm",
+      "at rest",
+      "at-rest",
+      "unencrypted",
+    ],
+    controls: [
+      {
+        framework: "NCSC Cloud Security Principles",
+        control: "Principle 1",
+        title: "Data in transit protection",
+      },
+      {
+        framework: "Cyber Essentials",
+        control: "Secure Configuration",
+        title: "Secure configuration",
+      },
+      { framework: "CIS Controls v8", control: "3.11", title: "Encrypt sensitive data at rest" },
+      {
+        framework: "NHS DSPT",
+        control: "Standard 1",
+        title: "Personal confidential data protected",
+      },
+    ],
+  },
+  {
+    theme: "encryption-in-transit",
+    signals: ["tls", "ssl", "https", "in transit", "in-transit", "insecure protocol", "http "],
+    controls: [
+      {
+        framework: "NCSC Cloud Security Principles",
+        control: "Principle 1",
+        title: "Data in transit protection",
+      },
+      { framework: "CIS Controls v8", control: "3.10", title: "Encrypt sensitive data in transit" },
+    ],
+  },
+  {
+    theme: "public-exposure",
+    signals: ["public", "0.0.0.0/0", "publicly", "anonymous", "open to the internet", "ingress"],
+    controls: [
+      {
+        framework: "NCSC Cloud Security Principles",
+        control: "Principle 9",
+        title: "Secure user management / network separation",
+      },
+      {
+        framework: "Cyber Essentials",
+        control: "Firewalls",
+        title: "Boundary firewalls and internet gateways",
+      },
+      {
+        framework: "CIS Controls v8",
+        control: "4.4",
+        title: "Implement and manage a firewall on servers",
+      },
+      {
+        framework: "Secure by Design",
+        control: "SbD-7",
+        title: "Protect data in transit and at rest",
+      },
+    ],
+  },
+  {
+    theme: "least-privilege",
+    signals: [
+      "iam",
+      "wildcard",
+      "least privilege",
+      "least-privilege",
+      "policy",
+      "admin",
+      "privilege",
+      "*:*",
+      "role",
+    ],
+    controls: [
+      {
+        framework: "NCSC Cloud Security Principles",
+        control: "Principle 9",
+        title: "Secure user management",
+      },
+      {
+        framework: "Cyber Essentials",
+        control: "User Access Control",
+        title: "User access control",
+      },
+      {
+        framework: "CIS Controls v8",
+        control: "6.8",
+        title: "Define and maintain role-based access control",
+      },
+      { framework: "NHS DSPT", control: "Standard 4", title: "Managing access" },
+    ],
+  },
+  {
+    theme: "logging-audit",
+    // NB avoid the bare token "log" — it's a substring of "catalog"/"blog" and
+    // would false-match; use the explicit phrases/longer tokens instead.
+    signals: [
+      "logging",
+      "log group",
+      "audit",
+      "cloudtrail",
+      "flow log",
+      "access log",
+      "monitoring",
+      "cloudwatch",
+    ],
+    controls: [
+      {
+        framework: "NCSC Cloud Security Principles",
+        control: "Principle 13",
+        title: "Audit information and alerting",
+      },
+      { framework: "CIS Controls v8", control: "8.2", title: "Collect audit logs" },
+      { framework: "NHS DSPT", control: "Standard 7", title: "Continuity planning / monitoring" },
+      { framework: "SOC 2", control: "CC7.2", title: "Security monitoring" },
+    ],
+  },
+  {
+    theme: "backup-resilience",
+    signals: ["versioning", "backup", "snapshot", "retention", "deletion protection", "multi-az"],
+    controls: [
+      {
+        framework: "NCSC Cloud Security Principles",
+        control: "Principle 2",
+        title: "Asset protection and resilience",
+      },
+      { framework: "NHS DSPT", control: "Standard 7", title: "Continuity planning" },
+      { framework: "CIS Controls v8", control: "11.2", title: "Perform automated backups" },
+    ],
+  },
+  {
+    theme: "secrets-management",
+    signals: ["secret", "credential", "password", "hardcoded", "plaintext", "access key", "token"],
+    controls: [
+      {
+        framework: "NCSC Cloud Security Principles",
+        control: "Principle 10",
+        title: "Identity and authentication",
+      },
+      { framework: "CIS Controls v8", control: "16.4", title: "Securely store credentials" },
+      {
+        framework: "Cyber Essentials",
+        control: "Secure Configuration",
+        title: "Secure configuration",
+      },
+    ],
+  },
+];
+
+/**
+ * Map a single concern to the indicative control references it touches. Matches
+ * the concern's `rule_id` + `evidence` (and an optional `category`) against the
+ * crosswalk themes; unions the controls of every theme that fires. Pure.
+ * Returns an empty array when nothing matches (honest — better than a forced
+ * mapping). De-duplicates identical control refs.
+ */
+export function mapConcernToControls(concern: {
+  rule_id: string;
+  evidence: string;
+  category?: string;
+}): { themes: string[]; controls: ControlRef[] } {
+  const haystack = `${concern.rule_id} ${concern.evidence}`.toLowerCase();
+  const themes: string[] = [];
+  const controls: ControlRef[] = [];
+  const seen = new Set<string>();
+  for (const rule of CROSSWALK) {
+    if (!rule.signals.some((s) => haystack.includes(s))) continue;
+    themes.push(rule.theme);
+    for (const c of rule.controls) {
+      const key = `${c.framework}|${c.control}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      controls.push(c);
+    }
+  }
+  return { themes, controls };
+}
+
+export interface ConcernForCrosswalk {
+  id: string;
+  rule_id: string;
+  evidence: string;
+  category?: string;
+  severity?: string;
+  location?: { file: string; line: number | null };
+}
+
+export interface CrosswalkEntry {
+  concern_id: string;
+  rule_id: string;
+  themes: string[];
+  controls: ControlRef[];
+}
+
+export interface CrosswalkReport {
+  version: string;
+  reviewed: string;
+  /** per-concern control mappings (only concerns that mapped to ≥1 control). */
+  entries: CrosswalkEntry[];
+  /** framework → the distinct controls this scan touched, for an auditor index. */
+  by_framework: Record<string, { control: string; title: string }[]>;
+  /** concerns that did not map to any control (honest coverage signal). */
+  unmapped_concern_ids: string[];
+}
+
+/**
+ * Build the auditor crosswalk for a set of concerns: per-concern control refs
+ * plus a `by_framework` index (which controls this scan touched, deduped) and an
+ * honest `unmapped` list. Pure + deterministic. Carries the pack version + date
+ * so the report is reproducible and clearly indicative.
+ */
+export function buildCrosswalkReport(concerns: ConcernForCrosswalk[]): CrosswalkReport {
+  const entries: CrosswalkEntry[] = [];
+  const unmapped: string[] = [];
+  const byFramework = new Map<string, Map<string, string>>();
+  for (const c of concerns) {
+    const { themes, controls } = mapConcernToControls(c);
+    if (controls.length === 0) {
+      unmapped.push(c.id);
+      continue;
+    }
+    entries.push({ concern_id: c.id, rule_id: c.rule_id, themes, controls });
+    for (const ctl of controls) {
+      const map = byFramework.get(ctl.framework) ?? new Map<string, string>();
+      if (!map.has(ctl.control)) map.set(ctl.control, ctl.title);
+      byFramework.set(ctl.framework, map);
+    }
+  }
+  const by_framework: Record<string, { control: string; title: string }[]> = {};
+  for (const [framework, controls] of [...byFramework.entries()].sort((a, b) =>
+    a[0].localeCompare(b[0]),
+  )) {
+    by_framework[framework] = [...controls.entries()]
+      .map(([control, title]) => ({ control, title }))
+      .sort((a, b) => a.control.localeCompare(b.control));
+  }
+  return {
+    version: CROSSWALK_VERSION,
+    reviewed: CROSSWALK_REVIEWED,
+    entries,
+    by_framework,
+    unmapped_concern_ids: unmapped,
+  };
+}
+
+export const ComplianceCrosswalkParams = type({
+  concerns: type({
+    id: type.string,
+    rule_id: type.string,
+    evidence: type.string,
+    "category?": type.string,
+    "severity?": type.string,
+  })
+    .array()
+    .describe("the concerns to map (pass the `concerns` array from terraform_scan/read_findings)."),
+});
+
+export function ComplianceCrosswalkTool(ctx: ToolContext) {
+  void ctx;
+  return tool({
+    name: "terraform_compliance_crosswalk",
+    description:
+      "Map a scan's concerns to the UK public-sector + general compliance controls they touch (§23) — NCSC " +
+      "Cloud Security Principles, Cyber Essentials, NHS DSPT, Secure by Design, CIS Controls, SOC 2 — so a " +
+      "remediation PR can be narrated to an ASSESSOR in their own framework. Pass the `concerns` from " +
+      "terraform_scan/read_findings; returns a per-concern control mapping plus a `by_framework` index and an " +
+      "honest `unmapped_concern_ids` list. The mapping is an INDICATIVE starter rule-pack (version + review " +
+      "date included) keyed on the defect theme — cite it as 'indicative alignment', never an audit verdict.",
+    parameters: ComplianceCrosswalkParams,
+    execute: execute(async ({ concerns }) => {
+      const report = buildCrosswalkReport(concerns as ConcernForCrosswalk[]);
+      log.info(
+        `» terraform_compliance_crosswalk: ${report.entries.length} mapped / ${report.unmapped_concern_ids.length} unmapped across ${Object.keys(report.by_framework).length} framework(s)`,
+      );
+      return toolOk({
+        ...report,
+        note: `Indicative crosswalk v${report.version} (reviewed ${report.reviewed}) — alignment guidance, not an audit verdict.`,
+      });
+    }),
+  });
+}