@intentius/chant-lexicon-github 0.49.0 → 0.50.0

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [
@@ -9,6 +9,114 @@
       "description": "Typed class wrapping a raw GitHub Actions expression, serializing to `${{ }}` (chant #1069 — was registered as \"expression\", which src/index.ts never exported)",
       "outputKey": "expression",
       "isTag": false
+    },
+    {
+      "name": "secrets",
+      "description": "Access a secret by name.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "matrix",
+      "description": "Access a matrix value by key.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "steps",
+      "description": "Access a step output.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "needs",
+      "description": "Access a job output from a needed job.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "inputs",
+      "description": "Access a workflow input.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "vars",
+      "description": "Access a configuration variable.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "env",
+      "description": "Access an environment variable.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "always",
+      "description": "Always run, regardless of status.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "failure",
+      "description": "Run only if a previous step has failed.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "success",
+      "description": "Run only if all previous steps succeeded.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "cancelled",
+      "description": "Run only if the workflow was cancelled.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "contains",
+      "description": "Check if a string contains a substring.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "startsWith",
+      "description": "Check if a string starts with a prefix.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "toJSON",
+      "description": "Convert a value to JSON.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "fromJSON",
+      "description": "Parse a JSON string.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "format",
+      "description": "Format a string with placeholders.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "branch",
+      "description": "Check if the ref matches a branch name.",
+      "isTag": false,
+      "foldsEagerly": true
+    },
+    {
+      "name": "tag",
+      "description": "Check if the ref matches a tag prefix.",
+      "isTag": false,
+      "foldsEagerly": true
     }
   ],
   "pseudoParameters": {}

package/dist/meta.json

@@ -53,6 +53,11 @@
           "read",
           "none"
         ]
+      },
+      "copilot-requests": {
+        "enum": [
+          "write"
+        ]
       }
     }
   },

package/dist/okf/index.md

@@ -68,3 +68,13 @@ okf_version: '0.2'
 * [GHA056](/rules/GHA056.md) - Workflow without a name
 * [GHA057](/rules/GHA057.md) - Dependency update allows executing untrusted external code
 * [GHA058](/rules/GHA058.md) - Dependency update has no cooldown window
+* [GHA059](/rules/GHA059.md) - SHA-pinned action reference has a missing or internally-inconsistent version annotation
+* [GHA060](/rules/GHA060.md) - Generated GitHub App token granted broader scope than its consuming steps evidence
+* [GHA061](/rules/GHA061.md) - Action reference outside the configured usage policy (opt-in)
+* [GHA062](/rules/GHA062.md) - Pinned action reference matches a known-vulnerability advisory (feed-driven)
+* [GHA063](/rules/GHA063.md) - Dependency setup action without caching enabled
+* [GHA064](/rules/GHA064.md) - Job hardcoded onto an expensive runner with no sign it needs that OS
+* [GHA065](/rules/GHA065.md) - Matrix combines dimensions into an uncapped, large fan-out
+* [GHA066](/rules/GHA066.md) - Uploaded artifact has no explicit retention-days
+* [GHA067](/rules/GHA067.md) - Unconditional docker build with no path filter or guard
+* [GHA068](/rules/GHA068.md) - Pull-request workflow missing a concurrency group

package/dist/okf/rules/GHA059.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA059
+description: SHA-pinned action reference has a missing or internally-inconsistent version annotation
+id: GHA059
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+SHA-pinned action reference has a missing or internally-inconsistent version annotation
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA060.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA060
+description: Generated GitHub App token granted broader scope than its consuming steps evidence
+id: GHA060
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Generated GitHub App token granted broader scope than its consuming steps evidence
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA061.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA061
+description: Action reference outside the configured usage policy (opt-in)
+id: GHA061
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Action reference outside the configured usage policy (opt-in)
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA062.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA062
+description: Pinned action reference matches a known-vulnerability advisory (feed-driven)
+id: GHA062
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Pinned action reference matches a known-vulnerability advisory (feed-driven)
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA063.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA063
+description: Dependency setup action without caching enabled
+id: GHA063
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Dependency setup action without caching enabled
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA064.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA064
+description: Job hardcoded onto an expensive runner with no sign it needs that OS
+id: GHA064
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Job hardcoded onto an expensive runner with no sign it needs that OS
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA065.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA065
+description: Matrix combines dimensions into an uncapped, large fan-out
+id: GHA065
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Matrix combines dimensions into an uncapped, large fan-out
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA066.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA066
+description: Uploaded artifact has no explicit retention-days
+id: GHA066
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Uploaded artifact has no explicit retention-days
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA067.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA067
+description: Unconditional docker build with no path filter or guard
+id: GHA067
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Unconditional docker build with no path filter or guard
+
+## Applies to
+
+- [Job](/types/Job.md)

