@intentius/chant-lexicon-github 0.1.22 → 0.2.0

package/dist/rules/gha055.ts

@@ -0,0 +1,50 @@
+/**
+ * GHA055: Runtime Install of a Tool Already on the Runner
+ *
+ * Flags a `run:` step that installs (apt/brew/apk/choco) a tool that GitHub-
+ * hosted runners already ship. The redundant install adds a third-party
+ * download and supply-chain surface for no benefit and slows the job. Advisory;
+ * irrelevant on self-hosted runners that may lack the tool.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractRunBlocks } from "./yaml-helpers";
+import { PREINSTALLED_TOOLS } from "../rules/data/preinstalled-tools";
+
+const INSTALL_RE = /\b(?:apt(?:-get)?\s+install|brew\s+install|apk\s+add|choco\s+install)\b([^\n]*)/g;
+
+export const gha055: PostSynthCheck = {
+  id: "GHA055",
+  description: "Runtime install of a tool already present on the runner",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const preinstalled = new Set(PREINSTALLED_TOOLS);
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, run } of extractRunBlocks(yaml)) {
+        const redundant = new Set<string>();
+        let m: RegExpExecArray | null;
+        INSTALL_RE.lastIndex = 0;
+        while ((m = INSTALL_RE.exec(run)) !== null) {
+          for (const tok of m[1].split(/\s+/)) {
+            const name = tok.replace(/[^\w.+-]/g, "");
+            if (name && preinstalled.has(name)) redundant.add(name);
+          }
+        }
+        if (redundant.size > 0) {
+          diagnostics.push({
+            checkId: "GHA055",
+            severity: "info",
+            message: `Job "${job}" installs ${[...redundant].join(", ")} at runtime, but GitHub-hosted runners already ship ${redundant.size > 1 ? "these tools" : "this tool"}. Drop the redundant install (or rely on the preinstalled version) to reduce supply-chain surface.`,
+            entity: job,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha056.ts

@@ -0,0 +1,37 @@
+/**
+ * GHA056: Workflow Without a `name:`
+ *
+ * Flags an emitted workflow with no top-level `name:`. Without one, GitHub falls
+ * back to the file path in the Actions UI and audit logs, making runs harder to
+ * identify and review. A clear name improves observability and audit output.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractWorkflowName } from "./yaml-helpers";
+
+export const gha056: PostSynthCheck = {
+  id: "GHA056",
+  description: "Workflow without a name",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [lexicon, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      // Only inspect things that look like workflows (have a jobs: block).
+      if (!/^jobs:\s*$/m.test(yaml)) continue;
+      const name = extractWorkflowName(yaml);
+      if (!name) {
+        diagnostics.push({
+          checkId: "GHA056",
+          severity: "info",
+          message: `Workflow "${lexicon}" has no top-level name: — add one so runs are identifiable in the Actions UI and audit logs.`,
+          entity: "workflow",
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha057.ts

@@ -0,0 +1,40 @@
+/**
+ * GHA057: Dependency Update Executing Untrusted External Code
+ *
+ * Flags a dependabot `updates:` entry with
+ * `insecure-external-code-execution: allow`. That setting lets a freshly-pulled
+ * dependency run lifecycle scripts (e.g. npm `postinstall`) during the update
+ * itself — a compromised release executes in the update job before any review.
+ * Set it to `deny`, or isolate the ecosystem.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getDependabotYaml, extractDependabotUpdates } from "./yaml-helpers";
+
+export const gha057: PostSynthCheck = {
+  id: "GHA057",
+  description: "Dependency update allows executing untrusted external code",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const dependabot = getDependabotYaml(output);
+      if (!dependabot) continue;
+      for (const update of extractDependabotUpdates(dependabot)) {
+        if (update["insecure-external-code-execution"] === "allow") {
+          const eco = String(update["package-ecosystem"] ?? "?");
+          diagnostics.push({
+            checkId: "GHA057",
+            severity: "error",
+            message: `Dependabot update for "${eco}" sets insecure-external-code-execution: allow, running dependency lifecycle scripts during the update. Set it to deny.`,
+            entity: eco,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha058.ts

@@ -0,0 +1,48 @@
+/**
+ * GHA058: Dependency Update Without a Cooldown
+ *
+ * Flags a dependabot `updates:` entry with no cooldown (or an all-zero one). A
+ * version published seconds ago — including a compromised one — is adopted
+ * immediately, with no window for the ecosystem to yank it or for anyone to
+ * react. Configure a `cooldown:` so freshly-published versions wait before they
+ * are proposed.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getDependabotYaml, extractDependabotUpdates } from "./yaml-helpers";
+
+const COOLDOWN_DAY_KEYS = ["default-days", "semver-major-days", "semver-minor-days", "semver-patch-days"];
+
+function hasEffectiveCooldown(cooldown: unknown): boolean {
+  if (!cooldown || typeof cooldown !== "object") return false;
+  const c = cooldown as Record<string, unknown>;
+  return COOLDOWN_DAY_KEYS.some((k) => typeof c[k] === "number" && (c[k] as number) > 0);
+}
+
+export const gha058: PostSynthCheck = {
+  id: "GHA058",
+  description: "Dependency update has no cooldown window",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const dependabot = getDependabotYaml(output);
+      if (!dependabot) continue;
+      for (const update of extractDependabotUpdates(dependabot)) {
+        if (!hasEffectiveCooldown(update.cooldown)) {
+          const eco = String(update["package-ecosystem"] ?? "?");
+          diagnostics.push({
+            checkId: "GHA058",
+            severity: "warning",
+            message: `Dependabot update for "${eco}" has no cooldown — a version published moments ago is adopted immediately. Add a cooldown window so fresh (possibly compromised) releases wait before they are proposed.`,
+            entity: eco,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/yaml-helpers.ts

@@ -2,8 +2,32 @@
  * Helpers for parsing serialized GitHub Actions YAML in post-synth checks.
  */
 
