@secureci/cli 0.5.1 → 0.7.0

package/dist/parser/allow-comments.js

@@ -0,0 +1,113 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepAllowComments = stepAllowComments;
+const YAML = __importStar(require("yaml"));
+/** `# secureci-allow <rule>` with an optional `: <reason>`. */
+function directive(rule) {
+    const name = rule.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^#\\s*secureci-allow\\s+${name}(?=\\s|:|$)(?::(.*))?$`);
+}
+/** Source offset of every comment, mapped to its text (`# ...`). */
+function commentOffsets(content) {
+    const comments = new Map();
+    let offset = 0;
+    for (const token of new YAML.Lexer().lex(content)) {
+        const type = YAML.CST.tokenType(token);
+        if (type === 'comment')
+            comments.set(offset, token);
+        // Control tokens mark the parser's state; they aren't in the source.
+        if (type !== 'doc-mode' && type !== 'flow-error-end' && type !== 'scalar') {
+            offset += token.length;
+        }
+    }
+    return comments;
+}
+/**
+ * Steps carrying a `# secureci-allow <rule>: <reason>` comment, as
+ * `jobs.<id>.steps[<i>]` paths mapped to the reason ('' when it's missing).
+ * The comment goes at the end of the step's first line (`- uses: ...`) or
+ * on a line of its own directly above the step; comments separated by a
+ * blank line, or inside the step, don't count.
+ */
+function stepAllowComments(content, rule) {
+    const allowed = new Map();
+    const doc = YAML.parseDocument(content);
+    if (doc.errors.length > 0)
+        return allowed;
+    const jobs = doc.get('jobs');
+    if (!YAML.isMap(jobs))
+        return allowed;
+    const comments = commentOffsets(content);
+    const pattern = directive(rule);
+    const lineStart = (offset) => content.lastIndexOf('\n', offset - 1) + 1;
+    for (const pair of jobs.items) {
+        const steps = YAML.isMap(pair.value) ? pair.value.get('steps') : undefined;
+        if (!YAML.isSeq(steps))
+            continue;
+        steps.items.forEach((step, i) => {
+            if (!YAML.isNode(step) || !step.range)
+                return;
+            const start = step.range[0];
+            const lineEnd = content.indexOf('\n', start);
+            const texts = [];
+            for (const [offset, text] of comments) {
+                if (offset >= start && (lineEnd === -1 || offset < lineEnd)) {
+                    texts.push(text);
+                }
+            }
+            // Whole-line comments directly above the step.
+            let line = lineStart(start);
+            while (line > 0) {
+                const above = lineStart(line - 1);
+                const indent = content.slice(above, line).search(/\S/);
+                const text = indent === -1 ? undefined : comments.get(above + indent);
+                if (text === undefined)
+                    break;
+                texts.push(text);
+                line = above;
+            }
+            for (const text of texts) {
+                const match = pattern.exec(text.trimEnd());
+                if (match) {
+                    allowed.set(`jobs.${String(pair.key)}.steps[${i}]`, (match[1] ?? '').trim());
+                    break;
+                }
+            }
+        });
+    }
+    return allowed;
+}
+//# sourceMappingURL=allow-comments.js.map

