actions-warden 0.2.0 → 0.3.0

package/src/commands/verify.js

@@ -0,0 +1,193 @@
+import { readFile } from 'node:fs/promises';
+import { parseWorkflowSource, collectUses } from '../lib/parser.js';
+import { resolveTargets } from '../lib/targets.js';
+import {
+  resolveRefToSha,
+  resolveToken,
+  verifyCommitInRepo,
+} from '../lib/resolver.js';
+import { readVersionComment } from '../lib/patcher.js';
+import { occurrenceId, canonicalPath } from '../lib/identity.js';
+import { format } from '../lib/formatter.js';
+import { mapLimit } from '../lib/concurrency.js';
+
+const SHA_RE = /^[0-9a-f]{40}$/i;
+
+export async function verify({ cwd = process.cwd(), workflows, token } = {}) {
+  const files = await resolveTargets({ workflows, cwd });
+  const resolvedToken = resolveToken(token);
+  const checks = [];
+  const warnings = [];
+  const errors = [];
+
+  for (const file of files) {
+    let source;
+    let workflow;
+    try {
+      source = await readFile(file, 'utf8');
+      workflow = parseWorkflowSource(source, file);
+    } catch (error) {
+      errors.push({ file, error: String(error.message ?? error) });
+      continue;
+    }
+
+    const refs = collectUses(workflow)
+      .map(item => item.ref)
+      .filter(ref => ref.kind === 'external' || ref.kind === 'reusable-workflow');
+    const results = await mapLimit(refs, 4, async ref => {
+      const id = occurrenceId({
+        kind: 'verify',
+        file,
+        cwd,
+        line: ref.line,
+        start: ref.start,
+        subject: ref.raw,
+      });
+      if (!ref.ref || !SHA_RE.test(ref.ref)) {
+        return { type: 'error', value: {
+          id,
+          file,
+          line: ref.line,
+          action: ref.raw,
+          error: 'reference is not pinned to a full commit SHA',
+        } };
+      }
+
+      try {
+        await verifyCommitInRepo({
+          owner: ref.owner,
+          repo: ref.repo,
+          sha: ref.ref,
+          token: resolvedToken,
+          cwd,
+        });
+        const version = readVersionComment(source, ref);
+        if (!version) {
+          const warning = {
+            id,
+            file,
+            line: ref.line,
+            action: ref.raw,
+            warning: 'pinned SHA has no actions-warden-ref version metadata',
+          };
+          return {
+            type: 'warning',
+            value: warning,
+            check: { id, file, line: ref.line, action: ref.raw, sha: ref.ref },
+          };
+        }
+        const expected = await resolveRefToSha({
+          owner: ref.owner,
+          repo: ref.repo,
+          ref: version,
+          token: resolvedToken,
+          cwd,
+        });
+        if (expected.sha.toLowerCase() !== ref.ref.toLowerCase()) {
+          throw new Error(`version metadata ${version} resolves to ${expected.sha}, not ${ref.ref}`);
+        }
+        return { type: 'check', value: {
+          id,
+          file,
+          line: ref.line,
+          action: `${ref.owner}/${ref.repo}${ref.subpath ? `/${ref.subpath}` : ''}`,
+          version,
+          sha: ref.ref.toLowerCase(),
+        } };
+      } catch (error) {
+        return { type: 'error', value: {
+          id,
+          file,
+          line: ref.line,
+          action: ref.raw,
+          error: String(error.message ?? error),
+        } };
+      }
+    });
+    for (const result of results) {
+      if (result.type === 'error') errors.push(result.value);
+      if (result.type === 'warning') {
+        warnings.push(result.value);
+        checks.push(result.check);
+      }
+      if (result.type === 'check') checks.push(result.value);
+    }
+  }
+
+  return {
+    files,
+    checks,
+    warnings,
+    errors,
+    status: errors.length === 0 ? 'OK' : 'FAIL',
+  };
+}
+
+export function renderVerify(result, { format: outputFormat, cwd = process.cwd() }) {
+  if (outputFormat === 'json') {
+    return format('json', [], {
+      status: result.status,
+      json: {
+        schemaVersion: '1.0',
+        files: result.files.map(file => canonicalPath(file, cwd)),
+        checks: result.checks.map(check => ({ ...check, file: canonicalPath(check.file, cwd) })),
+        warnings: result.warnings.map(warning => ({
+          ...warning,
+          file: canonicalPath(warning.file, cwd),
+        })),
+        errors: result.errors.map(error => ({
+          ...error,
+          file: error.file ? canonicalPath(error.file, cwd) : undefined,
+        })),
+        status: result.status,
+      },
+    });
+  }
+  const records = [];
+  for (const check of result.checks) {
+    records.push({
+      label: 'VERIFIED',
+      fields: {
+        id: check.id,
+        file: canonicalPath(check.file, cwd),
+        line: check.line,
+        action: check.action,
+        version: check.version,
+        sha: check.sha,
+      },
+    });
+  }
+  for (const warning of result.warnings) {
+    records.push({
+      label: 'WARNING',
+      fields: {
+        id: warning.id,
+        file: canonicalPath(warning.file, cwd),
+        line: warning.line,
+        action: warning.action,
+        msg: warning.warning,
+      },
+    });
+  }
+  for (const error of result.errors) {
+    records.push({
+      label: 'ERROR',
+      fields: {
+        id: error.id,
+        file: error.file ? canonicalPath(error.file, cwd) : undefined,
+        line: error.line,
+        action: error.action,
+        msg: error.error,
+      },
+    });
+  }
+  records.push({
+    label: 'SUMMARY',
+    fields: {
+      verified: result.checks.length,
+      warnings: result.warnings.length,
+      errors: result.errors.length,
+    },
+  });
+  return format(outputFormat, records, { status: result.status });
+}

