@secureci/cli 0.5.0 → 0.6.0

package/dist/cli.js

@@ -36,8 +36,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const dry_run_1 = require("./runner/dry-run");
+const job_plan_1 = require("./runner/job-plan");
 const executor_1 = require("./runner/executor");
 const action_fetcher_1 = require("./runner/action-fetcher");
+const progress_1 = require("./utils/progress");
 const contract_source_1 = require("./contract-source");
 const validator_1 = require("./parser/validator");
 const workflow_parser_1 = require("./parser/workflow-parser");
@@ -45,24 +47,19 @@ const pipeline_contract_parser_1 = require("./parser/pipeline-contract-parser");
 const pipeline_contract_validator_1 = require("./parser/pipeline-contract-validator");
 const report_1 = require("./report");
 const init_1 = require("./init");
+const pin_1 = require("./pin");
+const advisories_1 = require("./advisories");
 const inventory_1 = require("./inventory");
 const github_lockfile_1 = require("./github-lockfile");
 const logger_1 = require("./utils/logger");
-const key_value_1 = require("./utils/key-value");
+const env_file_1 = require("./utils/env-file");
 const config_1 = require("./config");
+const scheduler_1 = require("./runner/scheduler");
+const version_1 = require("./version");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 /** Committed at the repo root, like package-lock.json / yarn.lock. */
 const LOCKFILE_NAME = 'secureci.lock';
-function readVersion() {
-    try {
-        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
-        return String(pkg.version);
-    }
-    catch {
-        return '0.0.0';
-    }
-}
 const program = new commander_1.Command();
 const globalConfig = (0, config_1.loadConfig)();
 // An invalid container-runtime in the config file only stops `run`, so
@@ -76,10 +73,17 @@ catch (error) {
     configError = error instanceof Error ? error.message : String(error);
     defaultContainerRuntime = 'docker';
 }
+let defaultParallel = 1;
+try {
+    defaultParallel = (0, config_1.getDefaultParallel)(globalConfig);
+}
+catch (error) {
+    configError ?? (configError = error instanceof Error ? error.message : String(error));
+}
 program
     .name('secureci')
     .description('SecureCI: validate, check and run GitHub Actions workflows locally')
-    .version(readVersion(), '-V, --version', 'Print the version')
+    .version((0, version_1.readVersion)(), '-V, --version', 'Print the version')
     .helpOption('-h, --help', 'Show help')
     .addHelpCommand('help [command]', 'Show help for a command')
     .option('--verbose', 'Log debug output')
@@ -104,9 +108,14 @@ program
     .option('-s, --secret <key=value|NAME...>', 'Set a secret for the secrets context. A bare NAME reads $NAME from your shell, keeping the value off the command line. Repeatable')
     .option('--env <key=value|NAME...>', 'Set an env var for every step, below workflow/job/step env:. A bare NAME passes $NAME from your shell (steps get nothing else from it). Repeatable')
     .option('--var <key=value...>', 'Set a configuration variable for the vars context. Repeatable')
+    .option('--env-file <file...>', 'Read --env values from a .env-style file. Repeatable; later files win, --env wins over files. Config: env-file')
+    .option('--secret-file <file...>', 'Read --secret values from a .env-style file; every value is masked. Repeatable; later files win, --secret wins over files. Config: secret-file')
+    .option('--input-file <file...>', 'Read --input values from a .env-style file. Repeatable; later files win, --input wins over files. Config: input-file')
+    .option('--var-file <file...>', 'Read --var values from a .env-style file. Repeatable; later files win, --var wins over files. Config: var-file')
     .option('--event-path <file>', 'Read the event payload (github.event, $GITHUB_EVENT_PATH) from a JSON file')
     .option('--event-name <name>', 'Set github.event_name. Default: $GITHUB_EVENT_NAME, else workflow_dispatch if declared, else the first trigger')
     .option('-j, --job <name>', 'Run only this job')
