@intentius/chant-lexicon-github 0.1.22 → 0.2.0

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

@@ -0,0 +1,43 @@
+/**
+ * GHA040: Self-Hosted Runner on a Trigger That Can Run Untrusted Code
+ *
+ * Flags a job that runs on a self-hosted runner under a trigger reachable by a
+ * fork or outside contributor (`pull_request`, `pull_request_target`,
+ * `workflow_run`). Self-hosted runners are non-ephemeral by default and share a
+ * host, so untrusted code can persist on the runner and compromise later jobs.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractTriggers, extractRunsOnByJob } from "./yaml-helpers";
+
+const UNTRUSTED_TRIGGERS = ["pull_request", "pull_request_target", "workflow_run"];
+
+export const gha040: PostSynthCheck = {
+  id: "GHA040",
+  description: "Self-hosted runner 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;
+
+      for (const [job, labels] of extractRunsOnByJob(yaml)) {
+        if (labels.some((l) => l === "self-hosted")) {
+          diagnostics.push({
+            checkId: "GHA040",
+            severity: "warning",
+            message: `Job "${job}" runs on a self-hosted runner under the ${untrusted.join("/")} trigger, which a fork can reach. Use ephemeral GitHub-hosted runners for untrusted code, or require approval before the job runs.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha041 } from "./gha041";
+
+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("GHA041: secrets: inherit", () => {
+  test("flags a reusable call with secrets: inherit", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  call:
+    uses: org/repo/.github/workflows/deploy.yml@v1
+    secrets: inherit
+`;
+    const diags = gha041.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA041");
+    expect(diags[0].entity).toBe("call");
+  });
+
+  test("does not flag explicit secret pass-through", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  call:
+    uses: org/repo/.github/workflows/deploy.yml@v1
+    secrets:
+      token: \${{ secrets.DEPLOY_TOKEN }}
+`;
+    const diags = gha041.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * GHA041: Blanket `secrets: inherit` into a Reusable Workflow
+ *
+ * Flags a reusable-workflow call that passes `secrets: inherit`. Inheritance
+ * hands the called workflow every secret the caller can see, regardless of what
+ * it needs. Pass through only the specific secrets the reusable workflow uses.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, jobLines } from "./yaml-helpers";
+
+export const gha041: PostSynthCheck = {
+  id: "GHA041",
+  description: "Blanket secrets: inherit into a reusable workflow",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const seen = new Set<string>();
+      for (const { job, line } of jobLines(yaml)) {
+        if (/^\s+secrets:\s*inherit\s*$/.test(line) && !seen.has(job)) {
+          seen.add(job);
+          diagnostics.push({
+            checkId: "GHA041",
+            severity: "warning",
+            message: `Job "${job}" calls a reusable workflow with secrets: inherit, passing every caller secret. Pass through only the specific secrets it needs.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,53 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha042 } from "./gha042";
+
+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("GHA042: whole secrets context passed", () => {
+  test("flags toJSON(secrets)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: some/action@v1
+        with:
+          blob: \${{ toJSON(secrets) }}
+`;
+    const diags = gha042.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA042");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag a specific secret reference", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: some/action@v1
+        with:
+          token: \${{ secrets.API_TOKEN }}
+`;
+    const diags = gha042.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,40 @@
+/**
+ * GHA042: Whole Secrets Context Passed Where Specific Secrets Would Do
+ *
+ * Flags `toJSON(secrets)` (serializing the entire secrets context) passed into
+ * a step's `with:`/`env:` or to a reusable workflow. It hands the consumer every
+ * secret instead of the one or two it needs. Reference specific secrets.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, jobLines } from "./yaml-helpers";
+
+const TO_JSON_SECRETS = /to_?json\s*\(\s*secrets\s*\)/i;
+
+export const gha042: PostSynthCheck = {
+  id: "GHA042",
+  description: "Entire secrets context passed where specific secrets would do",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const seen = new Set<string>();
+      for (const { job, line } of jobLines(yaml)) {
+        if (TO_JSON_SECRETS.test(line) && !seen.has(job)) {
+          seen.add(job);
+          diagnostics.push({
+            checkId: "GHA042",
+            severity: "warning",
+            message: `Job "${job}" passes the entire secrets context via toJSON(secrets). Reference only the specific secrets the consumer needs.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha043 } from "./gha043";
+
+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("GHA043: secret without environment gate (inconsistent gating)", () => {
+  test("flags a secret-using job with no environment when others are gated", () => {
+    const yaml = `name: CD
+on:
+  push:
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - run: echo deploy
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ secrets.SLACK_TOKEN }}
+`;
+    const diags = gha043.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA043");
+    expect(diags[0].entity).toBe("notify");
+  });
+
+  test("does not flag when the secret-using job is itself gated", () => {
+    const yaml = `name: CD
+on:
+  push:
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - run: echo \${{ secrets.DEPLOY_TOKEN }}
+`;
+    const diags = gha043.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not fire when no job uses an environment (GHA026 territory)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo \${{ secrets.TOKEN }}
+`;
+    const diags = gha043.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * GHA043: Secret Consumed in a Job Without an Environment Gate
+ *
+ * Extends GHA026 (which fires only when a workflow uses secrets and defines no
+ * environment at all). When a workflow *does* gate some jobs with an
+ * `environment:`, this flags the specific jobs that consume secrets without one
+ * — the inconsistent-gating case, where a secret-using job skips the approval
+ * and scoping the author applied elsewhere.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, jobsReferencingSecrets, extractJobEnvironments } from "./yaml-helpers";
+
+export const gha043: PostSynthCheck = {
+  id: "GHA043",
+  description: "Secret consumed in a job without an environment gate",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const gated = extractJobEnvironments(yaml);
+      if (gated.size === 0) continue; // no environments used anywhere — GHA026 territory
+
+      for (const job of jobsReferencingSecrets(yaml)) {
+        if (!gated.has(job)) {
+          diagnostics.push({
+            checkId: "GHA043",
+            severity: "warning",
+            message: `Job "${job}" consumes a secret but declares no environment:, while other jobs in this workflow are environment-gated. Gate this job too, or confirm it should bypass the approval/scoping the others use.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,56 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha044 } from "./gha044";
+
+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("GHA044: hardcoded registry/container credential", () => {
+  test("flags a hardcoded password literal", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: docker/login-action@v3
+        with:
+          username: myuser
+          password: hunter2
+`;
+    const diags = gha044.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA044");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag a password sourced from a secret", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: docker/login-action@v3
+        with:
+          username: myuser
+          password: \${{ secrets.DOCKER_PASSWORD }}
+`;
+    const diags = gha044.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * GHA044: Hardcoded Registry / Container Credential
+ *
+ * Flags a `password:` / `token:` / `registry-password:` value that is a literal
+ * rather than a `${{ secrets.* }}` reference — e.g. a registry login or service
+ * credential inlined in plain text. Move it into a secret.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, jobLines } from "./yaml-helpers";
+
+const CRED_KEY_RE = /^\s+(?:- )?(password|token|registry-password):\s*(.+)$/;
+
+export const gha044: PostSynthCheck = {
+  id: "GHA044",
+  description: "Hardcoded registry/container credential",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, line } of jobLines(yaml)) {
+        const m = line.match(CRED_KEY_RE);
+        if (!m) continue;
+        const key = m[1];
+        const value = m[2].trim().replace(/^['"]|['"]$/g, "");
+        if (value === "" || value.includes("${{")) continue; // empty or a proper expression
+        diagnostics.push({
+          checkId: "GHA044",
+          severity: "error",
+          message: `Job "${job}" sets ${key}: to a hardcoded literal. Reference a secret (\${{ secrets.NAME }}) instead of inlining the credential.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,51 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha045 } from "./gha045";
+
+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("GHA045: secret interpolated into run:", () => {
+  test("flags a secret interpolated into a run command", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: curl -H "Authorization: \${{ secrets.API_TOKEN }}" https://example.com
+`;
+    const diags = gha045.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA045");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag a secret passed via env (the recommended form)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          TOKEN: \${{ secrets.API_TOKEN }}
+        run: curl -H "Authorization: $TOKEN" https://example.com
+`;
+    const diags = gha045.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * GHA045: Secret Interpolated Directly into a Shell Command
+ *
+ * Flags `${{ secrets.* }}` expanded straight into a `run:` script. The value is
+ * substituted into the command line before the shell runs, where a transform
+ * (base64, reversing, splitting) can defeat GitHub's log masking and leak it,
+ * and the raw value is exposed to argument-injection. Pass secrets through an
+ * `env:` variable and reference "$VAR" quoted instead.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractRunBlocks, extractExpressions } from "./yaml-helpers";
+
+export const gha045: PostSynthCheck = {
+  id: "GHA045",
+  description: "Secret interpolated directly 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)) {
+        const leaked = extractExpressions(run).some((e) => /\bsecrets\./.test(e));
+        if (!leaked) continue;
+        diagnostics.push({
+          checkId: "GHA045",
+          severity: "warning",
+          message: `Job "${job}" interpolates a secret directly into a run: script, where a transform can defeat log masking. Pass it through an env: variable and reference "$VAR" quoted instead.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,59 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha046, unsoundReason } from "./gha046";
+
+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("GHA046: unsound guard condition", () => {
+  test("unsoundReason classifies constants", () => {
+    expect(unsoundReason("true")).toContain("always true");
+    expect(unsoundReason("${{ false }}")).toContain("always false");
+    expect(unsoundReason("${{ success() || true }}")).toContain("always true");
+    expect(unsoundReason("${{ github.ref == github.ref }}")).toContain("always true");
+    expect(unsoundReason("${{ github.ref == 'refs/heads/main' }}")).toBeUndefined();
+  });
+
+  test("flags an always-true literal gate", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: true
+    steps:
+      - run: echo build
+`;
+    const diags = gha046.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA046");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag a real condition", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ github.ref == 'refs/heads/main' }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha046.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,56 @@
+/**
+ * GHA046: Logically Unsound Guard Condition
+ *
+ * Flags an `if:` condition that reads like a security/flow gate but evaluates to
+ * a constant — `true`/`false` literals, an `X == X` tautology, or an expression
+ * that collapses via `|| true` / `&& false`. These pass review by looking like a
+ * control while gating nothing (or everything).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIfConditions } from "./yaml-helpers";
+
+/** Strip a leading `${{` / trailing `}}` wrapper from an expression. */
+function inner(expr: string): string {
+  return expr.replace(/^\$\{\{/, "").replace(/\}\}$/, "").trim();
+}
+
+/** Classify a condition as a constant guard, returning a reason or undefined. */
+export function unsoundReason(expr: string): string | undefined {
+  const e = inner(expr);
+  if (e === "true") return "always true (true literal)";
+  if (e === "false") return "always false (false literal)";
+  if (/\|\|\s*true\b/.test(e)) return "always true (|| true collapses the condition)";
+  if (/&&\s*false\b/.test(e)) return "always false (&& false collapses the condition)";
+  const eq = e.match(/^([\w.$'"[\]-]+)\s*==\s*([\w.$'"[\]-]+)$/);
+  if (eq && eq[1] === eq[2]) return "always true (both sides of == are identical)";
+  const ne = e.match(/^([\w.$'"[\]-]+)\s*!=\s*([\w.$'"[\]-]+)$/);
+  if (ne && ne[1] === ne[2]) return "always false (both sides of != are identical)";
+  return undefined;
+}
+
+export const gha046: PostSynthCheck = {
+  id: "GHA046",
+  description: "Logically unsound (constant) guard condition",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, expr } of extractIfConditions(yaml)) {
+        const reason = unsoundReason(expr);
+        if (!reason) continue;
+        diagnostics.push({
+          checkId: "GHA046",
+          severity: "warning",
+          message: `Job "${job}" has an if: condition that is ${reason}: "${expr}". A gate that does not constrain anything is misleading — remove it or write the real condition.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};