@secureci/cli 0.1.1 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@ Test and vet your GitHub Actions **before you push**.
 `@secureci/cli` (the `secureci` command) runs your workflows locally, validates
 them, and checks them against your organization's pipeline standards — without
 committing, pushing, or waiting on a CI runner. It is the free, open-source part
-of [SecureCI](https://www.secure-ci.dev).
+of [SecureCI](https://secure-ci.dev).
 
 > 📖 This README is the quick tour. Every flag, context and edge case lives in
 > the **[full reference → DOCS.md](DOCS.md)**.
@@ -38,8 +38,8 @@ npm install -g @secureci/cli
 npx @secureci/cli --help
 ```
 
-Node.js 20+ is required. (Until the package is published to npm, build from
-source: `npm install && npm run build`.)
+Node.js 20+ is required. To build from source instead:
+`npm install && npm run build`.
 
 ## First run
 
@@ -74,6 +74,11 @@ secureci inventory --check    # fail on drift (use in CI)
   check.
 - **Machine-readable output** — `--format json|sarif` drops straight into CI and
   GitHub code scanning.
+- **Audit evidence** — the contract, `secureci.lock` and reports are plain files
+  you can commit and keep. See
+  [using output as audit evidence](DOCS.md#using-output-as-audit-evidence) and
+  the [compliance mapping](https://secure-ci.dev/compliance) (PCI DSS, DORA,
+  NIS2, ISO 27001, SOC 2 and more).
 
 See the [reference](DOCS.md) for the complete command list and flags.
 

package/dist/cli.js

@@ -45,6 +45,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 +196,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 +284,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);
@@ -413,6 +434,7 @@ function runInit(options) {
         process.exit(1);
     }
     const content = (0, init_1.renderInitWorkflow)({
+        version: readVersion(),
         contract: options.contract,
         upload: options.upload
     });

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/init.js

@@ -3,7 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderInitWorkflow = renderInitWorkflow;
 /**
  * Render a ready-to-commit `.github/workflows/secureci.yml` that runs SecureCI
- * on every pull request via the published `secure-ci/cli` action.
+ * on every pull request via the published `secure-ci/cli` action, pinned to
+ * the release tag matching this CLI's version.
  *
  * The output is deterministic for a given set of options, so it can be
  * regenerated and diffed. With uploads on (the default) the workflow asks for
@@ -26,7 +27,7 @@ function renderInitWorkflow(options) {
     ];
     if (upload)
         lines.push('  security-events: write');
-    lines.push('', 'jobs:', '  secureci:', '    runs-on: ubuntu-latest', '    steps:', '      - uses: actions/checkout@v4', '      - uses: secure-ci/cli@v1');
+    lines.push('', 'jobs:', '  secureci:', '    runs-on: ubuntu-latest', '    steps:', '      - uses: actions/checkout@v4', `      - uses: secure-ci/cli@v${options.version}`);
     const withLines = [];
     if (contract)
         withLines.push(`          contract: ${yamlScalar(contract)}`);

package/dist/report.js

@@ -59,7 +59,7 @@ function formatReport(entries, format) {
                 tool: {
                     driver: {
                         name: 'secureci',
-                        informationUri: 'https://www.secure-ci.dev',
+                        informationUri: 'https://secure-ci.dev',
                         rules: Object.entries(RULES).map(([id, name]) => ({ id, name }))
                     }
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secureci/cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "SecureCI: validate, check against pipeline standards, and run GitHub Actions workflows locally",
   "main": "dist/index.js",
   "bin": {
@@ -42,7 +42,7 @@
     }
   ],
   "license": "MIT",
-  "homepage": "https://www.secure-ci.dev",
+  "homepage": "https://secure-ci.dev",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/secure-ci/cli.git"