actions-warden 0.2.0 → 0.3.0

package/src/rules/pull-request-target-checkout.js

@@ -3,44 +3,175 @@
  * head ref expose secrets to attacker-supplied code (pwn-request pattern).
  */
 
+import { hasTrigger } from '../lib/triggers.js';
+import { executesWorkspace, normalizeSourcePath } from '../lib/execution.js';
+import semver from 'semver';
+
 export const id = 'pull-request-target-checkout';
 export const severity = 'critical';
-export const description = 'pull_request_target workflow checks out attacker-controlled head ref.';
-
-function hasPullRequestTarget(on) {
-  if (!on) return false;
-  if (typeof on === 'string') return on === 'pull_request_target';
-  if (Array.isArray(on)) return on.includes('pull_request_target');
-  if (typeof on === 'object') return Object.prototype.hasOwnProperty.call(on, 'pull_request_target');
-  return false;
+export const description = 'pull_request_target can fetch attacker-controlled code without an active checkout guard.';
+
+// GitHub backported fork-PR checkout protection on 2026-07-20. Floating major
+// tags v2-v7 received it automatically; immutable callers need one of these
+// release commits (or a later release that a future warden version recognizes).
+const PROTECTED_MINIMUM = new Map([
+  [2, '2.8.0'],
+  [3, '3.7.0'],
+  [4, '4.4.0'],
+  [5, '5.1.0'],
+  [6, '6.1.0'],
+  [7, '7.0.0'],
+]);
+const KNOWN_PROTECTED_SHAS = new Set([
+  '0717577d45739eb3c851188b29f50ed6c0b2194e', // v2.8.0
+  'a37ce9120846195fa4ece8f58b268e6043cb2f26', // v3.7.0
+  '11d5960a326750d5838078e36cf38b85af677262', // v4.4.0
+  'fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09', // v5.1.0
+  'd23441a48e516b6c34aea4fa41551a30e30af803', // v6.1.0
+  '9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0', // v7.0.0
+  '3d3c42e5aac5ba805825da76410c181273ba90b1', // v7.0.1
+]);
+
+function checkoutProtection(step) {
+  const optOut = step.with_?.['allow-unsafe-pr-checkout'];
+  if (optOut === true || (typeof optOut === 'string' && optOut.trim().toLowerCase() === 'true')) {
+    return { active: false, reason: 'explicit-opt-out' };
+  }
+  if (typeof optOut === 'string' && optOut.includes('${{')) {
+    return { active: false, reason: 'dynamic-opt-out' };
+  }
+
+  const ref = step.uses?.ref ?? '';
+  if (KNOWN_PROTECTED_SHAS.has(ref.toLowerCase())) {
+    return { active: true, reason: 'protected-release-sha' };
+  }
+  const majorTag = ref.match(/^v([2-7])$/i);
+  if (majorTag) return { active: true, reason: 'protected-floating-major' };
+
+  const version = ref.match(/^v?(\d+)\.(\d+)(?:\.(\d+))?$/i);
+  if (version) {
+    const major = Number(version[1]);
+    const minimum = PROTECTED_MINIMUM.get(major);
+    const normalized = `${major}.${version[2]}.${version[3] ?? '0'}`;
+    if (minimum && semver.gte(normalized, minimum)) {
+      return { active: true, reason: 'protected-release-tag' };
+    }
+  }
+  return { active: false, reason: 'unknown-or-unprotected-version' };
 }
 
-function checksOutHead(step) {
-  if (!step.uses) return false;
-  if (step.uses.owner !== 'actions' || step.uses.repo !== 'checkout') return false;
+export function checkoutOfUntrustedPr(step) {
+  if (!step.uses) return null;
+  if (
+    step.uses.owner?.toLowerCase() !== 'actions'
+    || step.uses.repo?.toLowerCase() !== 'checkout'
+  ) return null;
   const ref = step.with_?.ref;
-  if (typeof ref !== 'string') return false;
-  return /github\.event\.pull_request\.head/i.test(ref) || /github\.head_ref/i.test(ref);
+  const repository = step.with_?.repository;
+  const untrustedRef = typeof ref === 'string' && (
+    /github\.event\.pull_request\.head/i.test(ref)
+    || /github\.event\.pull_request\.merge_commit_sha/i.test(ref)
+    || /github\.head_ref/i.test(ref)
+    || /refs\/pull\//i.test(ref)
+  );
+  const untrustedRepository = typeof repository === 'string'
+    && /github\.event\.pull_request\.head\.repo/i.test(repository);
+  if (!untrustedRef && !untrustedRepository) return null;
+
+  const protection = checkoutProtection(step);
+  if (protection.active) return null;
+
+  return {
+    line: step.uses.line,
+    path: normalizeSourcePath(step.with_?.path),
+    protection: protection.reason,
+  };
+}
+
+export function fetchesUntrustedPrCode(step) {
+  if (typeof step.run !== 'string') return false;
+  if (/\bgh\s+pr\s+(?:checkout|co)\b/i.test(step.run)) return true;
+  return /\bgit\s+fetch\b[\s\S]*(?:(?:refs\/)?pull\/|github\.event\.pull_request\.(?:head|number)|github\.head_ref)/i
+    .test(step.run);
 }
 
 /**
  * @param {import('../lib/parser.js').WorkflowDoc} workflow
  */
 export function check(workflow) {
-  if (!hasPullRequestTarget(workflow.on)) return [];
+  if (!hasTrigger(workflow.on, 'pull_request_target')) return [];
   const findings = [];
   for (const job of workflow.jobs) {
+    const untrustedSources = [];
+    let executed = false;
     for (const step of job.steps) {
-      if (checksOutHead(step)) {
+      const checkout = checkoutOfUntrustedPr(step);
+      if (checkout) {
+        untrustedSources.push(checkout);
+        continue;
+      }
+      if (fetchesUntrustedPrCode(step)) {
+        untrustedSources.push({
+          line: step.runLine || step.line,
+          path: '.',
+          protection: 'not-applicable-direct-fetch',
+        });
+        continue;
+      }
+      const untrustedSource = untrustedSources.find(source => (
+        executesWorkspace(step, { sourcePaths: [source.path] })
+      ));
+      if (untrustedSource) {
         findings.push({
           id,
           severity,
-          line: step.line,
-          fields: { type: id, sev: severity, job: job.name },
-          explain: 'avoid checking out PR head under pull_request_target - use pull_request, or split build/deploy',
+          line: step.runLine || step.line,
+          fields: {
+            type: id,
+            sev: severity,
+            job: job.name,
+            source_line: untrustedSource.line,
+            checkout_protection: untrustedSource.protection,
+          },
+          explain: remediation(untrustedSource.protection, true),
         });
+        executed = true;
+        break;
       }
     }
+    if (untrustedSources.length > 0 && !executed) {
+      const [untrustedSource] = untrustedSources;
+      findings.push({
+        id,
+        severity: 'high',
+        line: untrustedSource.line,
+        fields: {
+          type: id,
+          sev: 'high',
+          job: job.name,
+          source_line: untrustedSource.line,
+          stage: 'checkout-only',
+          checkout_protection: untrustedSource.protection,
+        },
+        explain: remediation(untrustedSource.protection, false),
+      });
+    }
   }
   return findings;
 }
+
+function remediation(protection, executed) {
+  if (protection === 'explicit-opt-out' || protection === 'dynamic-opt-out') {
+    return executed
+      ? 'remove `allow-unsafe-pr-checkout` and keep the built-in fork guard; run pull-request code under `pull_request`, or split untrusted build from privileged publication'
+      : 'remove `allow-unsafe-pr-checkout` unless this job only inspects data; if the opt-out is required, use a dedicated path, disable persisted credentials, minimize permissions and secrets, and never execute the checkout';
+  }
+  if (protection === 'unknown-or-unprotected-version') {
+    return executed
+      ? 'pin the full SHA of a current protected actions/checkout release, or run pull-request code under `pull_request` and keep privileged publication in a separate trusted job'
+      : 'pin the full SHA of a current protected actions/checkout release and avoid consuming the pull-request checkout in this privileged job';
+  }
+  return executed
+    ? 'do not fetch and execute pull-request code in a privileged `pull_request_target` job; use `pull_request` or split untrusted build from privileged publication'
+    : 'avoid fetching pull-request code in a privileged `pull_request_target` job; if inspection is required, isolate it as data with minimal permissions and no persisted credentials';
+}

package/src/rules/reusable-workflow-secrets.js

@@ -0,0 +1,32 @@
+export const id = 'reusable-workflow-secrets-inherit';
+export const severity = 'high';
+export const description = 'Cross-repository reusable workflow inherits every caller secret.';
+
+/**
+ * @param {import('../lib/parser.js').WorkflowDoc} workflow
+ */
+export function check(workflow) {
+  const findings = [];
+  for (const job of workflow.jobs) {
+    if (
+      job.uses?.kind !== 'reusable-workflow'
+      || job.secrets !== 'inherit'
+    ) {
+      continue;
+    }
+    findings.push({
+      id,
+      severity,
+      line: job.uses.line,
+      start: job.uses.start,
+      fields: {
+        type: id,
+        sev: severity,
+        job: job.name,
+        workflow: job.uses.raw,
+      },
+      explain: 'declare required names under the callee\'s `on.workflow_call.secrets`, then map only those secrets in this caller instead of using `inherit`',
+    });
+  }
+  return findings;
+}

package/src/rules/script-injection.js

@@ -9,16 +9,26 @@
 
 export const id = 'script-injection';
 export const severity = 'critical';
-export const description = 'Untrusted GitHub context interpolated into shell script.';
+export const description = 'Untrusted GitHub context is interpolated into run or github-script code.';
 
 const TAINTED_PATTERNS = [
   /github\.event\.issue\.(title|body)/i,
   /github\.event\.pull_request\.(title|body|head\.ref|head\.label)/i,
+  /github\.event\.pull_request\.head\.repo\.default_branch/i,
   /github\.event\.comment\.body/i,
   /github\.event\.review\.body/i,
+  /github\.event\.review_comment\.body/i,
   /github\.event\.discussion\.(title|body)/i,
-  /github\.event\.commits\.[\d*]+\.message/i,
-  /github\.event\.workflow_run\.head_branch/i,
+  /github\.event\.commits(?:\[[^\]]+\]|\.[\d*]+)\.message/i,
+  /github\.event\.commits(?:\[[^\]]+\]|\.[\d*]+)\.author\.(name|email)/i,
+  /github\.event\.head_commit\.message/i,
+  /github\.event\.head_commit\.author\.(name|email)/i,
+  /github\.event\.label\.name/i,
+  /github\.event\.milestone\.title/i,
+  /github\.event\.release\.(name|body|tag_name)/i,
+  /github\.event\.pages(?:\[[^\]]+\]|\.[\d*]+)\.page_name/i,
+  /github\.event\.workflow_run\.(display_title|head_branch)/i,
+  /github\.event\.workflow_run\.head_repository\.default_branch/i,
   /github\.head_ref/i,
 ];
 