package/dist/okf/rules/GHA068.md

@@ -0,0 +1,15 @@
+---
+type: post-synth-check
+title: GHA068
+description: Pull-request workflow missing a concurrency group
+id: GHA068
+severity: error
+category: post-synth
+lexicon: github
+docs: https://intentius.io/chant/lexicons/github/rules/
+---
+Pull-request workflow missing a concurrency group
+
+## Applies to
+
+- [Workflow](/types/Workflow.md)

package/dist/okf/types/Job.md

@@ -67,3 +67,12 @@ resource_type: GitHub::Actions::Job
 - [GHA053](/rules/GHA053.md): Re-enables unsafe set-env / add-path workflow commands
 - [GHA054](/rules/GHA054.md): Use of a feature with a known security footgun
 - [GHA055](/rules/GHA055.md): Runtime install of a tool already present on the runner
+- [GHA059](/rules/GHA059.md): SHA-pinned action reference has a missing or internally-inconsistent version annotation
+- [GHA060](/rules/GHA060.md): Generated GitHub App token granted broader scope than its consuming steps evidence
+- [GHA061](/rules/GHA061.md): Action reference outside the configured usage policy (opt-in)
+- [GHA062](/rules/GHA062.md): Pinned action reference matches a known-vulnerability advisory (feed-driven)
+- [GHA063](/rules/GHA063.md): Dependency setup action without caching enabled
+- [GHA064](/rules/GHA064.md): Job hardcoded onto an expensive runner with no sign it needs that OS
+- [GHA065](/rules/GHA065.md): Matrix combines dimensions into an uncapped, large fan-out
+- [GHA066](/rules/GHA066.md): Uploaded artifact has no explicit retention-days
+- [GHA067](/rules/GHA067.md): Unconditional docker build with no path filter or guard

package/dist/okf/types/Workflow.md

@@ -34,3 +34,4 @@ resource_type: GitHub::Actions::Workflow
 - [GHA041](/rules/GHA041.md): Blanket secrets: inherit into a reusable workflow
 - [GHA053](/rules/GHA053.md): Re-enables unsafe set-env / add-path workflow commands
 - [GHA056](/rules/GHA056.md): Workflow without a name
+- [GHA068](/rules/GHA068.md): Pull-request workflow missing a concurrency group

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AA4B7F,eAAO,MAAM,YAAY,EAAE,aA+S1B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AA6B7F,eAAO,MAAM,YAAY,EAAE,aA0U1B,CAAC"}

package/dist/rules/gha059.ts

