actions-warden 0.2.0 → 0.4.0

package/src/lib/resolver.js

@@ -7,10 +7,14 @@
  */
 
 import semver from 'semver';
-import { readCache, writeCache } from './cache.js';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { readCache, readCacheEntry, writeCache } from './cache.js';
 import { redact } from './redact.js';
 
 const API = 'https://api.github.com';
+const IN_FLIGHT = new Map();
+const COMMIT_SHA_RE = /^[0-9a-f]{40}$/i;
 
 /**
  * Resolve the API token. Precedence: explicit param > GITHUB_TOKEN > GH_TOKEN.
@@ -32,13 +36,42 @@ export function resolveToken(explicit) {
  * @param {number} [opts.retries]
  * @param {string} [opts.cwd]
  * @param {boolean} [opts.useCache]
+ * @param {(event: {attempt: number, maxRetries: number, reason: 'network'|'rate-limit'|'server-error', delayMs: number, status?: number}) => void|Promise<void>} [opts.onRetry]
  * @returns {Promise<{status: number, body: unknown}>}
  */
-export async function ghFetch({ url, token, retries = 3, cwd = process.cwd(), useCache = true }) {
-  if (useCache) {
-    const cached = await readCache({ key: url, cwd });
-    if (cached !== undefined) return { status: 200, body: cached };
+export function ghFetch(options) {
+  const {
+    url,
+    token,
+    cwd = process.cwd(),
+    useCache = true,
+  } = options;
+  const inFlightKey = `${requestCacheKey(url, token)}|cwd=${resolve(cwd)}|cache=${useCache}`;
+  const existing = IN_FLIGHT.get(inFlightKey);
+  if (existing) return existing;
+  const request = ghFetchInternal(options).finally(() => {
+    if (IN_FLIGHT.get(inFlightKey) === request) IN_FLIGHT.delete(inFlightKey);
+  });
+  IN_FLIGHT.set(inFlightKey, request);
+  return request;
+}
+
+async function ghFetchInternal({
+  url,
+  token,
+  retries = 3,
+  cwd = process.cwd(),
+  useCache = true,
+  onRetry,
+}) {
+  if (onRetry !== undefined && typeof onRetry !== 'function') {
+    throw new Error('onRetry must be a function');
   }
+  const cacheKey = requestCacheKey(url, token);
+  const cached = useCache
+    ? await readCacheEntry({ key: cacheKey, cwd, allowExpired: true })
+    : undefined;
+  if (cached?.fresh) return { status: 200, body: cached.value };
 
   const headers = {
     accept: 'application/vnd.github+json',
@@ -46,31 +79,70 @@ export async function ghFetch({ url, token, retries = 3, cwd = process.cwd(), us
     'x-github-api-version': '2022-11-28',
   };
   if (token) headers.authorization = `Bearer ${token}`;
+  if (cached?.etag) headers['if-none-match'] = cached.etag;
 
   let attempt = 0;
   for (;;) {
     let response;
     try {
-      response = await fetch(url, { headers });
+      response = await fetch(url, {
+        headers,
+        signal: AbortSignal.timeout(15_000),
+      });
     } catch (err) {
       if (attempt >= retries) throw new Error(`github fetch failed: ${redact(String(err))}`);
-      await sleep(backoff(attempt));
+      const delayMs = backoff(attempt);
+      await notifyRetry(onRetry, {
+        attempt: attempt + 1,
+        maxRetries: retries,
+        reason: 'network',
+        delayMs,
+      });
+      await sleep(delayMs);
       attempt += 1;
       continue;
     }
     const remaining = response.headers.get('x-ratelimit-remaining');
+    if (response.status === 304 && cached) {
+      await writeCache({
+        key: cacheKey,
+        value: cached.value,
+        etag: cached.etag,
+        cwd,
+      });
+      return { status: 200, body: cached.value };
+    }
     if ((response.status === 403 && remaining === '0') || response.status === 429) {
       const reset = Number(response.headers.get('x-ratelimit-reset') ?? 0) * 1000;
       const wait = Math.max(reset - Date.now(), backoff(attempt));
       if (attempt >= retries) {
-        throw new Error('github rate limit exhausted');
+        const resetMessage = Number.isFinite(reset) && reset > Date.now()
+          ? `; resets at ${new Date(reset).toISOString()}`
+          : '';
+        throw new Error(`github rate limit exhausted${resetMessage}`);
       }
-      await sleep(Math.min(wait, 30_000));
+      const delayMs = Math.min(wait, 30_000);
+      await notifyRetry(onRetry, {
+        attempt: attempt + 1,
+        maxRetries: retries,
+        reason: 'rate-limit',
+        delayMs,
+        status: response.status,
+      });
+      await sleep(delayMs);
       attempt += 1;
       continue;
     }
     if (response.status >= 500 && attempt < retries) {
-      await sleep(backoff(attempt));
+      const delayMs = backoff(attempt);
+      await notifyRetry(onRetry, {
+        attempt: attempt + 1,
+        maxRetries: retries,
+        reason: 'server-error',
+        delayMs,
+        status: response.status,
+      });
+      await sleep(delayMs);
       attempt += 1;
       continue;
     }
@@ -79,12 +151,23 @@ export async function ghFetch({ url, token, retries = 3, cwd = process.cwd(), us
     let body;
     try { body = text ? JSON.parse(text) : null; } catch { body = text; }
     if (response.status === 200 && useCache) {
-      await writeCache({ key: url, value: body, cwd });
+      await writeCache({
+        key: cacheKey,
+        value: body,
+        etag: response.headers.get('etag') ?? undefined,
+        cwd,
+      });
     }
     return { status: response.status, body };
   }
 }
 
+function requestCacheKey(url, token) {
+  if (!token) return `${url}|auth=anonymous`;
+  const identity = createHash('sha256').update(token).digest('hex').slice(0, 16);
+  return `${url}|auth=${identity}`;
+}
+
 function backoff(attempt) {
   return Math.min(1000 * 2 ** attempt, 8000);
 }
@@ -92,6 +175,10 @@ function sleep(ms) {
   return new Promise(res => setTimeout(res, ms));
 }
 
+async function notifyRetry(onRetry, event) {
+  if (onRetry) await onRetry(event);
+}
+
 /**
  * Resolve a ref (tag, branch, or commit-ish) to an immutable commit SHA.
  *
@@ -105,7 +192,7 @@ function sleep(ms) {
  */
 export async function resolveRefToSha({ owner, repo, ref, token, cwd }) {
   // Already a full SHA?
-  if (/^[0-9a-f]{40}$/i.test(ref)) {
+  if (COMMIT_SHA_RE.test(ref)) {
     return { sha: ref.toLowerCase(), type: 'commit' };
   }
   // Try as tag.
@@ -113,35 +200,87 @@ export async function resolveRefToSha({ owner, repo, ref, token, cwd }) {
   const tagRes = await ghFetch({ url: tagUrl, token, cwd });
   if (tagRes.status === 200 && tagRes.body && typeof tagRes.body === 'object') {
     const obj = tagRes.body.object;
-    if (obj && obj.sha) {
+    if (obj && COMMIT_SHA_RE.test(String(obj.sha))) {
       if (obj.type === 'tag') {
-        // Annotated tag - dereference to commit.
-        const tagObjUrl = `${API}/repos/${owner}/${repo}/git/tags/${obj.sha}`;
-        const tagObj = await ghFetch({ url: tagObjUrl, token, cwd });
-        if (tagObj.status === 200 && tagObj.body && tagObj.body.object) {
-          return { sha: tagObj.body.object.sha, type: 'tag' };
-        }
+        const sha = await dereferenceTagToCommit({
+          owner,
+          repo,
+          sha: String(obj.sha),
+          token,
+          cwd,
+        });
+        return { sha, type: 'tag' };
       }
-      return { sha: obj.sha, type: 'tag' };
+      if (obj.type !== 'commit') {
+        throw new Error(`tag ${owner}/${repo}@${ref} does not resolve to a commit`);
+      }
+      return { sha: String(obj.sha).toLowerCase(), type: 'tag' };
     }
   }
   // Try as branch.
   const branchUrl = `${API}/repos/${owner}/${repo}/git/refs/heads/${encodeURIComponent(ref)}`;
   const branchRes = await ghFetch({ url: branchUrl, token, cwd });
-  if (branchRes.status === 200 && branchRes.body?.object?.sha) {
-    return { sha: branchRes.body.object.sha, type: 'branch' };
+  if (
+    branchRes.status === 200
+    && branchRes.body?.object?.type === 'commit'
+    && COMMIT_SHA_RE.test(String(branchRes.body.object.sha))
+  ) {
+    return { sha: String(branchRes.body.object.sha).toLowerCase(), type: 'branch' };
   }
   // Try as commit.
   const commitUrl = `${API}/repos/${owner}/${repo}/commits/${encodeURIComponent(ref)}`;
   const commitRes = await ghFetch({ url: commitUrl, token, cwd });
-  if (commitRes.status === 200 && commitRes.body?.sha) {
-    return { sha: commitRes.body.sha, type: 'commit' };
+  if (commitRes.status === 200 && COMMIT_SHA_RE.test(String(commitRes.body?.sha))) {
+    return { sha: String(commitRes.body.sha).toLowerCase(), type: 'commit' };
   }
   throw new Error(`could not resolve ${owner}/${repo}@${ref}`);
 }
 
+async function dereferenceTagToCommit({ owner, repo, sha, token, cwd }) {
+  let currentSha = sha;
+  for (let depth = 0; depth < 10; depth += 1) {
+    const url = `${API}/repos/${owner}/${repo}/git/tags/${currentSha}`;
+    const response = await ghFetch({ url, token, cwd });
+    const target = response.body?.object;
+    if (
+      response.status !== 200
+      || !target
+      || !COMMIT_SHA_RE.test(String(target.sha))
+    ) {
+      throw new Error(`could not dereference annotated tag ${owner}/${repo}@${sha}`);
+    }
+    if (target.type === 'commit') return String(target.sha).toLowerCase();
+    if (target.type !== 'tag') {
+      throw new Error(`annotated tag ${owner}/${repo}@${sha} targets ${target.type ?? 'an unknown object'}, not a commit`);
+    }
+    currentSha = String(target.sha);
+  }
+  throw new Error(`annotated tag chain is too deep for ${owner}/${repo}@${sha}`);
+}
+
 /**
- * List all tags for a repo (paginated, up to 200).
+ * Confirm that a commit SHA is reachable through the requested repository's
+ * commits API rather than merely looking like a SHA.
+ */
+export async function verifyCommitInRepo({ owner, repo, sha, token, cwd }) {
+  if (!COMMIT_SHA_RE.test(sha)) {
+    throw new Error(`invalid commit SHA for ${owner}/${repo}`);
+  }
+  const url = `${API}/repos/${owner}/${repo}/commits/${encodeURIComponent(sha)}`;
+  const response = await ghFetch({ url, token, cwd });
+  if (
+    response.status !== 200
+    || !response.body
+    || typeof response.body !== 'object'
+    || String(response.body.sha).toLowerCase() !== sha.toLowerCase()
+  ) {
+    throw new Error(`commit ${sha} is not verifiable in ${owner}/${repo} (HTTP ${response.status})`);
+  }
+  return true;
+}
+
+/**
+ * List all tags for a repo.
  *
  * @param {object} opts
  * @param {string} opts.owner
@@ -153,10 +292,15 @@ export async function resolveRefToSha({ owner, repo, ref, token, cwd }) {
 export async function listTags({ owner, repo, token, cwd }) {
   /** @type {Array<{name: string, sha: string}>} */
   const out = [];
-  for (let page = 1; page <= 2; page += 1) {
+  for (let page = 1; page <= 100; page += 1) {
     const url = `${API}/repos/${owner}/${repo}/tags?per_page=100&page=${page}`;
     const res = await ghFetch({ url, token, cwd });
-    if (res.status !== 200 || !Array.isArray(res.body)) break;
+    if (res.status !== 200) {
+      throw new Error(`could not list tags for ${owner}/${repo} (HTTP ${res.status})`);
+    }
+    if (!Array.isArray(res.body)) {
+      throw new Error(`invalid tag response for ${owner}/${repo}`);
+    }
     for (const t of res.body) {
       if (t && t.name && t.commit?.sha) out.push({ name: t.name, sha: t.commit.sha });
     }
@@ -166,27 +310,46 @@ export async function listTags({ owner, repo, token, cwd }) {
 }
 
 /**
- * Fetch the committer date of a commit (ms epoch).
+ * Get conservative age evidence for a tag.
+ *
+ * Git commit and tagger timestamps are author-controlled, so they are not
+ * suitable for a security cooldown. Prefer GitHub's release publication time.
+ * For tags without releases, persist when this exact tag-to-SHA mapping was
+ * first observed and age it from that point.
  *
  * @param {object} opts
  * @param {string} opts.owner
  * @param {string} opts.repo
+ * @param {string} opts.tag
  * @param {string} opts.sha
  * @param {string} [opts.token]
  * @param {string} [opts.cwd]
- * @returns {Promise<number>}
+ * @returns {Promise<{dateMs: number, source: 'release'|'first-seen'}>}
  */
-export async function getCommitDate({ owner, repo, sha, token, cwd }) {
-  const url = `${API}/repos/${owner}/${repo}/commits/${encodeURIComponent(sha)}`;
-  const res = await ghFetch({ url, token, cwd });
-  if (res.status !== 200 || !res.body) {
-    throw new Error(`could not fetch commit date for ${owner}/${repo}@${sha}`);
+export async function getTagAgeEvidence({ owner, repo, tag, sha, token, cwd = process.cwd() }) {
+  const releaseUrl = `${API}/repos/${owner}/${repo}/releases/tags/${encodeURIComponent(tag)}`;
+  const release = await ghFetch({ url: releaseUrl, token, cwd });
+  if (release.status === 200 && release.body && typeof release.body === 'object') {
+    const dateText = release.body.published_at;
+    const dateMs = Date.parse(dateText);
+    if (Number.isFinite(dateMs)) return { dateMs, source: 'release' };
+  }
+  // A release object without a trustworthy timestamp provides no stronger age
+  // evidence than a tag without a release. Start the conservative first-seen
+  // cooldown instead of failing the entire upgrade.
+  if (release.status !== 404 && release.status !== 200) {
+    throw new Error(`could not verify tag age for ${owner}/${repo}@${tag} (HTTP ${release.status})`);
+  }
+
+  const observationKey = `first-seen:${owner.toLowerCase()}/${repo.toLowerCase()}@${tag}:${sha}`;
+  const ttlMs = 10 * 365 * 86_400_000;
+  const existing = await readCache({ key: observationKey, ttlMs, cwd });
+  if (existing && typeof existing === 'object' && Number.isFinite(existing.dateMs)) {
+    return { dateMs: existing.dateMs, source: 'first-seen' };
   }
-  const dateStr = res.body.commit?.committer?.date ?? res.body.commit?.author?.date;
-  if (!dateStr) throw new Error('commit response missing date');
-  const ms = Date.parse(dateStr);
-  if (!Number.isFinite(ms)) throw new Error(`invalid commit date: ${dateStr}`);
-  return ms;
+  const evidence = { dateMs: Date.now(), source: 'first-seen' };
+  await writeCache({ key: observationKey, value: evidence, ttlMs, cwd });
+  return evidence;
 }
 
 /**
@@ -200,15 +363,21 @@ export async function getCommitDate({ owner, repo, sha, token, cwd }) {
  */
 export function pickLatestTag({ tags, currentRef, mode = 'major' }) {
   const semverTags = tags
-    .map(t => ({ tag: t, parsed: semver.coerce(t.name) }))
+    .map(t => ({ tag: t, parsed: parseActionVersion(t.name) }))
     .filter(x => x.parsed)
-    .map(x => ({ tag: x.tag, version: x.parsed.version }))
-    .sort((a, b) => semver.rcompare(a.version, b.version));
+    .filter(x => x.parsed.prerelease.length === 0)
+    .map(x => ({
+      tag: x.tag,
+      version: x.parsed.version,
+      specificity: versionSpecificity(x.tag.name),
+    }))
+    .sort((a, b) => semver.rcompare(a.version, b.version) || b.specificity - a.specificity);
   if (semverTags.length === 0) return null;
 
-  const current = currentRef ? semver.coerce(currentRef) : null;
+  const current = currentRef ? parseActionVersion(currentRef) : null;
   if (!current || mode === 'major') return semverTags[0].tag;
   for (const candidate of semverTags) {
+    if (semver.lt(candidate.version, current.version)) continue;
     if (mode === 'minor' && semver.major(candidate.version) === current.major) {
       return candidate.tag;
     }
@@ -222,3 +391,16 @@ export function pickLatestTag({ tags, currentRef, mode = 'major' }) {
   }
   return null;
 }
+
+function parseActionVersion(input) {
+  if (typeof input !== 'string') return null;
+  const match = input.match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(-[0-9A-Za-z.-]+)?$/);
+  if (!match) return null;
+  const normalized = `${match[1]}.${match[2] ?? '0'}.${match[3] ?? '0'}${match[4] ?? ''}`;
+  return semver.parse(normalized);
+}
+
+function versionSpecificity(input) {
+  const core = input.replace(/^v/, '').split('-')[0];
+  return core.split('.').length;
+}

package/src/lib/targets.js

@@ -0,0 +1,28 @@
+import { discoverWorkflows, resolveWorkflowArg } from './paths.js';
+
+/**
+ * Resolve command workflow targets and reject empty scopes.
+ *
+ * @param {object} input
+ * @param {string[]|undefined} input.workflows
+ * @param {string} input.cwd
+ */
+export async function resolveTargets({ workflows, cwd }) {
+  if (!workflows || workflows.length === 0) {
+    const discovered = await discoverWorkflows({ cwd });
+    if (discovered.length === 0) {
+      throw new Error('no workflow or composite action files found');
+    }
+    return discovered;
+  }
+
+  const out = new Set();
+  for (const workflow of workflows) {
+    const files = await resolveWorkflowArg(workflow, cwd);
+    if (files.length === 0) {
+      throw new Error(`no workflows matched: ${workflow}`);
+    }
+    for (const file of files) out.add(file);
+  }
+  return [...out].sort();
+}

package/src/lib/triggers.js

@@ -0,0 +1,12 @@
+/**
+ * Test whether a parsed workflow subscribes to an event.
+ *
+ * @param {unknown} on
+ * @param {string} name
+ */
+export function hasTrigger(on, name) {
+  if (!on) return false;
+  if (typeof on === 'string') return on === name;
+  if (Array.isArray(on)) return on.includes(name);
+  return typeof on === 'object' && Object.prototype.hasOwnProperty.call(on, name);
+}

package/src/lib/writer.js

@@ -5,8 +5,9 @@
  * (the default), no bytes are written - the change is recorded and reported.
  */
 
-import { writeFile } from 'node:fs/promises';
-import { resolve, relative } from 'node:path';
+import { open, rename, unlink, lstat, realpath } from 'node:fs/promises';
+import { resolve, relative, dirname, basename, isAbsolute, sep, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
 
 /**
  * @typedef {object} WriteResult
@@ -25,16 +26,49 @@ import { resolve, relative } from 'node:path';
  * @returns {Promise<WriteResult>}
  */
 export async function writeFileGuarded({ path, content, dryRun = true, cwd = process.cwd() }) {
-  const abs = resolve(cwd, path);
-  const rel = relative(cwd, abs);
-  if (rel.startsWith('..') || rel.includes('\0')) {
+  if (typeof path !== 'string' || path.includes('\0')) throw new Error('invalid path');
+  const requestedRoot = resolve(cwd);
+  const requestedPath = resolve(requestedRoot, path);
+  if (!isAbsolute(path) && isOutside(relative(requestedRoot, requestedPath))) {
     throw new Error(`refusing to write outside working directory: ${path}`);
   }
+  const root = await realpath(requestedRoot);
+  const parent = await realpath(dirname(requestedPath));
+  if (isOutside(relative(root, parent))) {
+    throw new Error(`refusing to write outside working directory: ${path}`);
+  }
+  const abs = join(parent, basename(requestedPath));
+  let existingMode;
+  try {
+    const entry = await lstat(requestedPath);
+    if (entry.isSymbolicLink()) {
+      throw new Error(`refusing to write through a symlink: ${path}`);
+    }
+    if (!entry.isFile()) {
+      throw new Error(`refusing to replace a non-file path: ${path}`);
+    }
+    existingMode = entry.mode & 0o777;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
   const bytes = Buffer.byteLength(content, 'utf8');
   if (dryRun) {
     return { path: abs, written: false, dryRun: true, bytes };
   }
-  await writeFile(abs, content, 'utf8');
+  const tempPath = join(parent, `.${basename(abs)}.actions-warden-${process.pid}-${randomUUID()}`);
+  let handle;
+  try {
+    handle = await open(tempPath, 'wx', existingMode ?? 0o600);
+    await handle.writeFile(content, 'utf8');
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await rename(tempPath, abs);
+  } catch (error) {
+    if (handle) await handle.close().catch(() => {});
+    await unlink(tempPath).catch(() => {});
+    throw error;
+  }
   return { path: abs, written: true, dryRun: false, bytes };
 }
 
@@ -49,8 +83,14 @@ export function assertSafePath(path, cwd = process.cwd()) {
   if (typeof path !== 'string' || path.includes('\0')) {
     throw new Error('invalid path');
   }
-  if (path.includes('..')) {
+  const root = resolve(cwd);
+  const abs = resolve(root, path);
+  if (isOutside(relative(root, abs))) {
     throw new Error(`path traversal rejected: ${path}`);
   }
-  return resolve(cwd, path);
+  return abs;
+}
+
+function isOutside(rel) {
+  return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
 }

package/src/rules/excessive-permissions.js

@@ -5,37 +5,30 @@
 
 export const id = 'excessive-permissions';
 export const severity = 'medium';
-export const description = 'Workflow or job grants overly broad GITHUB_TOKEN permissions.';
+export const description = 'Workflow or job grants broadly writable GITHUB_TOKEN permissions.';
 
-const BROAD_VALUES = new Set(['write-all', 'write', 'all']);
-const WRITE_SCOPES = new Set([
-  'contents',
-  'actions',
-  'packages',
-  'deployments',
-  'id-token',
-  'issues',
-  'pull-requests',
-  'security-events',
-]);
+const BROAD_VALUES = new Set(['write-all']);
 
 /**
  * @param {unknown} permissions
- * @returns {string|null}  - returns offending scope label, or null
+ * @param {boolean} declared
+ * @returns {string|null}  - returns an offending scope label, or null
  */
-function inspect(permissions) {
-  if (permissions === undefined || permissions === null) {
-    return 'unset-default'; // GitHub default is permissive when not declared
-  }
+function inspect(permissions, declared) {
+  if (!declared) return 'unset-default';
+  if (permissions === undefined || permissions === null) return null;
   if (typeof permissions === 'string') {
     return BROAD_VALUES.has(permissions) ? permissions : null;
   }
   if (typeof permissions === 'object') {
-    for (const [scope, val] of Object.entries(permissions)) {
-      if (val === 'write' && WRITE_SCOPES.has(scope)) {
-        return `${scope}=write`;
-      }
-    }
+    const writable = Object.entries(permissions)
+      .filter(([scope, value]) => value === 'write' && scope !== 'id-token')
+      .map(([scope]) => scope);
+    // Specific job capabilities such as contents:write or security-events:write
+    // are often the least privilege needed. Flag only maps broad enough to
+    // approximate write-all. Other rules independently report untrusted code
+    // flowing into privileged trigger contexts.
+    if (writable.length >= 3) return writable.map(scope => `${scope}=write`).join(',');
   }
   return null;
 }
@@ -44,37 +37,35 @@ function inspect(permissions) {
  * @param {import('../lib/parser.js').WorkflowDoc} workflow
  */
 export function check(workflow) {
-  // Composite actions inherit the calling workflow's token permissions and do
-  // not support a top-level permissions block of their own.
-  if (workflow.kind === 'composite-action') return [];
+  if (workflow.kind !== 'workflow') return [];
   const findings = [];
-  const topScope = inspect(workflow.permissions);
+  const topScope = inspect(workflow.permissions, workflow.permissionsDeclared);
   if (topScope === 'unset-default') {
     findings.push({
       id,
       severity: 'low',
       line: 1,
-      fields: { type: id, sev: 'low', scope: 'workflow-default' },
-      explain: 'declare `permissions:` at workflow root with least-privilege scopes',
+      fields: { type: id, sev: 'low', scope: 'workflow-default-unspecified' },
+      explain: 'declare workflow-level `permissions: {}` and grant only the read or write scopes each job requires, so configurable repository defaults cannot broaden the token',
     });
   } else if (topScope) {
     findings.push({
       id,
       severity,
-      line: 1,
+      line: workflow.permissionsLine || 1,
       fields: { type: id, sev: severity, scope: topScope, target: 'workflow' },
-      explain: `workflow grants ${topScope} - narrow to specific scopes`,
+      explain: `replace workflow ${topScope} with an empty permissions map, then grant only the scopes required by each job`,
     });
   }
   for (const job of workflow.jobs) {
-    const jobScope = inspect(job.permissions);
+    const jobScope = inspect(job.permissions, job.permissionsDeclared);
     if (jobScope && jobScope !== 'unset-default') {
       findings.push({
         id,
         severity,
-        line: job.line,
+        line: job.permissionsLine || job.line,
         fields: { type: id, sev: severity, scope: jobScope, job: job.name },
-        explain: `job "${job.name}" grants ${jobScope}`,
+        explain: `replace ${jobScope} in job "${job.name}" with only the specific read or write scopes its steps require`,
       });
     }
   }

package/src/rules/index.js

@@ -3,12 +3,30 @@
  */
 
 import * as unpinned from './unpinned-action.js';
+import * as unpinnedDocker from './unpinned-docker-action.js';
+import * as unpinnedContainer from './unpinned-container-image.js';
 import * as perms from './excessive-permissions.js';
 import * as secrets from './secrets-in-env.js';
 import * as injection from './script-injection.js';
 import * as prTarget from './pull-request-target-checkout.js';
+import * as reusableSecrets from './reusable-workflow-secrets.js';
+import * as selfHosted from './untrusted-self-hosted-runner.js';
+import * as workflowRunArtifact from './workflow-run-artifact-execution.js';
+import * as workflowStructure from './workflow-structure.js';
 
-export const RULES = [unpinned, perms, secrets, injection, prTarget];
+export const RULES = [
+  unpinned,
+  unpinnedDocker,
+  unpinnedContainer,
+  perms,
+  secrets,
+  injection,
+  prTarget,
+  reusableSecrets,
+  selfHosted,
+  workflowRunArtifact,
+  workflowStructure,
+];
 
 /**
  * @returns {Array<{id: string, severity: string, description: string}>}