@intentius/chant-lexicon-gitlab 0.1.23 → 0.3.0

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

@@ -0,0 +1,48 @@
+/**
+ * WGL030: Mutable or Insecure include:remote
+ *
+ * Flags `include:remote` URLs that are fetched over HTTP (no transport
+ * integrity) or over HTTPS but inherently mutable (a raw URL can be repointed
+ * at any time). Prefer `include:project` pinned to a tag/SHA, or a pinned
+ * component, over a remote URL. Generalizes WGL017 (non-HTTPS) to includes.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIncludes } from "./yaml-helpers";
+
+export const wgl030: PostSynthCheck = {
+  id: "WGL030",
+  description: "include:remote is insecure (HTTP) or mutable",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const entry of extractIncludes(yaml)) {
+        const isRemote = entry.kind === "remote" || (entry.kind === "string" && /^https?:\/\//.test(entry.value));
+        if (!isRemote) continue;
+
+        if (/^http:\/\//.test(entry.value)) {
+          diagnostics.push({
+            checkId: "WGL030",
+            severity: "error",
+            message: `include:remote "${entry.value}" is fetched over HTTP — an attacker on the network can swap the included config. Use HTTPS, and prefer a pinned include:project or component.`,
+            entity: entry.value,
+            lexicon: "gitlab",
+          });
+        } else {
+          diagnostics.push({
+            checkId: "WGL030",
+            severity: "warning",
+            message: `include:remote "${entry.value}" is a mutable URL — its contents can change after review. Prefer include:project pinned to a tag/SHA, or a pinned component.`,
+            entity: entry.value,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,66 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl031 } from "./wgl031";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL031: container image without digest", () => {
+  test("flags an image pinned to a tag", () => {
+    const yaml = `build-job:
+  image:
+    name: node:20
+  script:
+    - echo build
+`;
+    const diags = wgl031.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL031");
+    expect(diags[0].message).toContain("node:20");
+  });
+
+  test("flags a service image pinned to a tag", () => {
+    const yaml = `build-job:
+  services:
+    - name: postgres:16
+  script:
+    - echo build
+`;
+    const diags = wgl031.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("postgres:16");
+  });
+
+  test("does not flag an image pinned to a digest", () => {
+    const yaml = `build-job:
+  image:
+    name: node@sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+  script:
+    - echo build
+`;
+    const diags = wgl031.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag a variable-based image reference", () => {
+    const yaml = `build-job:
+  image:
+    name: $CI_REGISTRY_IMAGE:latest
+  script:
+    - echo build
+`;
+    const diags = wgl031.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,37 @@
+/**
+ * WGL031: Container Image Without an Immutable Digest
+ *
+ * Flags `image:` and `services:` references that are not pinned to an immutable
+ * `@sha256:` digest. A mutable tag can be repointed to a different image after
+ * review. Images built from a variable (e.g. `$CI_REGISTRY_IMAGE:tag`) are
+ * skipped — their concrete reference is not knowable from the static config.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractImageRefs } from "./yaml-helpers";
+
+export const wgl031: PostSynthCheck = {
+  id: "WGL031",
+  description: "Container image not pinned to an immutable digest",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, image, source } of extractImageRefs(yaml)) {
+        if (image.includes("@sha256:")) continue;
+        if (image.includes("$")) continue; // variable-based reference — not statically knowable
+        diagnostics.push({
+          checkId: "WGL031",
+          severity: "warning",
+          message: `Job "${job}" ${source === "service" ? "service image" : "image"} "${image}" is not pinned to a digest — reference it by @sha256:... so the image cannot change after review.`,
+          entity: job,
+          lexicon: "gitlab",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,53 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl032, nearestKnownSource } from "./wgl032";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL032: look-alike include source", () => {
+  test("nearestKnownSource flags a near-miss", () => {
+    expect(nearestKnownSource("gitlab-org/gitlab")).toBeUndefined();
+    expect(nearestKnownSource("gitlab-org/gitlabb")).toBe("gitlab-org/gitlab");
+    expect(nearestKnownSource("totally/unrelated")).toBeUndefined();
+  });
+
+  test("flags a typo-squatted include:project", () => {
+    const yaml = `include:
+  - project: gitlab-org/gitlabb
+    ref: v1.0.0
+    file: /x.yml
+
+stages:
+  - build
+`;
+    const diags = wgl032.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL032");
+    expect(diags[0].message).toContain("gitlab-org/gitlab");
+  });
+
+  test("does not flag an exact known source", () => {
+    const yaml = `include:
+  - project: gitlab-org/gitlab
+    ref: v1.0.0
+    file: /x.yml
+
+stages:
+  - build
+`;
+    const diags = wgl032.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,68 @@
+/**
+ * WGL032: Include/Component Source Resembling a Well-Known Project
+ *
+ * Flags an `include:project` path or `component:` source that is a near-miss
+ * (edit distance 1–2) of a well-known GitLab CI source but not an exact match —
+ * a likely typo or an impersonation of the trusted project. Advisory; backed by
+ * a vendored reference list.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIncludes } from "./yaml-helpers";
+import { KNOWN_INCLUDE_SOURCES, editDistance } from "../rules/data/known-include-sources";
+
+const KNOWN = new Set(KNOWN_INCLUDE_SOURCES);
+
+/** Reduce a component address (`host/group/name@ver`) or project path to its group/name path. */
+function sourcePath(value: string, kind: string): string {
+  let v = value;
+  if (kind === "component") {
+    const at = v.lastIndexOf("@");
+    if (at !== -1) v = v.slice(0, at);
+    const slash = v.indexOf("/");
+    if (slash !== -1 && v.slice(0, slash).includes(".")) v = v.slice(slash + 1); // drop host
+  }
+  return v;
+}
+
+export function nearestKnownSource(path: string): string | undefined {
+  if (KNOWN.has(path)) return undefined;
+  let best: string | undefined;
+  let bestDist = 3;
+  for (const known of KNOWN) {
+    const d = editDistance(path, known, 2);
+    if (d >= 1 && d <= 2 && d < bestDist) {
+      best = known;
+      bestDist = d;
+    }
+  }
+  return best;
+}
+
+export const wgl032: PostSynthCheck = {
+  id: "WGL032",
+  description: "Include/component source resembles a well-known project (possible impersonation)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const entry of extractIncludes(yaml)) {
+        if (entry.kind !== "project" && entry.kind !== "component") continue;
+        const path = sourcePath(entry.value, entry.kind);
+        const lookAlike = nearestKnownSource(path);
+        if (!lookAlike) continue;
+        diagnostics.push({
+          checkId: "WGL032",
+          severity: "warning",
+          message: `Include source "${path}" closely resembles the well-known "${lookAlike}". Confirm the source is who you intend — this may be a typo or impersonation.`,
+          entity: entry.value,
+          lexicon: "gitlab",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,58 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl033 } from "./wgl033";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL033: OIDC id_token audience scoping", () => {
+  test("flags a wildcard audience", () => {
+    const yaml = `deploy:
+  stage: deploy
+  id_tokens:
+    GCP_TOKEN:
+      aud: '*'
+  script:
+    - echo deploy
+`;
+    const diags = wgl033.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL033");
+    expect(diags[0].entity).toBe("deploy");
+  });
+
+  test("flags an empty audience", () => {
+    const yaml = `deploy:
+  id_tokens:
+    GCP_TOKEN:
+      aud: ''
+  script:
+    - echo deploy
+`;
+    const diags = wgl033.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("does not flag a scoped audience", () => {
+    const yaml = `deploy:
+  id_tokens:
+    GCP_TOKEN:
+      aud: https://iam.googleapis.com
+  script:
+    - echo deploy
+`;
+    const diags = wgl033.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,38 @@
+/**
+ * WGL033: OIDC id_token Without a Scoped Audience
+ *
+ * Flags an `id_tokens:` declaration with no `aud:` or a wildcard audience. The
+ * audience binds the minted OIDC token to a specific relying party; without it
+ * (or with `*`), a leaked token is accepted anywhere, defeating the point of
+ * short-lived federated identity. Set `aud:` to the exact audience(s) needed.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIdTokens } from "./yaml-helpers";
+
+export const wgl033: PostSynthCheck = {
+  id: "WGL033",
+  description: "OIDC id_token without a scoped audience",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const { job, name, aud } of extractIdTokens(yaml)) {
+        const broad = aud.length === 0 || aud.some((a) => a === "*" || a === "" || a.includes("*"));
+        if (broad) {
+          diagnostics.push({
+            checkId: "WGL033",
+            severity: "warning",
+            message: `Job "${job}" id_token "${name}" has ${aud.length === 0 ? "no aud:" : "a wildcard audience"}. Scope it to the exact audience the relying party expects so a leaked token cannot be used elsewhere.`,
+            entity: job,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,60 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl034 } from "./wgl034";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL034: OIDC token mintable from a merge-request pipeline", () => {
+  test("flags an OIDC job reachable from merge requests", () => {
+    const yaml = `deploy:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  id_tokens:
+    GCP_TOKEN:
+      aud: https://iam.googleapis.com
+  script:
+    - echo deploy
+`;
+    const diags = wgl034.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL034");
+    expect(diags[0].entity).toBe("deploy");
+  });
+
+  test("does not flag an OIDC job gated to a protected branch", () => {
+    const yaml = `deploy:
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+  id_tokens:
+    GCP_TOKEN:
+      aud: https://iam.googleapis.com
+  script:
+    - echo deploy
+`;
+    const diags = wgl034.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag a merge-request job without OIDC", () => {
+    const yaml = `test:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - echo test
+`;
+    const diags = wgl034.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,42 @@
+/**
+ * WGL034: OIDC id_token Mintable from a Merge-Request Pipeline
+ *
+ * Flags a job that declares an `id_tokens:` (OIDC) and is reachable from
+ * merge-request pipelines. MR pipelines can be triggered by outside
+ * contributors, so a job that mints a cloud-federated token there hands fork
+ * code a path to your cloud roles. Gate OIDC jobs to protected refs, or require
+ * approval before they run.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIdTokens, extractJobSection, isMergeRequestReachable } from "./yaml-helpers";
+
+export const wgl034: PostSynthCheck = {
+  id: "WGL034",
+  description: "OIDC id_token mintable from a merge-request pipeline",
+
+  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 } of extractIdTokens(yaml)) {
+        if (seen.has(job)) continue;
+        const section = extractJobSection(yaml, job);
+        if (section && isMergeRequestReachable(section)) {
+          seen.add(job);
+          diagnostics.push({
+            checkId: "WGL034",
+            severity: "warning",
+            message: `Job "${job}" mints an OIDC id_token and is reachable from merge-request pipelines, which outside contributors can trigger. Restrict it to protected refs or require approval before it runs.`,
+            entity: job,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,42 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl035 } from "./wgl035";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL035: untrusted CI variable in script", () => {
+  test("flags an untrusted ref name used in a script command", () => {
+    const yaml = `build:
+  stage: build
+  script:
+    - git checkout $CI_COMMIT_REF_NAME
+`;
+    const diags = wgl035.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL035");
+    expect(diags[0].entity).toBe("build");
+    expect(diags[0].message).toContain("CI_COMMIT_REF_NAME");
+  });
+
+  test("does not flag a trusted variable", () => {
+    const yaml = `build:
+  stage: build
+  script:
+    - echo "$CI_COMMIT_SHA"
+`;
+    const diags = wgl035.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,44 @@
+/**
+ * WGL035: Untrusted CI Variable Interpolated into a Script
+ *
+ * Flags an attacker-controllable predefined variable (branch/tag name, commit or
+ * merge-request title/description, author) referenced in a `script:` command. A
+ * crafted branch name or commit title containing shell metacharacters can break
+ * out of the command. Quote the reference and avoid using it in sensitive
+ * commands, or sanitize it first.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractScriptCommands } from "./yaml-helpers";
+import { UNTRUSTED_CI_VARIABLES, variableReferenced } from "../rules/data/untrusted-variables";
+
+export const wgl035: PostSynthCheck = {
+  id: "WGL035",
+  description: "Untrusted CI variable interpolated into a script command",
+
+  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, command } of extractScriptCommands(yaml)) {
+        for (const name of UNTRUSTED_CI_VARIABLES) {
+          if (!variableReferenced(command, name)) continue;
+          const key = `${job}:${name}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          diagnostics.push({
+            checkId: "WGL035",
+            severity: "warning",
+            message: `Job "${job}" uses the attacker-controllable variable $${name} in a script command. A crafted value can inject shell commands — quote it ("$${name}") and avoid using it in sensitive commands, or sanitize it first.`,
+            entity: job,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl036 } from "./wgl036";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL036: privileged DinD reachable from merge requests", () => {
+  test("flags DinD in a merge-request-reachable job", () => {
+    const yaml = `build:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  image: docker:24
+  services:
+    - docker:24-dind
+  script:
+    - docker build .
+`;
+    const diags = wgl036.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL036");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("does not flag DinD gated to a protected branch", () => {
+    const yaml = `build:
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+  image: docker:24
+  services:
+    - docker:24-dind
+  script:
+    - docker build .
+`;
+    const diags = wgl036.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,44 @@
+/**
+ * WGL036: Privileged Service / Docker-in-Docker Reachable from Merge Requests
+ *
+ * Flags a job that uses Docker-in-Docker (a privileged service) and is reachable
+ * from merge-request pipelines. MR pipelines can run code from an outside
+ * contributor; a privileged DinD service shares the host daemon socket and can
+ * be used to escape the build and reach the runner. Restrict privileged services
+ * to protected refs, or require approval before such jobs run.
+ *
+ * Complements WGL026 (DinD without TLS) by adding the trust-boundary dimension.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs, extractJobSection, isMergeRequestReachable } from "./yaml-helpers";
+
+const DIND_RE = /docker:[\w.-]*dind|dind|privileged:\s*true/;
+
+export const wgl036: PostSynthCheck = {
+  id: "WGL036",
+  description: "Privileged service / DinD reachable from merge-request pipelines",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const [job] of extractJobs(yaml)) {
+        const section = extractJobSection(yaml, job);
+        if (!section) continue;
+        if (DIND_RE.test(section) && isMergeRequestReachable(section)) {
+          diagnostics.push({
+            checkId: "WGL036",
+            severity: "warning",
+            message: `Job "${job}" runs a privileged Docker-in-Docker service and is reachable from merge-request pipelines, which outside contributors can trigger. Restrict privileged services to protected refs or require approval.`,
+            entity: job,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};