@noctcore/lint-meta-rules 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -52,6 +52,26 @@ interface CanonicalHelpersSingleHomeOptions {
  */
 declare function createCanonicalHelpersSingleHomeRule(options?: CanonicalHelpersSingleHomeOptions): IMetaRule;
 
+/**
+ * Options for {@link createDockerfileBaseImageDigestPinRule}.
+ *
+ * Ported from a private monorepo that walked the whole tree with a hardcoded Dockerfile
+ * name regex and skip list; both are now options.
+ */
+interface DockerfileBaseImageDigestPinOptions {
+    /**
+     * Globs that find Dockerfiles. Default `Dockerfile`, `Dockerfile.*` and
+     * `*.Dockerfile` at any depth, dot-directories included.
+     */
+    readonly dockerfileGlobs?: readonly string[];
+    /** A path with any of these segments is skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/** Every Dockerfile FROM must pin its base image by digest. */
+declare function createDockerfileBaseImageDigestPinRule(options?: DockerfileBaseImageDigestPinOptions): IMetaRule;
+
 /**
  * Options for {@link createFileSizeRatchetRule}.
  *
@@ -96,6 +116,38 @@ interface FileSizeRatchetOptions {
  */
 declare function createFileSizeRatchetRule(options?: FileSizeRatchetOptions): IMetaRule;
 
+/**
+ * Options for {@link createGithubActionsRunnerPinnedRule}.
+ *
+ * Ported from a private monorepo that hardcoded the `*-latest` label shape and read a
+ * pre-collected `workflowFiles` list; both are now options.
+ */
+interface GithubActionsRunnerPinnedOptions {
+    /** Globs of the workflow files to scan. Default `.github/workflows/*.y(a)ml`. */
+    readonly workflowGlobs?: readonly string[];
+    /** A runner label matching this is floating. Default `/^[\w.-]+-latest$/u`. */
+    readonly floatingLabel?: RegExp;
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/** No workflow job may run on a floating (`*-latest`) runner label. */
+declare function createGithubActionsRunnerPinnedRule(options?: GithubActionsRunnerPinnedOptions): IMetaRule;
+
+/**
+ * Options for {@link createGithubActionsShaPinnedRule}.
+ *
+ * Ported from a private monorepo whose runner handed the rule a pre-collected
+ * `workflowFiles` list; that list is now the `workflowGlobs` option.
+ */
+interface GithubActionsShaPinnedOptions {
+    /** Globs of the workflow files to scan. Default `.github/workflows/*.y(a)ml`. */
+    readonly workflowGlobs?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/** Every workflow `uses:` ref must be a full commit SHA with a `# vN` comment. */
+declare function createGithubActionsShaPinnedRule(options?: GithubActionsShaPinnedOptions): IMetaRule;
+
 /**
  * Options for {@link createLayerRankRule}.
  *
@@ -219,6 +271,75 @@ interface PackageShapeOptions {
  */
 declare function createPackageShapeRule(options?: PackageShapeOptions): IMetaRule;
 
+/**
+ * Options for {@link createSecurityScannerVersionParityRule}.
+ *
+ * Ported from a private monorepo that hardcoded gitleaks, its `GITLEAKS_VERSION` /
+ * `GITLEAKS_IMAGE` variable names, the hook path `scripts/ci/pre-push.sh` and a
+ * pre-collected `workflowFiles` list. Each is now an option whose default is the
+ * original value, so the rule can pin any scanner that prints `<scanner> version`.
+ */
+interface SecurityScannerVersionParityOptions {
+    /** The scanner's binary name, as it appears in the hook and in its image name. Default `gitleaks`. */
+    readonly scanner?: string;
+    /** The env / shell variable both sides pin the version in. Default `GITLEAKS_VERSION`. */
+    readonly versionVariable?: string;
+    /** The hook's optional image variable, whose `<scanner>:vX.Y.Z` tag must agree. Default `GITLEAKS_IMAGE`. */
+    readonly imageVariable?: string;
+    /** The local hook script, repo-relative. Default `scripts/ci/pre-push.sh`. */
+    readonly hookFile?: string;
+    /** Globs of the workflow files to scan. Default `.github/workflows/*.y(a)ml`. */
+    readonly workflowGlobs?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Different scanner versions ship different rulesets, so a push can pass the
+ * local hook and fail CI (or the reverse) with no code difference. This ties
+ * three things together:
+ *
+ *   - every workflow that pins the version variable pins the same one,
+ *   - the hook declares the same variable equal to it (and a literal image tag,
+ *     if it has one, agrees too),
+ *   - the hook actually runs `<scanner> version`, so a drifted native install is
+ *     caught at run time.
+ *
+ * Dormant when neither side mentions the scanner.
+ */
+declare function createSecurityScannerVersionParityRule(options?: SecurityScannerVersionParityOptions): IMetaRule;
+
+/**
+ * Options for {@link createServiceImageDigestPinRule}.
+ *
+ * Ported from a private monorepo that hardcoded a one-entry exemption list (an
+ * OpenTelemetry collector tag its registry does not serve), a compose file name
+ * regex, a skip list and a pre-collected `workflowFiles` list. All four are now
+ * options; the exemption list defaults to empty.
+ */
+interface ServiceImageDigestPinOptions {
+    /** Globs of the workflow files to scan. Default `.github/workflows/*.y(a)ml`. */
+    readonly workflowGlobs?: readonly string[];
+    /** Globs that find compose files. Default every `compose` / `docker-compose` `.yml` / `.yaml` variant at any depth, dot-directories included. */
+    readonly composeGlobs?: readonly string[];
+    /** A compose path with any of these segments is skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /**
+     * Exact image refs that are allowed unpinned, for a ref the registry cannot
+     * serve a digest for. Each entry should say why in the consumer's config.
+     * Default none.
+     */
+    readonly allowUnpinned?: readonly string[];
+    /** Whether a violation fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/**
+ * Every workflow service/container image and every compose image must be pinned
+ * by digest. A tag (`postgres:17-alpine`) or `latest` names whatever the registry
+ * serves today, so a green build can change under an unchanged commit.
+ * `tag@sha256:<digest>` keeps the readable tag and fixes the content.
+ */
+declare function createServiceImageDigestPinRule(options?: ServiceImageDigestPinOptions): IMetaRule;
+
 /**
  * Options for {@link createTestRunnerSegregationRule}.
  *
@@ -376,11 +497,16 @@ declare function countLines(text: string): number;
 declare const RULE_FACTORIES: {
     readonly 'agents-doc-presence': typeof createAgentsDocPresenceRule;
     readonly 'canonical-helpers-single-home': typeof createCanonicalHelpersSingleHomeRule;
+    readonly 'dockerfile-base-image-digest-pin': typeof createDockerfileBaseImageDigestPinRule;
     readonly 'file-size-ratchet': typeof createFileSizeRatchetRule;
+    readonly 'github-actions-runner-pinned': typeof createGithubActionsRunnerPinnedRule;
+    readonly 'github-actions-sha-pinned': typeof createGithubActionsShaPinnedRule;
     readonly 'layer-rank': typeof createLayerRankRule;
     readonly 'no-cloned-component-folders': typeof createNoClonedComponentFoldersRule;
     readonly 'no-warn-severity': typeof createNoWarnSeverityRule;
     readonly 'package-shape': typeof createPackageShapeRule;
+    readonly 'security-scanner-version-parity': typeof createSecurityScannerVersionParityRule;
+    readonly 'service-image-digest-pin': typeof createServiceImageDigestPinRule;
     readonly 'test-runner-segregation': typeof createTestRunnerSegregationRule;
     readonly 'test-sibling-enforcement': typeof createTestSiblingEnforcementRule;
     readonly 'test-workspace-enrollment': typeof createTestWorkspaceEnrollmentRule;
@@ -392,4 +518,4 @@ declare const RULE_IDS: (keyof typeof RULE_FACTORIES)[];
 /** Instantiate every catalog rule with its default options. */
 declare function createAllRules(): IMetaRule[];
 
-export { type AgentsDocPresenceOptions, type CanonicalHelpersSingleHomeOptions, type FileSizeRatchetOptions, type LayerRankOptions, type NoClonedComponentFoldersOptions, type NoWarnSeverityOptions, type PackageShapeOptions, RULE_FACTORIES, RULE_IDS, type TestRunnerSegregationOptions, type TestSiblingEnforcementOptions, type TestWorkspaceEnrollmentOptions, type UiPrimitiveShapeOptions, type WorkspaceGraphParityOptions, countLines, createAgentsDocPresenceRule, createAllRules, createCanonicalHelpersSingleHomeRule, createFileSizeRatchetRule, createLayerRankRule, createNoClonedComponentFoldersRule, createNoWarnSeverityRule, createPackageShapeRule, createTestRunnerSegregationRule, createTestSiblingEnforcementRule, createTestWorkspaceEnrollmentRule, createUiPrimitiveShapeRule, createWorkspaceGraphParityRule };
+export { type AgentsDocPresenceOptions, type CanonicalHelpersSingleHomeOptions, type DockerfileBaseImageDigestPinOptions, type FileSizeRatchetOptions, type GithubActionsRunnerPinnedOptions, type GithubActionsShaPinnedOptions, type LayerRankOptions, type NoClonedComponentFoldersOptions, type NoWarnSeverityOptions, type PackageShapeOptions, RULE_FACTORIES, RULE_IDS, type SecurityScannerVersionParityOptions, type ServiceImageDigestPinOptions, type TestRunnerSegregationOptions, type TestSiblingEnforcementOptions, type TestWorkspaceEnrollmentOptions, type UiPrimitiveShapeOptions, type WorkspaceGraphParityOptions, countLines, createAgentsDocPresenceRule, createAllRules, createCanonicalHelpersSingleHomeRule, createDockerfileBaseImageDigestPinRule, createFileSizeRatchetRule, createGithubActionsRunnerPinnedRule, createGithubActionsShaPinnedRule, createLayerRankRule, createNoClonedComponentFoldersRule, createNoWarnSeverityRule, createPackageShapeRule, createSecurityScannerVersionParityRule, createServiceImageDigestPinRule, createTestRunnerSegregationRule, createTestSiblingEnforcementRule, createTestWorkspaceEnrollmentRule, createUiPrimitiveShapeRule, createWorkspaceGraphParityRule };

package/dist/index.js

@@ -17,6 +17,36 @@ function countLines(text) {
 function recursiveGlobs(roots, extensions) {
   return roots.flatMap((root) => extensions.map((ext) => `${root}/**/*${ext}`));
 }
+var DEFAULT_WORKFLOW_GLOBS = [
+  ".github/workflows/*.yml",
+  ".github/workflows/*.yaml"
+];
+var DEFAULT_SKIP_DIRS = [
+  "node_modules",
+  ".git",
+  "dist",
+  ".turbo",
+  "coverage"
+];
+function globFiles(glob, globs, skipDirs = []) {
+  const skip = new Set(skipDirs);
+  const found = /* @__PURE__ */ new Set();
+  for (const pattern of globs) {
+    for (const rel of glob(pattern)) {
+      if (!rel.split("/").some((segment) => skip.has(segment))) found.add(rel);
+    }
+  }
+  return [...found].sort();
+}
+function stripYamlComment(line) {
+  return line.replace(/(^|\s)#.*$/u, "");
+}
+function unquote(value) {
+  return value.trim().replace(/^(['"])(.*)\1$/u, "$2");
+}
+function anywhereGlobs(baseNames) {
+  return baseNames.flatMap((name) => [`**/${name}`, `**/.*/**/${name}`]);
+}
 
 // src/rules/agents-doc-presence.ts
 function createAgentsDocPresenceRule(options = {}) {
@@ -111,6 +141,63 @@ function createCanonicalHelpersSingleHomeRule(options = {}) {
   };
 }
 
+// src/rules/dockerfile-base-image-digest-pin.ts
+var RULE_ID = "dockerfile-base-image-digest-pin";
+var DEFAULT_DOCKERFILE_GLOBS = anywhereGlobs(["Dockerfile", "Dockerfile.*", "*.Dockerfile"]);
+var FROM_LINE = /^\s*FROM\s+(?:--\S+\s+)*(\S+)(?:\s+AS\s+(\S+))?\s*$/iu;
+var ARG_DEFAULT = /^\s*ARG\s+(\w+)=(\S+)\s*$/iu;
+var DIGEST = /@sha256:[0-9a-f]{64}$/u;
+function checkDockerfileBases(file, text) {
+  const violations = [];
+  const stages = /* @__PURE__ */ new Set();
+  const argDefaults = /* @__PURE__ */ new Map();
+  let seenFrom = false;
+  text.split("\n").forEach((line, index) => {
+    const arg = ARG_DEFAULT.exec(line);
+    if (arg?.[1] !== void 0 && arg[2] !== void 0 && !seenFrom) {
+      argDefaults.set(arg[1], arg[2].replace(/^(['"])(.*)\1$/u, "$2"));
+    }
+    const from = FROM_LINE.exec(line);
+    if (from?.[1] === void 0) {
+      return;
+    }
+    seenFrom = true;
+    const written = from[1];
+    const variable = /^\$\{?(\w+)\}?$/u.exec(written)?.[1];
+    const image = variable === void 0 ? written : argDefaults.get(variable) ?? written;
+    const isExempt = image.toLowerCase() === "scratch" || stages.has(image.toLowerCase());
+    if (from[2] !== void 0) {
+      stages.add(from[2].toLowerCase());
+    }
+    if (!isExempt && !DIGEST.test(image)) {
+      const reference = image.split("@")[0];
+      violations.push({
+        file,
+        rule: RULE_ID,
+        message: `line ${index + 1}: base image "${image}" is not pinned by digest. Write \`FROM ${reference}@sha256:<digest>\` (resolve it with \`docker buildx imagetools inspect ${reference}\`).`,
+        line: index + 1
+      });
+    }
+  });
+  return violations;
+}
+function createDockerfileBaseImageDigestPinRule(options = {}) {
+  const dockerfileGlobs = options.dockerfileGlobs ?? DEFAULT_DOCKERFILE_GLOBS;
+  const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: RULE_ID,
+    category: "ci",
+    ciCritical,
+    description: "Dockerfile FROM base images must be pinned by `@sha256:` digest (scratch and earlier build stages exempt).",
+    run(ctx) {
+      return globFiles((p) => ctx.glob(p), dockerfileGlobs, skipDirs).flatMap(
+        (file) => checkDockerfileBases(file, ctx.read(file) ?? "")
+      );
+    }
+  };
+}
+
 // src/rules/file-size-ratchet.ts
 import { DEFAULT_BASELINE_DIR, isGrandfathered, loadBaseline } from "@noctcore/harness";
 var DEFAULT_EXCLUDE_CONTAINS = [".test.", ".spec.", ".stories."];
@@ -193,6 +280,121 @@ function createFileSizeRatchetRule(options = {}) {
   };
 }
 
+// src/rules/github-actions-runner-pinned.ts
+var RULE_ID2 = "github-actions-runner-pinned";
+var RUNS_ON = /^(\s*)runs-on:\s*(.*)$/u;
+var DEFAULT_FLOATING_LABEL = /^[\w.-]+-latest$/u;
+function runnerLabels(lines, start, indent) {
+  const inline = stripYamlComment(RUNS_ON.exec(lines[start] ?? "")?.[2] ?? "").trim();
+  const collected = [inline];
+  if (inline === "") {
+    for (const line of lines.slice(start + 1)) {
+      const text = stripYamlComment(line);
+      if (text.trim() === "") {
+        continue;
+      }
+      if ((/^\s*/u.exec(text)?.[0].length ?? 0) <= indent) {
+        break;
+      }
+      collected.push(text.replace(/^\s*(?:-\s+|labels:\s*)/u, ""));
+    }
+  }
+  return collected.filter((value) => !value.includes("${{")).flatMap((value) => value.split(/[\s,[\]'"]+/u)).filter((label) => label !== "");
+}
+function checkWorkflowRunnersPinned(file, text, floatingLabel = DEFAULT_FLOATING_LABEL) {
+  const violations = [];
+  const lines = text.split("\n");
+  lines.forEach((line, index) => {
+    const match = RUNS_ON.exec(line);
+    if (match === null || line.trimStart().startsWith("#")) {
+      return;
+    }
+    for (const label of runnerLabels(lines, index, match[1]?.length ?? 0)) {
+      if (floatingLabel.test(label)) {
+        violations.push({
+          file,
+          rule: RULE_ID2,
+          message: `line ${index + 1}: \`runs-on\` uses the floating runner label "${label}". Pin a named image (for example \`ubuntu-24.04\`) so a runner image change is a reviewed diff.`,
+          line: index + 1
+        });
+      }
+    }
+  });
+  return violations;
+}
+function createGithubActionsRunnerPinnedRule(options = {}) {
+  const workflowGlobs = options.workflowGlobs ?? DEFAULT_WORKFLOW_GLOBS;
+  const floatingLabel = options.floatingLabel ?? DEFAULT_FLOATING_LABEL;
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: RULE_ID2,
+    category: "ci",
+    ciCritical,
+    description: "GitHub Actions jobs must run on a pinned runner image (for example ubuntu-24.04), never a *-latest label.",
+    run(ctx) {
+      return globFiles((p) => ctx.glob(p), workflowGlobs).flatMap(
+        (file) => checkWorkflowRunnersPinned(file, ctx.read(file) ?? "", floatingLabel)
+      );
+    }
+  };
+}
+
+// src/rules/github-actions-sha-pinned.ts
+var RULE_ID3 = "github-actions-sha-pinned";
+var USES_LINE = /^\s*(?:-\s+)?uses:\s*['"]?([^\s'"#]+)['"]?\s*(#.*)?$/u;
+var FULL_SHA = /^[0-9a-f]{40}$/u;
+var DOCKER_DIGEST = /@sha256:[0-9a-f]{64}$/u;
+var VERSION_COMMENT = /^#\s*v\d/u;
+function checkWorkflowActionsPinned(file, text) {
+  const violations = [];
+  text.split("\n").forEach((line, index) => {
+    const match = USES_LINE.exec(line);
+    const ref = match?.[1];
+    if (ref === void 0 || ref.startsWith("./")) {
+      return;
+    }
+    const where = `line ${index + 1}`;
+    const report = (message) => {
+      violations.push({ file, rule: RULE_ID3, message, line: index + 1 });
+    };
+    if (ref.startsWith("docker://")) {
+      if (!DOCKER_DIGEST.test(ref)) {
+        report(`${where}: \`uses: ${ref}\` is not pinned by digest. Append \`@sha256:<digest>\`.`);
+      }
+      return;
+    }
+    const at = ref.lastIndexOf("@");
+    const pin = at === -1 ? "" : ref.slice(at + 1);
+    if (!FULL_SHA.test(pin)) {
+      report(
+        `${where}: \`uses: ${ref}\` is not pinned to a 40-character commit SHA. Resolve the tag to its commit and write \`uses: ${at === -1 ? ref : ref.slice(0, at)}@<sha> # vN\`.`
+      );
+      return;
+    }
+    if (!VERSION_COMMENT.test(match?.[2] ?? "")) {
+      report(
+        `${where}: \`uses: ${ref}\` is SHA-pinned but has no \`# vN\` comment. Keep the version beside the SHA so the pin stays readable and Dependabot can bump it.`
+      );
+    }
+  });
+  return violations;
+}
+function createGithubActionsShaPinnedRule(options = {}) {
+  const workflowGlobs = options.workflowGlobs ?? DEFAULT_WORKFLOW_GLOBS;
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: RULE_ID3,
+    category: "ci",
+    ciCritical,
+    description: "GitHub Actions `uses:` refs must be pinned to a 40-character commit SHA with a `# vN` comment (local ./ actions exempt).",
+    run(ctx) {
+      return globFiles((p) => ctx.glob(p), workflowGlobs).flatMap(
+        (file) => checkWorkflowActionsPinned(file, ctx.read(file) ?? "")
+      );
+    }
+  };
+}
+
 // src/rules/layer-rank.ts
 var DEFAULT_SOURCE_GLOBS = [
   "packages/*/src/**/*.ts",
@@ -405,6 +607,228 @@ function createPackageShapeRule(options = {}) {
   };
 }
 
+// src/rules/security-scanner-version-parity.ts
+var RULE_ID4 = "security-scanner-version-parity";
+function createSecurityScannerVersionParityRule(options = {}) {
+  const scanner = options.scanner ?? "gitleaks";
+  const versionVariable = options.versionVariable ?? "GITLEAKS_VERSION";
+  const imageVariable = options.imageVariable ?? "GITLEAKS_IMAGE";
+  const hookFile = options.hookFile ?? "scripts/ci/pre-push.sh";
+  const workflowGlobs = options.workflowGlobs ?? DEFAULT_WORKFLOW_GLOBS;
+  const ciCritical = options.ciCritical ?? true;
+  const name = escapeRegExp(scanner);
+  const versionVar = escapeRegExp(versionVariable);
+  const workflowVersion = new RegExp(
+    `^\\s*${versionVar}:\\s*['"]?(\\d+\\.\\d+\\.\\d+)['"]?\\s*(?:#.*)?$`,
+    "mu"
+  );
+  const hookVersion = new RegExp(
+    `^\\s*(?:readonly\\s+)?${versionVar}=['"]?(\\d+\\.\\d+\\.\\d+)['"]?\\s*(?:#.*)?$`,
+    "mu"
+  );
+  const hookImageTag = new RegExp(
+    `^\\s*${escapeRegExp(imageVariable)}=['"][^'"\\n]*${name}:v(\\d+\\.\\d+\\.\\d+)['"]`,
+    "mu"
+  );
+  const runtimeCheck = new RegExp(`\\b${name}\\s+version\\b`, "u");
+  const mentionsScanner = new RegExp(name, "iu");
+  return {
+    id: RULE_ID4,
+    category: "ci",
+    ciCritical,
+    description: `The ${scanner} version pinned in the workflows must equal the one in ${hookFile}, and the hook must compare a native ${scanner} against it at run time.`,
+    run(ctx) {
+      const hookText = ctx.read(hookFile) ?? "";
+      const ciVersions = /* @__PURE__ */ new Map();
+      for (const file of globFiles((p) => ctx.glob(p), workflowGlobs)) {
+        const version = workflowVersion.exec(ctx.read(file) ?? "")?.[1];
+        if (version !== void 0) {
+          ciVersions.set(version, [...ciVersions.get(version) ?? [], file]);
+        }
+      }
+      const hookUsesScanner = mentionsScanner.test(hookText);
+      if (ciVersions.size === 0 && !hookUsesScanner) {
+        return [];
+      }
+      const violations = [];
+      const report = (file, message) => {
+        violations.push({ file, rule: RULE_ID4, message });
+      };
+      if (ciVersions.size > 1) {
+        report(
+          [...ciVersions.values()].flat()[0] ?? hookFile,
+          `Workflows pin different ${scanner} versions (${[...ciVersions.keys()].join(", ")}). Use one \`${versionVariable}\` everywhere.`
+        );
+      }
+      const ciVersion = ciVersions.size === 1 ? [...ciVersions.keys()][0] : void 0;
+      if (ciVersions.size === 0) {
+        report(
+          hookFile,
+          `${hookFile} runs ${scanner} but no workflow pins \`${versionVariable}\`, so CI's scanner version is unknown. Pin it in the workflow env.`
+        );
+      }
+      if (!hookUsesScanner) {
+        report(
+          hookFile,
+          `Workflows pin ${scanner} ${ciVersion ?? ""} but ${hookFile} does not run ${scanner}, so the local hook cannot agree with CI.`
+        );
+        return violations;
+      }
+      const declared = hookVersion.exec(hookText)?.[1];
+      if (declared === void 0) {
+        report(
+          hookFile,
+          `${hookFile} does not declare \`${versionVariable}="x.y.z"\`. Declare the version CI pins (${ciVersion ?? "see the workflow"}) and derive the Docker image tag from it.`
+        );
+      } else if (ciVersion !== void 0 && declared !== ciVersion) {
+        report(
+          hookFile,
+          `${hookFile} pins ${scanner} ${declared} but CI pins ${ciVersion}. Bump them together.`
+        );
+      }
+      const imageTag = hookImageTag.exec(hookText)?.[1];
+      if (imageTag !== void 0 && ciVersion !== void 0 && imageTag !== ciVersion) {
+        report(
+          hookFile,
+          `${hookFile} \`${imageVariable}\` is tagged v${imageTag} but CI pins ${ciVersion}. Derive the tag from \`${versionVariable}\` or bump it.`
+        );
+      }
+      if (!runtimeCheck.test(hookText)) {
+        report(
+          hookFile,
+          `${hookFile} never runs \`${scanner} version\`. A native ${scanner} of another version scans with another ruleset: compare it with \`${versionVariable}\` and refuse a mismatch.`
+        );
+      }
+      return violations;
+    }
+  };
+}
+
+// src/rules/service-image-digest-pin.ts
+var RULE_ID5 = "service-image-digest-pin";
+var DIGEST2 = /@sha256:[0-9a-f]{64}$/u;
+var KEY_LINE = /^(\s*)(?:-\s+)?([\w-]+):\s*(.*)$/u;
+var DEFAULT_COMPOSE_GLOBS = anywhereGlobs(
+  ["compose", "docker-compose"].flatMap(
+    (stem) => ["", ".*", "-*"].flatMap((infix) => ["yml", "yaml"].map((ext) => `${stem}${infix}.${ext}`))
+  )
+);
+function indentOf(line) {
+  return /^\s*/u.exec(line)?.[0].length ?? 0;
+}
+function workflowImages(text) {
+  const found = [];
+  const stack = [];
+  text.split("\n").forEach((line, index) => {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) {
+      return;
+    }
+    const match = KEY_LINE.exec(line);
+    if (match === null) {
+      return;
+    }
+    const indent = match[1]?.length ?? 0;
+    const key = match[2] ?? "";
+    const value = unquote(stripYamlComment(match[3] ?? "").trim());
+    while (stack.length > 0 && (stack[stack.length - 1]?.indent ?? 0) >= indent) {
+      stack.pop();
+    }
+    const insideService = stack.some((entry) => entry.key === "services");
+    const isContainerScalar = key === "container" && value !== "";
+    const isImageKey = key === "image" && value !== "";
+    const insideContainer = stack.some((entry) => entry.key === "container");
+    if (isContainerScalar || isImageKey && (insideService || insideContainer)) {
+      found.push({ line: index + 1, image: value });
+    }
+    stack.push({ indent, key });
+  });
+  return found;
+}
+function composeImages(text) {
+  const lines = text.split("\n");
+  const found = [];
+  const servicesAt = lines.findIndex((line) => /^services:\s*(?:#.*)?$/u.test(line));
+  if (servicesAt === -1) {
+    return found;
+  }
+  let serviceIndent = null;
+  let propertyIndent = null;
+  let current = null;
+  const flush = () => {
+    if (current !== null && !current.hasBuild) {
+      found.push(...current.images);
+    }
+    current = null;
+  };
+  for (let index = servicesAt + 1; index < lines.length; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "" || line.trimStart().startsWith("#")) {
+      continue;
+    }
+    const indent = indentOf(line);
+    if (indent === 0) {
+      break;
+    }
+    serviceIndent ??= indent;
+    const match = KEY_LINE.exec(line);
+    if (match === null) {
+      continue;
+    }
+    if (indent === serviceIndent) {
+      flush();
+      current = { images: [], hasBuild: false };
+      propertyIndent = null;
+      continue;
+    }
+    propertyIndent ??= indent;
+    if (current === null || indent !== propertyIndent) {
+      continue;
+    }
+    const value = unquote(stripYamlComment(match[3] ?? "").trim());
+    if (match[2] === "build") {
+      current.hasBuild = true;
+    } else if (match[2] === "image" && value !== "") {
+      current.images.push({ line: index + 1, image: value });
+    }
+  }
+  flush();
+  return found;
+}
+function violationsFor(file, images, allowUnpinned) {
+  return images.filter(({ image }) => !DIGEST2.test(image) && !allowUnpinned.has(image)).map(({ line, image }) => {
+    const reference = image.split("@")[0];
+    return {
+      file,
+      rule: RULE_ID5,
+      message: `line ${line}: image "${image}" is not pinned by digest. Write \`${reference}@sha256:<digest>\` (resolve it with \`docker buildx imagetools inspect ${reference}\`) so CI and local runs use the same bytes.`,
+      line
+    };
+  });
+}
+function createServiceImageDigestPinRule(options = {}) {
+  const workflowGlobs = options.workflowGlobs ?? DEFAULT_WORKFLOW_GLOBS;
+  const composeGlobs = options.composeGlobs ?? DEFAULT_COMPOSE_GLOBS;
+  const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+  const allowUnpinned = new Set(options.allowUnpinned ?? []);
+  const ciCritical = options.ciCritical ?? true;
+  return {
+    id: RULE_ID5,
+    category: "ci",
+    ciCritical,
+    description: "Workflow service and container images, and docker-compose images, must be pinned by `@sha256:` digest (a service that builds locally is exempt).",
+    run(ctx) {
+      const glob = (p) => ctx.glob(p);
+      const workflowViolations = globFiles(glob, workflowGlobs).flatMap(
+        (file) => violationsFor(file, workflowImages(ctx.read(file) ?? ""), allowUnpinned)
+      );
+      const composeViolations = globFiles(glob, composeGlobs, skipDirs).flatMap(
+        (file) => violationsFor(file, composeImages(ctx.read(file) ?? ""), allowUnpinned)
+      );
+      return [...workflowViolations, ...composeViolations];
+    }
+  };
+}
+
 // src/rules/test-runner-segregation.ts
 function createTestRunnerSegregationRule(options = {}) {
   const bunPackageGlobs = options.bunPackageGlobs ?? ["packages/*/package.json"];
@@ -671,11 +1095,16 @@ function createWorkspaceGraphParityRule(options = {}) {
 var RULE_FACTORIES = {
   "agents-doc-presence": createAgentsDocPresenceRule,
   "canonical-helpers-single-home": createCanonicalHelpersSingleHomeRule,
+  "dockerfile-base-image-digest-pin": createDockerfileBaseImageDigestPinRule,
   "file-size-ratchet": createFileSizeRatchetRule,
+  "github-actions-runner-pinned": createGithubActionsRunnerPinnedRule,
+  "github-actions-sha-pinned": createGithubActionsShaPinnedRule,
   "layer-rank": createLayerRankRule,
   "no-cloned-component-folders": createNoClonedComponentFoldersRule,
   "no-warn-severity": createNoWarnSeverityRule,
   "package-shape": createPackageShapeRule,
+  "security-scanner-version-parity": createSecurityScannerVersionParityRule,
+  "service-image-digest-pin": createServiceImageDigestPinRule,
   "test-runner-segregation": createTestRunnerSegregationRule,
   "test-sibling-enforcement": createTestSiblingEnforcementRule,
   "test-workspace-enrollment": createTestWorkspaceEnrollmentRule,
@@ -693,11 +1122,16 @@ export {
   createAgentsDocPresenceRule,
   createAllRules,
   createCanonicalHelpersSingleHomeRule,
+  createDockerfileBaseImageDigestPinRule,
   createFileSizeRatchetRule,
+  createGithubActionsRunnerPinnedRule,
+  createGithubActionsShaPinnedRule,
   createLayerRankRule,
   createNoClonedComponentFoldersRule,
   createNoWarnSeverityRule,
   createPackageShapeRule,
+  createSecurityScannerVersionParityRule,
+  createServiceImageDigestPinRule,
   createTestRunnerSegregationRule,
   createTestSiblingEnforcementRule,
   createTestWorkspaceEnrollmentRule,

package/docs/rules/dockerfile-base-image-digest-pin.md

@@ -0,0 +1,43 @@
+# `dockerfile-base-image-digest-pin`
+
+> Dockerfile `FROM` base images are pinned by `@sha256:` digest.
+
+## Why
+
+`FROM node:22-slim` names whatever the registry serves at build time, so two builds of one commit can
+differ and a moved tag ships a change nobody reviewed. `tag@sha256:<digest>` keeps the tag for readers
+and fixes the bytes.
+
+## What it flags
+
+Every `FROM` whose image has no `@sha256:` digest. Exempt: `FROM scratch` and `FROM <earlier stage>`.
+An image chosen through a build arg (`FROM ${BASE}`) is resolved from its `ARG BASE=<default>` before
+the first `FROM`; one that cannot be resolved is reported, since the text does not show what is
+pulled. Each violation carries the 1-indexed line.
+
+```dockerfile
+# Bad
+FROM node:22-slim AS deps
+
+# Good
+FROM node:22-slim@sha256:<digest> AS deps
+FROM deps AS build
+FROM scratch
+```
+
+## Factory
+
+```ts
+createDockerfileBaseImageDigestPinRule(options?: DockerfileBaseImageDigestPinOptions): IMetaRule
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `dockerfileGlobs` | `string[]` | `Dockerfile`, `Dockerfile.*`, `*.Dockerfile` at any depth, dot-directories included | Dockerfiles to scan. |
+| `skipDirs` | `string[]` | `['node_modules', '.git', 'dist', '.turbo', 'coverage']` | A path with any of these segments is skipped. |
+| `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
+
+## Limits
+
+A `FROM` split with a line continuation (`\`) is not read. Add a `Containerfile` glob if you use
+Podman naming.