actions-warden 0.1.0

package/src/commands/audit.js

@@ -0,0 +1,161 @@
+/**
+ * Audit command - scan workflows for security findings.
+ *
+ * Programmatic API:
+ *   const result = await audit({ cwd, workflows, severity, explain });
+ *   result.findings: Finding[]
+ *   result.summary:  { files, findings, critical, high, medium, low }
+ *   result.status:   'OK' | 'FAIL'
+ *
+ * A finding looks like:
+ *   { id, ruleId, severity, file, line, fields, explain }
+ */
+
+import { createHash } from 'node:crypto';
+import { parseWorkflowFile } from '../lib/parser.js';
+import { discoverWorkflows, resolveWorkflowArg } from '../lib/paths.js';
+import { format, summarize, SEVERITY_ORDER } from '../lib/formatter.js';
+import { parseIgnoreDirectives, isIgnored } from '../lib/ignore.js';
+import { RULES } from '../rules/index.js';
+
+/**
+ * @typedef {object} Finding
+ * @property {string} id           - unique id (sha1 short)
+ * @property {string} ruleId
+ * @property {string} severity
+ * @property {string} file
+ * @property {number} line
+ * @property {Record<string, unknown>} fields
+ * @property {string} explain
+ */
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string[]} [opts.workflows]      - explicit file/glob args
+ * @param {'low'|'medium'|'high'|'critical'} [opts.severity]  - minimum severity
+ * @param {boolean} [opts.explain]
+ * @returns {Promise<{findings: Finding[], summary: object, status: 'OK'|'FAIL', files: string[]}>}
+ */
+export async function audit({ cwd = process.cwd(), workflows, severity, explain = false } = {}) {
+  const files = await resolveTargets(workflows, cwd);
+  /** @type {Finding[]} */
+  const findings = [];
+  for (const file of files) {
+    let doc;
+    try {
+      doc = await parseWorkflowFile(file);
+    } catch (err) {
+      findings.push({
+        id: shortId(`parse:${file}`),
+        ruleId: 'parse-error',
+        severity: 'high',
+        file,
+        line: 0,
+        fields: { type: 'parse-error', sev: 'high', file },
+        explain: String(err.message ?? err),
+      });
+      continue;
+    }
+    const ignore = parseIgnoreDirectives(doc.source);
+    for (const rule of RULES) {
+      const ruleFindings = rule.check(doc);
+      for (const f of ruleFindings) {
+        if (isIgnored(ignore, f.line, rule.id)) continue;
+        const finding = {
+          id: shortId(`${rule.id}:${file}:${f.line}:${JSON.stringify(f.fields)}`),
+          ruleId: rule.id,
+          severity: f.severity,
+          file,
+          line: f.line,
+          fields: { ...f.fields, file: relPath(file, cwd) },
+          explain: f.explain,
+        };
+        findings.push(finding);
+      }
+    }
+  }
+  const filtered = filterBySeverity(findings, severity);
+  const counts = summarize(filtered);
+  const status = filtered.length === 0 ? 'OK' : 'FAIL';
+  return {
+    files,
+    findings: explain ? filtered : filtered.map(stripExplain),
+    summary: { files: files.length, findings: filtered.length, ...counts },
+    status,
+  };
+}
+
+function stripExplain(f) {
+  const { explain: _unused, ...rest } = f;
+  return rest;
+}
+
+/**
+ * @param {string[]|undefined} workflows
+ * @param {string} cwd
+ */
+async function resolveTargets(workflows, cwd) {
+  if (!workflows || workflows.length === 0) {
+    return discoverWorkflows({ cwd });
+  }
+  const out = new Set();
+  for (const w of workflows) {
+    const files = await resolveWorkflowArg(w, cwd);
+    for (const f of files) out.add(f);
+  }
+  return [...out].sort();
+}
+
+/**
+ * @param {Finding[]} findings
+ * @param {string|undefined} min
+ */
+function filterBySeverity(findings, min) {
+  if (!min) return findings;
+  const minIdx = SEVERITY_ORDER.indexOf(min);
+  if (minIdx === -1) return findings;
+  return findings.filter(f => SEVERITY_ORDER.indexOf(f.severity) >= minIdx);
+}
+
+function shortId(input) {
+  return createHash('sha1').update(input).digest('hex').slice(0, 10);
+}
+
+function relPath(p, cwd) {
+  if (p.startsWith(cwd)) return p.slice(cwd.length + 1);
+  return p;
+}
+
+/**
+ * Render an audit result to the chosen format.
+ *
+ * @param {Awaited<ReturnType<typeof audit>>} result
+ * @param {{format: 'toon'|'json'|'text', explain?: boolean, cwd?: string}} opts
+ */
+export function renderAudit(result, opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  if (opts.format === 'json') {
+    return format('json', [], {
+      status: result.status,
+      json: {
+        files: result.files.map(f => relPath(f, cwd)),
+        findings: result.findings.map(f => ({ ...f, file: relPath(f.file, cwd) })),
+        summary: result.summary,
+        status: result.status,
+      },
+    });
+  }
+  /** @type {Array<{label: string, fields: Record<string, unknown>}>} */
+  const records = [];
+  for (const f of result.files) {
+    records.push({ label: 'SCAN', fields: { file: relPath(f, opts.cwd ?? process.cwd()) } });
+  }
+  for (const finding of result.findings) {
+    const fields = { id: finding.id, ...finding.fields, line: finding.line };
+    if (opts.explain) fields.explain = finding.explain;
+    records.push({ label: 'FINDING', fields });
+  }
+  records.push({ label: 'SUMMARY', fields: result.summary });
+  return format(opts.format, records, { status: result.status });
+}