+    .option('--matrix <key:value...>', 'Run only the matrix combinations whose key has this value (as shown in the job name). Repeat for more keys (all must match) or values (any matches)')
     .option('--offline', 'Use only cached remote actions and workflows; never download')
     .option('--no-local-checkout', 'Run the real actions/checkout for this repository instead of using the working copy')
     .addOption(new commander_1.Option('--container-runtime <name>', 'Container engine for jobs. "host" runs steps directly on this machine, without a container. Config: container-runtime')
@@ -119,14 +128,23 @@ program
     .option('--container-memory <limit>', 'Limit job container memory, e.g. 512m. Config: container-memory', globalConfig['container-memory'])
     .option('--no-network', 'Turn off container network access (on by default)')
     .option('--allow-network', 'Turn on container network access, overriding allow-network: false in the config')
+    .option('--parallel <n>', 'Run up to this many jobs (and matrix combinations) at once; 1 runs them one after another. Default: the number of CPUs. Config: parallel', String(defaultParallel))
     .action(async (file, options) => {
     if (configError) {
         logger_1.logger.error(configError);
         process.exit(1);
     }
     requireFile(file);
+    let matrix;
+    try {
+        matrix = (0, job_plan_1.parseMatrixFilter)(options.matrix);
+    }
+    catch (error) {
+        logger_1.logger.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
     if (options.dryRun) {
-        const result = (0, dry_run_1.dryRun)(file);
+        const result = (0, dry_run_1.dryRun)(file, { job: options.job, matrix });
         if (!result.success) {
             process.exit(1);
         }
@@ -134,15 +152,38 @@ program
     }
     logger_1.logger.info("Running the workflow for real (not a dry run). Use --dry-run to simulate without executing, or 'secureci validate' to only check for errors.");
     try {
-        const inputs = (0, key_value_1.parseKeyValuePairs)(options.input, '--input');
-        const secrets = (0, key_value_1.parseKeyValuePairs)(options.secret, '--secret', {
-            redact: true,
+        const inputs = (0, env_file_1.loadKeyValues)({
+            flagName: '--input',
+            fileFlagName: '--input-file',
+            pairs: options.input,
+            files: options.inputFile,
+            configFiles: globalConfig['input-file']
+        });
+        const secrets = (0, env_file_1.loadKeyValues)({
+            flagName: '--secret',
+            fileFlagName: '--secret-file',
+            pairs: options.secret,
+            files: options.secretFile,
+            configFiles: globalConfig['secret-file'],
+            secret: true,
             fromEnv: process.env
         });
-        const vars = (0, key_value_1.parseKeyValuePairs)(options.var, '--var');
-        const env = (0, key_value_1.parseKeyValuePairs)(options.env, '--env', {
+        const vars = (0, env_file_1.loadKeyValues)({
+            flagName: '--var',
+            fileFlagName: '--var-file',
+            pairs: options.var,
+            files: options.varFile,
+            configFiles: globalConfig['var-file']
+        });
+        const env = (0, env_file_1.loadKeyValues)({
+            flagName: '--env',
+            fileFlagName: '--env-file',
+            pairs: options.env,
+            files: options.envFile,
+            configFiles: globalConfig['env-file'],
             fromEnv: process.env
         });
+        const parallel = (0, scheduler_1.parseParallel)(options.parallel);
         const result = await (0, executor_1.executeWorkflow)(file, {
             dryRun: false,
             inputs,
@@ -152,6 +193,7 @@ program
             eventPath: options.eventPath,
             eventName: options.eventName,
             job: options.job,
+            matrix,
             localCheckout: options.localCheckout,
             offline: options.offline,
             verbose: program.opts().verbose,
@@ -163,7 +205,8 @@ program
                 ? Number(options.containerTimeout)
                 : undefined,
             containerMemoryLimit: options.containerMemory,
-            networkDisabled: (0, config_1.resolveNetworkDisabled)({ network: options.network, allowNetwork: options.allowNetwork }, globalConfig)
+            networkDisabled: (0, config_1.resolveNetworkDisabled)({ network: options.network, allowNetwork: options.allowNetwork }, globalConfig),
+            parallel
         });
         if (!result.success) {
             process.exit(1);
@@ -185,15 +228,16 @@ program
     .addOption(new commander_1.Option('--format <format>', 'Output format: text (default), or json / sarif for machine-readable results (sarif uploads to GitHub code scanning)')
     .choices(['text', 'json', 'sarif'])
     .default('text'))
+    .option('--offline', 'Do not use the network: skip the security advisory lookup (cached advisories are still used), and read remote contracts and actions only from the cache')
     .action(async (files, options) => {
     files.forEach(requireFile);
-    await validateFiles(files, options.contract, options.contractRecurse, options.format);
+    await validateFiles(files, options.contract, options.contractRecurse, options.format, options.offline ?? false);
 });
 program
     .command('inventory')
     .description('List the actions and reusable workflows a workflow uses (including the actions those actions use), with their commit SHAs; track supply-chain drift with a committed secureci.lock')
     .argument('[file...]', 'Workflow files (default: every file in .github/workflows)')
-    .option('--offline', 'Do not resolve tags to commit SHAs over the network (already-pinned refs still resolve)')
+    .option('--offline', 'Do not resolve tags to commit SHAs or query security advisories over the network (already-pinned refs still resolve; cached advisories are used)')
     .option('--dry-run', `Print the resolved inventory as JSON without writing or checking ${LOCKFILE_NAME}`)
     .option('--update-lock', `Write/update ./${LOCKFILE_NAME} with the current commit SHAs (commit it to your repo)`)
     .option('--update-lockfile', `Alias of --update-lock`)
@@ -202,6 +246,17 @@ program
     .action(async (files, options) => {
     await runInventory(files, options);
 });
+program
+    .command('pin')
+    .description('Pin action and reusable-workflow tags to commit SHAs in place (`owner/repo@<sha> # v4`), keeping formatting and comments')
+    .argument('[file...]', 'Workflow or action files (default: every file in .github/workflows, plus the local actions and reusable workflows they use)')
+    .option('--check', 'Change nothing; exit non-zero if any reference would be pinned or cannot be resolved (for CI)')
+    .option('-c, --contract <file>', "Leave the owners/actions in this pipeline contract's pins.allow on their tags")
+    .option('--offline', 'Do not use the network: only refs already in the action cache resolve; others are reported, not changed')
+    .option('--update-lock', `Afterwards, write ./${LOCKFILE_NAME} from the pinned workflows (as \`inventory --update-lock\`)`)
+    .action(async (files, options) => {
+    await runPin(files, options);
+});
 program
     .command('list')
     .description('List workflows in .github/workflows/')
@@ -248,9 +303,6 @@ async function runInventory(files, options) {
         process.exit(1);
     }
     targets.forEach(requireFile);
-    const resolver = options.offline
-        ? undefined
-        : (uses) => (0, action_fetcher_1.resolveActionSha)(uses);
     // Merge every file's remote actions by `uses`.
     const byUses = new Map();
     for (const file of targets) {
@@ -258,7 +310,11 @@ async function runInventory(files, options) {
             const parsed = (0, workflow_parser_1.parseFile)(file);
             if (parsed.type !== 'workflow')
                 continue;
-            const inv = await (0, inventory_1.buildInventory)({ type: 'workflow', path: file, file: parsed.file }, resolver);
+            const inv = await (0, inventory_1.buildInventory)({
+                type: 'workflow',
+                path: file,
+                file: parsed.file
+            });
             for (const action of inv.actions) {
                 const existing = byUses.get(action.uses);
                 if (existing)
@@ -272,19 +328,7 @@ async function runInventory(files, options) {
             process.exit(1);
         }
     }
-    // Download progress would corrupt --dry-run's JSON on stdout; warnings
-    // still go to stderr.
-    if (options.dryRun)
-        logger_1.logger.setLevel(logger_1.LogLevel.WARN);
-    // Follow remote composite actions and reusable workflows into the
-    // actions they use, downloaded at the resolved commit.
-    const actions = (await (0, inventory_1.addTransitive)([...byUses.values()], {
-        resolveSha: resolver,
-        fetch: (uses, kind) => kind === 'action'
-            ? (0, action_fetcher_1.fetchAction)(uses, { offline: options.offline })
-            : (0, action_fetcher_1.fetchRepoFile)(uses, { offline: options.offline }),
-        warn: (message) => logger_1.logger.warn(message)
-    })).sort((a, b) => a.uses.localeCompare(b.uses));
+    const direct = [...byUses.values()];
     const lockPath = path.join(process.cwd(), LOCKFILE_NAME);
     // secureci.lock is first-class; GitHub's actions.lock is used only when
     // it is the lockfile the repository provides.
@@ -293,10 +337,11 @@ async function runInventory(files, options) {
     // writes the lock; otherwise (`--check`, or bare `inventory` with a
     // lockfile) compares against it.
     const writing = update || (!check && !source);
+    const comparing = !writing && !options.dryRun;
     let lock;
     const github = source?.kind === 'github';
     const lockName = github ? 'actions.lock' : LOCKFILE_NAME;
-    if (!writing && !options.dryRun) {
+    if (comparing) {
         if (!source) {
             logger_1.logger.error(`No ${LOCKFILE_NAME} found (or GitHub's ${github_lockfile_1.GITHUB_LOCKFILE}). Create one with: secureci inventory --update-lock`);
             process.exit(1);
@@ -309,24 +354,94 @@ async function runInventory(files, options) {
             process.exit(1);
         }
     }
-    // Repository identity: recorded when writing; when checking, looked up
-    // only for repositories the lock has an identity for.
-    if (!options.offline) {
-        const lookups = new Map();
+    // Download messages would corrupt --dry-run's JSON on stdout and clash
+    // with the progress lines; warnings and errors still go to stderr.
+    const level = logger_1.logger.getLevel();
+    if (level === logger_1.LogLevel.INFO)
+        logger_1.logger.setLevel(logger_1.LogLevel.WARN);
+    const online = !options.offline;
+    if (online && direct.length > 0) {
+        process.stderr.write(`Resolving ${direct.length} action(s) over the network, and reading the actions they use. This can take a while (--offline uses only what is cached).\n`);
+    }
+    // 1. Resolve each tag or branch to the commit it points at.
+    const toResolve = online ? direct.filter((a) => !a.resolvedSha) : [];
+    const resolving = new progress_1.Progress('Resolving tags', toResolve.length);
+    for (const action of toResolve) {
+        resolving.tick(action.uses);
+        action.resolvedSha = await (0, action_fetcher_1.resolveActionSha)(action.uses);
+    }
+    resolving.done(`Resolved ${toResolve.length} tag(s)`);
+    // 2. Follow remote composite actions and reusable workflows into the
+    // actions they use, downloaded at the resolved commit.
+    const reading = new progress_1.Progress('Reading actions', online ? direct.length : 0);
+    let read = 0;
+    const actions = (await (0, inventory_1.addTransitive)(direct, {
+        resolveSha: online ? (uses) => (0, action_fetcher_1.resolveActionSha)(uses) : undefined,
+        fetch: (uses, kind) => {
+            if (online)
+                reading.tick(uses.replace(/@([0-9a-f]{12})[0-9a-f]{28}$/, '@$1'));
+            read++;
+            return kind === 'action'
+                ? (0, action_fetcher_1.fetchAction)(uses, { offline: options.offline })
+                : (0, action_fetcher_1.fetchRepoFile)(uses, { offline: options.offline });
+        },
+        warn: (message) => logger_1.logger.warn(message),
+        onQueue: () => reading.grow()
+    })).sort((a, b) => a.uses.localeCompare(b.uses));
+    reading.done(`Read ${read} action(s) for the actions they use`);
+    const repos = new Map();
+    if (online) {
         for (const action of actions) {
             if (!action.resolvedSha)
                 continue;
-            if (lock && lock.actions[action.uses]?.repoId === undefined)
+            const identity = !lock || lock.actions[action.uses]?.repoId !== undefined;
+            const existence = comparing && action.pinned;
+            if (!identity && !existence)
                 continue;
             const key = `${action.owner}/${action.repo}`.toLowerCase();
-            if (!lookups.has(key)) {
-                lookups.set(key, (0, action_fetcher_1.resolveRepoIdentity)(action.owner, action.repo));
-            }
-            const identity = await lookups.get(key);
-            if (identity)
-                Object.assign(action, identity);
+            const entry = repos.get(key) ?? {
+                owner: action.owner,
+                repo: action.repo,
+                identity: false,
+                existence: false
+            };
+            entry.identity || (entry.identity = identity);
+            entry.existence || (entry.existence = existence);
+            repos.set(key, entry);
         }
     }
+    const identities = new Map();
+    const missingRepos = new Set();
+    const checking = new progress_1.Progress('Checking repositories', repos.size);
+    for (const [key, r] of repos) {
+        checking.tick(`${r.owner}/${r.repo}`);
+        const identity = r.identity
+            ? await (0, action_fetcher_1.resolveRepoIdentity)(r.owner, r.repo)
+            : undefined;
+        if (identity)
+            identities.set(key, identity);
+        else if (r.existence && !(await (0, action_fetcher_1.repoExists)(r.owner, r.repo))) {
+            missingRepos.add(key);
+        }
+    }
+    checking.done(`Checked ${repos.size} repositor${repos.size === 1 ? 'y' : 'ies'}`);
+    for (const action of actions) {
+        const identity = identities.get(`${action.owner}/${action.repo}`.toLowerCase());
+        if (identity && action.resolvedSha)
+            Object.assign(action, identity);
+    }
+    // 4. Known security advisories for every action, direct and transitive.
+    const repoCount = new Set(actions.map((a) => `${a.owner}/${a.repo}`.toLowerCase())).size;
+    const advising = new progress_1.Progress('Checking security advisories', online ? repoCount : 0);
+    const advisoryReport = await new advisories_1.AdvisoryChecker({
+        offline: !online,
+        onLookup: (repo) => {
+            if (online)
+                advising.tick(repo);
+        }
+    }).check((0, advisories_1.targetsFromInventory)(actions));
+    advising.done(`Checked security advisories for ${repoCount} repositor${repoCount === 1 ? 'y' : 'ies'}`);
+    logger_1.logger.setLevel(level);
     const current = {};
     for (const action of actions) {
         if (!action.resolvedSha)
@@ -341,10 +456,28 @@ async function runInventory(files, options) {
     // --dry-run: print the resolved inventory as JSON, touching nothing.
     if (options.dryRun) {
         // eslint-disable-next-line no-console
-        console.log(JSON.stringify({ actions }, null, 2));
+        console.log(JSON.stringify({
+            actions,
+            advisories: advisoryReport.findings,
+            advisoryUnknownVersions: advisoryReport.unknownVersions
+        }, null, 2));
+        // The findings are in the JSON; say on stderr what wasn't checked.
+        (0, advisories_1.describeReport)(advisoryReport)
+            .filter((line) => line.kind === 'note' && line.level === 'warn')
+            .forEach((line) => logger_1.logger.warn(line.text));
         return;
     }
+    // Advisories are reported, but don't change the exit code here: gate on
+    // them with `secureci validate` (rule secureci/vulnerable-action).
+    for (const line of (0, advisories_1.describeReport)(advisoryReport)) {
+        logger_1.logger[line.level](line.text);
+    }
+    // Used references that couldn't be resolved to a commit now.
+    const unresolved = actions.filter((a) => !a.resolvedSha);
     if (writing) {
+        if (online) {
+            unresolved.forEach((a) => logger_1.logger.warn(`Not locked: could not resolve ${a.uses} (repository deleted, renamed or private, or the network is unavailable?)`));
+        }
         fs.writeFileSync(lockPath, (0, github_lockfile_1.serializeSecureciLockfile)(current));
         const transitive = Object.values(current).filter((e) => e.via).length;
         logger_1.logger.success(`Wrote ${Object.keys(current).length} action(s) to ${LOCKFILE_NAME}` +
@@ -363,16 +496,41 @@ async function runInventory(files, options) {
     for (const d of diff.identity) {
         logger_1.logger.error(`Repository changed: ${d.uses} ${d.field} is now ${d.to} (was ${d.from}). The name now points at a different ${d.field === 'repo_id' ? 'repository (deleted and re-created?)' : 'owner (transferred, or the account re-registered?)'}.`);
     }
+    for (const a of actions) {
+        if (missingRepos.has(`${a.owner}/${a.repo}`.toLowerCase())) {
+            logger_1.logger.error(`Repository gone: ${a.uses} can no longer be read (deleted, renamed or made private?). The locked commit can't be fetched, and the name could be re-registered by someone else.`);
+        }
+    }
+    // Online, a used reference that doesn't resolve is a failure (its
+    // repository may be gone); offline, tags can't resolve, so it's a warning.
+    for (const a of unresolved) {
+        const locked = lock?.actions[a.uses];
+        const at = locked ? ` (locked at ${locked.commit.slice(0, 12)})` : '';
+        if (online) {
+            logger_1.logger.error(`Could not resolve ${a.uses}${at}: the repository or ref may have been deleted, renamed or made private, or the network is unavailable.`);
+        }
+    }
+    if (!online && unresolved.length > 0) {
+        logger_1.logger.warn(`Not checked offline (tags need the network): ${unresolved.map((a) => a.uses).join(', ')}`);
+    }
     diff.added.forEach((u) => logger_1.logger.warn(`New action not in ${lockName}: ${u}`));
     // actions.lock is written by `gh actions-lock`, which may record entries
     // SecureCI doesn't follow, so "no longer used" is only for secureci.lock.
+    // A reference still in use but unresolved isn't "no longer used".
     if (!github) {
-        diff.removed.forEach((u) => logger_1.logger.info(`In ${lockName} but no longer used: ${u}`));
+        const used = new Set(unresolved.map((a) => a.uses));
+        diff.removed
+            .filter((u) => !used.has(u))
+            .forEach((u) => logger_1.logger.info(`In ${lockName} but no longer used: ${u}`));
     }
     if (diff.identity.length > 0) {
         logger_1.logger.error(`A locked repository is no longer the one that was locked. Verify it before trusting it, then ${fixHint}.`);
         process.exit(1);
     }
+    if (missingRepos.size > 0 || (online && unresolved.length > 0)) {
+        logger_1.logger.error(`Locked actions could not be verified. Check that each repository and ref still exists and is readable${(0, action_fetcher_1.githubToken)() ? '' : ' (set GITHUB_TOKEN for private repositories)'}.`);
+        process.exit(1);
+    }
     if (diff.drifted.length > 0) {
         logger_1.logger.error(`Action commits drifted from ${lockName}. Review the change, then ${fixHint}.`);
         process.exit(1);
@@ -383,7 +541,130 @@ async function runInventory(files, options) {
     }
     logger_1.logger.success(`No action drift against ${lockName}.`);
 }
-async function validateOneFile(filePath, contractFile, recurse, say) {
+async function runPin(files, options) {
+    if (options.check && options.updateLock) {
+        logger_1.logger.error('Use either --update-lock or --check, not both.');
+        process.exit(1);
+    }
+    const given = files.length > 0 ? files : defaultWorkflowFiles();
+    if (given.length === 0) {
+        logger_1.logger.error('No workflow files given and none found in .github/workflows');
+        process.exit(1);
+    }
+    given.forEach(requireFile);
+    // Explicit files are pinned as given; the default run covers the whole
+    // repository, including local actions the workflows use.
+    const targets = files.length > 0 ? given : (0, pin_1.localPinTargets)(given);
+    let allow = [];
+    if (options.contract) {
+        try {
+            const source = await (0, contract_source_1.resolveContractSource)(options.contract, {
+                fetchFile: (uses) => (0, action_fetcher_1.fetchRepoFile)(uses, { offline: options.offline }),
+                resolveSha: (uses) => options.offline
+                    ? Promise.resolve((0, action_fetcher_1.cachedActionSha)(uses))
+                    : (0, action_fetcher_1.resolveActionSha)(uses),
+                warn: (message) => logger_1.logger.warn(message)
+            });
+            allow = (0, pipeline_contract_parser_1.parsePipelineContract)(source.file).pins?.allow ?? [];
+        }
+        catch (error) {
+            logger_1.logger.error(`Could not read contract ${options.contract}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            process.exit(1);
+        }
+    }
+    // Each distinct reference is resolved once, across all files.
+    const resolving = new progress_1.Progress('Resolving tags', 0);
+    const resolved = new Map();
+    const resolve = (uses) => {
+        let sha = resolved.get(uses);
+        if (!sha) {
+            if (options.offline) {
+                sha = Promise.resolve((0, action_fetcher_1.cachedActionSha)(uses));
+            }
+            else {
+                resolving.grow();
+                resolving.tick(uses);
+                sha = (0, action_fetcher_1.resolveActionSha)(uses);
+            }
+            resolved.set(uses, sha);
+        }
+        return sha;
+    };
+    const display = (file) => path.relative(process.cwd(), path.resolve(file)) || file;
+    let changes = 0;
+    let changedFiles = 0;
+    let unresolved = 0;
+    let unreadable = false;
+    const report = options.check
+        ? (m) => logger_1.logger.error(m)
+        : (m) => logger_1.logger.warn(m);
+    for (const file of targets) {
+        const name = display(file);
+        let result;
+        try {
+            result = await (0, pin_1.pinContent)(fs.readFileSync(file, 'utf-8'), resolve, {
+                allow
+            });
+        }
+        catch (error) {
+            logger_1.logger.error(`Could not read ${name}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            unreadable = true;
+            continue;
+        }
+        for (const a of result.allowed) {
+            logger_1.logger.info(`${name}:${a.line} ${a.uses} left on its tag (pins.allow)`);
+        }
+        for (const c of result.changes) {
+            logger_1.logger.info(`${name}:${c.line} ${c.uses} -> ${c.sha.slice(0, 12)} (${c.ref})`);
+        }
+        for (const u of result.unresolved) {
+            report(`${name}:${u.line} ${u.uses} ${u.reason}` +
+                (options.offline && u.reason.startsWith('could not')
+                    ? ' (offline: only refs in the action cache resolve)'
+                    : '') +
+                '; left unchanged');
+        }
+        changes += result.changes.length;
+        unresolved += result.unresolved.length;
+        if (result.changes.length > 0) {
+            changedFiles++;
+            if (!options.check)
+                fs.writeFileSync(file, result.content);
+        }
+    }
+    resolving.done(`Resolved ${resolved.size} reference(s)`);
+    const fileCount = `${changedFiles} file(s)`;
+    const unresolvedHint = options.offline
+        ? ''
+        : ` (check that each repository and ref exists${(0, action_fetcher_1.githubToken)() ? '' : '; set GITHUB_TOKEN for private repositories'})`;
+    if (options.check) {
+        if (changes > 0) {
+            logger_1.logger.error(`${changes} reference(s) would be pinned in ${fileCount}. Run \`secureci pin\` to pin them.`);
+        }
+        if (unresolved > 0) {
+            logger_1.logger.error(`${unresolved} reference(s) could not be resolved${unresolvedHint}.`);
+        }
+        if (changes > 0 || unresolved > 0 || unreadable)
+            process.exit(1);
+        logger_1.logger.success('Nothing to pin: every remote reference is pinned.');
+        return;
+    }
+    if (changes > 0) {
+        logger_1.logger.success(`Pinned ${changes} reference(s) in ${fileCount}.`);
+    }
+    else if (unresolved === 0) {
+        logger_1.logger.success('Nothing to pin: every remote reference is pinned.');
+    }
+    if (unresolved > 0) {
+        logger_1.logger.warn(`${unresolved} reference(s) could not be resolved and were left unchanged${unresolvedHint}.`);
+    }
+    if (unreadable)
+        process.exit(1);
+    if (options.updateLock) {
+        await runInventory(files, { offline: options.offline, updateLock: true });
+    }
+}
+async function validateOneFile(filePath, contractFile, recurse, say, advisories, offline) {
     const parsed = (0, workflow_parser_1.parseFile)(filePath);
     let result;
     if (parsed.type === 'workflow') {
@@ -394,6 +675,7 @@ async function validateOneFile(filePath, contractFile, recurse, say) {
         result = (0, validator_1.validateAction)(filePath);
         say(() => logger_1.logger.info(`Validating action: ${filePath}`));
     }
+    let failOn;
     if (contractFile) {
         say(() => logger_1.logger.info(`Validating against pipeline contract: ${contractFile}`));
         if (parsed.type !== 'workflow') {
@@ -411,18 +693,23 @@ async function validateOneFile(filePath, contractFile, recurse, say) {
         }
         else {
             const spec = (0, pipeline_contract_parser_1.parsePipelineContract)(contractFile);
+            failOn = spec.advisories?.failOn;
             const contractResult = await (0, pipeline_contract_validator_1.validatePipelineContract)(parsed, spec, {
-                recurse
+                recurse,
+                offline
             });
-            result = {
-                valid: result.valid && contractResult.valid,
-                errors: [...result.errors, ...contractResult.errors]
-            };
+            result = (0, validator_1.mergeValidationResults)(result, contractResult);
         }
     }
-    return result;
+    // Known security advisories for the file's own uses: references.
+    const { errors, report } = await (0, advisories_1.checkFileAdvisories)(parsed, advisories.checker, failOn);
+    advisories.reports.push(report);
+    return {
+        valid: result.valid && errors.every((e) => e.severity !== 'error'),
+        errors: [...result.errors, ...errors]
+    };
 }
-async function validateFiles(files, contractFile, recurse = 'local', format = 'text') {
+async function validateFiles(files, contractFile, recurse, format, offline) {
     // Only text mode narrates; json/sarif write nothing but the report to
     // stdout, so the output is pipeable.
     const quiet = format !== 'text';
@@ -438,8 +725,8 @@ async function validateFiles(files, contractFile, recurse = 'local', format = 't
     if (contractFile) {
         try {
             const source = await (0, contract_source_1.resolveContractSource)(contractFile, {
-                fetchFile: (uses) => (0, action_fetcher_1.fetchRepoFile)(uses),
-                resolveSha: (uses) => (0, action_fetcher_1.resolveActionSha)(uses),
+                fetchFile: (uses) => (0, action_fetcher_1.fetchRepoFile)(uses, { offline }),
+                resolveSha: async (uses) => offline ? undefined : (0, action_fetcher_1.resolveActionSha)(uses),
                 warn: (message) => logger_1.logger.warn(message)
             });
             contractPath = source.file;
@@ -460,12 +747,17 @@ async function validateFiles(files, contractFile, recurse = 'local', format = 't
             contractError = error instanceof Error ? error.message : 'Unknown error';
         }
     }
+    // One lookup per repository across all files (and a 24h disk cache).
+    const advisories = {
+        checker: new advisories_1.AdvisoryChecker({ offline }),
+        reports: []
+    };
     const entries = [];
     for (const filePath of files) {
         try {
             if (contractError)
                 throw new Error(contractError);
-            const result = await validateOneFile(filePath, contractPath, recurse, say);
+            const result = await validateOneFile(filePath, contractPath, recurse, say, advisories, offline);
             entries.push({ file: filePath, result });
         }
         catch (error) {
@@ -485,6 +777,16 @@ async function validateFiles(files, contractFile, recurse = 'local', format = 't
         }
     }
     const allValid = entries.every((e) => e.result.valid);
+    // What couldn't be checked, once for all files: warnings on stderr, and
+    // (text mode only) unknown versions as info. Findings are in the results.
+    for (const line of (0, advisories_1.describeReport)((0, advisories_1.mergeReports)(advisories.reports))) {
+        if (line.kind !== 'note')
+            continue;
+        if (line.level === 'warn')
+            logger_1.logger.warn(line.text);
+        else
+            say(() => logger_1.logger.info(line.text));
+    }
     if (quiet) {
         // eslint-disable-next-line no-console
         console.log((0, report_1.formatReport)(entries, format, { contract }));
@@ -512,7 +814,7 @@ function runInit(options) {
         process.exit(1);
     }
     const content = (0, init_1.renderInitWorkflow)({
-        version: readVersion(),
+        version: (0, version_1.readVersion)(),
         contract: options.contract,
         upload: options.upload
     });