@@ -28,29 +38,84 @@ const TAINTED_PATTERNS = [
  */
 function detectTaintedExpr(run) {
   if (typeof run !== 'string') return null;
-  for (const pat of TAINTED_PATTERNS) {
-    const m = run.match(new RegExp(`\\$\\{\\{[^}]*${pat.source}[^}]*\\}\\}`, 'i'));
-    if (m) return m[0];
+  for (const expression of expressionsIn(run)) {
+    for (const pat of TAINTED_PATTERNS) {
+      if (pat.test(expression)) return expression;
+    }
+  }
+  return null;
+}
+
+function detectTaintedEnvExpr(value, taintedKeys) {
+  if (typeof value !== 'string') return null;
+  for (const expression of expressionsIn(value)) {
+    for (const key of taintedKeys) {
+      const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const property = `env(?:\\.${escaped}|\\[\\s*['"]${escaped}['"]\\s*\\])`;
+      if (new RegExp(property, 'i').test(expression)) return { expression, key };
+    }
   }
   return null;
 }
 
+function expressionsIn(value) {
+  return value.match(/\$\{\{[\s\S]*?\}\}/g) ?? [];
+}
+
+function mergeTaintedEnv(inherited, env) {
+  const merged = new Set(inherited);
+  if (!env || typeof env !== 'object' || Array.isArray(env)) return merged;
+  for (const [key, value] of Object.entries(env)) {
+    merged.delete(key);
+    if (
+      detectTaintedExpr(value)
+      || detectTaintedEnvExpr(value, inherited)
+    ) merged.add(key);
+  }
+  return merged;
+}
+
 /**
  * @param {import('../lib/parser.js').WorkflowDoc} workflow
  */
 export function check(workflow) {
   const findings = [];
+  const workflowTaintedEnv = mergeTaintedEnv(new Set(), workflow.env);
   for (const job of workflow.jobs) {
+    const jobTaintedEnv = mergeTaintedEnv(workflowTaintedEnv, job.env);
     for (const step of job.steps) {
-      if (!step.run) continue;
-      const match = detectTaintedExpr(step.run);
-      if (match) {
+      const stepTaintedEnv = mergeTaintedEnv(jobTaintedEnv, step.env);
+      const sinks = [];
+      if (step.run) sinks.push({ kind: 'run', value: step.run, line: step.runLine || step.line });
+      if (
+        step.uses?.owner?.toLowerCase() === 'actions'
+        && step.uses?.repo?.toLowerCase() === 'github-script'
+        && typeof step.with_?.script === 'string'
+      ) {
+        sinks.push({ kind: 'github-script', value: step.with_.script, line: step.line });
+      }
+      for (const sink of sinks) {
+        const directMatch = detectTaintedExpr(sink.value);
+        const envMatch = directMatch
+          ? null
+          : detectTaintedEnvExpr(sink.value, stepTaintedEnv);
+        const match = directMatch ?? envMatch?.expression;
+        if (!match) continue;
         findings.push({
           id,
           severity,
-          line: step.line,
-          fields: { type: id, sev: severity, job: job.name, expr: match },
-          explain: 'move untrusted input through an env var and quote it in the script',
+          line: sink.line,
+          fields: {
+            type: id,
+            sev: severity,
+            job: job.name,
+            sink: sink.kind,
+            expr: match,
+            ...(envMatch ? { via_env: envMatch.key } : {}),
+          },
+          explain: sink.kind === 'github-script'
+            ? 'assign the expression to step-level `env`, then read it through `process.env`; do not interpolate `${{ }}` into the script body'
+            : 'assign the expression to step-level `env`, then read it with the shell\'s quoted variable syntax (for example, `"$VALUE"`), not `${{ env.VALUE }}`',
         });
       }
     }

package/src/rules/secrets-in-env.js

@@ -1,51 +1,134 @@
 /**
- * Rule: secrets exposed via env at workflow/job level leak to every step,
- * including third-party actions. Prefer step-scoped `env`.
+ * Rule: secrets exposed via env at workflow/job level are available to every
+ * step in that scope, including third-party actions. Prefer step-scoped `env`
+ * unless job scope is required for condition evaluation.
  */
 
 export const id = 'secrets-in-env';
-export const severity = 'critical';
-export const description = 'Secret is exposed broadly via workflow- or job-level env.';
-
-const SECRET_EXPR = /\$\{\{\s*secrets\./i;
+export const severity = 'medium';
+export const description = 'Workflow- or job-level env exposes secrets to unrelated steps.';
 
 /**
  * @param {unknown} env
- * @returns {string[]} keys that reference secrets
+ * @returns {Array<{key: string, exposure: 'named-secret'|'all-secrets'}>}
  */
 function secretKeys(env) {
   if (!env || typeof env !== 'object') return [];
   const out = [];
   for (const [key, val] of Object.entries(env)) {
-    if (typeof val === 'string' && SECRET_EXPR.test(val)) out.push(key);
+    if (typeof val !== 'string' || !containsSecretReference(val)) continue;
+    out.push({ key, exposure: secretExposure(val) });
   }
   return out;
 }
 
+function secretExposure(value) {
+  if (/\btoJSON\s*\(\s*secrets\s*\)/i.test(value)) return 'all-secrets';
+  if (/\bsecrets\s*\.\s*\*/i.test(value)) return 'all-secrets';
+  for (const match of value.matchAll(/\bsecrets\s*\[([^\]]+)\]/gi)) {
+    if (!/^\s*(['"])[A-Za-z_][A-Za-z0-9_]*\1\s*$/.test(match[1])) {
+      return 'all-secrets';
+    }
+  }
+  if (/\bsecrets\s*(?:[,)]|\}\})/i.test(withoutQuotedStrings(value))) {
+    return 'all-secrets';
+  }
+  return 'named-secret';
+}
+
+function containsSecretReference(value) {
+  const expressions = value.match(/\$\{\{[\s\S]*?\}\}/g) ?? [];
+  return expressions.some(expression => (
+    /\bsecrets\s*(?:\.|\[|[,)]|\}\})/i.test(withoutQuotedStrings(expression))
+  ));
+}
+
+function withoutQuotedStrings(value) {
+  let output = '';
+  let quote = null;
+  let escaped = false;
+  for (const char of value) {
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      output += ' ';
+    } else if (char === '\'' || char === '"') {
+      quote = char;
+      output += ' ';
+    } else {
+      output += char;
+    }
+  }
+  return output;
+}
+
 /**
  * @param {import('../lib/parser.js').WorkflowDoc} workflow
  */
 export function check(workflow) {
   const findings = [];
-  for (const key of secretKeys(workflow.env)) {
+  for (const { key, exposure } of secretKeys(workflow.env)) {
+    const findingSeverity = 'high';
     findings.push({
       id,
-      severity,
-      line: 1,
-      fields: { type: id, sev: severity, key, scope: 'workflow' },
-      explain: `secret ${key} is in workflow-level env - every step (including 3rd-party) can read it`,
+      severity: findingSeverity,
+      line: workflow.envLine || 1,
+      fields: {
+        type: id,
+        sev: findingSeverity,
+        key,
+        scope: 'workflow',
+        exposure,
+      },
+      explain: exposure === 'all-secrets'
+        ? `replace ${key} with explicit named secret references, then scope each reference to only the consuming step or action input; never serialize or dynamically index the secrets context`
+        : `move ${key} to step-level env or a supported action input so only the step that consumes it receives the secret`,
     });
   }
   for (const job of workflow.jobs) {
-    for (const key of secretKeys(job.env)) {
+    for (const { key, exposure } of secretKeys(job.env)) {
+      const findingSeverity = exposure === 'all-secrets' ? 'high' : severity;
       findings.push({
         id,
-        severity,
-        line: job.line,
-        fields: { type: id, sev: severity, key, scope: 'job', job: job.name },
-        explain: `secret ${key} is in job-level env for "${job.name}"`,
+        severity: findingSeverity,
+        line: job.envLine || job.line,
+        fields: {
+          type: id,
+          sev: findingSeverity,
+          key,
+          scope: 'job',
+          job: job.name,
+          exposure,
+        },
+        explain: exposure === 'all-secrets'
+          ? `replace ${key} with explicit named secret references, then scope each reference to only the consuming step or action input; never serialize or dynamically index the secrets context`
+          : `move ${key} to step-level env or an action input; if job scope is required for an if condition, keep every step in "${job.name}" trusted and minimize the secret's privileges`,
       });
     }
+    for (const step of job.steps) {
+      for (const { key, exposure } of secretKeys(step.env)) {
+        if (exposure !== 'all-secrets') continue;
+        findings.push({
+          id,
+          severity: 'high',
+          line: step.envLine || step.line,
+          fields: {
+            type: id,
+            sev: 'high',
+            key,
+            scope: 'step',
+            job: job.name,
+            exposure,
+          },
+          explain: `replace ${key} with explicit named secret references; dynamic indexing or toJSON(secrets) can expose every secret even when the env key is step-scoped`,
+        });
+      }
+    }
   }
   return findings;
 }

package/src/rules/unpinned-action.js

@@ -9,7 +9,7 @@ import { collectUses } from '../lib/parser.js';
 
 export const id = 'unpinned-action';
 export const severity = 'high';
-export const description = 'External action is not pinned to a commit SHA.';
+export const description = 'External action or reusable workflow is not pinned to a full commit SHA.';
 
 const SHA_RE = /^[0-9a-f]{40}$/i;
 
@@ -26,13 +26,14 @@ export function check(workflow) {
       id,
       severity,
       line: ref.line,
+      start: ref.start,
       fields: {
         type: id,
         sev: severity,
         action: ref.raw,
         ref: ref.ref ?? '',
       },
-      explain: `pin ${ref.owner}/${ref.repo} to a 40-char commit SHA - tags are mutable`,
+      explain: `replace the mutable ref in \`${ref.raw}\` with a reviewed full 40-character commit SHA, preserving any action or workflow subpath; retain the release tag as update metadata`,
     });
   }
   return findings;

package/src/rules/unpinned-container-image.js

@@ -0,0 +1,39 @@
+import { collectImages } from '../lib/parser.js';
+
+export const id = 'unpinned-container-image';
+export const severity = 'high';
+export const description = 'Job, service, or Docker action image is not pinned to a SHA-256 digest.';
+
+const DIGEST_RE = /@sha256:[0-9a-f]{64}$/i;
+
+/**
+ * @param {import('../lib/parser.js').WorkflowDoc} workflow
+ */
+export function check(workflow) {
+  const findings = [];
+  for (const image of collectImages(workflow)) {
+    const localDockerAction = image.context === 'docker-action'
+      && !image.raw.startsWith('/')
+      && /(?:^|\/)Dockerfile$/.test(image.raw);
+    if (DIGEST_RE.test(image.raw) || localDockerAction) {
+      continue;
+    }
+    findings.push({
+      id,
+      severity,
+      line: image.line,
+      start: image.start,
+      fields: {
+        type: id,
+        sev: severity,
+        image: image.raw,
+        context: image.context,
+        job: image.jobName,
+      },
+      explain: image.raw.includes('${{')
+        ? 'make every possible expression or matrix value an immutable image reference ending in `@sha256:<64-hex-digest>`'
+        : 'resolve the intended image from its trusted registry, then replace the tag with the verified `@sha256:<64-hex-digest>` reference',
+    });
+  }
+  return findings;
+}

package/src/rules/unpinned-docker-action.js

@@ -0,0 +1,30 @@
+import { collectUses } from '../lib/parser.js';
+
+export const id = 'unpinned-docker-action';
+export const severity = 'high';
+export const description = 'Docker action image is not pinned to a SHA-256 digest.';
+
+const DIGEST_RE = /@sha256:[0-9a-f]{64}$/i;
+
+/**
+ * @param {import('../lib/parser.js').WorkflowDoc} workflow
+ */
+export function check(workflow) {
+  const findings = [];
+  for (const { ref } of collectUses(workflow)) {
+    if (ref.kind !== 'docker' || DIGEST_RE.test(ref.raw)) continue;
+    findings.push({
+      id,
+      severity,
+      line: ref.line,
+      start: ref.start,
+      fields: {
+        type: id,
+        sev: severity,
+        image: ref.raw.slice('docker://'.length),
+      },
+      explain: 'resolve the intended image from its trusted registry, then replace the tag with the verified `@sha256:<64-hex-digest>` reference',
+    });
+  }
+  return findings;
+}