@intentius/chant-lexicon-github 0.1.23 → 0.3.0

package/src/lint/post-synth/gha029.ts

@@ -0,0 +1,68 @@
+/**
+ * GHA029: Unpinned Action or Reusable-Workflow Reference
+ *
+ * Flags any `uses:` (step action or job-level reusable workflow) that is pinned
+ * to a mutable tag or branch instead of a full 40-character commit SHA. A tag
+ * can be repointed to malicious code after review, so every external reference
+ * is a supply-chain trust decision.
+ *
+ * `actions/checkout` is intentionally left to the more specific GHA021. Local
+ * references (`./`, `../`) and `docker://` images (GHA030) are out of scope.
+ * Owners in the trusted allowlist are exempt.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractActionRefs, parseActionUses } from "./yaml-helpers";
+import { TRUSTED_ACTION_OWNERS } from "../rules/data/trusted-action-owners";
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+export interface UnpinnedRef {
+  job: string;
+  ref: string;
+  slug: string;
+}
+
+/**
+ * Find every action/reusable-workflow `uses:` that is not pinned to a commit
+ * SHA. Exposed as a pure function so the allowlist behaviour is testable.
+ */
+export function findUnpinnedActions(
+  yaml: string,
+  trustedOwners: ReadonlySet<string> = TRUSTED_ACTION_OWNERS,
+): UnpinnedRef[] {
+  const result: UnpinnedRef[] = [];
+  for (const { job, ref } of extractActionRefs(yaml)) {
+    const parsed = parseActionUses(ref);
+    if (!parsed) continue; // local or docker:// reference
+    if (parsed.slug === "actions/checkout") continue; // owned by GHA021
+    if (trustedOwners.has(parsed.owner)) continue;
+    if (SHA_RE.test(parsed.gitRef)) continue; // already pinned
+    result.push({ job, ref, slug: parsed.slug });
+  }
+  return result;
+}
+
+export const gha029: PostSynthCheck = {
+  id: "GHA029",
+  description: "Action or reusable workflow not pinned to a commit SHA",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, ref } of findUnpinnedActions(yaml)) {
+        diagnostics.push({
+          checkId: "GHA029",
+          severity: "warning",
+          message: `Job "${job}" uses ${ref} pinned to a tag or branch — pin to a full commit SHA for supply-chain security.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/gha030.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha030 } from "./gha030";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("GHA030: container image without digest", () => {
+  test("flags a container image pinned to a tag", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: node:20
+    steps:
+      - run: echo build
+`;
+    const diags = gha030.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA030");
+    expect(diags[0].entity).toBe("build");
+    expect(diags[0].message).toContain("node:20");
+  });
+
+  test("flags a service image pinned to a tag", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    services:
+      redis:
+        image: redis:7
+    steps:
+      - run: echo build
+`;
+    const diags = gha030.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("redis:7");
+  });
+
+  test("flags a docker:// step reference without digest", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: docker://alpine:3.19
+`;
+    const diags = gha030.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("alpine:3.19");
+  });
+
+  test("does not flag a container image pinned to a digest", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: node@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+    steps:
+      - run: echo build
+`;
+    const diags = gha030.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/gha030.ts

@@ -0,0 +1,41 @@
+/**
+ * GHA030: Container Image Without an Immutable Digest
+ *
+ * Flags job `container:` images, `services:` images, and `docker://` step
+ * references that are not pinned to an immutable `@sha256:` digest. A mutable
+ * tag (`:latest`, `:20`) can be repointed to a different image after review.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractImageRefs } from "./yaml-helpers";
+
+const SOURCE_LABEL: Record<string, string> = {
+  container: "container image",
+  service: "service image",
+  step: "docker:// image",
+};
+
+export const gha030: PostSynthCheck = {
+  id: "GHA030",
+  description: "Container image not pinned to an immutable digest",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, image, source } of extractImageRefs(yaml)) {
+        if (image.includes("@sha256:")) continue;
+        diagnostics.push({
+          checkId: "GHA030",
+          severity: "warning",
+          message: `Job "${job}" ${SOURCE_LABEL[source]} "${image}" is not pinned to a digest — reference it by @sha256:... so the image cannot change after review.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/gha031.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha031, editDistance, nearestLookAlike } from "./gha031";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("GHA031: look-alike action reference", () => {
+  test("editDistance basics", () => {
+    expect(editDistance("abc", "abc", 2)).toBe(0);
+    expect(editDistance("actions/chekout", "actions/checkout", 2)).toBe(1);
+    expect(editDistance("totally/different-name-xyz", "actions/checkout", 2)).toBe(3);
+  });
+
+  test("nearestLookAlike returns the close known slug", () => {
+    expect(nearestLookAlike("actions/checkout")).toBeUndefined(); // exact match
+    expect(nearestLookAlike("actions/chekout")).toBe("actions/checkout");
+    expect(nearestLookAlike("totally/unrelated")).toBeUndefined();
+  });
+
+  test("flags a typo-squatted action", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkoutt@v4
+`;
+    const diags = gha031.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA031");
+    expect(diags[0].message).toContain("actions/checkout");
+  });
+
+  test("does not flag a legitimate exact known action", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+`;
+    const diags = gha031.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag an unrelated third-party action", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: my-org/my-custom-thing@v1
+`;
+    const diags = gha031.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/gha031.ts

@@ -0,0 +1,77 @@
+/**
+ * GHA031: Action Reference Resembling a Well-Known Action
+ *
+ * Flags a `uses:` slug that is a near-miss (edit distance 1–2) of a popular
+ * action but not an exact match — a likely typo or a deliberate impersonation
+ * of the well-known action under different ownership. Advisory only; backed by
+ * a vendored reference list.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractActionRefs, parseActionUses } from "./yaml-helpers";
+import { KNOWN_ACTION_SLUGS } from "../rules/data/known-action-slugs";
+
+const KNOWN = new Set(KNOWN_ACTION_SLUGS);
+
+/** Levenshtein edit distance, capped: returns early once it exceeds `max`. */
+export function editDistance(a: string, b: string, max: number): number {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const curr = [i];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+      curr.push(val);
+      if (val < rowMin) rowMin = val;
+    }
+    if (rowMin > max) return max + 1;
+    prev = curr;
+  }
+  return prev[b.length];
+}
+
+/** Find the nearest known slug within edit distance 1–2 of `slug`, if any. */
+export function nearestLookAlike(slug: string): string | undefined {
+  if (KNOWN.has(slug)) return undefined; // exact match is legitimate
+  let best: string | undefined;
+  let bestDist = 3;
+  for (const known of KNOWN) {
+    const d = editDistance(slug, known, 2);
+    if (d >= 1 && d <= 2 && d < bestDist) {
+      best = known;
+      bestDist = d;
+    }
+  }
+  return best;
+}
+
+export const gha031: PostSynthCheck = {
+  id: "GHA031",
+  description: "Action reference resembles a well-known action (possible impersonation)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, ref } of extractActionRefs(yaml)) {
+        const parsed = parseActionUses(ref);
+        if (!parsed) continue;
+        const lookAlike = nearestLookAlike(parsed.slug);
+        if (!lookAlike) continue;
+        diagnostics.push({
+          checkId: "GHA031",
+          severity: "warning",
+          message: `Job "${job}" uses "${parsed.slug}", which closely resembles the well-known action "${lookAlike}". Confirm the owner is who you intend — this may be a typo or impersonation.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/gha032.test.ts

@@ -0,0 +1,65 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha032 } from "./gha032";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("GHA032: archived or compromised action", () => {
+  test("flags a known compromised action", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: tj-actions/changed-files@v44
+`;
+    const diags = gha032.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA032");
+    expect(diags[0].entity).toBe("build");
+    expect(diags[0].message).toContain("tj-actions/changed-files");
+  });
+
+  test("flags a known archived action", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-ruby@v1
+`;
+    const diags = gha032.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("ruby/setup-ruby");
+  });
+
+  test("does not flag a maintained action", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+`;
+    const diags = gha032.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/gha032.ts

@@ -0,0 +1,39 @@
+/**
+ * GHA032: Reference to an Archived or Compromised Action
+ *
+ * Flags a `uses:` slug that a vendored snapshot marks as archived/abandoned or
+ * carrying a disclosed security issue. Advisory only — the dataset is
+ * necessarily incomplete and may lag upstream changes.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractActionRefs, parseActionUses } from "./yaml-helpers";
+import { FLAGGED_ACTIONS } from "../rules/data/flagged-actions";
+
+export const gha032: PostSynthCheck = {
+  id: "GHA032",
+  description: "Action is archived/abandoned or has a disclosed security issue",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, ref } of extractActionRefs(yaml)) {
+        const parsed = parseActionUses(ref);
+        if (!parsed) continue;
+        const flagged = FLAGGED_ACTIONS[parsed.slug];
+        if (!flagged) continue;
+        diagnostics.push({
+          checkId: "GHA032",
+          severity: "warning",
+          message: `Job "${job}" uses "${parsed.slug}" — ${flagged.reason}. ${flagged.remediation}.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/gha033.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha033 } from "./gha033";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("GHA033: blanket write-all permissions", () => {
+  test("flags workflow-level write-all", () => {
+    const yaml = `name: CI
+on:
+  push:
+permissions: write-all
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha033.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA033");
+    expect(diags[0].message).toContain("write-all");
+  });
+
+  test("flags job-level write-all", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions: write-all
+    steps:
+      - run: echo build
+`;
+    const diags = gha033.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag scoped permissions", () => {
+    const yaml = `name: CI
+on:
+  push:
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha033.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/gha033.ts

@@ -0,0 +1,47 @@
+/**
+ * GHA033: Blanket `write-all` Token Permissions
+ *
+ * Flags a `permissions: write-all` grant at the workflow or job level. It hands
+ * the `GITHUB_TOKEN` every write scope regardless of what the job uses, so any
+ * compromised or injected step becomes a write-capable actor across the repo.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractWorkflowPermissions, extractJobPermissions, writeSurface } from "./yaml-helpers";
+
+export const gha033: PostSynthCheck = {
+  id: "GHA033",
+  description: "Blanket write-all token permissions",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      const wf = extractWorkflowPermissions(yaml);
+      if (wf && writeSurface(wf).writeAll) {
+        diagnostics.push({
+          checkId: "GHA033",
+          severity: "warning",
+          message: `Workflow declares permissions: write-all — replace it with the specific scopes the jobs actually need (least privilege).`,
+          lexicon: "github",
+        });
+      }
+
+      for (const [job, perms] of extractJobPermissions(yaml)) {
+        if (writeSurface(perms).writeAll) {
+          diagnostics.push({
+            checkId: "GHA033",
+            severity: "warning",
+            message: `Job "${job}" declares permissions: write-all — replace it with the specific scopes this job needs (least privilege).`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/gha034.test.ts

@@ -0,0 +1,86 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha034 } from "./gha034";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("GHA034: workflow-wide write scope", () => {
+  test("flags a workflow-level write scope", () => {
+    const yaml = `name: CI
+on:
+  push:
+permissions:
+  contents: write
+  packages: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha034.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA034");
+    expect(diags[0].message).toContain("contents");
+    expect(diags[0].message).toContain("packages");
+  });
+
+  test("does not flag workflow-level read-only scopes", () => {
+    const yaml = `name: CI
+on:
+  push:
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha034.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag write-all (owned by GHA033)", () => {
+    const yaml = `name: CI
+on:
+  push:
+permissions: write-all
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha034.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag job-scoped write (the recommended form)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - run: echo build
+`;
+    const diags = gha034.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/gha034.ts

@@ -0,0 +1,41 @@
+/**
+ * GHA034: Workflow-Wide Write Scope (Prefer Job-Scoped Permissions)
+ *
+ * Flags individual write scopes granted at the workflow level. A workflow-wide
+ * grant gives every job that scope even when only one needs it. Least privilege
+ * prefers declaring the write scope on the single job that uses it.
+ *
+ * The `write-all` blanket preset is handled by GHA033 and skipped here.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractWorkflowPermissions, writeSurface } from "./yaml-helpers";
+
+export const gha034: PostSynthCheck = {
+  id: "GHA034",
+  description: "Write permissions granted workflow-wide instead of per-job",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      const wf = extractWorkflowPermissions(yaml);
+      if (!wf) continue;
+
+      const { writeAll, scopes } = writeSurface(wf);
+      if (writeAll) continue; // GHA033 owns write-all
+      if (scopes.length === 0) continue;
+
+      diagnostics.push({
+        checkId: "GHA034",
+        severity: "warning",
+        message: `Workflow grants write scope (${scopes.join(", ")}) for all jobs — move each write scope onto the specific job that needs it for least privilege.`,
+        lexicon: "github",
+      });
+    }
+
+    return diagnostics;
+  },
+};