@intentius/chant-lexicon-github 0.1.23 → 0.3.0

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

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha035 } from "./gha035";
+
+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("GHA035: elevated scope on untrusted-code trigger", () => {
+  test("errors on workflow-level write with pull_request_target", () => {
+    const yaml = `name: Review
+on:
+  pull_request_target:
+permissions:
+  contents: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha035.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA035");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("pull_request_target");
+  });
+
+  test("errors on job-level write-all with workflow_run", () => {
+    const yaml = `name: Followup
+on:
+  workflow_run:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions: write-all
+    steps:
+      - run: echo build
+`;
+    const diags = gha035.check(makeCtx(yaml));
+    expect(diags.some((d) => d.severity === "error" && d.entity === "build")).toBe(true);
+  });
+
+  test("does not flag write scope on a safe trigger", () => {
+    const yaml = `name: CI
+on:
+  push:
+permissions:
+  contents: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha035.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag read-only scope on untrusted trigger", () => {
+    const yaml = `name: Review
+on:
+  pull_request_target:
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha035.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,66 @@
+/**
+ * GHA035: Elevated Token Scope on an Untrusted-Code Trigger
+ *
+ * Raises the stakes of GHA033/GHA034: when a workflow can run untrusted code
+ * (`pull_request_target`, `workflow_run`) and also grants the token write
+ * access, an injected step runs with standing write credentials. This is the
+ * combination behind most CI privilege-escalation incidents, so it is an error.
+ *
+ * Cross-references the trust-boundary checks (GHA018 / GHA025 / GHA038).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import {
+  getPrimaryOutput,
+  extractTriggers,
+  extractWorkflowPermissions,
+  extractJobPermissions,
+  writeSurface,
+  grantsWrite,
+} from "./yaml-helpers";
+
+const UNTRUSTED_TRIGGERS = ["pull_request_target", "workflow_run"];
+
+function describeWrite(perms: ReturnType<typeof writeSurface>): string {
+  return perms.writeAll ? "write-all" : perms.scopes.map((s) => `${s}: write`).join(", ");
+}
+
+export const gha035: PostSynthCheck = {
+  id: "GHA035",
+  description: "Elevated token scope on a trigger that can run untrusted code",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const triggers = extractTriggers(yaml);
+      const untrusted = UNTRUSTED_TRIGGERS.filter((t) => triggers[t]);
+      if (untrusted.length === 0) continue;
+
+      const wf = extractWorkflowPermissions(yaml);
+      if (wf && grantsWrite(wf)) {
+        diagnostics.push({
+          checkId: "GHA035",
+          severity: "error",
+          message: `Workflow grants write token scope (${describeWrite(writeSurface(wf))}) while using the ${untrusted.join("/")} trigger, which can run untrusted code. Drop write scope or gate the privileged work behind a separate trusted workflow.`,
+          lexicon: "github",
+        });
+      }
+
+      for (const [job, perms] of extractJobPermissions(yaml)) {
+        if (grantsWrite(perms)) {
+          diagnostics.push({
+            checkId: "GHA035",
+            severity: "error",
+            message: `Job "${job}" grants write token scope (${describeWrite(writeSurface(perms))}) while the workflow uses the ${untrusted.join("/")} trigger, which can run untrusted code. Drop write scope or isolate the privileged work.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,68 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha036 } from "./gha036";
+
+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("GHA036: untrusted input in run:", () => {
+  test("flags PR title interpolated into a block-scalar run", () => {
+    const yaml = `name: CI
+on:
+  pull_request_target:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: greet
+        run: |
+          echo "Title: \${{ github.event.pull_request.title }}"
+`;
+    const diags = gha036.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA036");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("build");
+    expect(diags[0].message).toContain("github.event.pull_request.title");
+  });
+
+  test("flags head_ref interpolated into an inline run", () => {
+    const yaml = `name: CI
+on:
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ github.head_ref }}
+`;
+    const diags = gha036.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("github.head_ref");
+  });
+
+  test("does not flag a trusted context in run:", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ github.sha }}
+`;
+    const diags = gha036.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,42 @@
+/**
+ * GHA036: Untrusted Input Interpolated into a Shell Command
+ *
+ * Flags attacker-controllable expression contexts (PR titles, branch names,
+ * issue/comment bodies, commit messages) interpolated directly into a `run:`
+ * script. The value is expanded into the shell before the script runs, so a
+ * crafted payload becomes command execution. Pass untrusted input through an
+ * `env:` variable and reference it quoted instead.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractRunBlocks, extractExpressions } from "./yaml-helpers";
+import { matchUntrustedContext } from "../rules/data/untrusted-contexts";
+
+export const gha036: PostSynthCheck = {
+  id: "GHA036",
+  description: "Untrusted input interpolated into a run: shell command",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, run } of extractRunBlocks(yaml)) {
+        for (const expr of extractExpressions(run)) {
+          const ctxName = matchUntrustedContext(expr);
+          if (!ctxName) continue;
+          diagnostics.push({
+            checkId: "GHA036",
+            severity: "error",
+            message: `Job "${job}" interpolates untrusted input \${{ ${ctxName} ... }} into a run: script — this is a script-injection sink. Pass it through an env: variable and reference "$VAR" quoted instead.`,
+            entity: job,
+            lexicon: "github",
+          });
+          break; // one diagnostic per run block is enough
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,66 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha037 } from "./gha037";
+
+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("GHA037: untrusted input to GITHUB_ENV / GITHUB_PATH", () => {
+  test("flags untrusted input written to GITHUB_ENV", () => {
+    const yaml = `name: CI
+on:
+  pull_request_target:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          echo "BRANCH=\${{ github.event.pull_request.head.ref }}" >> "$GITHUB_ENV"
+`;
+    const diags = gha037.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA037");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("GITHUB_ENV");
+  });
+
+  test("does not flag a trusted value written to GITHUB_ENV", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          echo "SHA=\${{ github.sha }}" >> "$GITHUB_ENV"
+`;
+    const diags = gha037.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag untrusted input that does not touch env files", () => {
+    const yaml = `name: CI
+on:
+  pull_request_target:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo done
+`;
+    const diags = gha037.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,46 @@
+/**
+ * GHA037: Untrusted Input Written to GITHUB_ENV / GITHUB_PATH
+ *
+ * Flags a `run:` step that writes attacker-controllable input into the
+ * `$GITHUB_ENV` or `$GITHUB_PATH` files. Those files set environment variables
+ * and PATH entries for *later* steps, so injecting into them escalates a data
+ * value into influence over subsequent privileged steps (a known path to
+ * `LD_PRELOAD`/`NODE_OPTIONS`-style takeover).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractRunBlocks, extractExpressions } from "./yaml-helpers";
+import { matchUntrustedContext } from "../rules/data/untrusted-contexts";
+
+const ENV_FILE_RE = /GITHUB_ENV|GITHUB_PATH/;
+
+export const gha037: PostSynthCheck = {
+  id: "GHA037",
+  description: "Untrusted input written to GITHUB_ENV / GITHUB_PATH",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, run } of extractRunBlocks(yaml)) {
+        if (!ENV_FILE_RE.test(run)) continue;
+        for (const expr of extractExpressions(run)) {
+          const ctxName = matchUntrustedContext(expr);
+          if (!ctxName) continue;
+          const file = run.includes("GITHUB_PATH") ? "GITHUB_PATH" : "GITHUB_ENV";
+          diagnostics.push({
+            checkId: "GHA037",
+            severity: "error",
+            message: `Job "${job}" writes untrusted input \${{ ${ctxName} ... }} into $${file}, which sets state for later steps. Sanitize/validate the value or avoid persisting untrusted input across steps.`,
+            entity: job,
+            lexicon: "github",
+          });
+          break;
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,64 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha038 } from "./gha038";
+
+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("GHA038: workflow_run with checkout", () => {
+  test("flags checkout under workflow_run", () => {
+    const yaml = `name: Followup
+on:
+  workflow_run:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo build
+`;
+    const diags = gha038.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA038");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag workflow_run without checkout", () => {
+    const yaml = `name: Followup
+on:
+  workflow_run:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha038.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag checkout on a safe trigger", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+`;
+    const diags = gha038.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * GHA038: Privileged `workflow_run` Trigger Checking Out Untrusted Code
+ *
+ * Generalizes GHA018 (pull_request_target + checkout) to the other privileged
+ * trigger that runs in the base-repo context: `workflow_run`. A `workflow_run`
+ * workflow has repo write scope and secrets, and checking out the artifact/head
+ * of the triggering run pulls untrusted code into that privileged context.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractTriggers, extractJobs, hasCheckoutAction } from "./yaml-helpers";
+
+export const gha038: PostSynthCheck = {
+  id: "GHA038",
+  description: "workflow_run trigger with checkout runs untrusted code in a privileged context",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const triggers = extractTriggers(yaml);
+      if (!triggers["workflow_run"]) continue;
+
+      const jobs = extractJobs(yaml);
+      for (const [jobName, job] of jobs) {
+        if (job.steps && hasCheckoutAction(job.steps)) {
+          diagnostics.push({
+            checkId: "GHA038",
+            severity: "warning",
+            message: `Job "${jobName}" checks out code under a workflow_run trigger, which runs with repo write scope and secrets. Treat the checked-out code as untrusted — avoid executing it, or move execution to an unprivileged workflow.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,66 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha039 } from "./gha039";
+
+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("GHA039: spoofable identity gate", () => {
+  test("flags an if: gating on commit author email", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ github.event.head_commit.author.email == 'maintainer@example.com' }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha039.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA039");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag an if: on a trustworthy signal", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ github.ref == 'refs/heads/main' }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha039.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag a non-author field referenced without comparison", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ always() }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha039.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * GHA039: Spoofable Identity Used as an Authorization Gate
+ *
+ * Flags an `if:` condition that gates execution on a commit-author identity
+ * field (`...author.name` / `...author.email`). Those values come straight from
+ * git metadata the committer sets freely, so an attacker can forge them to pass
+ * the gate. Use a trustworthy signal — environment protection rules, CODEOWNERS,
+ * or membership checks against a verified actor.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIfConditions } from "./yaml-helpers";
+
+const SPOOFABLE_FIELD_RE = /\.author\.(name|email)\b/;
+const COMPARISON_RE = /==|!=|contains\s*\(/;
+
+export const gha039: PostSynthCheck = {
+  id: "GHA039",
+  description: "Authorization gate on a spoofable commit-author identity field",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, expr } of extractIfConditions(yaml)) {
+        if (SPOOFABLE_FIELD_RE.test(expr) && COMPARISON_RE.test(expr)) {
+          diagnostics.push({
+            checkId: "GHA039",
+            severity: "warning",
+            message: `Job "${job}" gates on a commit-author identity field in an if: condition (${expr}). Author name/email are attacker-controlled and can be spoofed — gate on a verified signal (environment protection, CODEOWNERS, verified actor) instead.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,77 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha040 } from "./gha040";
+
+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("GHA040: self-hosted runner on untrusted trigger", () => {
+  test("flags self-hosted runner under pull_request", () => {
+    const yaml = `name: CI
+on:
+  pull_request:
+jobs:
+  build:
+    runs-on: self-hosted
+    steps:
+      - run: echo build
+`;
+    const diags = gha040.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA040");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("flags self-hosted in an array runs-on under workflow_run", () => {
+    const yaml = `name: CI
+on:
+  workflow_run:
+jobs:
+  build:
+    runs-on: [self-hosted, linux]
+    steps:
+      - run: echo build
+`;
+    const diags = gha040.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("does not flag GitHub-hosted runner under untrusted trigger", () => {
+    const yaml = `name: CI
+on:
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha040.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag self-hosted on a safe trigger", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: self-hosted
+    steps:
+      - run: echo build
+`;
+    const diags = gha040.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});