actions-warden 0.2.0 → 0.4.0

package/src/lib/baseline.js

@@ -0,0 +1,103 @@
+import { readFile } from 'node:fs/promises';
+import { canonicalPath, occurrenceId } from './identity.js';
+import { resolveRepositoryFile } from './config.js';
+
+/**
+ * Load a versioned baseline and return its finding IDs.
+ */
+export async function loadBaseline({ path, cwd = process.cwd() }) {
+  const resolvedPath = await resolveRepositoryFile(path, cwd);
+  const raw = JSON.parse(await readFile(resolvedPath, 'utf8'));
+  if (!raw || typeof raw !== 'object' || raw.schemaVersion !== '1.0') {
+    throw new Error('baseline schemaVersion must be "1.0"');
+  }
+  if (!Array.isArray(raw.findings)) {
+    throw new Error('baseline findings must be an array');
+  }
+  const ids = new Set();
+  const fingerprints = new Set();
+  for (const finding of raw.findings) {
+    if (!finding || typeof finding !== 'object' || typeof finding.id !== 'string') {
+      throw new Error('every baseline finding must contain a string id');
+    }
+    ids.add(finding.id);
+    if (finding.fingerprint !== undefined && typeof finding.fingerprint !== 'string') {
+      throw new Error('baseline finding fingerprints must be strings');
+    }
+    if (finding.fingerprint) fingerprints.add(finding.fingerprint);
+  }
+  return { path: resolvedPath, ids, fingerprints };
+}
+
+/**
+ * Serialize current findings deterministically for review and version control.
+ */
+export function serializeBaseline(findings, cwd = process.cwd()) {
+  const records = findings
+    .filter(finding => finding.ruleId !== 'parse-error')
+    .map(finding => ({
+      id: finding.id,
+      fingerprint: finding.fingerprint,
+      ruleId: finding.ruleId,
+      severity: finding.severity,
+      file: canonicalPath(finding.file, cwd),
+      line: finding.line,
+    }))
+    .sort((a, b) => (
+      a.file.localeCompare(b.file)
+      || a.line - b.line
+      || a.ruleId.localeCompare(b.ruleId)
+      || a.id.localeCompare(b.id)
+    ));
+  return `${JSON.stringify({
+    schemaVersion: '1.0',
+    generatedBy: 'actions-warden',
+    findings: records,
+  }, null, 2)}\n`;
+}
+
+/**
+ * Attach line-independent semantic fingerprints while distinguishing repeated
+ * equivalent findings by their source-order ordinal.
+ */
+export function assignBaselineFingerprints(findings, cwd = process.cwd()) {
+  const ordered = [...findings].sort((a, b) => (
+    canonicalPath(a.file, cwd).localeCompare(canonicalPath(b.file, cwd))
+    || a.line - b.line
+    || a.ruleId.localeCompare(b.ruleId)
+    || a.id.localeCompare(b.id)
+  ));
+  const occurrences = new Map();
+  for (const finding of ordered) {
+    const semantic = stableValue(Object.fromEntries(
+      Object.entries(finding.fields ?? {})
+        .filter(([key]) => !['file', 'line', 'sev', 'source_line'].includes(key)),
+    ));
+    const key = JSON.stringify({
+      ruleId: finding.ruleId,
+      file: canonicalPath(finding.file, cwd),
+      fields: semantic,
+    });
+    const ordinal = occurrences.get(key) ?? 0;
+    occurrences.set(key, ordinal + 1);
+    finding.fingerprint = occurrenceId({
+      kind: 'baseline',
+      file: finding.file,
+      cwd,
+      subject: `${key}#${ordinal}`,
+    });
+  }
+  return findings;
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, stableValue(item)]),
+    );
+  }
+  return value;
+}

package/src/lib/cache.js

@@ -1,19 +1,22 @@
 /**
  * On-disk cache for GitHub API responses.
  *
- * Keyed by sha1 of the request URL. TTL stored in the cache entry. Files live
- * in `.actions-warden-cache/` inside the working directory.
+ * Keyed by sha1 of the request identity. TTL is stored in each cache entry.
+ * Files live outside the scanned repository, under ACTIONS_WARDEN_CACHE_DIR,
+ * XDG_CACHE_HOME, or the user's platform cache directory.
  */
 
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, rename, unlink } from 'node:fs/promises';
 import { resolve, join } from 'node:path';