@@ -0,0 +1,132 @@
+/**
+ * GHA059: Stale or Missing Pin Annotation
+ *
+ * A ref pinned to a commit SHA is only as trustworthy as the label a reviewer
+ * reads next to it — `uses: actions/setup-node@1a2b…9a0b # v4.0.2` lets a
+ * reviewer sanity-check the digest without resolving it themselves. This check
+ * flags two ways that label goes stale:
+ *
+ *  1. Missing — a SHA-pinned ref with no trailing version comment at all.
+ *  2. Mismatched — inferred without any network call, from internal
+ *     inconsistency in the workflow itself: the same action is pinned to the
+ *     same commit SHA in one place and a *different* label in another, or the
+ *     same label is attached to two *different* commit SHAs. Either shape
+ *     proves at least one of the labels is wrong — a real digest has exactly
+ *     one correct human-readable name.
+ *
+ * Cross-referencing a label against the actual git history (to catch a lone,
+ * internally-consistent but still-wrong annotation) needs a network call and
+ * is out of scope here — see GHA062 for the feed-based advisory check, which
+ * takes the same "no network in the rule itself" stance via an injected feed.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractActionRefs, extractUsesComment, parseActionUses } from "./yaml-helpers";
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+export interface StalePinFinding {
+  job: string;
+  ref: string;
+  slug: string;
+  sha: string;
+  kind: "missing" | "mismatched";
+  /** For "mismatched": the other label/SHA this one conflicts with. */
+  conflict?: string;
+}
+
+/**
+ * Find every SHA-pinned `uses:` with a missing or internally-inconsistent
+ * version annotation. Scoped to one workflow document — cross-file
+ * consistency isn't attempted since two independent workflows pinning the
+ * same action differently isn't evidence of drift.
+ */
+export function findStalePinAnnotations(yaml: string): StalePinFinding[] {
+  const refs = extractActionRefs(yaml)
+    .map(({ job, ref }) => ({ job, ref, parsed: parseActionUses(ref) }))
+    .filter((r): r is { job: string; ref: string; parsed: NonNullable<ReturnType<typeof parseActionUses>> } => !!r.parsed && SHA_RE.test(r.parsed.gitRef));
+
+  const findings: StalePinFinding[] = [];
+
+  // First pass: missing annotations.
+  const withComment: Array<{ job: string; ref: string; slug: string; sha: string; comment: string }> = [];
+  for (const { job, ref, parsed } of refs) {
+    const comment = extractUsesComment(ref);
+    if (!comment) {
+      findings.push({ job, ref, slug: parsed.slug, sha: parsed.gitRef, kind: "missing" });
+    } else {
+      withComment.push({ job, ref, slug: parsed.slug, sha: parsed.gitRef, comment });
+    }
+  }
+
+  // Second pass: internal mismatch. Group by slug — the same action's
+  // commit-SHA↔label mapping must be one-to-one across the whole file.
+  const bySlug = new Map<string, Array<{ job: string; ref: string; slug: string; sha: string; comment: string }>>();
+  for (const entry of withComment) {
+    const list = bySlug.get(entry.slug) ?? [];
+    list.push(entry);
+    bySlug.set(entry.slug, list);
+  }
+
+  for (const [, entries] of bySlug) {
+    const shaToComments = new Map<string, Set<string>>();
+    const commentToShas = new Map<string, Set<string>>();
+    for (const e of entries) {
+      (shaToComments.get(e.sha) ?? shaToComments.set(e.sha, new Set()).get(e.sha)!).add(e.comment);
+      (commentToShas.get(e.comment) ?? commentToShas.set(e.comment, new Set()).get(e.comment)!).add(e.sha);
+    }
+    for (const e of entries) {
+      const otherComments = [...(shaToComments.get(e.sha) ?? [])].filter((c) => c !== e.comment);
+      const otherShas = [...(commentToShas.get(e.comment) ?? [])].filter((s) => s !== e.sha);
+      if (otherComments.length > 0) {
+        findings.push({
+          job: e.job,
+          ref: e.ref,
+          slug: e.slug,
+          sha: e.sha,
+          kind: "mismatched",
+          conflict: `commit ${e.sha} is also annotated "# ${otherComments[0]}" elsewhere`,
+        });
+      } else if (otherShas.length > 0) {
+        findings.push({
+          job: e.job,
+          ref: e.ref,
+          slug: e.slug,
+          sha: e.sha,
+          kind: "mismatched",
+          conflict: `label "# ${e.comment}" is also attached to commit ${otherShas[0]} elsewhere`,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+export const gha059: PostSynthCheck = {
+  id: "GHA059",
+  description: "SHA-pinned action reference has a missing or internally-inconsistent version annotation",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const finding of findStalePinAnnotations(yaml)) {
+        const message =
+          finding.kind === "missing"
+            ? `Job "${finding.job}" pins ${finding.ref} to a commit SHA with no trailing version comment (e.g. "# v4.0.2") — add one so reviewers can sanity-check the digest.`
+            : `Job "${finding.job}" pins ${finding.ref} whose annotation is internally inconsistent (${finding.conflict}) — one of these labels no longer matches the digest it's attached to.`;
+        diagnostics.push({
+          checkId: "GHA059",
+          severity: "warning",
+          message,
+          entity: finding.job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha060.ts

@@ -0,0 +1,146 @@
+/**
+ * GHA060: Over-Scoped Generated Token
+ *
+ * Flags a GitHub App installation token minted with a `permission-<scope>:
+ * write`/`admin` input broader than what the job's consuming steps evidence.
+ * Targets the well-known GitHub App token actions (`actions/create-github-app-
+ * token`, `tibdex/github-app-token`, `getsentry/action-github-app-token`),
+ * which take `permission-<resource>: read|write|admin` inputs and hand back
+ * the minted token as a step output.
+ *
+ * Two ways a generated token is over-scoped:
+ *  1. Unused — the token's output (`steps.<id>.outputs.token`) is never
+ *     referenced by any other step in the job, so every write/admin scope
+ *     granted is pure waste.
+ *  2. No signal — the token IS consumed, but no other step in the job shows
+ *     any evidence (a `gh`/`git` invocation, an API path, a keyword) of
+ *     exercising a scope granted `write`/`admin`.
+ *
+ * "No signal" is a heuristic, not a proof — a step could exercise a scope
+ * through machinery this doesn't recognize (a custom script calling `octokit`
+ * directly, say). It reports `guidance`, not a `deterministic` fix, for
+ * exactly that reason: a human confirms before narrowing the grant.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractStepsByJob, parseActionUses } from "./yaml-helpers";
+
+const APP_TOKEN_SLUGS = new Set([
+  "actions/create-github-app-token",
+  "tibdex/github-app-token",
+  "getsentry/action-github-app-token",
+]);
+
+const WRITE_LEVELS = new Set(["write", "admin"]);
+
+/** Textual evidence that a step exercises a given permission scope. Not exhaustive — a fallback covers unlisted scopes. */
+const SCOPE_SIGNALS: Record<string, RegExp> = {
+  contents: /git\s+push|gh\s+release|\/(?:git\/)?contents\b/i,
+  issues: /gh\s+issue|\/issues\b/i,
+  "pull-requests": /gh\s+pr\b|\/pulls\b/i,
+  packages: /npm\s+publish|docker\s+push|\/packages\b/i,
+  administration: /\/admin\b|administration/i,
+  actions: /\/actions\/runs|gh\s+run\b/i,
+  checks: /check-runs|\bchecks\b/i,
+  deployments: /\/deployments\b/i,
+  statuses: /\/statuses\b/i,
+  workflows: /\.github\/workflows/i,
+  environments: /\/environments\b/i,
+};
+
+function scopeSignalMatches(scope: string, text: string): boolean {
+  const signal = SCOPE_SIGNALS[scope];
+  if (signal) return signal.test(text);
+  return new RegExp(scope.replace(/-/g, "[-_ ]?"), "i").test(text);
+}
+
+function stepText(step: Record<string, unknown>): string {
+  const parts: string[] = [];
+  if (typeof step.run === "string") parts.push(step.run);
+  if (step.with && typeof step.with === "object") parts.push(JSON.stringify(step.with));
+  if (step.env && typeof step.env === "object") parts.push(JSON.stringify(step.env));
+  if (typeof step.uses === "string") parts.push(step.uses);
+  return parts.join("\n");
+}
+
+export interface OverScopedTokenFinding {
+  job: string;
+  stepId: string;
+  scopes: string[];
+  reason: "unused" | "no-signal";
+}
+
+/** Find every generated GitHub App token whose granted write/admin scopes exceed what the job's other steps evidence. */
+export function findOverScopedTokens(yaml: string): OverScopedTokenFinding[] {
+  const findings: OverScopedTokenFinding[] = [];
+
+  for (const [job, steps] of extractStepsByJob(yaml)) {
+    steps.forEach((step, idx) => {
+      const uses = typeof step.uses === "string" ? step.uses : undefined;
+      if (!uses) return;
+      const parsed = parseActionUses(uses);
+      if (!parsed || !APP_TOKEN_SLUGS.has(parsed.slug)) return;
+
+      const withBlock = step.with && typeof step.with === "object" ? (step.with as Record<string, unknown>) : {};
+      const stepId = typeof step.id === "string" ? step.id : `#${idx}`;
+
+      const writeScopes: string[] = [];
+      for (const [key, value] of Object.entries(withBlock)) {
+        const m = /^permission-([a-z-]+)$/i.exec(key);
+        if (!m) continue;
+        if (WRITE_LEVELS.has(String(value).toLowerCase())) writeScopes.push(m[1]);
+      }
+      if (writeScopes.length === 0) return;
+
+      // Evidence comes only from OTHER steps — the minting step's own `with:`
+      // block names the scopes being granted, so it can't also count as
+      // evidence they're used.
+      const otherStepsText = steps
+        .filter((_, i) => i !== idx)
+        .map(stepText)
+        .join("\n");
+
+      const outputRef = `steps.${stepId}.outputs.token`;
+      if (!otherStepsText.includes(outputRef)) {
+        findings.push({ job, stepId, scopes: writeScopes, reason: "unused" });
+        return;
+      }
+
+      const unsignaled = writeScopes.filter((scope) => !scopeSignalMatches(scope, otherStepsText));
+      if (unsignaled.length > 0) {
+        findings.push({ job, stepId, scopes: unsignaled, reason: "no-signal" });
+      }
+    });
+  }
+
+  return findings;
+}
+
+export const gha060: PostSynthCheck = {
+  id: "GHA060",
+  description: "Generated GitHub App token granted broader scope than its consuming steps evidence",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const finding of findOverScopedTokens(yaml)) {
+        const scopeList = finding.scopes.map((s) => `permission-${s}`).join(", ");
+        const message =
+          finding.reason === "unused"
+            ? `Job "${finding.job}" step "${finding.stepId}" mints a GitHub App token with ${scopeList} but no other step references its output — remove the unused scope(s) or the token step entirely.`
+            : `Job "${finding.job}" step "${finding.stepId}" mints a GitHub App token with ${scopeList}, but no consuming step shows evidence of exercising that scope — narrow the token to the scopes actually used.`;
+        diagnostics.push({
+          checkId: "GHA060",
+          severity: "warning",
+          message,
+          entity: finding.job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};