@secureci/cli 0.6.0 → 0.7.0

package/README.md

@@ -16,14 +16,16 @@ of [SecureCI](https://secure-ci.dev).
 
 A single CLI that understands GitHub Actions the way the runner does:
 
-- **Run workflows locally** — jobs in `needs:` order, matrix builds, reusable
-  workflows, composite / JavaScript / Docker actions, and the full
+- **Run workflows locally** — jobs in `needs:` order (independent jobs and
+  matrix combinations in parallel), matrix builds, reusable workflows, composite / JavaScript / Docker actions, and the full
   `${{ }}` / `if:` expression language.
 - **Validate** workflow and action files, flag **template injection**
-  (untrusted `${{ }}` input expanded into `run:` scripts) and over-broad
-  `GITHUB_TOKEN` permissions, and **check them against a pipeline contract**
-  (required/forbidden actions, ordering, minimum versions, SHA-pinning and
-  permissions rules).
+  (untrusted `${{ }}` input expanded into `run:` scripts), over-broad
+  `GITHUB_TOKEN` permissions and `pull_request_target` / `workflow_run` jobs
+  that run untrusted code (noting whether `actions/checkout`'s safe default
+  covers the checkout), and **check them against a pipeline contract**
+  (required/forbidden actions, ordering, minimum versions, SHA-pinning,
+  permissions, forbidden triggers and advisory severity rules).
 - **Inventory** every action a workflow pulls in, resolve each tag to a commit
   SHA, and **catch supply-chain drift** when a tag quietly starts pointing
   somewhere new.
@@ -235,9 +237,9 @@ the feature named, and none runs at install time.
 | Capability               | Where                                                                  | Why                                                                                                                                                                                       |
 | ------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Shell / process spawning | `run:` steps, JavaScript actions, `docker`/`podman`/`nerdctl`          | Runs workflow steps in a container (or on your host with `--container-runtime host`). `commander` also loads `child_process`, used only for executable subcommands this CLI does not use. |
-| Network                  | `github.com`, `api.github.com` (or the GHES host you set)              | Downloads actions and workflows, and resolves tags to commit SHAs.                                                                                                                        |
+| Network                  | `github.com`, `api.github.com` (or the GHES host you set)              | Downloads actions and workflows, resolves tags to commit SHAs, and looks up security advisories for the actions you use (skipped with `--offline`).                                       |
 | Environment variables    | `HOME`, `PATH`, `GITHUB_*`, `GITHUB_TOKEN`, `GH_TOKEN`                 | Builds the runner environment and authenticates GitHub downloads.                                                                                                                         |
-| Filesystem               | `~/.secureci/`, the working directory, temp dirs                       | Caches actions, stores artifacts and config, and reads your workflow files.                                                                                                               |
+| Filesystem               | `~/.secureci/`, the working directory, temp dirs                       | Caches actions and advisories, stores artifacts and config, and reads your workflow files.                                                                                                |
 | Hard-coded URLs          | GitHub documentation and JSON Schema URLs in messages and editor hints | Informational only; the CLI does not fetch them.                                                                                                                                          |
 
 No install scripts run for consumers. The published tarball contains only

package/dist/cli.js

@@ -795,13 +795,16 @@ async function validateFiles(files, contractFile, recurse, format, offline) {
         return;
     }
     for (const { file, result } of entries) {
-        if (result.valid) {
+        if (result.valid)
             logger_1.logger.success(`Validation passed: ${file}`);
-            result.errors.forEach((error) => logger_1.logger.warn(`  [${error.severity.toUpperCase()}] ${error.path}: ${error.message}`));
-        }
-        else {
+        else
             logger_1.logger.error(`Validation failed: ${file}`);
-            result.errors.forEach((error) => logger_1.logger.error(`  [${error.severity.toUpperCase()}] ${error.path}: ${error.message}`));
+        for (const error of result.errors) {
+            const line = `  [${error.severity.toUpperCase()}] ${error.path}: ${error.message}`;
+            if (error.severity === 'warning')
+                logger_1.logger.warn(line);
+            else
+                logger_1.logger.error(line);
         }
     }
     if (!allValid)

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

@@ -4,6 +4,8 @@ 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.
@@ -51,6 +53,30 @@ function untrustedCheckoutInput(step) {
     }
     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)
@@ -72,8 +98,12 @@ function executes(step) {
  * - 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) {
+function dangerousTriggerErrors(workflow, allowed = new Map()) {
     const triggers = workflowTriggers(workflow.on).filter((t) => PRIVILEGED_TRIGGERS.includes(t));
     if (triggers.length === 0)
         return [];
@@ -87,16 +117,24 @@ function dangerousTriggerErrors(workflow) {
         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: `jobs.${jobId}.steps[${checkoutIdx}]`,
+            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` +
+                `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`),
-            severity: gated ? 'warning' : 'error',
+                    : `. 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
         });
     }

package/dist/parser/validator.js

@@ -1,15 +1,50 @@
 "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.workflowExpressionErrors = workflowExpressionErrors;
 exports.actionExpressionErrors = actionExpressionErrors;
 exports.validateWorkflow = validateWorkflow;
 exports.mergeValidationResults = mergeValidationResults;
 exports.validateAction = validateAction;
+const fs = __importStar(require("fs"));
 const workflow_parser_1 = require("./workflow-parser");
 const expression_1 = require("../runner/expression");
 const injection_1 = require("./injection");
 const permissions_1 = require("./permissions");
 const dangerous_triggers_1 = require("./dangerous-triggers");
+const allow_comments_1 = require("./allow-comments");
 /**
  * Invalid `if:` expressions in a workflow: syntax errors, or contexts and
  * functions not available where they're used. GitHub rejects such a
@@ -126,7 +161,7 @@ function validateWorkflow(filePath) {
         errors.push(...workflowExpressionErrors(workflow));
         errors.push(...(0, injection_1.workflowInjectionErrors)(workflow, filePath));
         errors.push(...(0, permissions_1.workflowPermissionErrors)(workflow));
-        errors.push(...(0, dangerous_triggers_1.dangerousTriggerErrors)(workflow));
+        errors.push(...(0, dangerous_triggers_1.dangerousTriggerErrors)(workflow, (0, allow_comments_1.stepAllowComments)(fs.readFileSync(filePath, 'utf-8'), 'dangerous-trigger')));
     }
     catch (error) {
         errors.push({

package/dist/report.js

@@ -28,7 +28,8 @@ function jsonForFile(entry) {
         errors: entry.result.errors.map((e) => ({
             path: e.path,
             message: e.message,
-            severity: e.severity
+            severity: e.severity,
+            rule: ruleIdFor(e)
         }))
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secureci/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "SecureCI: validate, check against pipeline standards, and run GitHub Actions workflows locally",
   "main": "dist/index.js",
   "bin": {