-import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
 
 /**
  * @typedef {object} CacheEntry
  * @property {number} savedAt   - ms epoch
  * @property {number} ttlMs
  * @property {unknown} value
+ * @property {string|undefined} etag
  */
 
 /**
@@ -21,7 +24,11 @@ import { createHash } from 'node:crypto';
  * @returns {string}
  */
 export function cacheDir(cwd = process.cwd()) {
-  return resolve(cwd, '.actions-warden-cache');
+  const base = process.env.ACTIONS_WARDEN_CACHE_DIR
+    ?? (process.env.XDG_CACHE_HOME
+      ? join(process.env.XDG_CACHE_HOME, 'actions-warden')
+      : join(homedir(), '.cache', 'actions-warden'));
+  return join(resolve(base), digest(resolve(cwd)));
 }
 
 /**
@@ -40,13 +47,28 @@ function digest(key) {
  * @returns {Promise<unknown|undefined>}
  */
 export async function readCache({ key, ttlMs = 3600 * 1000, cwd = process.cwd() }) {
+  const cached = await readCacheEntry({ key, ttlMs, cwd });
+  return cached?.fresh ? cached.value : undefined;
+}
+
+/**
+ * Read cache metadata, optionally including an expired value for ETag
+ * revalidation.
+ */
+export async function readCacheEntry({
+  key,
+  ttlMs = 3600 * 1000,
+  cwd = process.cwd(),
+  allowExpired = false,
+}) {
   const path = join(cacheDir(cwd), `${digest(key)}.json`);
   try {
     const raw = await readFile(path, 'utf8');
     /** @type {CacheEntry} */
     const entry = JSON.parse(raw);
-    if (Date.now() - entry.savedAt > Math.min(entry.ttlMs, ttlMs)) return undefined;
-    return entry.value;
+    const fresh = Date.now() - entry.savedAt <= Math.min(entry.ttlMs, ttlMs);
+    if (!fresh && !allowExpired) return undefined;
+    return { value: entry.value, etag: entry.etag, fresh };
   } catch {
     return undefined;
   }
@@ -58,11 +80,26 @@ export async function readCache({ key, ttlMs = 3600 * 1000, cwd = process.cwd()
  * @param {unknown} opts.value
  * @param {number} [opts.ttlMs]
  * @param {string} [opts.cwd]
+ * @param {string} [opts.etag]
  */
-export async function writeCache({ key, value, ttlMs = 3600 * 1000, cwd = process.cwd() }) {
+export async function writeCache({
+  key,
+  value,
+  ttlMs = 3600 * 1000,
+  cwd = process.cwd(),
+  etag,
+}) {
   const dir = cacheDir(cwd);
   await mkdir(dir, { recursive: true });
   /** @type {CacheEntry} */
-  const entry = { savedAt: Date.now(), ttlMs, value };
-  await writeFile(join(dir, `${digest(key)}.json`), JSON.stringify(entry), 'utf8');
+  const entry = { savedAt: Date.now(), ttlMs, value, ...(etag ? { etag } : {}) };
+  const path = join(dir, `${digest(key)}.json`);
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, JSON.stringify(entry), { encoding: 'utf8', mode: 0o600 });
+    await rename(temp, path);
+  } catch (error) {
+    await unlink(temp).catch(() => {});
+    throw error;
+  }
 }

package/src/lib/concurrency.js

@@ -0,0 +1,27 @@
+/**
+ * Order-preserving bounded async map.
+ */
+export async function mapLimit(values, limit, worker) {
+  if (!Number.isInteger(limit) || limit < 1) throw new Error('concurrency limit must be positive');
+  const results = new Array(values.length);
+  let cursor = 0;
+  let stopped = false;
+  async function run() {
+    for (;;) {
+      if (stopped) return;
+      const index = cursor;
+      cursor += 1;
+      if (index >= values.length) return;
+      try {
+        results[index] = await worker(values[index], index);
+      } catch (error) {
+        stopped = true;
+        throw error;
+      }
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(limit, values.length) }, () => run()),
+  );
+  return results;
+}

package/src/lib/config.js

@@ -0,0 +1,185 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import picomatch from 'picomatch';
+import { parseDocument } from 'yaml';
+
+const CONFIG_NAMES = ['.actions-warden.yml', '.actions-warden.yaml'];
+const SEVERITIES = new Set(['low', 'medium', 'high', 'critical']);
+const TOP_LEVEL_KEYS = new Set([
+  'version',
+  'baseline',
+  'ignore-paths',
+  'rules',
+  'runner-policy',
+]);
+
+export const DEFAULT_CONFIG = Object.freeze({
+  path: null,
+  baseline: null,
+  ignorePaths: [],
+  rules: {},
+  runnerPolicy: {
+    trustedGroups: [],
+    selfHostedLabels: [],
+    flagUnknownGroups: false,
+  },
+});
+
+/**
+ * Load and strictly validate repository policy.
+ *
+ * @param {object} options
+ * @param {string} [options.cwd]
+ * @param {string|false} [options.path]
+ * @param {string[]} [options.ruleIds]
+ */
+export async function loadConfig({
+  cwd = process.cwd(),
+  path,
+  ruleIds = [],
+} = {}) {
+  if (path === false) {
+    return { ...DEFAULT_CONFIG, runnerPolicy: { ...DEFAULT_CONFIG.runnerPolicy } };
+  }
+  let resolvedPath;
+  if (path) {
+    resolvedPath = await resolveRepositoryFile(path, cwd);
+  } else {
+    for (const candidate of CONFIG_NAMES) {
+      try {
+        resolvedPath = await resolveRepositoryFile(candidate, cwd);
+        break;
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+    }
+  }
+  if (!resolvedPath) return { ...DEFAULT_CONFIG, runnerPolicy: { ...DEFAULT_CONFIG.runnerPolicy } };
+
+  const source = await readFile(resolvedPath, 'utf8');
+  const document = parseDocument(source);
+  if (document.errors.length > 0) {
+    throw new Error(`invalid actions-warden config: ${document.errors[0].message}`);
+  }
+  const raw = document.toJS() ?? {};
+  if (!isRecord(raw)) throw new Error('actions-warden config must be a mapping');
+  rejectUnknownKeys(raw, TOP_LEVEL_KEYS, 'config');
+  if (raw.version !== undefined && raw.version !== 1) {
+    throw new Error('actions-warden config version must be 1');
+  }
+
+  const knownRules = new Set(ruleIds);
+  const rules = validateRules(raw.rules, knownRules);
+  const runnerPolicy = validateRunnerPolicy(raw['runner-policy']);
+  const baseline = optionalString(raw.baseline, 'baseline');
+  const ignorePaths = stringArray(raw['ignore-paths'], 'ignore-paths');
+
+  return {
+    path: resolvedPath,
+    baseline,
+    ignorePaths,
+    rules,
+    runnerPolicy,
+  };
+}
+
+export function filterIgnoredPaths(files, config, cwd) {
+  if (config.ignorePaths.length === 0) return files;
+  const matchers = config.ignorePaths.map(pattern => picomatch(pattern, { dot: true }));
+  return files.filter(file => {
+    const path = relative(cwd, file).split(sep).join('/');
+    return !matchers.some(matches => matches(path));
+  });
+}
+
+export async function resolveRepositoryFile(path, cwd = process.cwd()) {
+  const requestedRoot = resolve(cwd);
+  const requested = resolve(requestedRoot, path);
+  if (!isAbsolute(path) && isOutside(relative(requestedRoot, requested))) {
+    throw new Error(`path traversal rejected: ${path}`);
+  }
+  const [root, target] = await Promise.all([
+    realpath(requestedRoot),
+    realpath(requested),
+  ]);
+  if (isOutside(relative(root, target))) {
+    throw new Error(`repository file escapes working directory: ${path}`);
+  }
+  return target;
+}
+
+function validateRules(value, knownRules) {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new Error('config.rules must be a mapping');
+  const rules = {};
+  for (const [ruleId, policy] of Object.entries(value)) {
+    if (knownRules.size > 0 && !knownRules.has(ruleId)) {
+      throw new Error(`unknown rule in config: ${ruleId}`);
+    }
+    if (!isRecord(policy)) throw new Error(`config.rules.${ruleId} must be a mapping`);
+    rejectUnknownKeys(policy, new Set(['enabled', 'severity']), `config.rules.${ruleId}`);
+    if (policy.enabled !== undefined && typeof policy.enabled !== 'boolean') {
+      throw new Error(`config.rules.${ruleId}.enabled must be a boolean`);
+    }
+    if (policy.severity !== undefined && !SEVERITIES.has(policy.severity)) {
+      throw new Error(`config.rules.${ruleId}.severity must be low, medium, high, or critical`);
+    }
+    rules[ruleId] = {
+      enabled: policy.enabled ?? true,
+      severity: policy.severity,
+    };
+  }
+  return rules;
+}
+
+function validateRunnerPolicy(value) {
+  if (value === undefined) return { ...DEFAULT_CONFIG.runnerPolicy };
+  if (!isRecord(value)) throw new Error('config.runner-policy must be a mapping');
+  rejectUnknownKeys(
+    value,
+    new Set(['trusted-groups', 'self-hosted-labels', 'flag-unknown-groups']),
+    'config.runner-policy',
+  );
+  const flagUnknownGroups = value['flag-unknown-groups'] ?? false;
+  if (typeof flagUnknownGroups !== 'boolean') {
+    throw new Error('config.runner-policy.flag-unknown-groups must be a boolean');
+  }
+  return {
+    trustedGroups: stringArray(value['trusted-groups'], 'runner-policy.trusted-groups'),
+    selfHostedLabels: stringArray(
+      value['self-hosted-labels'],
+      'runner-policy.self-hosted-labels',
+    ),
+    flagUnknownGroups,
+  };
+}
+
+function rejectUnknownKeys(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`unknown ${label} key: ${key}`);
+  }
+}
+
+function stringArray(value, label) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item)) {
+    throw new Error(`config.${label} must be an array of non-empty strings`);
+  }
+  return [...new Set(value)];
+}
+
+function optionalString(value, label) {
+  if (value === undefined) return null;
+  if (typeof value !== 'string' || !value) {
+    throw new Error(`config.${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isOutside(path) {
+  return path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path);
+}

package/src/lib/execution.js

@@ -0,0 +1,71 @@
+/**
+ * Conservative indicators that a step may execute or interpret files from the
+ * current workspace. Avoid treating harmless shell commands such as `echo` as
+ * code execution while covering common build/test/package entry points.
+ */
+
+const WORKSPACE_COMMAND = /(?:^|[;&|])\s*(?:sudo\s+)?(?:(?:\.{0,2}[\\/]|[A-Za-z]:[\\/]|[A-Za-z0-9_.-]+[\\/])[^\s;&|]+|source\s+[^\s;&|]+|make(?:\s|$)|npm\s+(?:ci|install|test|run|exec)\b|npx\b|pnpm\s+(?:install|test|run|exec)\b|yarn\s+(?:install|test|run|exec)\b|bun\s+(?:install|test|run|x)\b|(?:bash|sh|zsh|python3?|ruby|node|perl|php)\s+[^\s;&|]+|(?:pwsh|powershell)(?:\.exe)?\s+(?:-File\s+)?[^\s;&|]+|cmd(?:\.exe)?\s+\/c\s+[^\s;&|]+|java\s+-jar\s+[^\s;&|]+|cargo\s+(?:build|test|run)\b|go\s+(?:build|test|run)\b|mvn\b|gradle\b|\.\/gradlew\b|dotnet\s+(?:build|test|run|publish)\b|bundle\s+exec\b|rake\b|pytest\b)/im;
+const WORKSPACE_ACTION = /(?:^|[-_/])(build|builder|compile|exec|package|publish|runner|test|deploy)(?:[-_/]|$)/i;
+
+/**
+ * @param {import('./parser.js').StepNode} step
+ */
+export function executesWorkspace(step, { sourcePaths = ['.'] } = {}) {
+  let executes = false;
+  if (step.uses?.kind === 'local') executes = true;
+  if (typeof step.run === 'string' && WORKSPACE_COMMAND.test(step.run)) executes = true;
+  if (step.uses?.kind === 'external') {
+    const identity = [
+      step.uses.owner,
+      step.uses.repo,
+      step.uses.subpath,
+    ].filter(Boolean).join('/');
+    if (WORKSPACE_ACTION.test(identity)) executes = true;
+    if (Object.values(step.with_ ?? {}).some(
+      value => typeof value === 'string' && WORKSPACE_COMMAND.test(value),
+    )) executes = true;
+  }
+  if (!executes) return false;
+
+  const normalized = sourcePaths.map(normalizePath);
+  if (normalized.includes('.')) return true;
+  const candidates = [
+    step.run,
+    step.workingDirectory,
+    step.uses?.raw,
+    ...Object.values(step.with_ ?? {}),
+  ].filter(value => typeof value === 'string');
+  return normalized.some(sourcePath => (
+    candidates.some(candidate => referencesPath(candidate, sourcePath))
+  ));
+}
+
+export function normalizeSourcePath(value) {
+  if (typeof value !== 'string' || !value.trim()) return '.';
+  const expanded = normalizeTrustedRoots(value);
+  if (expanded.includes('${{')) return '.';
+  return normalizePath(expanded);
+}
+
+function normalizePath(value) {
+  const normalized = normalizeTrustedRoots(String(value))
+    .trim()
+    .replaceAll('\\', '/')
+    .replace(/^\.\/+/, '');
+  return normalized.replace(/\/+$/, '') || '.';
+}
+
+function normalizeTrustedRoots(value) {
+  return String(value)
+    .replace(/\$\{\{\s*runner\.temp\s*\}\}/gi, '__runner_temp__')
+    .replace(/\$(?:\{RUNNER_TEMP\}|RUNNER_TEMP\b)|%RUNNER_TEMP%/g, '__runner_temp__')
+    .replace(/\$\{\{\s*github\.workspace\s*\}\}/gi, '.')
+    .replace(/\$(?:\{GITHUB_WORKSPACE\}|GITHUB_WORKSPACE\b)|%GITHUB_WORKSPACE%/g, '.');
+}
+
+function referencesPath(value, path) {
+  const normalizedValue = normalizePath(value);
+  const escaped = path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`(?:^|[\\s"'=:/])${escaped}(?:$|[\\s"'/:;&|])`, 'i')
+    .test(normalizedValue);
+}

package/src/lib/formatter.js

@@ -1,6 +1,6 @@
 /**
- * Output formatter supporting TOON (Token-Oriented Object Notation), JSON, and
- * plain text.
+ * Output formatter supporting TOON (Token-Oriented Object Notation), JSON,
+ * plain text, and SARIF.
  *
  * TOON output rules:
  *   - One record per line: `LABEL: key=value key=value`
@@ -9,7 +9,7 @@
  *   - Trailing `STATUS: OK` or `STATUS: FAIL` signal for machine consumers
  */
 
-import { redact } from './redact.js';
+import { redact, redactDeep } from './redact.js';
 
 /**
  * Severity ordering, lowest-to-highest.
@@ -22,8 +22,8 @@ export const SEVERITY_ORDER = ['low', 'medium', 'high', 'critical'];
  */
 function quoteIfNeeded(value) {
   if (value === '') return '""';
-  if (/[\s="]/.test(value)) {
-    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  if (/[\s="\\]/.test(value) || [...value].some(char => char.charCodeAt(0) < 32)) {
+    return JSON.stringify(value);
   }
   return value;
 }
@@ -65,7 +65,7 @@ export function renderToon(records, options = {}) {
  * @returns {string}
  */
 export function renderJson(payload) {
-  return JSON.stringify(payload, null, 2) + '\n';
+  return JSON.stringify(redactDeep(payload), null, 2) + '\n';
 }
 
 /**
@@ -79,7 +79,7 @@ export function renderText(records, options = {}) {
   const lines = records.map(r => {
     const kv = Object.entries(r.fields)
       .filter(([, v]) => v !== null && v !== undefined && v !== '')
-      .map(([k, v]) => `${k}=${redact(String(v))}`)
+      .map(([k, v]) => `${k}=${escapeText(redact(String(v)))}`)
       .join(' ');
     return `[${r.label}] ${kv}`;
   });
@@ -87,10 +87,14 @@ export function renderText(records, options = {}) {
   return lines.join('\n') + '\n';
 }
 
+function escapeText(value) {
+  return JSON.stringify(value).slice(1, -1);
+}
+
 /**
  * Format records into the requested output mode.
  *
- * @param {'toon'|'json'|'text'} format
+ * @param {'toon'|'json'|'text'|'sarif'} format
  * @param {Array<{label: string, fields: Record<string, unknown>}>} records
  * @param {{status?: 'OK'|'FAIL', json?: unknown}} [options]
  * @returns {string}
@@ -101,12 +105,126 @@ export function format(format_, records, options = {}) {
       return renderJson(options.json ?? recordsToJson(records, options));
     case 'text':
       return renderText(records, options);
+    case 'sarif':
+      return renderSarif(records, options);
     case 'toon':
     default:
       return renderToon(records, options);
   }
 }
 
+/**
+ * Render records as SARIF 2.1.0 for GitHub code scanning.
+ *
+ * @param {Array<{label: string, fields: Record<string, unknown>}>} records
+ * @param {{status?: string}} [options]
+ */
+export function renderSarif(records, options = {}) {
+  const ruleRecords = records.filter(record => record.label === 'RULE');
+  const resultRecords = records.filter(record => (
+    record.label === 'FINDING'
+    || record.label === 'ERROR'
+    || record.label === 'WARNING'
+    || record.label === 'PIN'
+    || record.label === 'UPGRADE'
+  ));
+  const rules = new Map();
+  for (const record of ruleRecords) {
+    const id = String(record.fields.id ?? 'actions-warden');
+    rules.set(id, {
+      id,
+      shortDescription: {
+        text: String(record.fields.description ?? id),
+      },
+      defaultConfiguration: {
+        level: sarifLevel(String(record.fields.severity ?? 'low')),
+      },
+    });
+  }
+
+  const results = resultRecords.map(record => {
+    const fields = record.fields;
+    const ruleId = String(fields.type ?? `actions-warden/${record.label.toLowerCase()}`);
+    if (!rules.has(ruleId)) {
+      rules.set(ruleId, {
+        id: ruleId,
+        shortDescription: { text: ruleId },
+        defaultConfiguration: {
+          level: record.label === 'ERROR'
+            ? 'error'
+            : sarifLevel(String(fields.sev ?? 'low')),
+        },
+      });
+    }
+    const file = fields.file ? String(fields.file) : null;
+    const line = Number(fields.line);
+    return {
+      ruleId,
+      level: record.label === 'ERROR'
+        ? 'error'
+        : record.label === 'WARNING'
+          ? 'warning'
+          : sarifLevel(String(fields.sev ?? (record.label === 'FINDING' ? 'warning' : 'low'))),
+      message: {
+        text: String(fields.explain ?? fields.msg ?? summarizeFields(record.label, fields)),
+      },
+      ...(file ? {
+        locations: [{
+          physicalLocation: {
+            artifactLocation: { uri: file.replace(/\\/g, '/') },
+            ...(Number.isInteger(line) && line > 0
+              ? { region: { startLine: line } }
+              : {}),
+          },
+        }],
+      } : {}),
+      ...(fields.id ? {
+        partialFingerprints: {
+          // GitHub code scanning recognizes this key and uses the suffix to
+          // distinguish multiple results with the same semantic fingerprint.
+          primaryLocationLineHash: `${fields.fingerprint ?? fields.id}:1`,
+          'actions-warden/id': String(fields.id),
+          ...(fields.fingerprint
+            ? { 'actions-warden/semantic': String(fields.fingerprint) }
+            : {}),
+        },
+      } : {}),
+    };
+  });
+
+  return renderJson({
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'actions-warden',
+          informationUri: 'https://github.com/chiz0me/actions-warden',
+          rules: [...rules.values()],
+        },
+      },
+      invocations: [{
+        executionSuccessful: options.status !== 'ERROR',
+      }],
+      results,
+    }],
+  });
+}
+
+function sarifLevel(severity) {
+  if (severity === 'critical' || severity === 'high' || severity === 'error') return 'error';
+  if (severity === 'medium' || severity === 'warning') return 'warning';
+  return 'note';
+}
+
+function summarizeFields(label, fields) {
+  const details = Object.entries(fields)
+    .filter(([key, value]) => !['id', 'file', 'line'].includes(key) && value != null && value !== '')
+    .map(([key, value]) => `${key}=${String(value)}`)
+    .join(' ');
+  return `${label}: ${details}`;
+}
+
 /**
  * Convert records to a generic JSON payload when no custom JSON is supplied.
  *
@@ -116,6 +234,7 @@ export function format(format_, records, options = {}) {
  */
 function recordsToJson(records, options) {
   return {
+    schemaVersion: '1.0',
     records: records.map(r => ({ label: r.label, ...r.fields })),
     status: options.status ?? null,
   };