package/src/index.js

@@ -3,17 +3,34 @@
  *
  * Each command can be invoked without spawning a subprocess:
  *
- *   import { audit, pin, upgrade, report } from 'actions-warden';
+ *   import { audit, pin, upgrade, report, scanOrganization } from 'actions-warden';
  *   const result = await audit({ cwd: '/repo' });
  */
 
-export { audit, renderAudit } from './commands/audit.js';
+export { audit, auditSources, renderAudit } from './commands/audit.js';
 export { pin, renderPin, rewriteUses } from './commands/pin.js';
 export { upgrade, renderUpgrade } from './commands/upgrade.js';
 export { report, renderReport } from './commands/report.js';
+export { verify, renderVerify } from './commands/verify.js';
+export { scanOrganization, renderOrganizationScan } from './commands/org-scan.js';
 export { listRules } from './rules/index.js';
-export { parseWorkflowFile, parseWorkflowSource, collectUses, parseActionRef } from './lib/parser.js';
-export { format, renderToon, renderJson, renderText, summarize, SEVERITY_ORDER } from './lib/formatter.js';
+export { parseWorkflowFile, parseWorkflowSource, collectUses, collectImages, parseActionRef } from './lib/parser.js';
+export { format, renderToon, renderJson, renderText, renderSarif, summarize, SEVERITY_ORDER } from './lib/formatter.js';
 export { discoverWorkflows } from './lib/paths.js';
 export { redact } from './lib/redact.js';
 export { parseIgnoreDirectives, isIgnored } from './lib/ignore.js';
+export { loadConfig, DEFAULT_CONFIG } from './lib/config.js';
+export {
+  fetchRepositoryWorkflowTree,
+  fetchRepositoryWorkflows,
+  isWorkflowPath,
+  listOrganizationRepositories,
+  MAX_REPOSITORY_WORKFLOW_BYTES,
+  MAX_WORKFLOW_BYTES,
+  MAX_WORKFLOW_FILES,
+} from './lib/github-org.js';
+export {
+  assignBaselineFingerprints,
+  loadBaseline,
+  serializeBaseline,
+} from './lib/baseline.js';