package/dist/parser/dangerous-triggers.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowTriggers = workflowTriggers;
+exports.dangerousTriggerErrors = dangerousTriggerErrors;
+exports.forbiddenTriggerErrors = forbiddenTriggerErrors;
+const RULE = 'secureci/dangerous-trigger';
+/** The comment that downgrades a finding on a checkout step. */
+const ALLOW = '# secureci-allow dangerous-trigger';
+/**
+ * Triggers whose runs get the base repository's secrets and a read/write
+ * `GITHUB_TOKEN` even when the change came from a fork.
+ */
+const PRIVILEGED_TRIGGERS = ['pull_request_target', 'workflow_run'];
+/**
+ * Expressions (or literal refs) in `actions/checkout`'s `ref:` /
+ * `repository:` that select code the pull request's author controls,
+ * rather than the base branch.
+ */
+const UNTRUSTED_CHECKOUT = [
+    /github\.event\.pull_request\.head\.(sha|ref|repo\.full_name)\b/,
+    /github\.event\.pull_request\.merge_commit_sha\b/,
+    /github\.head_ref\b/,
+    /github\.event\.workflow_run\.head_(sha|branch|commit\.id|repository\.full_name)\b/,
+    /refs\/pull\//
+];
+/** A job `if:` that requires a maintainer-applied label to run. */
+const LABEL_GATE = /github\.event\.(pull_request\.labels|label\.name)\b/;
+/** The event names in `on:`, whichever form it takes (string, list or map). */
+function workflowTriggers(on) {
+    if (typeof on === 'string')
+        return [on];
+    if (Array.isArray(on)) {
+        return on.filter((t) => typeof t === 'string');
+    }
+    if (on && typeof on === 'object')
+        return Object.keys(on);
+    return [];
+}
+function isCheckout(step) {
+    return step.uses?.split('@')[0].toLowerCase() === 'actions/checkout';
+}
+/** `with.ref` / `with.repository` of a checkout that selects untrusted code. */
+function untrustedCheckoutInput(step) {
+    if (!isCheckout(step))
+        return undefined;
+    for (const key of ['ref', 'repository']) {
+        const value = step.with?.[key];
+        if (value === undefined)
+            continue;
+        if (UNTRUSTED_CHECKOUT.some((re) => re.test(String(value)))) {
+            return `${key}: ${String(value)}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether `actions/checkout` itself refuses the untrusted checkout: since
+ * June 2026 it won't check out a fork's code under these triggers unless
+ * `allow-unsafe-pr-checkout` is set. v7 has it, and floating major tags
+ * (`@v4`) and branches got it backported; SHA, minor or patch pins and v1
+ * did not.
+ */
+function checkoutProtection(step) {
+    const optOut = step.with?.['allow-unsafe-pr-checkout'];
+    if (String(optOut).toLowerCase() === 'true') {
+        return (`allow-unsafe-pr-checkout: true explicitly turns off actions/checkout's refusal to ` +
+            `check out a fork's code under these triggers`);
+    }
+    const version = step.uses?.split('@')[1];
+    if (version !== undefined &&
+        (/^[0-9a-f]{40}$/i.test(version) ||
+            /^v\d+\.\d+/.test(version) ||
+            /^v1$/.test(version))) {
+        return (`the safe default of actions/checkout does not apply to @${version} ` +
+            `(only v7, floating major tags like @v4 and branches have it), so the checkout succeeds`);
+    }
+    return (`actions/checkout refuses this checkout by default, so the step fails until someone ` +
+        `sets allow-unsafe-pr-checkout: true, which would run the fork's code`);
+}
+/** How a step would execute checked-out code, or undefined if it doesn't. */
+function executes(step) {
+    if (step.run)
+        return 'run:';
+    if (step.uses?.startsWith('./'))
+        return `uses: ${step.uses}`;
+    return undefined;
+}
+/**
+ * "Pwn request" detection (#46): a workflow triggered by
+ * `pull_request_target` or `workflow_run` runs with secrets and a write
+ * token, so a job that checks out the pull request's code and then runs
+ * it (a `run:` step or a local `./` action, both of which use the checked
+ * out files) lets a fork execute code with those privileges.
+ *
+ * - error: such a job (reported once, at its untrusted checkout).
+ * - warning: the same job when its `if:` requires a label, since a
+ *   maintainer must then approve each run.
+ * - warning: a privileged trigger with no such job, once per trigger, so
+ *   teams can audit it. Omitted when a job-level finding is reported, so
+ *   a workflow is never reported twice for the same problem.
+ *
+ * `allowed` maps checkout step paths with a `# secureci-allow
+ * dangerous-trigger: <reason>` comment to the reason (see
+ * stepAllowComments); a reason downgrades that job's error to a warning.
+ */
+function dangerousTriggerErrors(workflow, allowed = new Map()) {
+    const triggers = workflowTriggers(workflow.on).filter((t) => PRIVILEGED_TRIGGERS.includes(t));
+    if (triggers.length === 0)
+        return [];
+    const named = triggers.map((t) => `"${t}"`).join(', ');
+    const findings = [];
+    for (const [jobId, job] of Object.entries(workflow.jobs ?? {})) {
+        const steps = job.steps ?? [];
+        const checkoutIdx = steps.findIndex((s) => untrustedCheckoutInput(s));
+        if (checkoutIdx === -1)
+            continue;
+        const runIdx = steps.findIndex((s, i) => i > checkoutIdx && executes(s) !== undefined);
+        if (runIdx === -1)
+            continue;
+        const path = `jobs.${jobId}.steps[${checkoutIdx}]`;
+        const gated = LABEL_GATE.test(String(job.if ?? ''));
+        const reason = allowed.get(path);
+        findings.push({
+            path,
+            message: `Job "${jobId}" checks out untrusted code (${untrustedCheckoutInput(steps[checkoutIdx])}) ` +
+                `in a workflow triggered by ${named}, then executes it at steps[${runIdx}] (${executes(steps[runIdx])}). ` +
+                `These triggers run with the repository's secrets and a write token, so a fork can run its own code with them; ` +
+                `${checkoutProtection(steps[checkoutIdx])}` +
+                (gated
+                    ? `. The job is gated by a label check in its if:, so review the pull request's code before applying the label`
+                    : `. Check out the base ref instead, or move the build to an unprivileged pull_request workflow`) +
+                (reason
+                    ? `. Downgraded to a warning by "${ALLOW}" on this step: ${reason}`
+                    : reason === ''
+                        ? `. The "${ALLOW}" comment on this step needs a reason (${ALLOW}: <reason>) to downgrade this to a warning`
+                        : ''),
+            severity: gated || reason ? 'warning' : 'error',
+            rule: RULE
+        });
+    }
+    if (findings.length > 0)
+        return findings;
+    return triggers.map((trigger) => ({
+        path: `on.${trigger}`,
+        message: `Workflow is triggered by "${trigger}", which runs with the repository's secrets and a write token ` +
+            `even for ${trigger === 'workflow_run' ? 'runs started from a fork' : 'pull requests from forks'}; ` +
+            `make sure it never checks out or runs untrusted code`,
+        severity: 'warning',
+        rule: RULE
+    }));
+}
+/** Contract `forbidden-triggers`: one error per forbidden event in `on:`. */
+function forbiddenTriggerErrors(workflow, forbidden) {
+    return workflowTriggers(workflow.on)
+        .filter((t) => forbidden.includes(t))
+        .map((trigger) => ({
+        path: `on.${trigger}`,
+        message: `Trigger "${trigger}" is forbidden by the pipeline contract (forbidden-triggers)`,
+        severity: 'error',
+        rule: 'secureci/contract'
+    }));
+}
+//# sourceMappingURL=dangerous-triggers.js.map

