@intentius/chant-lexicon-gitlab 0.1.22 → 0.2.0

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

@@ -0,0 +1,41 @@
+/**
+ * WGL047: Software Fetched and Executed at Runtime Without Verification
+ *
+ * Flags a `script:` command that pipes a network download straight into a shell
+ * (`curl ... | bash`, `wget ... | sh`). The fetched script is unpinned and
+ * unverified, so whoever controls the URL controls what runs in the job.
+ * Download to a file, verify a checksum/signature, then execute it.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractScriptCommands } from "./yaml-helpers";
+
+const PIPE_TO_SHELL = /\b(curl|wget)\b[^\n|]*\|\s*(sudo\s+)?(ba)?sh\b/i;
+
+export const wgl047: PostSynthCheck = {
+  id: "WGL047",
+  description: "Software fetched and piped to a shell without verification",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const seen = new Set<string>();
+      for (const { job, command } of extractScriptCommands(yaml)) {
+        if (PIPE_TO_SHELL.test(command) && !seen.has(job)) {
+          seen.add(job);
+          diagnostics.push({
+            checkId: "WGL047",
+            severity: "warning",
+            message: `Job "${job}" pipes a network download directly into a shell — the fetched code is unpinned and unverified. Download to a file, verify a checksum or signature, then execute it.`,
+            entity: job,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,56 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl048 } from "./wgl048";
+
+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("WGL048: pipeline without a name", () => {
+  test("flags a workflow: block with no name", () => {
+    const yaml = `workflow:
+  rules:
+    - if: $CI_COMMIT_BRANCH
+
+build:
+  script:
+    - make
+`;
+    const diags = wgl048.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL048");
+  });
+
+  test("does not flag a named workflow", () => {
+    const yaml = `workflow:
+  name: My Pipeline
+  rules:
+    - if: $CI_COMMIT_BRANCH
+
+build:
+  script:
+    - make
+`;
+    const diags = wgl048.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag a pipeline with no workflow block", () => {
+    const yaml = `build:
+  script:
+    - make
+`;
+    const diags = wgl048.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,37 @@
+/**
+ * WGL048: Pipeline Without a Name
+ *
+ * Flags a pipeline that defines a `workflow:` block but no `workflow:name:`.
+ * A pipeline name shows up in the GitLab UI and audit output; naming pipelines
+ * makes runs easier to identify and review. Only flags pipelines that already
+ * customize `workflow:` (where a name is cheap to add and most useful).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput } from "./yaml-helpers";
+
+export const wgl048: PostSynthCheck = {
+  id: "WGL048",
+  description: "Pipeline defines workflow: but no workflow:name",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const workflowSection = yaml.split("\n\n").find((s) => /^workflow:/.test(s));
+      if (!workflowSection) continue;
+      if (!/^\s+name:/m.test(workflowSection)) {
+        diagnostics.push({
+          checkId: "WGL048",
+          severity: "info",
+          message: `The pipeline defines a workflow: block but no workflow:name. Add a name so runs are identifiable in the GitLab UI and audit output.`,
+          entity: "workflow",
+          lexicon: "gitlab",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/yaml-helpers.ts

@@ -223,3 +223,217 @@ export function extractJobRules(section: string): ParsedRule[] {
 
   return rules;
 }
+
+/** A container image reference (job/default `image:` or a `services:` entry). */
+export interface ImageRef {
+  /** Owning job name, or "default" for the global image. */
+  job: string;
+  /** The image reference (e.g. `node:20`). */
+  image: string;
+  /** Where the image was declared. */
+  source: "image" | "service";
+}
+
+/**
+ * Extract container image references from `image:` and `services:` across the
+ * pipeline. Handles both the object form (`image:\n  name: ...`) and the inline
+ * string form (`image: ...`).
+ */
+export function extractImageRefs(yaml: string): ImageRef[] {
+  const refs: ImageRef[] = [];
+  for (const section of yaml.split("\n\n")) {
+    const lines = section.split("\n");
+    const top = lines[0]?.match(/^(\.?[a-z][a-z0-9_.-]*):/i);
+    const job = top ? top[1] : "default";
+
+    for (let i = 0; i < lines.length; i++) {
+      // image: as object (next indented `name:`) or inline string
+      const imgInline = lines[i].match(/^\s+image:\s+(\S.*)$/);
+      if (imgInline) {
+        refs.push({ job, image: imgInline[1].trim().replace(/^['"]|['"]$/g, ""), source: "image" });
+        continue;
+      }
+      if (/^\s+image:\s*$/.test(lines[i])) {
+        const nameLine = lines.slice(i + 1, i + 4).find((l) => /^\s+name:\s+/.test(l));
+        if (nameLine) {
+          const v = nameLine.replace(/^\s+name:\s+/, "").trim().replace(/^['"]|['"]$/g, "");
+          refs.push({ job, image: v, source: "image" });
+        }
+        continue;
+      }
+      // services: list entries — `- name:` or `- 'image'`
+      const svcName = lines[i].match(/^\s+-\s+name:\s+(\S.*)$/);
+      if (svcName) {
+        refs.push({ job, image: svcName[1].trim().replace(/^['"]|['"]$/g, ""), source: "service" });
+      }
+    }
+  }
+  return refs;
+}
+
+/** An `include:` entry from the top-level include block. */
+export interface IncludeEntry {
+  kind: "project" | "remote" | "component" | "local" | "template" | "string";
+  /** The primary value (project path, URL, component address, …). */
+  value: string;
+  /** `ref:` for project includes, if present. */
+  ref?: string;
+}
+
+/**
+ * Parse the top-level `include:` block into structured entries.
+ */
+export function extractIncludes(yaml: string): IncludeEntry[] {
+  const entries: IncludeEntry[] = [];
+  const section = yaml.split("\n\n").find((s) => /^include:/.test(s));
+  if (!section) return entries;
+
+  // Inline string form: `include: <value>` (value on the same line, not a list)
+  const inline = section.match(/^include:[ \t]+(\S.*)$/m);
+  if (inline) {
+    entries.push({ kind: "string", value: inline[1].trim().replace(/^['"]|['"]$/g, "") });
+    return entries;
+  }
+
+  const lines = section.split("\n");
+  let current: IncludeEntry | undefined;
+  const push = () => { if (current) entries.push(current); current = undefined; };
+  for (const line of lines) {
+    const start = line.match(/^\s+-\s+(project|remote|component|local|template):\s*(.*)$/);
+    if (start) {
+      push();
+      current = { kind: start[1] as IncludeEntry["kind"], value: start[2].trim().replace(/^['"]|['"]$/g, "") };
+      continue;
+    }
+    const refLine = line.match(/^\s+ref:\s+(.+)$/);
+    if (refLine && current) {
+      current.ref = refLine[1].trim().replace(/^['"]|['"]$/g, "");
+    }
+    // A bare `- 'https://...'` short remote form
+    const bare = line.match(/^\s+-\s+(['"]?https?:\/\/\S+['"]?)\s*$/);
+    if (bare) {
+      push();
+      entries.push({ kind: "remote", value: bare[1].replace(/^['"]|['"]$/g, "") });
+    }
+  }
+  push();
+  return entries;
+}
+
+/** True if a git ref is an immutable pin (40-hex SHA or a vN.N.N-style tag). */
+export function isPinnedRef(ref: string): boolean {
+  if (/^[0-9a-f]{40}$/.test(ref)) return true;
+  // Semver-ish tag with all components fixed (v1.2.3 / 1.2.3)
+  if (/^v?\d+\.\d+\.\d+$/.test(ref)) return true;
+  return false;
+}
+
+/** An `id_tokens:` OIDC token declaration within a job. */
+export interface IdTokenDecl {
+  job: string;
+  /** Token variable name (e.g. `GCP_ID_TOKEN`). */
+  name: string;
+  /** Declared audiences (`aud:`), empty if none. */
+  aud: string[];
+}
+
+/**
+ * Extract `id_tokens:` declarations (OIDC) per job, with their audiences.
+ */
+export function extractIdTokens(yaml: string): IdTokenDecl[] {
+  const out: IdTokenDecl[] = [];
+  for (const section of yaml.split("\n\n")) {
+    const lines = section.split("\n");
+    const top = lines[0]?.match(/^(\.?[a-z][a-z0-9_.-]*):/i);
+    if (!top) continue;
+    const job = top[1];
+
+    let inIdTokens = false;
+    let idTokensIndent = -1;
+    let current: IdTokenDecl | undefined;
+    const flush = () => { if (current) out.push(current); current = undefined; };
+
+    for (const line of lines) {
+      if (/^\s+id_tokens:\s*$/.test(line)) {
+        inIdTokens = true;
+        idTokensIndent = line.search(/\S/);
+        continue;
+      }
+      if (!inIdTokens) continue;
+      const indent = line.search(/\S/);
+      if (line.trim() !== "" && indent <= idTokensIndent) { flush(); inIdTokens = false; continue; }
+
+      const tokenName = line.match(/^\s+([A-Z_][A-Z0-9_]*):\s*$/);
+      if (tokenName && indent === idTokensIndent + 2) {
+        flush();
+        current = { job, name: tokenName[1], aud: [] };
+        continue;
+      }
+      const audInline = line.match(/^\s+aud:\s+(\S.*)$/);
+      if (audInline && current) {
+        const v = audInline[1].trim();
+        if (v.startsWith("[")) {
+          for (const p of v.replace(/^\[|\]$/g, "").split(",")) {
+            const t = p.trim().replace(/^['"]|['"]$/g, "");
+            if (t) current.aud.push(t);
+          }
+        } else {
+          current.aud.push(v.replace(/^['"]|['"]$/g, ""));
+        }
+        continue;
+      }
+      const audItem = line.match(/^\s+-\s+(\S.*)$/);
+      if (audItem && current) {
+        current.aud.push(audItem[1].trim().replace(/^['"]|['"]$/g, ""));
+      }
+    }
+    flush();
+  }
+  return out;
+}
+
+/** True if a job section's rules make it reachable from merge-request pipelines. */
+export function isMergeRequestReachable(section: string): boolean {
+  return /merge_request_event|CI_MERGE_REQUEST|CI_PIPELINE_SOURCE\s*==\s*['"]?merge_request/.test(section);
+}
+
+/** A shell command line from a `script:` / `before_script:` / `after_script:`. */
+export interface ScriptCommand {
+  job: string;
+  command: string;
+}
+
+/**
+ * Extract shell command lines from all `script:` family blocks, per job.
+ */
+export function extractScriptCommands(yaml: string): ScriptCommand[] {
+  const out: ScriptCommand[] = [];
+  for (const section of yaml.split("\n\n")) {
+    const lines = section.split("\n");
+    const top = lines[0]?.match(/^(\.?[a-z][a-z0-9_.-]*):/i);
+    if (!top) continue;
+    const job = top[1];
+
+    let inScript = false;
+    let scriptIndent = -1;
+    for (const line of lines) {
+      if (/^\s+(before_script|after_script|script):\s*$/.test(line)) {
+        inScript = true;
+        scriptIndent = line.search(/\S/);
+        continue;
+      }
+      // inline form `script: cmd`
+      const inlineScript = line.match(/^\s+(?:before_script|after_script|script):\s+(\S.*)$/);
+      if (inlineScript) {
+        out.push({ job, command: inlineScript[1].trim().replace(/^['"]|['"]$/g, "") });
+        continue;
+      }
+      if (!inScript) continue;
+      const indent = line.search(/\S/);
+      if (line.trim() !== "" && indent <= scriptIndent) { inScript = false; continue; }
+      const item = line.match(/^\s+-\s+(.*)$/);
+      if (item) out.push({ job, command: item[1].trim().replace(/^['"]|['"]$/g, "") });
+    }
+  }
+  return out;
+}

package/src/lint/rules/data/known-include-sources.ts

@@ -0,0 +1,41 @@
+/**
+ * Vendored snapshot of well-known GitLab CI include/component source projects,
+ * used by the look-alike check (WGL032) as the reference set: an `include` or
+ * `component` source that is a near-miss (edit distance 1–2) of one of these —
+ * but not an exact match — is likely a typo or an impersonation.
+ *
+ * Advisory only. Refresh source: GitLab-maintained CI templates and the popular
+ * CI/CD Catalog components. Accept staleness — a stale entry only weakens
+ * look-alike detection, it never blocks a build.
+ */
+export const KNOWN_INCLUDE_SOURCES: readonly string[] = [
+  "gitlab-org/gitlab",
+  "gitlab-org/security-products/ci-templates",
+  "components/sast",
+  "components/secret-detection",
+  "components/dependency-scanning",
+  "components/container-scanning",
+  "components/code-quality",
+  "gitlab-org/components/sast",
+  "gitlab-org/components/secret-detection",
+];
+
+/** Levenshtein edit distance, capped: returns early once it exceeds `max`. */
+export function editDistance(a: string, b: string, max: number): number {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > max) return max + 1;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const curr = [i];
+    let rowMin = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+      curr.push(val);
+      if (val < rowMin) rowMin = val;
+    }
+    if (rowMin > max) return max + 1;
+    prev = curr;
+  }
+  return prev[b.length];
+}

package/src/lint/rules/data/untrusted-variables.ts

@@ -0,0 +1,31 @@
+/**
+ * Vendored snapshot of GitLab CI predefined variables whose values are
+ * attacker-controllable — branch/tag names, commit and merge-request titles and
+ * descriptions, author identity. Interpolating these into a `script:` (or using
+ * them as a gate) lets a crafted branch name or commit title influence what runs.
+ *
+ * Source: GitLab "Predefined CI/CD variables" reference, filtered to the values
+ * an outside contributor can set on a fork or merge request. Advisory and
+ * necessarily incomplete; editing this list is the refresh mechanism.
+ */
+export const UNTRUSTED_CI_VARIABLES: readonly string[] = [
+  "CI_COMMIT_TITLE",
+  "CI_COMMIT_MESSAGE",
+  "CI_COMMIT_DESCRIPTION",
+  "CI_COMMIT_REF_NAME",
+  "CI_COMMIT_REF_SLUG",
+  "CI_COMMIT_BRANCH",
+  "CI_COMMIT_TAG",
+  "CI_COMMIT_AUTHOR",
+  "CI_MERGE_REQUEST_TITLE",
+  "CI_MERGE_REQUEST_DESCRIPTION",
+  "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME",
+  "CI_MERGE_REQUEST_SOURCE_BRANCH_SHA",
+  "CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME",
+];
+
+/** Reference forms a variable can take in a script: `$VAR` or `${VAR}`. */
+export function variableReferenced(text: string, name: string): boolean {
+  const re = new RegExp(`\\$\\{?${name}\\}?(?![A-Z0-9_])`);
+  return re.test(text);
+}

package/src/migrate/from-github/diagnostics.ts

@@ -22,6 +22,24 @@ export function provenanceToDiagnostics(
 ): LintDiagnostic[] {
   const out: LintDiagnostic[] = [];
   for (const r of records) {
+    // Security records always emit a diagnostic, at their own severity
+    // (escalated to error under --strict when the property was lost or needs
+    // review), independent of the functional category.
+    if (r.security) {
+      const sev =
+        opts.strict && (r.security.fate === "lost" || r.security.fate === "needs-review")
+          ? "error"
+          : r.security.severity;
+      out.push({
+        file: r.sourceFile ?? "<input>",
+        line: r.sourceLine ?? 1,
+        column: r.sourceColumn ?? 1,
+        ruleId: r.rule,
+        severity: sev,
+        message: r.note ?? r.rule,
+      });
+      continue;
+    }
     let severity: "error" | "warning" | "info" | undefined;
     if (r.category === "needs-review") {
       severity = opts.strict ? "error" : "warning";

package/src/migrate/from-github/index.ts

@@ -12,6 +12,7 @@ import { ProvenanceAccumulator, type ProvenanceRecord } from "./provenance";
 import { transformIR } from "./transformer";
 import { emitGitlabYaml } from "./emit-yaml";
 import { provenanceToDiagnostics } from "./diagnostics";
+import { analyzeSecurity, runSecurityChecks, renderSecurityPosture } from "./security";
 import { GitLabGenerator } from "../../import/generator";
 import { applyComposites } from "./composites/rewriter";
 import type { ActionMappingRegistry } from "./actions/registry";
@@ -31,6 +32,12 @@ export interface MigrateOptions {
   registry?: ActionMappingRegistry;
   /** Escalate needs-review diagnostics to errors. */
   strict?: boolean;
+  /**
+   * Security-aware migration (#306): classify each security property's fate
+   * across the edge and run the GitLab security post-synth checks against the
+   * migrated YAML. Enabled by the CLI's `--validate` path.
+   */
+  security?: boolean;
 }
 
 export interface MigrationResult {
@@ -44,6 +51,8 @@ export interface MigrationResult {
   diagnostics: LintDiagnostic[];
   /** Inferred stage list. */
   stages: string[];
+  /** Markdown "Security posture" section (#306). */
+  securityPosture: string;
 }
 
 /**
@@ -106,10 +115,20 @@ export async function transform(
     output = emitGitlabYaml(ir);
   }
 
+  // Security-aware migration (#306): classify each security property's fate
+  // across the edge, and run the GitLab security post-synth checks against the
+  // migrated YAML so weaknesses lost in translation surface on the target side.
+  if (opts.security) {
+    const yamlForSecurity = opts.emit === "ts" ? emitGitlabYaml(ir) : output;
+    provAcc.pushAll(analyzeSecurity(yamlContent, { sourceFile: opts.sourceFile }));
+    provAcc.pushAll(await runSecurityChecks(yamlForSecurity, { sourceFile: opts.sourceFile }));
+  }
+
   const provenance = provAcc.all();
   const diagnostics = provenanceToDiagnostics(provenance, { strict: opts.strict });
+  const securityPosture = renderSecurityPosture(provenance);
 
-  return { ir, output, provenance, diagnostics, stages };
+  return { ir, output, provenance, diagnostics, stages, securityPosture };
 }
 
 /**

package/src/migrate/from-github/provenance.ts

@@ -37,6 +37,29 @@ export interface ProvenanceRecord {
   actionRef?: string;
   /** Tier 1/2/3 for action-map records */
   mappingTier?: 1 | 2 | 3;
+  /** Security classification, when this record concerns a security property. */
+  security?: SecurityProvenance;
+}
+
+/**
+ * Fate of a security property as it crosses the GitHub → GitLab boundary,
+ * mirroring the functional provenance categories.
+ */
+export type SecurityFate = "translated" | "approximated" | "needs-review" | "lost";
+
+/**
+ * Security classification attached to a provenance record — tracks whether a
+ * security-relevant property survived migration, alongside the functional one.
+ */
+export interface SecurityProvenance {
+  /** Human label for the property (e.g. "Pinned action SHA"). */
+  property: string;
+  /** What happened to the property across the migration edge. */
+  fate: SecurityFate;
+  /** Diagnostic severity for this finding. */
+  severity: "error" | "warning" | "info";
+  /** Cross-reference to the endpoint that re-establishes the property. */
+  reestablish?: string;
 }
 
 /**
@@ -65,4 +88,9 @@ export class ProvenanceAccumulator {
   needsReviewCount(): number {
     return this.records.filter((r) => r.category === "needs-review").length;
   }
+
+  /** Records carrying a security classification. */
+  securityRecords(): ProvenanceRecord[] {
+    return this.records.filter((r) => r.security !== undefined);
+  }
 }

package/src/migrate/from-github/rules.ts

@@ -79,4 +79,11 @@ export const MIGRATION_RULES: LintRule[] = [
 
   // Action mapping fallback
   rule("MIG-ACTION-UNKNOWN", "warning", "Marketplace action has no registered mapping"),
+
+  // ── Security posture across the migration edge (#306) ──────────────────
+  // Each cross-references the endpoint issue that re-establishes the property.
+  rule("MIG-PIN-LOST", "warning", "A pinned action SHA could not be carried to the GitLab include/image — re-pin on the GitLab side (#297)"),
+  rule("MIG-SECRET-UNSCOPED", "warning", "Migrated secret reference assumes a masked + protected GitLab variable (#300)"),
+  rule("MIG-INJECTION-CARRIED", "warning", "An untrusted-input injection site was translated verbatim across the edge (#299)"),
+  rule("MIG-TRUST-BOUNDARY", "warning", "Trigger/fork semantics shifted the trust boundary (pull_request_target → MR/fork pipeline) (#299)"),
 ];

package/src/migrate/from-github/security.test.ts

@@ -0,0 +1,98 @@
+import { describe, test, expect } from "vitest";
+import { analyzeSecurity, runSecurityChecks, renderSecurityPosture } from "./security";
+import { transform } from "./index";
+
+const WORKFLOW = `name: CI
+on:
+  pull_request_target:
+permissions:
+  contents: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - run: echo "title is \${{ github.event.pull_request.title }}"
+      - run: deploy --token \${{ secrets.DEPLOY_TOKEN }}
+`;
+
+describe("analyzeSecurity (#306)", () => {
+  test("classifies each security property's fate", () => {
+    const records = analyzeSecurity(WORKFLOW, { sourceFile: "ci.yml" });
+    const byRule = new Map(records.map((r) => [r.rule, r]));
+
+    expect(byRule.get("MIG-PIN-LOST")?.security?.fate).toBe("lost");
+    expect(byRule.get("MIG-SECRET-UNSCOPED")?.security?.fate).toBe("needs-review");
+    expect(byRule.get("MIG-INJECTION-CARRIED")?.security?.fate).toBe("translated");
+    expect(byRule.get("MIG-TRUST-BOUNDARY")?.security?.fate).toBe("needs-review");
+    expect(byRule.get("MIG-PERMISSIONS-001")?.security?.fate).toBe("needs-review");
+
+    // each cross-references the endpoint that re-establishes the property
+    expect(byRule.get("MIG-PIN-LOST")?.security?.reestablish).toBe("#297");
+    expect(byRule.get("MIG-SECRET-UNSCOPED")?.security?.reestablish).toBe("#300");
+  });
+
+  test("does not flag a clean workflow", () => {
+    const clean = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    expect(analyzeSecurity(clean)).toHaveLength(0);
+  });
+});
+
+describe("runSecurityChecks (#306)", () => {
+  test("runs the GitLab post-synth checks against migrated YAML", async () => {
+    // A migrated pipeline whose image is unpinned should trip WGL031.
+    const yaml = `stages:
+  - build
+
+build:
+  stage: build
+  image:
+    name: node:20
+  script:
+    - npm ci
+`;
+    const records = await runSecurityChecks(yaml);
+    expect(records.some((r) => r.rule === "WGL031")).toBe(true);
+    expect(records.every((r) => r.security !== undefined)).toBe(true);
+  });
+});
+
+describe("renderSecurityPosture (#306)", () => {
+  test("renders a posture table", () => {
+    const records = analyzeSecurity(WORKFLOW, { sourceFile: "ci.yml" });
+    const md = renderSecurityPosture(records);
+    expect(md).toContain("## Security posture");
+    expect(md).toContain("MIG-PIN-LOST");
+    expect(md).toContain("lost");
+  });
+
+  test("reports nothing for a clean workflow", () => {
+    expect(renderSecurityPosture([])).toContain("No security-relevant properties");
+  });
+});
+
+describe("transform with security: true (#306)", () => {
+  test("security findings flow into provenance + diagnostics + posture", async () => {
+    const result = await transform(WORKFLOW, { sourceFile: "ci.yml", security: true });
+    const ruleIds = new Set(result.diagnostics.map((d) => d.ruleId));
+    expect(ruleIds.has("MIG-PIN-LOST")).toBe(true);
+    expect(ruleIds.has("MIG-TRUST-BOUNDARY")).toBe(true);
+    expect(result.securityPosture).toContain("## Security posture");
+    expect(result.provenance.some((p) => p.security)).toBe(true);
+  });
+
+  test("security analysis is off by default", async () => {
+    const result = await transform(WORKFLOW, { sourceFile: "ci.yml" });
+    const ruleIds = new Set(result.diagnostics.map((d) => d.ruleId));
+    expect(ruleIds.has("MIG-PIN-LOST")).toBe(false);
+    expect(result.provenance.some((p) => p.security)).toBe(false);
+  });
+});