package/src/lib/action-status.js

@@ -0,0 +1,27 @@
+/**
+ * Decide whether the JavaScript Action step should fail. Findings can be
+ * advisory, but parse and resolution errors are always operational failures.
+ */
+export function shouldFailAction({ command, result, failOnFindings }) {
+  if (result.status !== 'FAIL') return false;
+  if (!['audit', 'report', 'org-scan'].includes(command)) return true;
+  if (hasOperationalFailure(command, result)) return true;
+  return failOnFindings;
+}
+
+function hasOperationalFailure(command, result) {
+  if (command === 'audit') {
+    return result.findings.some(finding => finding.ruleId === 'parse-error');
+  }
+  if (command === 'org-scan') {
+    return (
+      result.errors.length > 0
+      || result.findings.some(finding => finding.ruleId === 'parse-error')
+    );
+  }
+  return (
+    result.audit.findings.some(finding => finding.ruleId === 'parse-error')
+    || result.pin.errors.length > 0
+    || result.upgrade.errors.length > 0
+  );
+}

package/src/lib/agent-mode.js

@@ -0,0 +1,175 @@
+/**
+ * Explicit AI-agent execution defaults.
+ *
+ * There is no reliable cross-agent runtime signal, so callers opt in through
+ * `--agent-mode` or ACTIONS_WARDEN_MODE=agent. Organization artifact names are
+ * derived from the same identity used to validate resumable checkpoints.
+ */
+
+import { createHash } from 'node:crypto';
+import { lstat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { loadBaseline } from './baseline.js';
+import { loadConfig } from './config.js';
+import { format } from './formatter.js';
+import { createOrganizationCheckpointIdentity } from './org-checkpoint.js';
+import { RULES } from '../rules/index.js';
+
+export const AGENT_MODE_ENVIRONMENT_VARIABLE = 'ACTIONS_WARDEN_MODE';
+
+const ORGANIZATION_RE = /^[A-Za-z0-9_.-]+$/;
+const REPORT_EXTENSIONS = Object.freeze({
+  json: 'json',
+  sarif: 'sarif',
+  text: 'txt',
+  toon: 'toon',
+});
+
+/**
+ * Resolve explicit CLI precedence over the environment opt-in.
+ *
+ * @param {object} options
+ * @param {boolean} [options.optionValue]
+ * @param {string} [options.optionSource]
+ * @param {string} [options.environmentValue]
+ */
+export function resolveAgentMode({ optionValue, optionSource, environmentValue } = {}) {
+  if (optionSource === 'cli') return Boolean(optionValue);
+  if (environmentValue === undefined || environmentValue === '') return false;
+  if (environmentValue !== 'agent') {
+    throw new Error(`${AGENT_MODE_ENVIRONMENT_VARIABLE} must be "agent" when set`);
+  }
+  return true;
+}
+
+/**
+ * Build stable, scope-specific paths for an agent-initiated organization scan.
+ *
+ * @param {object} options
+ * @param {string} options.organization
+ * @param {string} options.cwd
+ * @param {string[]} [options.repositories]
+ * @param {'all'|'public'|'private'|'internal'} options.visibility
+ * @param {boolean} options.includeArchived
+ * @param {boolean} options.includeDisabled
+ * @param {boolean} options.includeForks
+ * @param {number} [options.maxRepositories]
+ * @param {'low'|'medium'|'high'|'critical'} [options.severity]
+ * @param {boolean} options.explain
+ * @param {string|false} [options.configPath]
+ * @param {string} [options.baseline]
+ * @param {'toon'|'json'|'text'|'sarif'} options.reportFormat
+ */
+export async function createOrganizationAgentArtifacts({
+  organization,
+  cwd,
+  repositories,
+  visibility,
+  includeArchived,
+  includeDisabled,
+  includeForks,
+  maxRepositories,
+  severity,
+  explain,
+  configPath,
+  baseline,
+  reportFormat,
+}) {
+  validateOrganization(organization);
+  const patterns = normalizePatterns(repositories);
+  const config = await loadConfig({
+    cwd,
+    path: configPath,
+    ruleIds: RULES.map(rule => rule.id),
+  });
+  const baselinePath = baseline ?? config.baseline;
+  const baselineData = baselinePath
+    ? await loadBaseline({ path: baselinePath, cwd })
+    : { path: null, ids: new Set(), fingerprints: new Set() };
+  const identity = createOrganizationCheckpointIdentity({
+    organization,
+    repositories: patterns,
+    visibility,
+    includeArchived,
+    includeDisabled,
+    includeForks,
+    maxRepositories,
+    severity,
+    explain,
+    config,
+    baselineData,
+  });
+  const key = createHash('sha256')
+    .update(JSON.stringify(identity))
+    .digest('hex')
+    .slice(0, 32);
+  const groupedKey = key.match(/.{8}/g).join('.');
+  const checkpointPath = `.actions-warden-agent.${groupedKey}.checkpoint.json`;
+  const reportExtension = REPORT_EXTENSIONS[reportFormat];
+  if (!reportExtension) throw new Error(`invalid agent report format: ${reportFormat}`);
+  const reportPath = `.actions-warden-agent.${groupedKey}.report.${reportExtension}`;
+
+  return {
+    checkpointPath,
+    reportPath,
+    resume: await pathExists(resolve(cwd, checkpointPath)),
+  };
+}
+
+/**
+ * Render the bounded stdout contract emitted after an agent-mode file report.
+ */
+export function renderOrganizationAgentReceipt({
+  result,
+  reportPath,
+  reportFormat,
+  checkpointPath,
+  resumed,
+}) {
+  return format('json', [], {
+    status: result.status,
+    json: {
+      schemaVersion: '1.0',
+      kind: 'actions-warden-agent-receipt',
+      command: 'org-scan',
+      organization: result.organization,
+      status: result.status,
+      summary: result.summary,
+      report: {
+        path: reportPath,
+        format: reportFormat,
+      },
+      checkpoint: {
+        path: checkpointPath,
+        resumed,
+      },
+    },
+  });
+}
+
+function validateOrganization(organization) {
+  if (
+    typeof organization !== 'string'
+    || !ORGANIZATION_RE.test(organization)
+    || organization === '.'
+    || organization === '..'
+  ) throw new Error('invalid organization');
+}
+
+function normalizePatterns(patterns) {
+  if (patterns === undefined) return [];
+  if (!Array.isArray(patterns) || patterns.some(pattern => typeof pattern !== 'string' || !pattern)) {
+    throw new Error('repository filters must be non-empty strings');
+  }
+  return [...new Set(patterns)];
+}
+
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}

