@secureci/cli 0.2.0 → 0.4.0

package/dist/cli.js

@@ -38,6 +38,7 @@ const commander_1 = require("commander");
 const dry_run_1 = require("./runner/dry-run");
 const executor_1 = require("./runner/executor");
 const action_fetcher_1 = require("./runner/action-fetcher");
+const contract_source_1 = require("./contract-source");
 const validator_1 = require("./parser/validator");
 const workflow_parser_1 = require("./parser/workflow-parser");
 const pipeline_contract_parser_1 = require("./parser/pipeline-contract-parser");
@@ -45,6 +46,7 @@ const pipeline_contract_validator_1 = require("./parser/pipeline-contract-valida
 const report_1 = require("./report");
 const init_1 = require("./init");
 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 config_1 = require("./config");
@@ -195,7 +197,7 @@ program
     .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`)
-    .option('--check', `Compare the current commit SHAs against ./${LOCKFILE_NAME} and fail on drift`)
+    .option('--check', `Compare the current commit SHAs against ./${LOCKFILE_NAME} (or GitHub's ${github_lockfile_1.GITHUB_LOCKFILE} when that is the only lockfile) and fail on drift`)
     .option('--compare', `Alias of --check`)
     .action(async (files, options) => {
     await runInventory(files, options);
@@ -283,38 +285,58 @@ async function runInventory(files, options) {
         return;
     }
     const lockPath = path.join(process.cwd(), LOCKFILE_NAME);
-    const lockExists = fs.existsSync(lockPath);
+    // secureci.lock is first-class; GitHub's actions.lock is used only when
+    // it is the lockfile the repository provides.
+    const source = (0, github_lockfile_1.findLockfile)(process.cwd());
     const writeLock = () => {
         const updated = { version: 1, actions: current };
         fs.writeFileSync(lockPath, JSON.stringify(updated, null, 2) + '\n');
         logger_1.logger.success(`Wrote ${Object.keys(current).length} action(s) to ${LOCKFILE_NAME}. Commit it to track supply-chain drift.`);
     };
     // `--update-lock`, or bare `inventory` when no lockfile exists yet: write it.
-    if (update || (!check && !lockExists)) {
+    if (update || (!check && !source)) {
         writeLock();
         return;
     }
     // Otherwise compare (explicit `--check`, or bare `inventory` with a lockfile).
-    if (!lockExists) {
-        logger_1.logger.error(`No ${LOCKFILE_NAME} found. Create one with: secureci inventory --update-lock`);
+    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);
     }
-    const lock = JSON.parse(fs.readFileSync(lockPath, 'utf-8'));
+    const github = source.kind === 'github';
+    const lockName = github ? 'actions.lock' : LOCKFILE_NAME;
+    const fixHint = github
+        ? 'run `gh actions-lock` to update actions.lock'
+        : 'run with --update-lock to accept it';
+    let lock;
+    try {
+        const text = fs.readFileSync(source.file, 'utf-8');
+        lock = github ? (0, github_lockfile_1.parseGitHubLockfile)(text) : JSON.parse(text);
+    }
+    catch (error) {
+        logger_1.logger.error(`Could not read ${lockName}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        process.exit(1);
+    }
+    logger_1.logger.info(`Checking against ${github ? github_lockfile_1.GITHUB_LOCKFILE : LOCKFILE_NAME}`);
     const diff = (0, inventory_1.diffLock)(current, lock);
     for (const d of diff.drifted) {
         logger_1.logger.error(`Drift: ${d.uses} now resolves to ${d.to.slice(0, 12)} (was ${d.from.slice(0, 12)})`);
     }
-    diff.added.forEach((u) => logger_1.logger.warn(`New action not in ${LOCKFILE_NAME}: ${u}`));
-    diff.removed.forEach((u) => logger_1.logger.info(`In ${LOCKFILE_NAME} but no longer used: ${u}`));
+    diff.added.forEach((u) => logger_1.logger.warn(`New action not in ${lockName}: ${u}`));
+    // actions.lock also records transitive dependencies, which SecureCI
+    // doesn't scan, so "no longer used" only means something for secureci.lock.
+    if (!github) {
+        diff.removed.forEach((u) => logger_1.logger.info(`In ${lockName} but no longer used: ${u}`));
+    }
     if (diff.drifted.length > 0) {
-        logger_1.logger.error(`Action commits drifted from ${LOCKFILE_NAME}. Review the change, then run with --update-lock to accept it.`);
+        logger_1.logger.error(`Action commits drifted from ${lockName}. Review the change, then ${fixHint}.`);
         process.exit(1);
     }
     if (diff.added.length > 0) {
-        logger_1.logger.warn(`New actions are not yet in ${LOCKFILE_NAME} (run --update-lock).`);
+        logger_1.logger.warn(`New actions are not yet in ${lockName} (${fixHint}).`);
         process.exit(1);
     }
-    logger_1.logger.success(`No action drift against ${LOCKFILE_NAME}.`);
+    logger_1.logger.success(`No action drift against ${lockName}.`);
 }
 async function validateOneFile(filePath, contractFile, recurse, say) {
     const parsed = (0, workflow_parser_1.parseFile)(filePath);
@@ -363,10 +385,42 @@ async function validateFiles(files, contractFile, recurse = 'local', format = 't
         if (!quiet)
             fn();
     };
+    // A contract may be a local file or `owner/repo/path@ref` in another
+    // repository; resolve it once and record which version was enforced.
+    let contractPath = contractFile;
+    let contract;
+    let contractError;
+    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),
+                warn: (message) => logger_1.logger.warn(message)
+            });
+            contractPath = source.file;
+            const remote = source.remote;
+            contract = remote
+                ? {
+                    source: remote.uses,
+                    ref: remote.ref,
+                    commit: remote.commit,
+                    pinned: remote.pinned
+                }
+                : { source: contractFile };
+            if (remote) {
+                say(() => logger_1.logger.info(`Using contract ${remote.uses}${remote.commit ? ` at commit ${remote.commit.slice(0, 12)}` : ''}`));
+            }
+        }
+        catch (error) {
+            contractError = error instanceof Error ? error.message : 'Unknown error';
+        }
+    }
     const entries = [];
     for (const filePath of files) {
         try {
-            const result = await validateOneFile(filePath, contractFile, recurse, say);
+            if (contractError)
+                throw new Error(contractError);
+            const result = await validateOneFile(filePath, contractPath, recurse, say);
             entries.push({ file: filePath, result });
         }
         catch (error) {
@@ -388,7 +442,7 @@ async function validateFiles(files, contractFile, recurse = 'local', format = 't
     const allValid = entries.every((e) => e.result.valid);
     if (quiet) {
         // eslint-disable-next-line no-console
-        console.log((0, report_1.formatReport)(entries, format));
+        console.log((0, report_1.formatReport)(entries, format, { contract }));
         if (!allValid)
             process.exit(1);
         return;

package/dist/contract-source.js

@@ -0,0 +1,63 @@
+"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.resolveContractSource = resolveContractSource;
+const fs = __importStar(require("fs"));
+// owner/repo/path/to/file@ref: the same form as a remote reusable workflow.
+const REMOTE_CONTRACT = /^[^/.][^/]*\/[^/@]+\/[^@]+@([^@]+)$/;
+const FULL_SHA = /^[0-9a-f]{40}$/;
+/**
+ * Where to read `--contract` from. An existing local file always wins;
+ * otherwise `owner/repo/path@ref` is fetched like a remote reusable workflow.
+ * A ref that isn't a commit SHA can change under you, so it warns.
+ */
+async function resolveContractSource(value, deps) {
+    if (fs.existsSync(value))
+        return { file: value };
+    const match = REMOTE_CONTRACT.exec(value);
+    if (!match)
+        throw new Error(`Contract file not found: ${value}`);
+    const ref = match[1];
+    const pinned = FULL_SHA.test(ref);
+    if (!pinned) {
+        deps.warn(`Contract ${value} uses the moving ref "${ref}": its owner can change the standard without a change in this repository. Pin it to a commit SHA to control when it changes.`);
+    }
+    const file = await deps.fetchFile(value);
+    if (!file)
+        throw new Error(`Could not fetch contract ${value}`);
+    const commit = pinned ? ref : await deps.resolveSha(value);
+    return { file, remote: { uses: value, ref, commit, pinned } };
+}
+//# sourceMappingURL=contract-source.js.map

package/dist/github-lockfile.js

@@ -0,0 +1,90 @@
+"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.GITHUB_LOCKFILE = exports.SECURECI_LOCKFILE = void 0;
+exports.findLockfile = findLockfile;
+exports.parseGitHubLockfile = parseGitHubLockfile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const YAML = __importStar(require("yaml"));
+/** SecureCI's own lockfile, at the repository root. */
+exports.SECURECI_LOCKFILE = 'secureci.lock';
+/**
+ * GitHub's workflow dependency lockfile, written by `gh actions-lock`
+ * (public preview). See
+ * https://docs.github.com/actions/concepts/security/workflow-dependency-lockfiles
+ */
+exports.GITHUB_LOCKFILE = path.join('.github', 'workflows', 'actions.lock');
+/**
+ * Versions of GitHub's format this release reads. The format is pre-1.0 and
+ * may change, so an unknown version is an error rather than a guess.
+ */
+const SUPPORTED_GITHUB_VERSIONS = ['v0.0.2', 'v0.0.3'];
+const SHA1_COMMIT = /^sha1-([0-9a-f]{40})$/;
+/**
+ * The lockfile to check against: `secureci.lock` when present (it stays
+ * first-class), otherwise GitHub's `actions.lock`, otherwise none.
+ */
+function findLockfile(repoRoot) {
+    const secureci = path.join(repoRoot, exports.SECURECI_LOCKFILE);
+    if (fs.existsSync(secureci))
+        return { kind: 'secureci', file: secureci };
+    const github = path.join(repoRoot, exports.GITHUB_LOCKFILE);
+    if (fs.existsSync(github))
+        return { kind: 'github', file: github };
+    return undefined;
+}
+/**
+ * Read GitHub's `actions.lock` as a `uses -> commit` map, the same shape as
+ * `secureci.lock`. It includes transitive dependencies (actions that your
+ * actions use), which SecureCI doesn't scan.
+ */
+function parseGitHubLockfile(text) {
+    const doc = YAML.parse(text);
+    const version = String(doc?.version ?? '');
+    if (!SUPPORTED_GITHUB_VERSIONS.includes(version)) {
+        throw new Error(`Unsupported actions.lock version "${version}" (this release reads ${SUPPORTED_GITHUB_VERSIONS.join(', ')}). Update @secureci/cli, or use ${exports.SECURECI_LOCKFILE}.`);
+    }
+    const actions = {};
+    for (const [uses, dep] of Object.entries(doc?.dependencies ?? {})) {
+        const match = SHA1_COMMIT.exec(String(dep?.commit ?? ''));
+        if (!match) {
+            throw new Error(`actions.lock entry ${uses} has no sha1 commit (got "${String(dep?.commit)}").`);
+        }
+        actions[uses] = match[1];
+    }
+    return { version: 1, actions };
+}
+//# sourceMappingURL=github-lockfile.js.map

package/dist/report.js

@@ -41,13 +41,15 @@ function sarifResults(entry) {
  * carrying every file's findings, suitable for GitHub code scanning (upload
  * with `github/codeql-action/upload-sarif`).
  */
-function formatReport(entries, format) {
+function formatReport(entries, format, meta = {}) {
+    const contract = meta.contract ? { contract: meta.contract } : {};
     if (format === 'json') {
         const body = entries.length === 1
-            ? jsonForFile(entries[0])
+            ? { ...jsonForFile(entries[0]), ...contract }
             : {
                 valid: entries.every((e) => e.result.valid),
-                files: entries.map(jsonForFile)
+                files: entries.map(jsonForFile),
+                ...contract
             };
         return JSON.stringify(body, null, 2);
     }
@@ -63,7 +65,8 @@ function formatReport(entries, format) {
                         rules: Object.entries(RULES).map(([id, name]) => ({ id, name }))
                     }
                 },
-                results: entries.flatMap(sarifResults)
+                results: entries.flatMap(sarifResults),
+                ...(meta.contract ? { properties: contract } : {})
             }
         ]
     }, null, 2);

package/package.json

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