package/src/commands/pin.js

@@ -0,0 +1,199 @@
+/**
+ * Pin command - rewrite tag-based `uses:` refs to immutable commit SHAs.
+ *
+ * Format: `uses: owner/repo@<sha>  # <original-ref>`
+ *
+ * The original tag is preserved as an inline comment so upgrades can find
+ * the human-readable version later.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { parseWorkflowSource, collectUses } from '../lib/parser.js';
+import { discoverWorkflows, resolveWorkflowArg } from '../lib/paths.js';
+import { resolveRefToSha, resolveToken } from '../lib/resolver.js';
+import { writeFileGuarded } from '../lib/writer.js';
+import { parseIgnoreDirectives, isIgnored } from '../lib/ignore.js';
+import { format } from '../lib/formatter.js';
+
+const SHA_RE = /^[0-9a-f]{40}$/i;
+
+/**
+ * @typedef {object} PinChange
+ * @property {string} id
+ * @property {string} file
+ * @property {string} action        - owner/repo
+ * @property {string} fromRef
+ * @property {string} toSha
+ * @property {number} line
+ * @property {'tag'|'branch'|'commit'} refType
+ */
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string[]} [opts.workflows]
+ * @param {boolean} [opts.dryRun]
+ * @param {string} [opts.token]
+ * @param {string} [opts.fix]            - finding/change id to apply (skip others)
+ * @returns {Promise<{changes: PinChange[], errors: object[], status: 'OK'|'FAIL'}>}
+ */
+export async function pin({ cwd = process.cwd(), workflows, dryRun = true, token, fix } = {}) {
+  const files = await resolveTargets(workflows, cwd);
+  const tok = resolveToken(token);
+  /** @type {PinChange[]} */
+  const changes = [];
+  const errors = [];
+
+  for (const file of files) {
+    let source;
+    try {
+      source = await readFile(file, 'utf8');
+    } catch (err) {
+      errors.push({ file, error: String(err.message ?? err) });
+      continue;
+    }
+    let doc;
+    try {
+      doc = parseWorkflowSource(source, file);
+    } catch (err) {
+      errors.push({ file, error: String(err.message ?? err) });
+      continue;
+    }
+    /** @type {Array<{ref: import('../lib/parser.js').ActionRef, sha: string, type: string}>} */
+    const planned = [];
+    const ignore = parseIgnoreDirectives(source);
+    for (const { ref } of collectUses(doc)) {
+      if (ref.kind !== 'external' && ref.kind !== 'reusable-workflow') continue;
+      if (!ref.ref || SHA_RE.test(ref.ref)) continue;
+      if (isIgnored(ignore, ref.line, 'unpinned-action')) continue;
+      try {
+        const resolved = await resolveRefToSha({
+          owner: ref.owner,
+          repo: ref.repo,
+          ref: ref.ref,
+          token: tok,
+          cwd,
+        });
+        planned.push({ ref, sha: resolved.sha, type: resolved.type });
+      } catch (err) {
+        errors.push({ file, action: ref.raw, error: String(err.message ?? err) });
+      }
+    }
+    if (planned.length === 0) continue;
+
+    let newSource = source;
+    for (const { ref, sha, type } of planned) {
+      const change = {
+        id: changeId(file, ref.raw),
+        file,
+        action: `${ref.owner}/${ref.repo}${ref.subpath ? `/${ref.subpath}` : ''}`,
+        fromRef: ref.ref,
+        toSha: sha,
+        line: ref.line,
+        refType: type,
+      };
+      if (fix && fix !== change.id) continue;
+      newSource = rewriteUses(newSource, ref, sha);
+      changes.push(change);
+    }
+    if (newSource !== source) {
+      await writeFileGuarded({ path: file, content: newSource, dryRun, cwd });
+    }
+  }
+  return { changes, errors, status: errors.length === 0 ? 'OK' : 'FAIL' };
+}
+
+/**
+ * Replace `uses: owner/repo[/sub]@<ref>` with the pinned SHA + comment.
+ *
+ * Operates on the source string; preserves quoting and whitespace.
+ *
+ * @param {string} source
+ * @param {import('../lib/parser.js').ActionRef} ref
+ * @param {string} sha
+ * @returns {string}
+ */
+export function rewriteUses(source, ref, sha) {
+  const left = ref.subpath ? `${ref.owner}/${ref.repo}/${ref.subpath}` : `${ref.owner}/${ref.repo}`;
+  const escLeft = escapeRegExp(left);
+  const escRef = escapeRegExp(ref.ref);
+  // Match: optional quote, owner/repo[/sub]@ref, optional quote, optional comment.
+  const re = new RegExp(
+    `(uses\\s*:\\s*['"]?)${escLeft}@${escRef}(['"]?)([^\\n]*)`,
+    'g',
+  );
+  return source.replace(re, (_, prefix, closingQuote, trailing) => {
+    const tail = stripExistingVersionComment(trailing);
+    return `${prefix}${left}@${sha}${closingQuote}${tail} # ${ref.ref}`;
+  });
+}
+
+function stripExistingVersionComment(trailing) {
+  // Remove any existing inline comment so we don't stack `# v3 # v3`.
+  const idx = trailing.indexOf('#');
+  if (idx === -1) return trailing;
+  return trailing.slice(0, idx).replace(/\s+$/, '');
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function changeId(file, raw) {
+  return createHash('sha1').update(`pin:${file}:${raw}`).digest('hex').slice(0, 10);
+}
+
+async function resolveTargets(workflows, cwd) {
+  if (!workflows || workflows.length === 0) return discoverWorkflows({ cwd });
+  const out = new Set();
+  for (const w of workflows) {
+    for (const f of await resolveWorkflowArg(w, cwd)) out.add(f);
+  }
+  return [...out].sort();
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof pin>>} result
+ * @param {{format: 'toon'|'json'|'text', dryRun: boolean, cwd?: string}} opts
+ */
+export function renderPin(result, opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  if (opts.format === 'json') {
+    return format('json', [], {
+      status: result.status,
+      json: {
+        dryRun: opts.dryRun,
+        changes: result.changes.map(c => ({ ...c, file: rel(c.file, cwd) })),
+        errors: result.errors,
+        status: result.status,
+      },
+    });
+  }
+  const records = [];
+  for (const c of result.changes) {
+    records.push({
+      label: 'PIN',
+      fields: {
+        id: c.id,
+        file: rel(c.file, cwd),
+        line: c.line,
+        action: c.action,
+        from: c.fromRef,
+        to: c.toSha,
+        kind: c.refType,
+        applied: !opts.dryRun,
+      },
+    });
+  }
+  for (const e of result.errors) {
+    records.push({ label: 'ERROR', fields: { file: rel(e.file ?? '', cwd), action: e.action ?? '', msg: e.error } });
+  }
+  records.push({ label: 'SUMMARY', fields: { changes: result.changes.length, errors: result.errors.length, dry_run: opts.dryRun } });
+  return format(opts.format, records, { status: result.status });
+}
+
+function rel(p, cwd) {
+  if (p && p.startsWith(cwd)) return p.slice(cwd.length + 1);
+  return p;
+}

package/src/commands/report.js

@@ -0,0 +1,93 @@
+/**
+ * Report command - runs audit + dry-run pin + dry-run upgrade and produces
+ * a combined view. Useful for "what would change?" review and LLM prompting.
+ */
+
+import { audit } from './audit.js';
+import { pin } from './pin.js';
+import { upgrade } from './upgrade.js';
+import { format } from '../lib/formatter.js';
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.cwd]
+ * @param {string[]} [opts.workflows]
+ * @param {string} [opts.token]
+ * @param {'major'|'minor'|'patch'} [opts.mode]
+ * @param {boolean} [opts.skipResolve]   - when true, skip pin/upgrade (offline mode)
+ */
+export async function report({
+  cwd = process.cwd(),
+  workflows,
+  token,
+  mode = 'minor',
+  skipResolve = false,
+  minAgeDays = 7,
+} = {}) {
+  const auditResult = await audit({ cwd, workflows, explain: true });
+  let pinResult = { changes: [], errors: [], status: 'OK' };
+  let upgradeResult = { changes: [], errors: [], skipped: [], status: 'OK' };
+  if (!skipResolve) {
+    pinResult = await pin({ cwd, workflows, dryRun: true, token });
+    upgradeResult = await upgrade({ cwd, workflows, dryRun: true, token, mode, minAgeDays });
+  }
+  const status = [auditResult.status, pinResult.status, upgradeResult.status].includes('FAIL')
+    ? 'FAIL' : 'OK';
+  return { audit: auditResult, pin: pinResult, upgrade: upgradeResult, status };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof report>>} result
+ * @param {{format: 'toon'|'json'|'text', mode: string, cwd?: string}} opts
+ */
+export function renderReport(result, opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  if (opts.format === 'json') {
+    return format('json', [], {
+      status: result.status,
+      json: {
+        audit: { files: result.audit.files.map(f => rel(f, cwd)), findings: result.audit.findings, summary: result.audit.summary },
+        pin: { changes: result.pin.changes.map(c => ({ ...c, file: rel(c.file, cwd) })) },
+        upgrade: { changes: result.upgrade.changes.map(c => ({ ...c, file: rel(c.file, cwd) })), mode: opts.mode },
+        status: result.status,
+      },
+    });
+  }
+  const records = [];
+  for (const finding of result.audit.findings) {
+    records.push({
+      label: 'FINDING',
+      fields: {
+        id: finding.id,
+        ...finding.fields,
+        line: finding.line,
+        explain: finding.explain,
+      },
+    });
+  }
+  for (const c of result.pin.changes) {
+    records.push({ label: 'PIN', fields: { id: c.id, file: rel(c.file, cwd), action: c.action, from: c.fromRef, to: c.toSha } });
+  }
+  for (const c of result.upgrade.changes) {
+    records.push({ label: 'UPGRADE', fields: { id: c.id, file: rel(c.file, cwd), action: c.action, from: c.fromVersion ?? c.fromRef, to: c.toTag, level: c.level } });
+  }
+  records.push({
+    label: 'SUMMARY',
+    fields: {
+      files: result.audit.summary.files,
+      findings: result.audit.summary.findings,
+      critical: result.audit.summary.critical,
+      high: result.audit.summary.high,
+      medium: result.audit.summary.medium,
+      low: result.audit.summary.low,
+      pins: result.pin.changes.length,
+      upgrades: result.upgrade.changes.length,
+    },
+  });
+  return format(opts.format, records, { status: result.status });
+}
+
+function rel(p, cwd) {
+  if (p && p.startsWith(cwd)) return p.slice(cwd.length + 1);
+  return p;
+}