package/src/lib/annotations.js

@@ -0,0 +1,250 @@
+/**
+ * Native GitHub Actions annotation support.
+ *
+ * This module stays independent of stdout and the Action runtime so collection,
+ * ordering, limits, and workflow-command encoding can be tested as pure logic.
+ */
+
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { listRules } from '../rules/index.js';
+import { redact } from './redact.js';
+
+const LEVEL_ORDER = new Map([
+  ['error', 0],
+  ['warning', 1],
+  ['notice', 2],
+]);
+const SEVERITY_ORDER = new Map([
+  ['critical', 0],
+  ['high', 1],
+  ['medium', 2],
+  ['low', 3],
+]);
+const RULE_DESCRIPTIONS = new Map(
+  listRules().map(rule => [rule.id, rule.description]),
+);
+
+/**
+ * @typedef {object} Annotation
+ * @property {'error'|'warning'|'notice'} level
+ * @property {string} title
+ * @property {string} message
+ * @property {string} [file]
+ * @property {number} [line]
+ * @property {number} [column]
+ * @property {string} [id]
+ * @property {'critical'|'high'|'medium'|'low'} [severity]
+ */
+
+/**
+ * Convert one command result into native annotation records.
+ *
+ * @param {object} input
+ * @param {string} input.command
+ * @param {object} input.result
+ * @param {string} [input.cwd]
+ * @returns {Annotation[]}
+ */
+export function collectAnnotations({ command, result, cwd = process.cwd() }) {
+  /** @type {Annotation[]} */
+  const annotations = [];
+  if (command === 'audit') {
+    annotations.push(...(result.findings ?? []).map(finding => (
+      findingAnnotation(finding, cwd)
+    )));
+  } else if (command === 'report') {
+    annotations.push(...(result.audit?.findings ?? []).map(finding => (
+      findingAnnotation(finding, cwd)
+    )));
+    annotations.push(...errorAnnotations('pin', result.pin?.errors, cwd));
+    annotations.push(...errorAnnotations('upgrade', result.upgrade?.errors, cwd));
+  } else if (command === 'org-scan') {
+    annotations.push(...(result.findings ?? []).map(finding => (
+      findingAnnotation({
+        ...finding,
+        file: undefined,
+        fields: {
+          ...finding.fields,
+          repository: finding.repository,
+          remote_path: finding.fields?.file,
+          source_url: finding.url,
+        },
+      }, cwd)
+    )));
+    annotations.push(...errorAnnotations('org-scan', result.errors, cwd));
+  } else if (command === 'verify') {
+    annotations.push(...(result.warnings ?? []).map(warning => ({
+      level: 'warning',
+      severity: 'medium',
+      title: 'actions-warden: verification warning',
+      message: diagnosticMessage(warning.warning, warning),
+      ...location(warning, cwd),
+      id: warning.id,
+    })));
+    annotations.push(...errorAnnotations('verify', result.errors, cwd));
+  } else if (command === 'pin' || command === 'upgrade') {
+    annotations.push(...errorAnnotations(command, result.errors, cwd));
+  }
+  return annotations.sort(compareAnnotations);
+}
+
+/**
+ * Apply a deterministic per-level cap.
+ *
+ * GitHub currently limits warning and error annotations per Action step. A
+ * matching notice cap keeps output bounded and predictable.
+ *
+ * @param {Annotation[]} annotations
+ * @param {number} [limitPerLevel]
+ */
+export function limitAnnotations(annotations, limitPerLevel = 10) {
+  const limit = Math.max(0, Math.min(10, Number.isInteger(limitPerLevel) ? limitPerLevel : 10));
+  const counts = new Map();
+  const emitted = [];
+  const omittedByLevel = { error: 0, warning: 0, notice: 0 };
+  for (const annotation of [...annotations].sort(compareAnnotations)) {
+    const count = counts.get(annotation.level) ?? 0;
+    if (count >= limit) {
+      omittedByLevel[annotation.level] += 1;
+      continue;
+    }
+    counts.set(annotation.level, count + 1);
+    emitted.push(annotation);
+  }
+  const omitted = Object.values(omittedByLevel).reduce((sum, count) => sum + count, 0);
+  return { emitted, omitted, omittedByLevel };
+}
+
+/**
+ * Encode annotations as GitHub workflow commands.
+ *
+ * @param {Annotation[]} annotations
+ */
+export function renderAnnotationCommands(annotations) {
+  if (annotations.length === 0) return '';
+  return annotations.map(annotation => {
+    const properties = [];
+    if (annotation.file) properties.push(`file=${escapeProperty(annotation.file)}`);
+    if (annotation.file && annotation.line) properties.push(`line=${annotation.line}`);
+    if (annotation.file && annotation.column) properties.push(`col=${annotation.column}`);
+    properties.push(`title=${escapeProperty(annotation.title)}`);
+    const suffix = properties.length > 0 ? ` ${properties.join(',')}` : '';
+    return `::${annotation.level}${suffix}::${escapeData(redact(annotation.message))}`;
+  }).join('\n') + '\n';
+}
+
+function findingAnnotation(finding, cwd) {
+  const severity = normalizeSeverity(finding.severity);
+  const description = finding.explain
+    || RULE_DESCRIPTIONS.get(finding.ruleId)
+    || 'GitHub Actions security finding.';
+  return {
+    level: annotationLevel(severity),
+    severity,
+    title: `actions-warden: ${finding.ruleId}`,
+    message: diagnosticMessage(description, {
+      ...finding.fields,
+      ruleId: finding.ruleId,
+      id: finding.id,
+    }),
+    ...location(finding, cwd),
+    id: finding.id,
+  };
+}
+
+function errorAnnotations(command, errors = [], cwd) {
+  return errors.map(error => ({
+    level: 'error',
+    severity: 'critical',
+    title: `actions-warden: ${command} error`,
+    message: diagnosticMessage(error.error, error),
+    ...location(error, cwd),
+    id: error.id,
+  }));
+}
+
+function diagnosticMessage(primary, diagnostic) {
+  const detailEntries = Object.entries(diagnostic ?? {})
+    .filter(([key, value]) => (
+      !['error', 'warning', 'explain', 'file', 'line', 'column', 'id'].includes(key)
+      && value !== null
+      && value !== undefined
+      && ['string', 'number', 'boolean'].includes(typeof value)
+    ))
+    .map(([key, value]) => `${key}=${String(value)}`);
+  const parts = [
+    String(primary || 'actions-warden reported a problem.'),
+    detailEntries.join(' '),
+    diagnostic?.id ? `[${diagnostic.id}]` : '',
+  ].filter(Boolean);
+  return truncate(parts.join(' '), 16_000);
+}
+
+function location(diagnostic, cwd) {
+  const file = normalizeFile(diagnostic?.file, cwd);
+  if (!file) return {};
+  const line = positiveInteger(diagnostic?.line) ?? 1;
+  const column = positiveInteger(diagnostic?.column);
+  return {
+    file,
+    line,
+    ...(column ? { column } : {}),
+  };
+}
+
+function normalizeFile(file, cwd) {
+  if (typeof file !== 'string' || file.length === 0 || file.includes('\0')) return undefined;
+  const root = resolve(cwd);
+  const absolute = resolve(root, file);
+  const rel = relative(root, absolute);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined;
+  return rel.split(/[\\/]/).join('/');
+}
+
+function normalizeSeverity(severity) {
+  return SEVERITY_ORDER.has(severity) ? severity : 'low';
+}
+
+function annotationLevel(severity) {
+  if (severity === 'critical' || severity === 'high') return 'error';
+  if (severity === 'medium') return 'warning';
+  return 'notice';
+}
+
+function compareAnnotations(a, b) {
+  return (LEVEL_ORDER.get(a.level) ?? 3) - (LEVEL_ORDER.get(b.level) ?? 3)
+    || (SEVERITY_ORDER.get(a.severity) ?? 4) - (SEVERITY_ORDER.get(b.severity) ?? 4)
+    || compareText(a.file, b.file)
+    || (a.line ?? 0) - (b.line ?? 0)
+    || compareText(a.title, b.title)
+    || compareText(a.id, b.id);
+}
+
+function compareText(a, b) {
+  const left = String(a ?? '');
+  const right = String(b ?? '');
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function positiveInteger(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : undefined;
+}
+
+function escapeData(value) {
+  return String(value)
+    .replaceAll('%', '%25')
+    .replaceAll('\r', '%0D')
+    .replaceAll('\n', '%0A');
+}
+
+function escapeProperty(value) {
+  return escapeData(value)
+    .replaceAll(':', '%3A')
+    .replaceAll(',', '%2C');
+}
+
+function truncate(value, maxLength) {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, maxLength - 1)}…`;
+}