continuous-improvement 3.17.0 → 3.18.0

package/bin/audit-actions.mjs

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+/**
+ * audit-actions — static GitHub Actions security scanner.
+ *
+ * Portfolio-spine train (docs/plans/2026-07-04-portfolio-spine.md).
+ *
+ * Scans `.github/workflows/*.yml|*.yaml` for the mechanical subset of the
+ * checks in templates/actions_security_checklist.md:
+ *
+ *   (a) missing explicit `permissions:` at workflow AND job level  -> high
+ *   (b) `permissions: write-all`                                   -> high
+ *   (c) `uses: owner/repo@ref` not pinned to a 40-hex commit SHA   -> medium
+ *       (first-party actions/* github/* not SHA-pinned             -> low)
+ *   (d) job missing `timeout-minutes`                              -> medium
+ *   (e) push/schedule-triggered workflow without `concurrency:`
+ *       at the workflow level or on every job                      -> low
+ *   (f) `${{ github.event.* }}` / `${{ github.head_ref }}` in run: -> high
+ *   (g) pull_request_target/issue_comment/issues trigger combined
+ *       with secrets.* usage or write permissions                  -> high
+ *
+ * Zero runtime dependencies: the YAML handling is hand-rolled, line-oriented
+ * parsing of the constrained GitHub-workflow YAML subset (indentation-based
+ * key detection). Its limits — naive comment stripping, shallow flow-style
+ * parsing, no anchors/aliases, block scalars tracked for run: only — are
+ * documented in docs/plans/2026-07-04-portfolio-spine.md. Constructs the
+ * parser does not understand produce no findings (false negatives over
+ * false positives); the checklist template is the human layer on top.
+ *
+ * Usage:
+ *   node bin/audit-actions.mjs [--repo <path>] [--out <file>] [--strict]
+ *     --repo <path>  repository root to scan (default ".")
+ *     --out <file>   markdown report path (default "reports/actions-security.md")
+ *     --strict       exit 1 when any high-severity finding exists
+ *     --help         print usage
+ *
+ * Exit codes: 0 scan completed; 1 --strict with high findings; 2 repo root
+ * not found (fail closed — a typo'd --repo must never pass a security gate).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { argv, exit } from "node:process";
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+const SHA_PIN = /^[0-9a-f]{40}$/;
+const DANGEROUS_TRIGGERS = ["pull_request_target", "issue_comment", "issues"];
+const CONCURRENCY_TRIGGERS = ["push", "schedule"];
+const UNTRUSTED_INTERPOLATION = /\$\{\{\s*github\.(?:event\.|head_ref\b)/;
+const SECRETS_INTERPOLATION = /\$\{\{\s*secrets\./;
+const REMEDIATION = {
+    "missing-permissions": "Declare explicit `permissions:` (default `contents: read`) at the workflow level; add write scopes per-job only where provably needed.",
+    "write-all-permissions": "Replace `write-all` with the minimal named scopes each job needs.",
+    "unpinned-third-party-action": "Pin third-party actions to a full 40-hex commit SHA — tags and branches are mutable.",
+    "unpinned-first-party-action": "Pin first-party actions to a full commit SHA, or at minimum a major version tag.",
+    "missing-timeout": "Add `timeout-minutes:` to the job to cap runaway or hung runs.",
+    "missing-concurrency": "Add a `concurrency:` block with a stable group key so overlapping runs cancel or queue.",
+    "untrusted-input-in-run": "Pass untrusted event text through `env:` and reference it as a quoted shell variable; never interpolate `${{ github.event.* }}` or `${{ github.head_ref }}` directly into `run:`.",
+    "dangerous-trigger-with-secrets": "Workflows on pull_request_target/issue_comment/issues run with attacker-influenced input; drop secrets/write tokens from them or add a maintainer-approval gate.",
+};
+/** Strip a trailing comment, tracking single/double quotes so `#` inside a quoted scalar survives. */
+export function stripComment(line) {
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === "'" && !inDouble)
+            inSingle = !inSingle;
+        else if (ch === '"' && !inSingle)
+            inDouble = !inDouble;
+        else if (ch === "#" && !inSingle && !inDouble) {
+            if (i === 0 || line[i - 1] === " " || line[i - 1] === "\t") {
+                return line.slice(0, i).trimEnd();
+            }
+        }
+    }
+    return line;
+}
+function indentOf(line) {
+    let n = 0;
+    while (n < line.length && line[n] === " ")
+        n++;
+    return n;
+}
+function unquote(value) {
+    const v = value.trim();
+    if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+/** Trigger names from an inline `on:` value — scalar (`push`) or flow list (`[push, schedule]`). */
+function parseInlineTriggers(value) {
+    const v = value.trim();
+    if (v.startsWith("[")) {
+        return v
+            .replace(/^\[/, "")
+            .replace(/\]$/, "")
+            .split(",")
+            .map((t) => unquote(t))
+            .filter((t) => t !== "");
+    }
+    return v === "" ? [] : [unquote(v)];
+}
+/**
+ * Parse one workflow into the facts the checks need. Line-oriented,
+ * indentation-based; see the module header for the documented subset limits.
+ */
+export function parseWorkflow(content) {
+    const parsed = {
+        triggers: [],
+        onLine: 1,
+        hasWorkflowPermissions: false,
+        hasConcurrency: false,
+        hasWritePermission: false,
+        writeAllLines: [],
+        usesSecrets: false,
+        usesRefs: [],
+        runInterpolationLines: [],
+        jobs: [],
+    };
+    const lines = content.split(/\r?\n/);
+    let topKey = "";
+    let onNestedIndent = -1;
+    let jobNameIndent = -1;
+    let jobPropIndent = -1;
+    let currentJob = null;
+    let permBlockIndent = -1; // inside a permissions: block (workflow or job level)
+    let runBlockIndent = -1; // inside a run: | block scalar
+    for (let i = 0; i < lines.length; i++) {
+        const raw = stripComment(lines[i] ?? "");
+        if (raw.trim() === "")
+            continue;
+        const lineNo = i + 1;
+        const indent = indentOf(raw);
+        let text = raw.trim();
+        if (SECRETS_INTERPOLATION.test(raw))
+            parsed.usesSecrets = true;
+        if (runBlockIndent >= 0) {
+            if (indent > runBlockIndent) {
+                if (UNTRUSTED_INTERPOLATION.test(raw))
+                    parsed.runInterpolationLines.push(lineNo);
+                continue;
+            }
+            runBlockIndent = -1;
+        }
+        if (permBlockIndent >= 0 && indent <= permBlockIndent)
+            permBlockIndent = -1;
+        if (permBlockIndent >= 0 && /:\s*(write|write-all)\s*$/.test(text)) {
+            parsed.hasWritePermission = true;
+            if (/write-all\s*$/.test(text))
+                parsed.writeAllLines.push(lineNo);
+            continue;
+        }
+        // Normalize step-item lines ("- uses: x", "- run: y") to key/value form.
+        const isListItem = text.startsWith("- ");
+        if (isListItem)
+            text = text.slice(2).trim();
+        const keyMatch = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(text);
+        if (indent === 0 && keyMatch && !isListItem) {
+            topKey = keyMatch[1];
+            const value = keyMatch[2].trim();
+            onNestedIndent = -1;
+            if (topKey === "on") {
+                parsed.onLine = lineNo;
+                parsed.triggers.push(...parseInlineTriggers(value));
+            }
+            else if (topKey === "permissions") {
+                parsed.hasWorkflowPermissions = true;
+                notePermissionsValue(parsed, value, lineNo);
+                if (value === "")
+                    permBlockIndent = indent;
+            }
+            else if (topKey === "concurrency") {
+                parsed.hasConcurrency = true;
+            }
+            else if (topKey === "jobs") {
+                jobNameIndent = -1;
+                jobPropIndent = -1;
+            }
+            continue;
+        }
+        if (topKey === "on" && keyMatch && !isListItem) {
+            if (onNestedIndent === -1)
+                onNestedIndent = indent;
+            if (indent === onNestedIndent)
+                parsed.triggers.push(keyMatch[1]);
+            continue;
+        }
+        if (topKey !== "jobs" || !keyMatch)
+            continue;
+        // First nested key under jobs: fixes the job-name indent level.
+        if (jobNameIndent === -1 && !isListItem)
+            jobNameIndent = indent;
+        if (indent === jobNameIndent && !isListItem && keyMatch[2].trim() === "") {
+            currentJob = { name: keyMatch[1], line: lineNo, hasPermissions: false, hasTimeout: false, hasConcurrency: false, isReusableCall: false };
+            parsed.jobs.push(currentJob);
+            jobPropIndent = -1;
+            continue;
+        }
+        if (currentJob === null)
+            continue;
+        if (jobPropIndent === -1 && indent > jobNameIndent && !isListItem)
+            jobPropIndent = indent;
+        const key = keyMatch[1];
+        const value = keyMatch[2].trim();
+        const isJobProp = indent === jobPropIndent && !isListItem;
+        if (isJobProp && key === "permissions") {
+            currentJob.hasPermissions = true;
+            notePermissionsValue(parsed, value, lineNo);
+            if (value === "")
+                permBlockIndent = indent;
+            continue;
+        }
+        if (isJobProp && key === "timeout-minutes") {
+            currentJob.hasTimeout = true;
+            continue;
+        }
+        if (isJobProp && key === "concurrency") {
+            currentJob.hasConcurrency = true;
+            continue;
+        }
+        if (key === "uses") {
+            if (isJobProp)
+                currentJob.isReusableCall = true;
+            parsed.usesRefs.push({ line: lineNo, spec: unquote(value) });
+            continue;
+        }
+        if (key === "run") {
+            if (/^[|>][+-]?\d*$/.test(value)) {
+                runBlockIndent = indent;
+            }
+            else if (UNTRUSTED_INTERPOLATION.test(value)) {
+                parsed.runInterpolationLines.push(lineNo);
+            }
+        }
+    }
+    return parsed;
+}
+/** Record write-all / inline write scopes from a `permissions:` value. */
+function notePermissionsValue(parsed, value, lineNo) {
+    if (value === "")
+        return;
+    if (/^["']?write-all["']?$/.test(value)) {
+        parsed.hasWritePermission = true;
+        parsed.writeAllLines.push(lineNo);
+    }
+    else if (/:\s*write\b/.test(value)) {
+        // Inline flow map, e.g. permissions: {contents: write}
+        parsed.hasWritePermission = true;
+    }
+}
+function checkFile(file) {
+    const w = parseWorkflow(file.content);
+    const findings = [];
+    const add = (line, severity, check, message) => {
+        findings.push({ file: file.path, line, severity, check, message, remediation: REMEDIATION[check] ?? "" });
+    };
+    // (a) permissions absent everywhere
+    if (!w.hasWorkflowPermissions && !w.jobs.some((j) => j.hasPermissions)) {
+        add(1, "high", "missing-permissions", "No explicit `permissions:` at the workflow level or on any job — the workflow runs with the default token grant.");
+    }
+    // (b) write-all
+    for (const line of w.writeAllLines) {
+        add(line, "high", "write-all-permissions", "`permissions: write-all` grants every scope to the workflow token.");
+    }
+    // (c) unpinned uses references
+    for (const ref of w.usesRefs) {
+        const finding = classifyUsesRef(ref);
+        if (finding)
+            add(ref.line, finding.severity, finding.check, finding.message);
+    }
+    // (d) missing timeout-minutes per job (reusable-workflow call jobs excluded)
+    for (const job of w.jobs) {
+        if (!job.isReusableCall && !job.hasTimeout) {
+            add(job.line, "medium", "missing-timeout", `Job \`${job.name}\` has no \`timeout-minutes\`.`);
+        }
+    }
+    // (e) push/schedule without concurrency — satisfied by a workflow-level
+    // block, or by every job declaring its own job-level concurrency.
+    const everyJobHasConcurrency = w.jobs.length > 0 && w.jobs.every((j) => j.hasConcurrency);
+    if (!w.hasConcurrency && !everyJobHasConcurrency && w.triggers.some((t) => CONCURRENCY_TRIGGERS.includes(t))) {
+        add(w.onLine, "low", "missing-concurrency", "Workflow is triggered by push/schedule but declares no `concurrency:` block.");
+    }
+    // (f) untrusted interpolation inside run:
+    for (const line of w.runInterpolationLines) {
+        add(line, "high", "untrusted-input-in-run", "Untrusted event text (`github.event.*` / `github.head_ref`) is interpolated directly into a `run:` shell command.");
+    }
+    // (g) dangerous trigger combined with secrets or write permissions
+    const dangerous = w.triggers.filter((t) => DANGEROUS_TRIGGERS.includes(t));
+    if (dangerous.length > 0 && (w.usesSecrets || w.hasWritePermission)) {
+        add(w.onLine, "high", "dangerous-trigger-with-secrets", `Trigger \`${dangerous.join("`, `")}\` is combined with ${w.usesSecrets ? "secrets access" : "write permissions"}.`);
+    }
+    return findings;
+}
+function classifyUsesRef(ref) {
+    const spec = ref.spec;
+    if (spec === "" || spec.startsWith("./") || spec.startsWith("docker://"))
+        return null;
+    const m = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)(?:\/[^@]*)?(?:@(.+))?$/.exec(spec);
+    if (!m)
+        return null;
+    const owner = m[1];
+    const gitRef = m[3] ?? "";
+    if (SHA_PIN.test(gitRef))
+        return null;
+    const firstParty = owner === "actions" || owner === "github";
+    if (firstParty) {
+        return {
+            severity: "low",
+            check: "unpinned-first-party-action",
+            message: `First-party action \`${spec}\` is not pinned to a commit SHA.`,
+        };
+    }
+    return {
+        severity: "medium",
+        check: "unpinned-third-party-action",
+        message: `Third-party action \`${spec}\` is not pinned to a 40-hex commit SHA.`,
+    };
+}
+/**
+ * Pure scanner: workflow files in, deterministic findings out.
+ * Sorted by file path, then line, then severity, then check id.
+ */
+export function auditWorkflows(files) {
+    const findings = [];
+    for (const file of [...files].sort((a, b) => a.path.localeCompare(b.path))) {
+        findings.push(...checkFile(file));
+    }
+    return findings.sort((a, b) => a.file.localeCompare(b.file) ||
+        a.line - b.line ||
+        SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] ||
+        a.check.localeCompare(b.check));
+}
+/** Markdown report: summary table on top, findings grouped per workflow file. */
+export function renderReport(findings, opts = {}) {
+    const scanned = opts.scannedFiles ?? [...new Set(findings.map((f) => f.file))].sort();
+    const counts = { high: 0, medium: 0, low: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    const out = [];
+    out.push("# GitHub Actions security audit");
+    out.push("");
+    out.push(`Scanned ${scanned.length} workflow file(s). Checks and remediation follow templates/actions_security_checklist.md.`);
+    out.push("");
+    out.push("## Summary");
+    out.push("");
+    out.push("| Severity | Count |");
+    out.push("|---|---|");
+    out.push(`| high | ${counts.high} |`);
+    out.push(`| medium | ${counts.medium} |`);
+    out.push(`| low | ${counts.low} |`);
+    out.push("");
+    if (findings.length === 0) {
+        out.push("No findings. All scanned workflows pass the mechanical checks.");
+        out.push("");
+        return out.join("\n");
+    }
+    const byFile = new Map();
+    for (const f of findings) {
+        const list = byFile.get(f.file) ?? [];
+        list.push(f);
+        byFile.set(f.file, list);
+    }
+    for (const [file, list] of byFile) {
+        out.push(`## ${file}`);
+        out.push("");
+        out.push("| Severity | Line | Finding | Remediation |");
+        out.push("|---|---|---|---|");
+        for (const f of list) {
+            out.push(`| ${f.severity} | ${f.line} | ${f.message} | ${f.remediation} |`);
+        }
+        out.push("");
+    }
+    return out.join("\n");
+}
+function listWorkflowFiles(repoRoot) {
+    const dir = join(repoRoot, ".github", "workflows");
+    if (!existsSync(dir))
+        return [];
+    const files = [];
+    for (const entry of readdirSync(dir).sort()) {
+        if (!entry.endsWith(".yml") && !entry.endsWith(".yaml"))
+            continue;
+        files.push({
+            path: `.github/workflows/${entry}`,
+            content: readFileSync(join(dir, entry), "utf8"),
+        });
+    }
+    return files;
+}
+const USAGE = `Usage: node bin/audit-actions.mjs [--repo <path>] [--out <file>] [--strict]
+
+  --repo <path>  repository root to scan (default ".")
+  --out <file>   markdown report path (default "reports/actions-security.md")
+  --strict       exit 1 when any high-severity finding exists
+  --help         print this usage
+
+Exit codes: 0 scan completed; 1 --strict with high findings; 2 repo root not found.
+`;
+function main() {
+    const args = argv.slice(2);
+    if (args.includes("--help")) {
+        console.log(USAGE);
+        return 0;
+    }
+    const repoIdx = args.indexOf("--repo");
+    const outIdx = args.indexOf("--out");
+    const repoRoot = repoIdx >= 0 ? (args[repoIdx + 1] ?? ".") : ".";
+    const outPath = outIdx >= 0 ? (args[outIdx + 1] ?? "reports/actions-security.md") : "reports/actions-security.md";
+    const strict = args.includes("--strict");
+    // Fail closed: a typo'd --repo (or wrong CWD) must not report a clean scan.
+    if (!existsSync(repoRoot)) {
+        console.error(`audit-actions: repo root not found: ${repoRoot}`);
+        return 2;
+    }
+    const workflowsDir = join(repoRoot, ".github", "workflows");
+    if (!existsSync(workflowsDir)) {
+        console.log(`audit-actions: no workflows directory at ${workflowsDir} — scanning zero workflow files.`);
+    }
+    const files = listWorkflowFiles(repoRoot);
+    const findings = auditWorkflows(files);
+    const report = renderReport(findings, { scannedFiles: files.map((f) => f.path) });
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, report);
+    const high = findings.filter((f) => f.severity === "high").length;
+    console.log(`audit-actions: ${files.length} workflow file(s), ${findings.length} finding(s) (${high} high).`);
+    console.log(`Report written to ${outPath}`);
+    if (strict && high > 0)
+        return 1;
+    return 0;
+}
+const invokedDirectly = argv[1]?.endsWith("audit-actions.mjs");
+if (invokedDirectly) {
+    exit(main());
+}

