@secureci/cli 0.5.0 → 0.6.0

package/dist/parser/pipeline-contract-parser.js

@@ -36,6 +36,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parsePipelineContract = parsePipelineContract;
 const fs = __importStar(require("fs"));
 const YAML = __importStar(require("yaml"));
+const permissions_1 = require("./permissions");
+const advisories_1 = require("../advisories");
 /**
  * Parse a pipeline contract file (`secureci validate --contract <file>`).
  *
@@ -48,6 +50,10 @@ const YAML = __importStar(require("yaml"));
  *   - uses: org/deploy
  * forbidden:
  *   - uses: org/legacy-deploy
+ * forbidden-triggers:
+ *   - pull_request_target
+ * advisories:
+ *   fail-on: high      # critical | high (default) | medium | low
  * ```
  */
 function parsePipelineContract(filePath) {
@@ -111,11 +117,75 @@ function parsePipelineContract(filePath) {
             result.lockfile.required = lockfile.required;
         }
     }
+    if (spec.permissions !== undefined) {
+        result.permissions = parsePermissionsPolicy(spec.permissions);
+    }
+    if (spec.advisories !== undefined) {
+        if (typeof spec.advisories !== 'object' ||
+            spec.advisories === null ||
+            Array.isArray(spec.advisories)) {
+            throw new Error('Contract "advisories" must be a mapping');
+        }
+        const advisories = spec.advisories;
+        result.advisories = {};
+        if (advisories['fail-on'] !== undefined) {
+            const level = String(advisories['fail-on']).toLowerCase();
+            if (!advisories_1.FAIL_ON_LEVELS.includes(level)) {
+                throw new Error(`Contract "advisories.fail-on" must be one of ${advisories_1.FAIL_ON_LEVELS.join(', ')}, got "${String(advisories['fail-on'])}"`);
+            }
+            result.advisories.failOn = level;
+        }
+    }
     if (spec['allowed-owners'] !== undefined) {
         result.allowedOwners = parseStringList(spec['allowed-owners'], 'allowed-owners');
     }
+    if (spec['forbidden-triggers'] !== undefined) {
+        result.forbiddenTriggers = parseStringList(spec['forbidden-triggers'], 'forbidden-triggers');
+    }
     return result;
 }
