actions-warden 0.1.0

package/src/rules/excessive-permissions.js

@@ -0,0 +1,79 @@
+/**
+ * Rule: workflows and jobs should not grant `write-all` or default-broad
+ * permissions when scoped tokens would suffice.
+ */
+
+export const id = 'excessive-permissions';
+export const severity = 'medium';
+export const description = 'Workflow or job grants overly broad 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',
+]);
+
+/**
+ * @param {unknown} permissions
+ * @returns {string|null}  - returns offending scope label, or null
+ */
+function inspect(permissions) {
+  if (permissions === undefined || permissions === null) {
+    return 'unset-default'; // GitHub default is permissive when not declared
+  }
+  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`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {import('../lib/parser.js').WorkflowDoc} workflow
+ */
+export function check(workflow) {
+  const findings = [];
+  const topScope = inspect(workflow.permissions);
+  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',
+    });
+  } else if (topScope) {
+    findings.push({
+      id,
+      severity,
+      line: 1,
+      fields: { type: id, sev: severity, scope: topScope, target: 'workflow' },
+      explain: `workflow grants ${topScope} - narrow to specific scopes`,
+    });
+  }
+  for (const job of workflow.jobs) {
+    const jobScope = inspect(job.permissions);
+    if (jobScope && jobScope !== 'unset-default') {
+      findings.push({
+        id,
+        severity,
+        line: job.line,
+        fields: { type: id, sev: severity, scope: jobScope, job: job.name },
+        explain: `job "${job.name}" grants ${jobScope}`,
+      });
+    }
+  }
+  return findings;
+}

package/src/rules/index.js

@@ -0,0 +1,18 @@
+/**
+ * Rule registry.
+ */
+
+import * as unpinned from './unpinned-action.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';
+
+export const RULES = [unpinned, perms, secrets, injection, prTarget];
+
+/**
+ * @returns {Array<{id: string, severity: string, description: string}>}
+ */
+export function listRules() {
+  return RULES.map(r => ({ id: r.id, severity: r.severity, description: r.description }));
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Rule: workflows triggered by `pull_request_target` that check out the PR
+ * head ref expose secrets to attacker-supplied code (pwn-request pattern).
+ */
+
+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;
+}
+
+function checksOutHead(step) {
+  if (!step.uses) return false;
+  if (step.uses.owner !== 'actions' || step.uses.repo !== 'checkout') return false;
+  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);
+}
+
+/**
+ * @param {import('../lib/parser.js').WorkflowDoc} workflow
+ */
+export function check(workflow) {
+  if (!hasPullRequestTarget(workflow.on)) return [];
+  const findings = [];
+  for (const job of workflow.jobs) {
+    for (const step of job.steps) {
+      if (checksOutHead(step)) {
+        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',
+        });
+      }
+    }
+  }
+  return findings;
+}

package/src/rules/script-injection.js

@@ -0,0 +1,59 @@
+/**
+ * Rule: attacker-controlled fields like `github.event.issue.title` interpolated
+ * directly into `run:` scripts allow arbitrary command execution.
+ *
+ * Safe pattern: pass through env vars and quote, e.g.
+ *   env: { TITLE: ${{ github.event.issue.title }} }
+ *   run: echo "$TITLE"
+ */
+
+export const id = 'script-injection';
+export const severity = 'critical';
+export const description = 'Untrusted GitHub context interpolated into shell script.';
+
+const TAINTED_PATTERNS = [
+  /github\.event\.issue\.(title|body)/i,
+  /github\.event\.pull_request\.(title|body|head\.ref|head\.label)/i,
+  /github\.event\.comment\.body/i,
+  /github\.event\.review\.body/i,
+  /github\.event\.discussion\.(title|body)/i,
+  /github\.event\.commits\.[\d*]+\.message/i,
+  /github\.event\.workflow_run\.head_branch/i,
+  /github\.head_ref/i,
+];
+
+/**
+ * @param {string} run
+ * @returns {string|null}
+ */
+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];
+  }
+  return null;
+}
+
+/**
+ * @param {import('../lib/parser.js').WorkflowDoc} workflow
+ */
+export function check(workflow) {
+  const findings = [];
+  for (const job of workflow.jobs) {
+    for (const step of job.steps) {
+      if (!step.run) continue;
+      const match = detectTaintedExpr(step.run);
+      if (match) {
+        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',
+        });
+      }
+    }
+  }
+  return findings;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Rule: secrets exposed via env at workflow/job level leak to every step,
+ * including third-party actions. Prefer step-scoped `env`.
+ */
+
+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;
+
+/**
+ * @param {unknown} env
+ * @returns {string[]} keys that reference 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);
+  }
+  return out;
+}
+
+/**
+ * @param {import('../lib/parser.js').WorkflowDoc} workflow
+ */
+export function check(workflow) {
+  const findings = [];
+  for (const key of secretKeys(workflow.env)) {
+    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`,
+    });
+  }
+  for (const job of workflow.jobs) {
+    for (const key of secretKeys(job.env)) {
+      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}"`,
+      });
+    }
+  }
+  return findings;
+}

package/src/rules/unpinned-action.js

@@ -0,0 +1,39 @@
+/**
+ * Rule: external action references must be pinned to a 40-character commit SHA.
+ *
+ * Tags like `v4` or `main` can be rewritten by repo owners (or attackers with
+ * write access), making them an unstable supply-chain link.
+ */
+
+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.';
+
+const SHA_RE = /^[0-9a-f]{40}$/i;
+
+/**
+ * @param {import('../lib/parser.js').WorkflowDoc} workflow
+ * @returns {Array<{id: string, severity: string, line: number, fields: object, explain: string}>}
+ */
+export function check(workflow) {
+  const findings = [];
+  for (const { ref } of collectUses(workflow)) {
+    if (ref.kind !== 'external' && ref.kind !== 'reusable-workflow') continue;
+    if (ref.ref && SHA_RE.test(ref.ref)) continue;
+    findings.push({
+      id,
+      severity,
+      line: ref.line,
+      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`,
+    });
+  }
+  return findings;
+}