@intentius/chant-lexicon-github 0.1.22 → 0.2.0

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

@@ -0,0 +1,66 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha047 } from "./gha047";
+
+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("GHA047: reversed contains() guard", () => {
+  test("flags contains('literal', dynamic)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ contains('refs/heads/main', github.ref) }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha047.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA047");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag normal contains(dynamic, 'literal')", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ contains(github.event.pull_request.labels.*.name, 'bug') }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha047.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag contains() of two literals", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ contains('abc', 'b') }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha047.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,51 @@
+/**
+ * GHA047: Ineffective `contains()` Guard (Reversed Arguments)
+ *
+ * Flags `contains('literal', <dynamic>)` — a string literal as the haystack and
+ * a dynamic value as the needle. `contains(search, item)` checks whether `item`
+ * is in `search`, so a constant first argument makes the result depend on a
+ * fixed string rather than the runtime value the author intended to test. The
+ * usual fix is to swap the arguments.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIfConditions } from "./yaml-helpers";
+
+// contains( 'literal' | "literal" , <something that is not a literal> )
+const REVERSED_CONTAINS = /contains\(\s*(['"][^'"]*['"])\s*,\s*([^)]+)\)/g;
+
+function isLiteral(arg: string): boolean {
+  const t = arg.trim();
+  return (t.startsWith("'") && t.endsWith("'")) || (t.startsWith('"') && t.endsWith('"'));
+}
+
+export const gha047: PostSynthCheck = {
+  id: "GHA047",
+  description: "Ineffective contains() guard with reversed arguments",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, expr } of extractIfConditions(yaml)) {
+        let m: RegExpExecArray | null;
+        REVERSED_CONTAINS.lastIndex = 0;
+        while ((m = REVERSED_CONTAINS.exec(expr)) !== null) {
+          // First arg is a literal; flag only when the second arg is dynamic.
+          if (isLiteral(m[2])) continue;
+          diagnostics.push({
+            checkId: "GHA047",
+            severity: "warning",
+            message: `Job "${job}" calls contains() with a string-literal haystack and a dynamic needle: "${m[0]}". contains(search, item) tests whether item is in search — swap the arguments so the dynamic value is searched.`,
+            entity: job,
+            lexicon: "github",
+          });
+          break;
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,51 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha048 } from "./gha048";
+
+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("GHA048: obfuscated guard condition", () => {
+  test("flags an operand built with format() in a comparison", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ format('{0}', github.actor) == 'octocat' }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha048.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA048");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag a direct comparison", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: \${{ github.actor == 'octocat' }}
+    steps:
+      - run: echo build
+`;
+    const diags = gha048.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,41 @@
+/**
+ * GHA048: Obfuscated Guard Condition
+ *
+ * Flags an `if:` condition that builds its compared value through string
+ * indirection — `format()`, `join()`, or `fromJSON()` feeding a comparison.
+ * Constructing the operand at evaluation time hides what the gate actually
+ * checks, which is how an unsound condition (GHA046/GHA047) is disguised to pass
+ * review. Write the comparison against the value directly.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIfConditions } from "./yaml-helpers";
+
+const INDIRECTION = /\b(format|join|fromJSON)\s*\(/i;
+const COMPARISON = /==|!=|&&|\|\||contains\(|startsWith\(|endsWith\(/;
+
+export const gha048: PostSynthCheck = {
+  id: "GHA048",
+  description: "Obfuscated guard condition (operand built by indirection)",
+
+  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 (INDIRECTION.test(expr) && COMPARISON.test(expr)) {
+          diagnostics.push({
+            checkId: "GHA048",
+            severity: "warning",
+            message: `Job "${job}" builds its if: gate through string indirection (format/join/fromJSON) feeding a comparison: "${expr}". Compare against the value directly so the condition is auditable.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha049 } from "./gha049";
+
+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("GHA049: persisted checkout credentials in artifact", () => {
+  test("flags checkout + upload-artifact without persist-credentials: false", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/upload-artifact@v4
+        with:
+          path: .
+`;
+    const diags = gha049.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA049");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag when persist-credentials is disabled", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/upload-artifact@v4
+        with:
+          path: .
+`;
+    const diags = gha049.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag checkout without artifact upload", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo build
+`;
+    const diags = gha049.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,42 @@
+/**
+ * GHA049: Persisted Checkout Credentials Reachable by an Uploaded Artifact
+ *
+ * `actions/checkout` writes the job token into `.git/config` by default
+ * (`persist-credentials: true`). A job that also uploads an artifact can sweep
+ * that `.git` directory into the artifact, leaking the token to anyone who can
+ * download it. Set `persist-credentials: false` on the checkout when the job
+ * uploads artifacts.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, linesByJob } from "./yaml-helpers";
+
+export const gha049: PostSynthCheck = {
+  id: "GHA049",
+  description: "Persisted checkout credentials reachable by an uploaded artifact",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const [job, lines] of linesByJob(yaml)) {
+        const text = lines.join("\n");
+        const hasCheckout = /uses:\s*actions\/checkout/.test(text);
+        const persistDisabled = /persist-credentials:\s*false/.test(text);
+        const uploadsArtifact = /uses:\s*actions\/upload-artifact/.test(text);
+        if (hasCheckout && uploadsArtifact && !persistDisabled) {
+          diagnostics.push({
+            checkId: "GHA049",
+            severity: "warning",
+            message: `Job "${job}" checks out with persisted credentials (default) and uploads an artifact — the token in .git/config can leak into the artifact. Set persist-credentials: false on the checkout.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,55 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha050 } from "./gha050";
+
+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("GHA050: cache populated in privileged context", () => {
+  test("flags actions/cache under pull_request_target", () => {
+    const yaml = `name: CI
+on:
+  pull_request_target:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-cache
+`;
+    const diags = gha050.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA050");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag cache on a safe trigger", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-cache
+`;
+    const diags = gha050.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,44 @@
+/**
+ * GHA050: Cache Populated in a Privileged Context (Poisoning Risk)
+ *
+ * Flags `actions/cache` use under a privileged trigger (`pull_request_target`,
+ * `workflow_run`) that runs in the base-repo context. Cache entries written from
+ * code influenced by a fork can later be restored by a trusted run and executed,
+ * a cache-poisoning path. Restrict caching to trusted triggers or scope keys so
+ * untrusted runs cannot write entries a privileged run will restore.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractTriggers, linesByJob } from "./yaml-helpers";
+
+const PRIVILEGED_TRIGGERS = ["pull_request_target", "workflow_run"];
+
+export const gha050: PostSynthCheck = {
+  id: "GHA050",
+  description: "Cache populated in a privileged context (poisoning risk)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const triggers = extractTriggers(yaml);
+      const privileged = PRIVILEGED_TRIGGERS.filter((t) => triggers[t]);
+      if (privileged.length === 0) continue;
+
+      for (const [job, lines] of linesByJob(yaml)) {
+        if (lines.some((l) => /uses:\s*actions\/cache/.test(l))) {
+          diagnostics.push({
+            checkId: "GHA050",
+            severity: "warning",
+            message: `Job "${job}" populates a cache under the ${privileged.join("/")} trigger, which runs in the privileged base context. A poisoned cache entry could be restored and executed by a trusted run — restrict caching to trusted triggers.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,72 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha051 } from "./gha051";
+
+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("GHA051: publish with long-lived token instead of OIDC", () => {
+  test("flags npm publish with a token secret and no id-token", () => {
+    const yaml = `name: Release
+on:
+  push:
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }}
+        run: npm publish
+`;
+    const diags = gha051.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA051");
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].entity).toBe("publish");
+  });
+
+  test("does not flag when id-token: write is requested", () => {
+    const yaml = `name: Release
+on:
+  push:
+permissions:
+  id-token: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }}
+        run: npm publish
+`;
+    const diags = gha051.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag a non-publish job", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          API: \${{ secrets.API_TOKEN }}
+        run: npm run build
+`;
+    const diags = gha051.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,45 @@
+/**
+ * GHA051: Publish/Release Step Using a Long-Lived Token Instead of OIDC
+ *
+ * Flags a job that publishes a release/package using a long-lived token secret
+ * (`*_TOKEN`, `*_PASSWORD`, `*_API_KEY`) while the workflow requests no
+ * `id-token: write` permission. Registries that support OIDC let a workflow mint
+ * a short-lived, audience-scoped credential per run instead of holding a
+ * standing secret. Advisory — not every registry supports OIDC.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, linesByJob } from "./yaml-helpers";
+
+const PUBLISH_RE = /npm publish|yarn publish|pnpm publish|twine upload|poetry publish|cargo publish|gh release create|docker push|gh-action-pypi-publish|npm-publish/;
+const LONG_LIVED_SECRET_RE = /secrets\.(?!GITHUB_TOKEN\b)\w*(TOKEN|PASSWORD|API_KEY|APIKEY)/i;
+
+export const gha051: PostSynthCheck = {
+  id: "GHA051",
+  description: "Publish/release step using a long-lived token instead of OIDC",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const requestsOidc = /id-token:\s*write/.test(yaml);
+      if (requestsOidc) continue;
+
+      for (const [job, lines] of linesByJob(yaml)) {
+        const text = lines.join("\n");
+        if (PUBLISH_RE.test(text) && LONG_LIVED_SECRET_RE.test(text)) {
+          diagnostics.push({
+            checkId: "GHA051",
+            severity: "info",
+            message: `Job "${job}" publishes using a long-lived token secret and requests no id-token: write. If the registry supports OIDC, mint a short-lived federated credential (permissions: id-token: write) instead of holding a standing token.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,52 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha052 } from "./gha052";
+
+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("GHA052: curl | bash runtime execution", () => {
+  test("flags curl piped to bash", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: curl -sSL https://example.com/install.sh | bash
+`;
+    const diags = gha052.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA052");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag download-then-verify", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: |
+          curl -sSLo install.sh https://example.com/install.sh
+          echo "abc123  install.sh" | sha256sum -c
+          bash install.sh
+`;
+    const diags = gha052.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,42 @@
+/**
+ * GHA052: Software Fetched and Executed at Runtime Without Verification
+ *
+ * Flags a `run:` step that pipes a network download straight into a shell
+ * (`curl ... | bash`, `wget ... | sh`, `iwr ... | iex`). The fetched script is
+ * unpinned and unverified, so whoever controls the URL controls what executes
+ * in the job. Download to a file, verify a checksum/signature, then run it.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractRunBlocks } from "./yaml-helpers";
+
+const PIPE_TO_SHELL = [
+  /\b(curl|wget)\b[^\n|]*\|\s*(sudo\s+)?(ba)?sh\b/i,
+  /\b(iwr|invoke-webrequest|irm|invoke-restmethod)\b[^\n|]*\|\s*(iex|invoke-expression)\b/i,
+];
+
+export const gha052: PostSynthCheck = {
+  id: "GHA052",
+  description: "Software fetched and piped to a shell without verification",
+
+  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 (PIPE_TO_SHELL.some((re) => re.test(run))) {
+          diagnostics.push({
+            checkId: "GHA052",
+            severity: "warning",
+            message: `Job "${job}" pipes a network download directly into a shell — the fetched code is unpinned and unverified. Download to a file, verify a checksum or signature, then execute it.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};