package/dist/parser/injection.js

@@ -0,0 +1,281 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNTRUSTED_CONTEXTS = void 0;
+exports.workflowInjectionErrors = workflowInjectionErrors;
+exports.actionInjectionErrors = actionInjectionErrors;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const expression_1 = require("../runner/expression");
+const repository_1 = require("../utils/repository");
+const workflow_parser_1 = require("./workflow-parser");
+/**
+ * Contexts an outside contributor can set to arbitrary text (`*` matches
+ * any key or array index). Based on GitHub Security Lab's list of untrusted
+ * input (https://securitylab.github.com/resources/github-actions-untrusted-input/),
+ * which GitHub's security hardening guide and zizmor's template-injection
+ * audit also use, plus discussion text, PR/issue label names and the
+ * fields of `workflow_run` that come from the triggering branch.
+ *
+ * Inputs of `workflow_dispatch` / `workflow_call` (and the matching
+ * `github.event.inputs.*`) are untrusted too, except typed ones that can't
+ * hold arbitrary text; those are derived from each workflow's triggers.
+ */
+exports.UNTRUSTED_CONTEXTS = [
+    'github.head_ref',
+    'github.event.issue.title',
+    'github.event.issue.body',
+    'github.event.issue.labels.*.name',
+    'github.event.pull_request.title',
+    'github.event.pull_request.body',
+    'github.event.pull_request.labels.*.name',
+    'github.event.pull_request.head.ref',
+    'github.event.pull_request.head.label',
+    'github.event.pull_request.head.repo.default_branch',
+    'github.event.comment.body',
+    'github.event.review.body',
+    'github.event.discussion.title',
+    'github.event.discussion.body',
+    'github.event.pages.*.page_name',
+    'github.event.commits.*.message',
+    'github.event.commits.*.author.email',
+    'github.event.commits.*.author.name',
+    'github.event.commits.*.committer.email',
+    'github.event.commits.*.committer.name',
+    'github.event.head_commit.message',
+    'github.event.head_commit.author.email',
+    'github.event.head_commit.author.name',
+    'github.event.head_commit.committer.email',
+    'github.event.head_commit.committer.name',
+    'github.event.workflow_run.display_title',
+    'github.event.workflow_run.head_branch',
+    'github.event.workflow_run.head_commit.message',
+    'github.event.workflow_run.head_commit.author.email',
+    'github.event.workflow_run.head_commit.author.name',
+    'github.event.workflow_run.pull_requests.*.head.ref'
+];
+const BASE_PATTERNS = exports.UNTRUSTED_CONTEXTS.map((c) => c.split('.'));
+/** Input types whose values are constrained, so can't carry a payload. */
+const SAFE_INPUT_TYPES = new Set([
+    'boolean',
+    'number',
+    'choice',
+    'environment'
+]);
+const GITHUB_SCRIPT = /^actions\/github-script(@|$)/i;
+const RULE = 'secureci/injection';
+/** The inner text of every `${{ }}` in a string, as the runner finds them. */
+function expressionsIn(text) {
+    return [...text.matchAll(/\$\{\{([\s\S]*?)\}\}/g)].map((m) => m[1].trim());
+}
+/** Whether `prefix` matches the leading segments of `full`. */
+function startsWith(full, prefix) {
+    return (prefix.length <= full.length &&
+        prefix.every((seg, i) => seg === '*' || full[i] === '*' || seg === full[i]));
+}
+/**
+ * The untrusted context paths that reach an expression's result: a value
+ * at or below an untrusted path, or (via toJSON) a whole subtree that holds
+ * one. An expression GitHub couldn't parse has none.
+ */
+function untrustedSources(expr, patterns) {
+    const flow = (0, expression_1.expressionDataFlow)(expr);
+    if (!flow)
+        return [];
+    const hits = [
+        ...flow.values.filter((v) => patterns.some((p) => startsWith(v, p))),
+        ...flow.trees.filter((t) => patterns.some((p) => startsWith(t, p) || startsWith(p, t)))
+    ];
+    return [...new Set(hits.map((h) => h.join('.')))];
+}
+function isUntrusted(text, patterns) {
+    return expressionsIn(String(text)).some((expr) => untrustedSources(expr, patterns).length > 0);
+}
+/** `inputs.<name>` / `github.event.inputs.<name>` of string-typed inputs. */
+function workflowInputPatterns(on) {
+    if (!on || typeof on !== 'object' || Array.isArray(on))
+        return [];
+    const names = new Set();
+    for (const trigger of ['workflow_dispatch', 'workflow_call']) {
+        const spec = on[trigger];
+        for (const [name, input] of Object.entries(spec?.inputs ?? {})) {
+            const type = String(input?.type ?? 'string').toLowerCase();
+            if (!SAFE_INPUT_TYPES.has(type))
+                names.add(name.toLowerCase());
+        }
+    }
+    return [...names].flatMap((name) => [
+        ['inputs', name],
+        ['github', 'event', 'inputs', name]
+    ]);
+}
+/**
+ * `inputs.<name>` of a composite action's inputs that its caller fills
+ * with untrusted input (or whose default is untrusted, when not given).
+ */
+function compositeInputPatterns(action, given, callerPatterns) {
+    const patterns = [];
+    for (const [name, input] of Object.entries(action.inputs ?? {})) {
+        // Input names are case-insensitive.
+        const passed = Object.entries(given ?? {}).find(([key]) => key.toLowerCase() === name.toLowerCase());
+        const untrusted = passed
+            ? isUntrusted(passed[1], callerPatterns)
+            : input?.default !== undefined &&
+                isUntrusted(input.default, BASE_PATTERNS);
+        if (untrusted)
+            patterns.push(['inputs', name.toLowerCase()]);
+    }
+    return patterns;
+}
+/** An environment variable name to suggest for a context path. */
+function envName(source) {
+    // The first segment is a context name, so some segment isn't `*`.
+    const segment = source
+        .split('.')
+        .filter((s) => s !== '*')
+        .pop();
+    return segment.toUpperCase().replace(/[^A-Z0-9_]/g, '_');
+}
+function finding(expr, sources, kind, at) {
+    const name = envName(sources[0]);
+    const target = kind === 'run'
+        ? 'the shell script, so a crafted value can run arbitrary commands'
+        : 'the github-script code, so a crafted value can run arbitrary code';
+    const use = kind === 'run' ? `"$${name}"` : `process.env.${name}`;
+    return {
+        path: at,
+        message: `\${{ ${expr} }} expands untrusted input (${sources.join(', ')}) into ${target}. Pass it through env: (e.g. env: ${name}: \${{ ${expr} }}) and use ${use} instead.`,
+        severity: 'error',
+        rule: RULE
+    };
+}
+function checkText(text, kind, at, patterns, scan) {
+    for (const expr of expressionsIn(String(text))) {
+        const sources = untrustedSources(expr, patterns);
+        if (sources.length > 0)
+            scan.errors.push(finding(expr, sources, kind, at));
+    }
+}
+/** Parse a file reached by recursion, or null if it can't be. */
+function tryParse(file) {
+    try {
+        return (0, workflow_parser_1.parseFile)(file);
+    }
+    catch {
+        // Not this check's concern: validating that file reports it.
+        return null;
+    }
+}
+/** The action.yml behind a local `uses: ./path`, if there is one. */
+function resolveLocalAction(uses, root) {
+    const target = path.resolve(root, uses);
+    return [
+        target,
+        path.join(target, 'action.yml'),
+        path.join(target, 'action.yaml')
+    ].find((f) => fs.existsSync(f) && fs.statSync(f).isFile());
+}
+const isLocal = (uses) => uses.startsWith('./') || uses.startsWith('../');
+function checkSteps(steps, at, patterns, stack, scan) {
+    steps.forEach((step, i) => {
+        const stepPath = `${at}steps[${i}]`;
+        if (step.run !== undefined) {
+            checkText(step.run, 'run', `${stepPath}.run`, patterns, scan);
+        }
+        if (!step.uses)
+            return;
+        if (GITHUB_SCRIPT.test(step.uses) && step.with?.script !== undefined) {
+            checkText(step.with.script, 'script', `${stepPath}.with.script`, patterns, scan);
+        }
+        if (!isLocal(step.uses))
+            return;
+        const file = resolveLocalAction(step.uses, scan.root);
+        if (!file || stack.includes(file))
+            return;
+        const parsed = tryParse(file);
+        if (parsed?.type !== 'action')
+            return;
+        checkSteps(parsed.file.runs.steps ?? [], `${stepPath} > ${step.uses} > `, [
+            ...BASE_PATTERNS,
+            ...compositeInputPatterns(parsed.file, step.with, patterns)
+        ], [...stack, file], scan);
+    });
+}
+function checkWorkflow(workflow, file, at, stack, scan) {
+    const patterns = [...BASE_PATTERNS, ...workflowInputPatterns(workflow.on)];
+    for (const [jobId, job] of Object.entries(workflow.jobs)) {
+        if (!job.uses) {
+            checkSteps(job.steps ?? [], `${at}jobs.${jobId}.`, patterns, stack, scan);
+            continue;
+        }
+        if (!isLocal(job.uses))
+            continue;
+        // A local reusable workflow resolves against its caller's repository.
+        const called = path.resolve((0, repository_1.repositoryRoot)(file), job.uses);
+        if (stack.includes(called) || !fs.existsSync(called))
+            continue;
+        const parsed = tryParse(called);
+        if (parsed?.type !== 'workflow')
+            continue;
+        checkWorkflow(parsed.file, called, `${at}jobs.${jobId} > ${job.uses} > `, [...stack, called], scan);
+    }
+}
+/**
+ * Template injection in a workflow: an untrusted `${{ }}` expression (see
+ * UNTRUSTED_CONTEXTS) in a `run:` script or `actions/github-script`'s
+ * `with.script`. GitHub substitutes expressions into the script text before
+ * it runs, so such a value becomes code. `env:` values are not checked:
+ * passing data through the environment is the fix. Local composite
+ * actions and local reusable workflows are checked recursively.
+ */
+function workflowInjectionErrors(workflow, workflowPath) {
+    const file = path.resolve(workflowPath);
+    const scan = { root: (0, repository_1.repositoryRoot)(file), errors: [] };
+    checkWorkflow(workflow, file, '', [file], scan);
+    return scan.errors;
+}
+/**
+ * Template injection in a composite action's steps (see
+ * workflowInjectionErrors). Its own inputs aren't treated as untrusted
+ * here, since the callers are unknown; a workflow that passes untrusted
+ * input to a local action is checked through that call.
+ */
+function actionInjectionErrors(action, actionPath) {
+    const file = path.resolve(actionPath);
+    const scan = { root: (0, repository_1.repositoryRoot)(file), errors: [] };
+    checkSteps(action.runs?.steps ?? [], 'runs.', BASE_PATTERNS, [file], scan);
+    return scan.errors;
+}
+//# sourceMappingURL=injection.js.map