+const isMapping = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * ```yaml
+ * permissions:
+ *   required: true          # every workflow (or job) declares permissions
+ *   max: { contents: read } # ceiling for workflow-level permissions
+ * ```
+ */
+function parsePermissionsPolicy(value) {
+    if (!isMapping(value)) {
+        throw new Error('Contract "permissions" must be a mapping');
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== 'required' && key !== 'max') {
+            throw new Error(`Contract "permissions" has an unknown key "${key}" (expected "required" or "max")`);
+        }
+    }
+    const policy = {};
+    if (value.required !== undefined) {
+        if (typeof value.required !== 'boolean') {
+            throw new Error('Contract "permissions.required" must be true or false');
+        }
+        policy.required = value.required;
+    }
+    if (value.max !== undefined) {
+        if (!isMapping(value.max)) {
+            throw new Error('Contract "permissions.max" must be a mapping of scope to read, write or none');
+        }
+        const max = {};
+        for (const [scope, level] of Object.entries(value.max)) {
+            if (!permissions_1.GITHUB_TOKEN_SCOPES.includes(scope)) {
+                throw new Error(`Contract "permissions.max" has an unknown scope "${scope}" (expected one of: ${permissions_1.GITHUB_TOKEN_SCOPES.join(', ')})`);
+            }
+            if (level !== 'read' && level !== 'write' && level !== 'none') {
+                throw new Error(`Contract "permissions.max.${scope}" must be "read", "write" or "none", got "${String(level)}"`);
+            }
+            max[scope] = level;
+        }
+        policy.max = max;
+    }
+    return policy;
+}
 function parseStringList(value, section) {
     if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
         throw new Error(`Contract "${section}" must be a list of strings`);

package/dist/parser/pipeline-contract-validator.js

@@ -38,9 +38,11 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const job_plan_1 = require("../runner/job-plan");
 const workflow_parser_1 = require("./workflow-parser");
+const dangerous_triggers_1 = require("./dangerous-triggers");
 const repository_1 = require("../utils/repository");
 const action_fetcher_1 = require("../runner/action-fetcher");
 const github_lockfile_1 = require("../github-lockfile");
+const permissions_1 = require("./permissions");
 /** Maximum nesting of composite actions / reusable workflows. */
 const MAX_DEPTH = 10;
 /**
@@ -51,13 +53,13 @@ const MAX_DEPTH = 10;
  * Composite actions (`uses: ./path`) and reusable workflows
  * (`jobs.<id>.uses: ./path.yml`) are resolved recursively, so wrapping an
  * action doesn't hide it: local ones by default, remote ones too with
- * `recurse: 'all'`. Ordering follows
+ * `recurse: 'all'` (`offline`: only from the cache). Ordering follows
  * what GitHub guarantees: steps of a job run in order, and a job runs after
  * the jobs it (transitively) `needs:`; jobs with no such relationship may
  * run in parallel, so neither is "before" the other.
  */
 async function validatePipelineContract(parsed, spec, options = {}) {
-    const graph = await buildGraph(parsed, options.recurse ?? 'local');
+    const graph = await buildGraph(parsed, options.recurse ?? 'local', options.offline ?? false);
     const { sequence, nodes } = graph;
     const errors = [...graph.errors];
     const ordering = spec.ordering ?? 'relative';
@@ -199,6 +201,16 @@ async function validatePipelineContract(parsed, spec, options = {}) {
     if (spec.lockfile?.required) {
         errors.push(...checkLockfile(parsed, sequence.filter(isRemote)));
     }
+    // The workflow file's own permissions; called workflows are validated as
+    // files of their own.
+    if (spec.permissions) {
+        errors.push(...(0, permissions_1.contractPermissionErrors)(parsed.file, spec.permissions));
+    }
+    // Only the workflow's own on: matters: a called reusable workflow runs
+    // under its caller's event.
+    if (spec.forbiddenTriggers) {
+        errors.push(...(0, dangerous_triggers_1.forbiddenTriggerErrors)(parsed.file, spec.forbiddenTriggers));
+    }
     return {
         valid: errors.every((e) => e.severity !== 'error'),
         errors
@@ -260,7 +272,7 @@ function needsTransitively(nodes, from, to) {
     }
     return false;
 }
-async function buildGraph(parsed, recurse) {
+async function buildGraph(parsed, recurse, offline) {
     const graph = { sequence: [], nodes: new Map(), errors: [] };
     const root = (0, repository_1.repositoryRoot)(parsed.path);
     const isLocal = (uses) => uses.startsWith('./') || uses.startsWith('../');
@@ -295,7 +307,9 @@ async function buildGraph(parsed, recurse) {
         }
         if (recurse !== 'all' || uses.startsWith('docker://'))
             return undefined;
-        const file = kind === 'action' ? await (0, action_fetcher_1.fetchAction)(uses) : await (0, action_fetcher_1.fetchRepoFile)(uses);
+        const file = kind === 'action'
+            ? await (0, action_fetcher_1.fetchAction)(uses, { offline })
+            : await (0, action_fetcher_1.fetchRepoFile)(uses, { offline });
         if (!file) {
             graph.errors.push({
                 path: at,

package/dist/parser/validator.js

@@ -3,9 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.workflowExpressionErrors = workflowExpressionErrors;
 exports.actionExpressionErrors = actionExpressionErrors;
 exports.validateWorkflow = validateWorkflow;
+exports.mergeValidationResults = mergeValidationResults;
 exports.validateAction = validateAction;
 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");
 /**
  * Invalid `if:` expressions in a workflow: syntax errors, or contexts and
  * functions not available where they're used. GitHub rejects such a
@@ -120,6 +124,9 @@ 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));
     }
     catch (error) {
         errors.push({
@@ -129,10 +136,27 @@ function validateWorkflow(filePath) {
         });
     }
     return {
-        valid: errors.length === 0,
+        valid: errors.every((e) => e.severity !== 'error'),
         errors
     };
 }
+/**
+ * Combine validation results (e.g. syntax checks and a contract). A warning
+ * is dropped when an error with the same rule and path supersedes it, such
+ * as a default permissions warning the contract turns into an error.
+ */
+function mergeValidationResults(...results) {
+    const all = results.flatMap((r) => r.errors);
+    const superseding = new Set(all
+        .filter((e) => e.severity === 'error' && e.rule)
+        .map((e) => `${e.rule}\0${e.path}`));
+    return {
+        valid: results.every((r) => r.valid),
+        errors: all.filter((e) => e.severity !== 'warning' ||
+            !e.rule ||
+            !superseding.has(`${e.rule}\0${e.path}`))
+    };
+}
 /**
  * Validate an action file
  */
@@ -201,6 +225,7 @@ function validateAction(filePath) {
                         }
                     });
                     errors.push(...actionExpressionErrors(action));
+                    errors.push(...(0, injection_1.actionInjectionErrors)(action, filePath));
                 }
             }
         }

package/dist/pin.js

@@ -0,0 +1,311 @@
+"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.findUsesSites = findUsesSites;
+exports.isPinAllowed = isPinAllowed;
+exports.pinContent = pinContent;
+exports.localPinTargets = localPinTargets;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const YAML = __importStar(require("yaml"));
+const repository_1 = require("./utils/repository");
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+/**
+ * Every `uses:` a runner reads: `jobs.<id>.uses` (reusable workflows),
+ * `jobs.<id>.steps[*].uses` and a composite action's `runs.steps[*].uses`.
+ * Read from the YAML syntax tree, so `uses:` inside a script or an input
+ * isn't mistaken for one, with source offsets for in-place edits.
+ */
+function findUsesSites(content) {
+    const doc = parseYaml(content);
+    const root = doc.contents;
+    if (!YAML.isMap(root))
+        return [];
+    const nodes = [];
+    const usesOf = (node) => {
+        if (!YAML.isMap(node))
+            return;
+        const uses = node.get('uses', true);
+        if (YAML.isScalar(uses))
+            nodes.push(uses);
+    };
+    const stepsOf = (node) => {
+        if (!YAML.isMap(node))
+            return;
+        const steps = node.get('steps', true);
+        if (YAML.isSeq(steps))
+            steps.items.forEach(usesOf);
+    };
+    const jobs = root.get('jobs', true);
+    if (YAML.isMap(jobs)) {
+        for (const pair of jobs.items) {
+            usesOf(pair.value);
+            stepsOf(pair.value);
+        }
+    }
+    stepsOf(root.get('runs', true));
+    return nodes
+        .filter((node) => node.range && typeof node.value === 'string')
+        .map((node) => {
+        const [start, end] = node.range;
+        return {
+            line: content.slice(0, start).split('\n').length,
+            uses: node.value,
+            start,
+            end,
+            style: scalarStyle(node.type)
+        };
+    })
+        .sort((a, b) => a.start - b.start);
+}
+function parseYaml(content) {
+    const doc = YAML.parseDocument(content);
+    if (doc.errors.length > 0) {
+        throw new Error(`File is not valid YAML: ${doc.errors[0].message}`);
+    }
+    return doc;
+}
+function scalarStyle(type) {
+    if (type === 'QUOTE_SINGLE')
+        return 'single';
+    if (type === 'QUOTE_DOUBLE')
+        return 'double';
+    if (type === 'BLOCK_LITERAL' || type === 'BLOCK_FOLDED')
+        return 'block';
+    return 'plain';
+}
+/**
+ * Whether a contract's `pins.allow` exempts a reference from pinning: an
+ * owner, or the exact action name, case-insensitively for owner and repo.
+ * This mirrors the contract's own pins check, so `pin` never leaves a
+ * reference on a tag that `validate --contract` would then reject.
+ */
+function isPinAllowed(uses, allow) {
+    const at = uses.lastIndexOf('@');
+    const name = normalizeName(at === -1 ? uses : uses.slice(0, at));
+    const owner = name.split('/')[0];
+    const allowed = new Set(allow.map(normalizeName));
+    return allowed.has(name) || allowed.has(owner);
+}
+function normalizeName(name) {
+    const parts = name.split('/');
+    return [
+        ...parts.slice(0, 2).map((p) => p.toLowerCase()),
+        ...parts.slice(2)
+    ].join('/');
+}
+/**
+ * Pin every remote `uses:` reference in a workflow or action file to the
+ * commit SHA `resolve` returns, keeping the tag in a trailing comment
+ * (`owner/repo@<sha> # v4`) so Dependabot and Renovate can still update
+ * it. The text is edited in place (only the value and its comment change),
+ * never re-serialised, so formatting and other comments survive.
+ *
+ * Left alone: local (`./`) and `docker://` references, references already
+ * pinned to a full SHA, and those `allow` exempts. A reference that can't
+ * be resolved is reported in `unresolved` and not changed.
+ */
+async function pinContent(content, resolve, options = {}) {
+    const sites = findUsesSites(content);
+    const result = {
+        content,
+        changes: [],
+        unresolved: [],
+        allowed: []
+    };
+    const lineCounts = new Map();
+    sites.forEach((s) => lineCounts.set(s.line, (lineCounts.get(s.line) ?? 0) + 1));
+    const resolved = new Map();
+    const edits = [];
+    for (const site of sites) {
+        const { uses, line } = site;
+        if (/^(\.\.?\/|docker:\/\/)/.test(uses))
+            continue;
+        const at = uses.lastIndexOf('@');
+        const name = at === -1 ? '' : uses.slice(0, at);
+        const ref = uses.slice(at + 1);
+        const parts = name.split('/');
+        if (at === -1 || !ref || parts.length < 2 || parts.some((p) => !p)) {
+            result.unresolved.push({
+                line,
+                uses,
+                reason: 'is not an owner/repo@ref reference'
+            });
+            continue;
+        }
+        if (FULL_SHA.test(ref))
+            continue;
+        if (isPinAllowed(uses, options.allow ?? [])) {
+            result.allowed.push({ line, uses });
+            continue;
+        }
+        if (site.style === 'block') {
+            result.unresolved.push({
+                line,
+                uses,
+                reason: 'is written as a block scalar; pin it by hand'
+            });
+            continue;
+        }
+        if (!resolved.has(uses))
+            resolved.set(uses, resolve(uses));
+        const sha = (await resolved.get(uses))?.toLowerCase();
+        if (!sha || !FULL_SHA.test(sha)) {
+            result.unresolved.push({
+                line,
+                uses,
+                reason: 'could not be resolved to a commit'
+            });
+            continue;
+        }
+        const pinned = `${name}@${sha}`;
+        const quote = site.style === 'single' ? "'" : site.style === 'double' ? '"' : '';
+        edits.push({
+            start: site.start,
+            end: site.end,
+            text: `${quote}${pinned}${quote}`
+        });
+        // Several references on one line (a flow sequence) can't each have a
+        // trailing comment, so none is written rather than a wrong one.
+        if (lineCounts.get(line) === 1) {
+            edits.push(commentEdit(content, site.end, ref));
+        }
+        result.changes.push({ line, uses, ref, sha, pinned });
+    }
+    result.content = edits
+        .sort((a, b) => b.start - a.start)
+        .reduce((text, e) => text.slice(0, e.start) + e.text + text.slice(e.end), content);
+    return result;
+}
+/**
+ * The edit that leaves `# <ref>` as the comment of the line a value ends
+ * on: an old version comment is replaced, any other comment kept after
+ * the ref, and with no comment one is added at the end of the line.
+ */
+function commentEdit(content, valueEnd, ref) {
+    let lineEnd = content.indexOf('\n', valueEnd);
+    if (lineEnd === -1)
+        lineEnd = content.length;
+    if (content[lineEnd - 1] === '\r')
+        lineEnd--;
+    const tail = content.slice(valueEnd, lineEnd);
+    const hash = commentStart(tail);
+    if (hash === -1) {
+        const at = valueEnd + tail.trimEnd().length;
+        return { start: at, end: at, text: ` # ${ref}` };
+    }
+    const body = tail.slice(hash + 1).trim();
+    return {
+        start: valueEnd + hash,
+        end: lineEnd,
+        text: `# ${ref}${commentRest(body, ref)}`
+    };
+}
+/** Where a YAML comment starts in the rest of a line, or -1. */
+function commentStart(tail) {
+    let quote;
+    for (let i = 0; i < tail.length; i++) {
+        const c = tail[i];
+        if (quote) {
+            if (c === '\\' && quote === '"')
+                i++;
+            else if (c === quote)
+                quote = undefined;
+        }
+        else if (c === "'" || c === '"') {
+            quote = c;
+        }
+        else if (c === '#' && i > 0 && /\s/.test(tail[i - 1])) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * What to keep of an existing comment after the new `# <ref>`: the text
+ * after an old version (`v3`, `3.2.1`, `tag=v3`, `pin @v3`, or the old
+ * ref itself), else the whole comment.
+ */
+function commentRest(body, ref) {
+    if (!body)
+        return '';
+    const version = body.match(/^(?:tag\s*=\s*|pin\s*@?\s*)?@?v?\d[\w.+-]*(.*)$/i);
+    const rest = version
+        ? version[1]
+        : body === ref || body.startsWith(`${ref} `)
+            ? body.slice(ref.length)
+            : undefined;
+    if (rest === undefined)
+        return ` - ${body}`;
+    return rest.trim() ? ` ${rest.trim()}` : '';
+}
+/**
+ * The given files plus the local composite actions (`./path`) and local
+ * reusable workflows they use, recursively, so a whole repository is
+ * pinned in one go. `./` resolves against the repository root, as on
+ * GitHub. Files are listed once; one that can't be read is kept (for the
+ * caller to report) but not followed.
+ */
+function localPinTargets(files) {
+    const seen = new Set(files.map((f) => path.resolve(f)));
+    const result = [...files];
+    const follow = (file, root) => {
+        let sites;
+        try {
+            sites = findUsesSites(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            return;
+        }
+        for (const { uses } of sites) {
+            if (!uses.startsWith('./') && !uses.startsWith('../'))
+                continue;
+            const target = path.resolve(root, uses);
+            const local = [
+                target,
+                ...['action.yml', 'action.yaml'].map((n) => path.join(target, n))
+            ].find((c) => fs.existsSync(c) && fs.statSync(c).isFile());
+            if (!local || seen.has(local))
+                continue;
+            seen.add(local);
+            result.push(local);
+            follow(local, root);
+        }
+    };
+    for (const file of files)
+        follow(file, (0, repository_1.repositoryRoot)(file));
+    return result;
+}
+//# sourceMappingURL=pin.js.map

package/dist/report.js

@@ -4,6 +4,8 @@ exports.formatReport = formatReport;
 exports.formatValidation = formatValidation;
 /** A SARIF rule id per error, so code-scanning can group findings. */
 function ruleIdFor(error) {
+    if (error.rule)
+        return error.rule;
     if (/^required\[|^forbidden\[/.test(error.path))
         return 'secureci/contract';
     if (/\.if$|\bif:/.test(error.path))
@@ -13,7 +15,11 @@ function ruleIdFor(error) {
 const RULES = {
     'secureci/validation': 'Workflow or action structure',
     'secureci/contract': 'Pipeline contract',
-    'secureci/expression': 'Expression / if: condition'
+    'secureci/expression': 'Expression / if: condition',
+    'secureci/injection': 'Untrusted input in a shell or script',
+    'secureci/permissions': 'GITHUB_TOKEN permissions',
+    'secureci/dangerous-trigger': 'Privileged trigger with untrusted code',
+    'secureci/vulnerable-action': 'Action with a known security advisory'
 };
 function jsonForFile(entry) {
     return {