package/bin/check-command-count.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Command Count Check
+ *
+ * The README "## Slash commands" section is hand-maintained: a fenced list of
+ * `/command  description` lines plus "All N commands" / "All N ship" count
+ * claims. The skill count is guarded (check-skill-count, check-skill-count-prose)
+ * but the command count was not — it silently drifted to "18" while 28 commands
+ * shipped (reconciled by hand in PR #263). This lint locks the README list and
+ * its count claims to the actual shipped command set so the drift cannot recur.
+ *
+ * Source of truth: `commands/*.md` (flat source, excluding README.md) — the set
+ * a contributor edits when adding a command. `npm run build` mirrors it into the
+ * bundle and `verify:everything-mirror` already guarantees parity.
+ *
+ * The check asserts, against the README "## Slash commands" section:
+ *   1. set parity — the fenced `/command` lines equal the commands/*.md set
+ *      (reports `missing` = shipped-but-unlisted, `extra` = listed-but-unshipped)
+ *   2. count claims — every "All N commands" / "All N ship" number equals the
+ *      actual command count
+ *
+ * Fail-closed: a missing section, an empty list, or a missing count claim each
+ * produce a violation rather than a silent pass.
+ *
+ * Usage:
+ *   node bin/check-command-count.mjs              # Check the current repo
+ *   node bin/check-command-count.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — README lists every shipped command and every count claim matches
+ *   1 — at least one command missing/extra, or a count claim is stale/missing
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const COMMANDS_DIR = "commands";
+const README = "README.md";
+export function listCommandFiles(repoRoot) {
+    return readdirSync(join(repoRoot, COMMANDS_DIR))
+        .filter((f) => f.endsWith(".md") && f !== "README.md")
+        .map((f) => f.slice(0, -3))
+        .sort();
+}
+export function parseReadmeSlashCommands(content) {
+    // Locate the "## Slash commands" section: from its heading to the next H2 (or EOF).
+    const heading = /^##\s+Slash commands\s*$/im.exec(content);
+    if (!heading)
+        return { hasSection: false, listed: [], counts: [] };
+    const rest = content.slice(heading.index + heading[0].length);
+    const nextH2 = /^##\s+/m.exec(rest);
+    const section = nextH2 ? rest.slice(0, nextH2.index) : rest;
+    // Listed commands: lines that begin with "/<name>" at column 0 (the fenced list).
+    const listed = [...section.matchAll(/^\/([a-z][a-z0-9-]*)/gm)].map((m) => m[1]);
+    // Count claims: "All N commands" / "All N ship".
+    const counts = [...section.matchAll(/All (\d+) (?:commands|ship)/g)].map((m) => Number(m[1]));
+    return { hasSection: true, listed, counts };
+}
+export function findViolations(actualNames, parsed) {
+    if (!parsed.hasSection) {
+        return ["README has no '## Slash commands' section — cannot verify the command list."];
+    }
+    const violations = [];
+    if (parsed.listed.length === 0) {
+        violations.push("the '## Slash commands' section lists no commands (expected the fenced /command block).");
+    }
+    const actual = new Set(actualNames);
+    const listed = new Set(parsed.listed);
+    for (const name of actualNames) {
+        if (!listed.has(name))
+            violations.push(`missing: /${name} ships in commands/ but is not listed in the README.`);
+    }
+    for (const name of parsed.listed) {
+        if (!actual.has(name))
+            violations.push(`extra: /${name} is listed in the README but has no commands/${name}.md.`);
+    }
+    if (parsed.counts.length === 0) {
+        violations.push("no 'All N commands' count claim found in the section.");
+    }
+    for (const n of parsed.counts) {
+        if (n !== actualNames.length) {
+            violations.push(`count claim states ${n} but commands/ ships ${actualNames.length}.`);
+        }
+    }
+    return violations;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const actual = listCommandFiles(repoRoot);
+    let content;
+    try {
+        content = readFileSync(join(repoRoot, README), "utf8");
+    }
+    catch {
+        console.error(`FAIL command-count: cannot read ${README} at ${repoRoot}.`);
+        exit(1);
+    }
+    const parsed = parseReadmeSlashCommands(content);
+    const violations = findViolations(actual, parsed);
+    if (violations.length === 0) {
+        console.log(`OK command-count: README lists all ${actual.length} command(s) and every count claim matches commands/.`);
+        exit(0);
+    }
+    console.error(`FAIL command-count: ${violations.length} issue(s) between the README "Slash commands" section and commands/.`);
+    console.error("");
+    for (const v of violations)
+        console.error(`  ${v}`);
+    console.error("");
+    console.error("Fix: update the README '## Slash commands' fenced list and its 'All N commands' / 'All N ship' counts to match commands/*.md.");
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-command-count.mjs")) {
+    main();
+}