+import { parseYAML } from "@intentius/chant/yaml";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
 export { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
 
+/**
+ * Return the emitted `.github/dependabot.yml` content from a serializer output,
+ * if present (it rides as an additional file alongside the workflow output).
+ */
+export function getDependabotYaml(output: string | SerializerResult): string | undefined {
+  if (typeof output === "string") return undefined;
+  return output.files?.["dependabot.yml"];
+}
+
+/** Parse the `updates:` array from a dependabot.yml document. */
+export function extractDependabotUpdates(dependabotYaml: string): Array<Record<string, unknown>> {
+  let doc: Record<string, unknown>;
+  try {
+    doc = parseYAML(dependabotYaml);
+  } catch {
+    return [];
+  }
+  const updates = doc.updates;
+  return Array.isArray(updates) ? (updates as Array<Record<string, unknown>>) : [];
+}
+
 export interface ParsedJob {
   name: string;
   needs?: string[];
@@ -127,3 +151,314 @@ export function extractWorkflowName(yaml: string): string | undefined {
 export function hasPermissions(yaml: string): boolean {
   return /^permissions:/m.test(yaml);
 }
+
+/** A single `uses:` reference found in a workflow. */
+export interface ActionRef {
+  /** Owning job name. */
+  job: string;
+  /** The raw `uses:` value (e.g. `actions/setup-node@v4`). */
+  ref: string;
+  /** Whether it is a step-level action or a job-level reusable workflow. */
+  level: "step" | "job";
+}
+
+/** A container/service/docker image reference found in a workflow. */
+export interface ImageRef {
+  /** Owning job name. */
+  job: string;
+  /** The raw image reference (e.g. `node:20`). */
+  image: string;
+  /** Where the image was declared. */
+  source: "container" | "service" | "step";
+}
+
+function parseDoc(yaml: string): Record<string, unknown> | undefined {
+  try {
+    return parseYAML(yaml);
+  } catch {
+    return undefined;
+  }
+}
+
+function jobEntries(yaml: string): Array<[string, Record<string, unknown>]> {
+  const doc = parseDoc(yaml);
+  const jobs = doc?.jobs;
+  if (!jobs || typeof jobs !== "object") return [];
+  const out: Array<[string, Record<string, unknown>]> = [];
+  for (const [name, val] of Object.entries(jobs as Record<string, unknown>)) {
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      out.push([name, val as Record<string, unknown>]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract every `uses:` reference from the workflow — both step-level actions
+ * and job-level reusable-workflow calls. Uses the structural YAML parser so
+ * nested jobs/steps are handled reliably.
+ */
+export function extractActionRefs(yaml: string): ActionRef[] {
+  const refs: ActionRef[] = [];
+  for (const [job, jobObj] of jobEntries(yaml)) {
+    if (typeof jobObj.uses === "string") {
+      refs.push({ job, ref: jobObj.uses, level: "job" });
+    }
+    const steps = jobObj.steps;
+    if (Array.isArray(steps)) {
+      for (const step of steps) {
+        if (step && typeof step === "object" && typeof (step as Record<string, unknown>).uses === "string") {
+          refs.push({ job, ref: (step as Record<string, unknown>).uses as string, level: "step" });
+        }
+      }
+    }
+  }
+  return refs;
+}
+
+/**
+ * Extract every container/service/`docker://` image reference from the workflow.
+ */
+export function extractImageRefs(yaml: string): ImageRef[] {
+  const refs: ImageRef[] = [];
+  for (const [job, jobObj] of jobEntries(yaml)) {
+    const container = jobObj.container;
+    if (typeof container === "string") {
+      refs.push({ job, image: container, source: "container" });
+    } else if (container && typeof container === "object" && typeof (container as Record<string, unknown>).image === "string") {
+      refs.push({ job, image: (container as Record<string, unknown>).image as string, source: "container" });
+    }
+
+    const services = jobObj.services;
+    if (services && typeof services === "object" && !Array.isArray(services)) {
+      for (const svc of Object.values(services as Record<string, unknown>)) {
+        if (typeof svc === "string") {
+          refs.push({ job, image: svc, source: "service" });
+        } else if (svc && typeof svc === "object" && typeof (svc as Record<string, unknown>).image === "string") {
+          refs.push({ job, image: (svc as Record<string, unknown>).image as string, source: "service" });
+        }
+      }
+    }
+
+    const steps = jobObj.steps;
+    if (Array.isArray(steps)) {
+      for (const step of steps) {
+        const uses = step && typeof step === "object" ? (step as Record<string, unknown>).uses : undefined;
+        if (typeof uses === "string" && uses.startsWith("docker://")) {
+          refs.push({ job, image: uses.slice("docker://".length), source: "step" });
+        }
+      }
+    }
+  }
+  return refs;
+}
+
+/**
+ * Walk the `jobs:` block line-by-line, tracking the current job. Robust to `|`
+ * block scalars (which the structural parser does not handle), so it is the
+ * right tool for scanning `run:`/`if:`/`runs-on:` content.
+ */
+function scanJobLines(yaml: string, onLine: (job: string, line: string, indent: number, lineNo: number, lines: string[]) => void): void {
+  const lines = yaml.split("\n");
+  let inJobs = false;
+  let currentJob = "";
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^jobs:\s*$/.test(line)) { inJobs = true; continue; }
+    if (!inJobs) continue;
+    if (/^\S/.test(line)) { inJobs = false; continue; } // dedented to a new top-level key
+    const jobHeader = line.match(/^ {2}([A-Za-z0-9_-]+):\s*$/);
+    if (jobHeader) { currentJob = jobHeader[1]; continue; }
+    if (!currentJob) continue;
+    const indent = line.search(/\S/);
+    if (indent < 0) continue;
+    onLine(currentJob, line, indent, i, lines);
+  }
+}
+
+/** A `run:` script block with its owning job. */
+export interface RunBlock {
+  job: string;
+  run: string;
+}
+
+/**
+ * Extract every `run:` script (inline and `|`/`>` block scalars) with its
+ * owning job.
+ */
+export function extractRunBlocks(yaml: string): RunBlock[] {
+  const out: RunBlock[] = [];
+  const consumed = new Set<number>();
+  scanJobLines(yaml, (job, line, _indent, lineNo, lines) => {
+    if (consumed.has(lineNo)) return;
+    const m = line.match(/^(\s*)(- )?run:\s*(.*)$/);
+    if (!m) return;
+    const keyIndent = m[1].length + (m[2] ? 2 : 0); // column where `run:` begins
+    const value = m[3].trim();
+    if (value === "|" || value === "|-" || value === ">" || value === ">-" || value === "|+" || value === ">+") {
+      const blockLines: string[] = [];
+      for (let j = lineNo + 1; j < lines.length; j++) {
+        const bl = lines[j];
+        if (bl.trim() === "") { blockLines.push(""); consumed.add(j); continue; }
+        const bi = bl.search(/\S/);
+        if (bi <= keyIndent) break;
+        blockLines.push(bl.trimStart());
+        consumed.add(j);
+      }
+      out.push({ job, run: blockLines.join("\n") });
+    } else {
+      out.push({ job, run: value.replace(/^['"]|['"]$/g, "") });
+    }
+  });
+  return out;
+}
+
+/** An `if:` condition with its owning job. */
+export interface IfCondition {
+  job: string;
+  expr: string;
+}
+
+/** Extract every `if:` condition (job-level and step-level) with its job. */
+export function extractIfConditions(yaml: string): IfCondition[] {
+  const out: IfCondition[] = [];
+  scanJobLines(yaml, (job, line) => {
+    const m = line.match(/^\s+(?:- )?if:\s*(.+)$/);
+    if (m) out.push({ job, expr: m[1].trim().replace(/^['"]|['"]$/g, "") });
+  });
+  return out;
+}
+
+/** Extract each job's `runs-on:` value(s) as a flat list of labels. */
+export function extractRunsOnByJob(yaml: string): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  scanJobLines(yaml, (job, line, indent, lineNo, lines) => {
+    const m = line.match(/^\s+runs-on:\s*(.*)$/);
+    if (!m) return;
+    const value = m[1].trim();
+    const labels: string[] = [];
+    if (value === "") {
+      for (let j = lineNo + 1; j < lines.length; j++) {
+        const item = lines[j].match(/^\s+- (.+)$/);
+        if (!item) break;
+        labels.push(item[1].trim().replace(/^['"]|['"]$/g, ""));
+      }
+    } else if (value.startsWith("[")) {
+      for (const part of value.replace(/^\[|\]$/g, "").split(",")) {
+        const t = part.trim().replace(/^['"]|['"]$/g, "");
+        if (t) labels.push(t);
+      }
+    } else {
+      labels.push(value.replace(/^['"]|['"]$/g, ""));
+    }
+    out.set(job, labels);
+  });
+  return out;
+}
+
+/** Pull every `${{ ... }}` expression body out of a string. */
+export function extractExpressions(text: string): string[] {
+  const out: string[] = [];
+  const re = /\$\{\{(.+?)\}\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    out.push(m[1].trim());
+  }
+  return out;
+}
+
+/** Every line inside the `jobs:` block paired with its owning job name. */
+export function jobLines(yaml: string): Array<{ job: string; line: string }> {
+  const out: Array<{ job: string; line: string }> = [];
+  scanJobLines(yaml, (job, line) => out.push({ job, line }));
+  return out;
+}
+
+/** All lines inside the `jobs:` block grouped by owning job. */
+export function linesByJob(yaml: string): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  scanJobLines(yaml, (job, line) => {
+    const arr = out.get(job) ?? [];
+    arr.push(line);
+    out.set(job, arr);
+  });
+  return out;
+}
+
+/** Set of jobs that declare an `environment:`. */
+export function extractJobEnvironments(yaml: string): Set<string> {
+  const set = new Set<string>();
+  scanJobLines(yaml, (job, line) => {
+    if (/^\s+environment:/.test(line)) set.add(job);
+  });
+  return set;
+}
+
+/** Set of jobs whose body references a `secrets.` context. */
+export function jobsReferencingSecrets(yaml: string): Set<string> {
+  const set = new Set<string>();
+  scanJobLines(yaml, (job, line) => {
+    if (/secrets\./.test(line)) set.add(job);
+  });
+  return set;
+}
+
+/** A permissions value as it appears in YAML: a string preset or a scope map. */
+export type PermissionsValue = string | Record<string, string>;
+
+/** The workflow-level `permissions:` value, if present. */
+export function extractWorkflowPermissions(yaml: string): PermissionsValue | undefined {
+  const doc = parseDoc(yaml);
+  const perms = doc?.permissions;
+  if (typeof perms === "string") return perms;
+  if (perms && typeof perms === "object" && !Array.isArray(perms)) return perms as Record<string, string>;
+  return undefined;
+}
+
+/** Per-job `permissions:` values, keyed by job name. Only jobs that declare one. */
+export function extractJobPermissions(yaml: string): Map<string, PermissionsValue> {
+  const out = new Map<string, PermissionsValue>();
+  for (const [job, jobObj] of jobEntries(yaml)) {
+    const perms = jobObj.permissions;
+    if (typeof perms === "string") out.set(job, perms);
+    else if (perms && typeof perms === "object" && !Array.isArray(perms)) out.set(job, perms as Record<string, string>);
+  }
+  return out;
+}
+
+/**
+ * Classify a permissions value's write surface.
+ * `writeAll` is the `write-all` blanket preset; `scopes` lists the individual
+ * scopes granted `write` in map form.
+ */
+export function writeSurface(perms: PermissionsValue): { writeAll: boolean; scopes: string[] } {
+  if (typeof perms === "string") {
+    return { writeAll: perms === "write-all", scopes: [] };
+  }
+  const scopes: string[] = [];
+  for (const [scope, level] of Object.entries(perms)) {
+    if (level === "write") scopes.push(scope);
+  }
+  return { writeAll: false, scopes };
+}
+
+/** True if the permissions value grants any write access (blanket or scoped). */
+export function grantsWrite(perms: PermissionsValue): boolean {
+  const { writeAll, scopes } = writeSurface(perms);
+  return writeAll || scopes.length > 0;
+}
+
+/**
+ * Split an action `uses:` value into its `owner/repo` slug and git ref.
+ * Returns undefined for local (`./`, `../`) and `docker://` references, which
+ * are not GitHub action repository references.
+ */
+export function parseActionUses(uses: string): { owner: string; repo: string; slug: string; gitRef: string } | undefined {
+  if (uses.startsWith("./") || uses.startsWith("../") || uses.startsWith("docker://")) return undefined;
+  const at = uses.lastIndexOf("@");
+  const path = at === -1 ? uses : uses.slice(0, at);
+  const gitRef = at === -1 ? "" : uses.slice(at + 1);
+  const segments = path.split("/");
+  if (segments.length < 2 || !segments[0] || !segments[1]) return undefined;
+  return { owner: segments[0], repo: segments[1], slug: `${segments[0]}/${segments[1]}`, gitRef };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.1.22",
+  "version": "0.2.0",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",