@secureci/cli 0.5.1 → 0.7.0

package/dist/parser/permissions.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITHUB_TOKEN_SCOPES = void 0;
+exports.workflowPermissionErrors = workflowPermissionErrors;
+exports.contractPermissionErrors = contractPermissionErrors;
+/** SARIF rule for every GITHUB_TOKEN permissions finding. */
+const RULE = 'secureci/permissions';
+/**
+ * Scopes `permissions:` accepts, per GitHub's workflow syntax.
+ * `repository-projects` is kept for older workflows (classic Projects).
+ */
+exports.GITHUB_TOKEN_SCOPES = [
+    'actions',
+    'artifact-metadata',
+    'attestations',
+    'checks',
+    'contents',
+    'deployments',
+    'discussions',
+    'id-token',
+    'issues',
+    'models',
+    'packages',
+    'pages',
+    'pull-requests',
+    'repository-projects',
+    'security-events',
+    'statuses'
+];
+const RANK = { none: 0, read: 1, write: 2 };
+const hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+/** Rank of a level, or undefined for anything that isn't one. */
+const rankOf = (level) => typeof level === 'string' && hasOwn(RANK, level)
+    ? RANK[level]
+    : undefined;
+const declared = (permissions) => permissions !== undefined && permissions !== null;
+const isScopeMap = (permissions) => typeof permissions === 'object' &&
+    permissions !== null &&
+    !Array.isArray(permissions);
+/**
+ * A reusable workflow runs with its caller's token, so a workflow whose only
+ * trigger is `workflow_call` doesn't need its own top-level block.
+ */
+function onlyWorkflowCall(on) {
+    const events = typeof on === 'string'
+        ? [on]
+        : Array.isArray(on)
+            ? on
+            : on && typeof on === 'object'
+                ? Object.keys(on)
+                : [];
+    return events.length > 0 && events.every((e) => e === 'workflow_call');
+}
+/**
+ * Jobs whose token falls back to the repository/organization default:
+ * no top-level `permissions:` and none on the job. Empty when the workflow
+ * declares a top-level block or only runs as a reusable workflow.
+ */
+function uncoveredJobs(workflow) {
+    if (declared(workflow.permissions) || onlyWorkflowCall(workflow.on)) {
+        return [];
+    }
+    return Object.entries(workflow.jobs ?? {})
+        .filter(([, job]) => !declared(job?.permissions))
+        .map(([id]) => id);
+}
+const quoteList = (ids) => ids.map((id) => `"${id}"`).join(', ');
+const finding = (path, message, severity) => ({ path, message, severity, rule: RULE });
+/**
+ * Default GITHUB_TOKEN checks (warnings, so existing workflows keep
+ * validating): jobs left on the default token, `write-all` at either level,
+ * and write scopes granted to every job at the workflow level.
+ */
+function workflowPermissionErrors(workflow) {
+    const errors = [];
+    const uncovered = uncoveredJobs(workflow);
+    if (uncovered.length > 0) {
+        errors.push(finding('permissions', `No top-level permissions: and job(s) ${quoteList(uncovered)} declare none, so their GITHUB_TOKEN gets the repository's default permissions (read/write on every scope in many repositories). Add a top-level block such as "permissions: { contents: read }", or declare permissions on each job`, 'warning'));
+    }
+    const top = workflow.permissions;
+    if (top === 'write-all') {
+        errors.push(finding('permissions', 'permissions: write-all gives every job write access to every scope. Keep the top level read-only (e.g. "contents: read") and grant write scopes on the jobs that need them', 'warning'));
+    }
+    else if (isScopeMap(top)) {
+        for (const [scope, level] of Object.entries(top)) {
+            if (level !== 'write')
+                continue;
+            errors.push(finding(`permissions.${scope}`, `Workflow-level "${scope}: write" applies to every job. Declare it on the job(s) that need it instead (job-level permissions replace the top-level ones)`, 'warning'));
+        }
+    }
+    for (const [jobId, job] of Object.entries(workflow.jobs ?? {})) {
+        if (job?.permissions === 'write-all') {
+            errors.push(finding(`jobs.${jobId}.permissions`, `Job "${jobId}" uses permissions: write-all, giving its GITHUB_TOKEN write access to every scope. List only the scopes it needs`, 'warning'));
+        }
+    }
+    return errors;
+}
+/**
+ * Contract `permissions:` policy (errors). `required`: every job must have
+ * declared permissions, top-level or its own. `max`: a ceiling on the
+ * top-level block (unlisted scopes are capped at `none`); job-level
+ * permissions aren't capped, so write scopes go per job. A workflow whose
+ * only trigger is `workflow_call` needs no top-level block for either.
+ */
+function contractPermissionErrors(workflow, policy) {
+    const uncovered = uncoveredJobs(workflow);
+    const max = policy.max;
+    if (uncovered.length > 0 && (policy.required || max)) {
+        return [
+            finding('permissions', policy.required
+                ? `The contract requires declared GITHUB_TOKEN permissions, but the workflow has no top-level permissions: and job(s) ${quoteList(uncovered)} declare none. Add a top-level permissions: block, or declare permissions on each job`
+                : `The contract caps workflow-level permissions at (${formatCeiling(max)}), but the workflow has no top-level permissions:, so job(s) ${quoteList(uncovered)} get the repository's default token permissions. Add a top-level block within the cap, or declare permissions on each job`, 'error')
+        ];
+    }
+    if (!max)
+        return [];
+    const ceiling = (scope) => (hasOwn(max, scope) ? rankOf(max[scope]) : undefined) ?? RANK.none;
+    const top = workflow.permissions;
+    if (top === 'read-all' || top === 'write-all') {
+        const needed = top === 'read-all' ? RANK.read : RANK.write;
+        if (exports.GITHUB_TOKEN_SCOPES.some((scope) => ceiling(scope) < needed)) {
+            return [
+                finding('permissions', `Workflow-level "${top}" exceeds the contract's cap on workflow-level permissions (${formatCeiling(max)}). List only the scopes the cap allows, and grant the rest on the jobs that need them`, 'error')
+            ];
+        }
+        return [];
+    }
+    const errors = [];
+    if (isScopeMap(top)) {
+        for (const [scope, level] of Object.entries(top)) {
+            const rank = rankOf(level);
+            if (rank !== undefined && rank > ceiling(scope)) {
+                errors.push(finding(`permissions.${scope}`, `Workflow-level "${scope}: ${level}" exceeds the contract's cap on workflow-level permissions (${formatCeiling(max)}). Grant it on the job(s) that need it instead`, 'error'));
+            }
+        }
+    }
+    return errors;
+}
+function formatCeiling(max) {
+    const entries = Object.entries(max);
+    return entries.length === 0
+        ? 'none'
+        : entries.map(([scope, level]) => `${scope}: ${level}`).join(', ');
+}
+//# sourceMappingURL=permissions.js.map

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

@@ -1,11 +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
@@ -120,6 +159,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, (0, allow_comments_1.stepAllowComments)(fs.readFileSync(filePath, 'utf-8'), 'dangerous-trigger')));
     }
     catch (error) {
         errors.push({
@@ -129,10 +171,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 +260,7 @@ function validateAction(filePath) {
                         }
                     });
                     errors.push(...actionExpressionErrors(action));
+                    errors.push(...(0, injection_1.actionInjectionErrors)(action, filePath));
                 }
             }
         }