@secureci/cli 0.9.0 → 1.0.0

package/README.md

@@ -36,22 +36,62 @@ far fewer false positives than plain pattern-matching tools.
 
 ## Install
 
+There are two ways to install it: from npm (needs Node.js 20+), or as a
+[standalone binary](#standalone-binary-no-nodejs-needed) for Linux, macOS or
+Windows that needs no Node.js.
+
 ```bash
 npm install -g @secureci/cli
 # or run without installing:
 npx @secureci/cli --help
 ```
 
-Node.js 20+ is required. To build from source instead:
-`npm install && npm run build`.
+To build from source instead: `npm install && npm run build`.
 
 ### Standalone binary (no Node.js needed)
 
-Each [release](https://github.com/secure-ci/cli/releases) has a single-file
-binary for Linux (x64, arm64), macOS (Intel, Apple silicon) and Windows (x64),
-a `SHA256SUMS` file, and a signed build-provenance attestation. Pick the asset
-for your platform: `secureci-linux-x64`, `secureci-linux-arm64`,
-`secureci-darwin-x64`, `secureci-darwin-arm64` or `secureci-win-x64.exe`.
+On macOS or Linux, the install script picks the binary for your platform,
+checks it against the release's `SHA256SUMS` (a mismatch aborts), verifies its
+build provenance when the [GitHub CLI](https://cli.github.com) is signed in, and
+installs it to `~/.local/bin` without `sudo`:
+
+```bash
+curl -fsSL https://secure-ci.dev/install.sh | sh
+```
+
+To read the script before running it ([source](install.sh)):
+
+```bash
+curl -fsSL https://secure-ci.dev/install.sh -o install.sh
+less install.sh
+sh install.sh
+```
+
+Set `SECURECI_VERSION=1.0.0` to install a specific release,
+`SECURECI_INSTALL_DIR` to install somewhere else, and
+`SECURECI_REQUIRE_ATTESTATION=1` to fail unless `gh` verifies build provenance
+(e.g. `curl -fsSL https://secure-ci.dev/install.sh | SECURECI_VERSION=1.0.0 sh`).
+`secure-ci.dev/install.sh` redirects to [`install.sh`](install.sh) on this
+repository's `main` branch.
+
+Or download a binary yourself. Every [release](https://github.com/secure-ci/cli/releases/latest) has a
+single-file binary for each platform below. The links always point to the
+latest release:
+
+| Platform              | Download                                                                                                   |
+| --------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Linux x64             | [`secureci-linux-x64`](https://github.com/secure-ci/cli/releases/latest/download/secureci-linux-x64)       |
+| Linux arm64           | [`secureci-linux-arm64`](https://github.com/secure-ci/cli/releases/latest/download/secureci-linux-arm64)   |
+| macOS (Apple silicon) | [`secureci-darwin-arm64`](https://github.com/secure-ci/cli/releases/latest/download/secureci-darwin-arm64) |
+| macOS (Intel)         | [`secureci-darwin-x64`](https://github.com/secure-ci/cli/releases/latest/download/secureci-darwin-x64)     |
+| Windows x64           | [`secureci-win-x64.exe`](https://github.com/secure-ci/cli/releases/latest/download/secureci-win-x64.exe)   |
+| Checksums             | [`SHA256SUMS`](https://github.com/secure-ci/cli/releases/latest/download/SHA256SUMS)                       |
+
+Before you run a binary, check it against `SHA256SUMS`. Each binary also has a
+signed build-provenance attestation, which `gh attestation verify` checks. The
+commands below download, verify and install it in one go. To install a
+specific version, take its assets from that version's
+[release page](https://github.com/secure-ci/cli/releases).
 
 ```bash
 # macOS / Linux (here: Linux x64)
@@ -107,6 +147,17 @@ secureci inventory --check    # fail on drift (use in CI)
 secureci pin
 ```
 
+### Agent skill
+
+[`skills/secureci`](skills/secureci/SKILL.md) walks a coding agent (Claude Code,
+Codex, Cursor, …) through setting SecureCI up in a repo: pin actions, commit
+`secureci.lock`, and add the `secure-ci/cli` action as a step in an existing job
+(replacing `actionlint` if present).
+
+```bash
+npx skills add secure-ci/cli --skill secureci
+```
+
 ## Where it shines
 
 - **Fast feedback loop** — iterate on a workflow in seconds instead of

package/dist/cli.js

@@ -278,8 +278,10 @@ initCommand
     .option('--no-upload', 'Do not upload SARIF to code scanning (keeps contents: read only)')
     .option('-o, --output <path>', 'Where to write the workflow', '.github/workflows/secureci.yml')
     .option('-f, --force', 'Overwrite the output file if it already exists')
-    .action((options) => {
-    runInit(options);
+    .option('--no-pin', 'Keep tag refs (e.g. actions/checkout@v4) instead of pinning them to commit SHAs')
+    .option('--offline', 'Pin only refs already in the action cache; others keep their tag')
+    .action(async (options) => {
+    await runInit(options);
 });
 function defaultWorkflowFiles() {
     const dir = path.join(process.cwd(), '.github', 'workflows');
@@ -808,22 +810,36 @@ async function validateFiles(files, contractFile, recurse, format, offline) {
     if (!allValid)
         process.exit(1);
 }
-function runInit(options) {
+async function runInit(options) {
     const output = path.resolve(process.cwd(), options.output);
     if (fs.existsSync(output) && !options.force) {
         logger_1.logger.error(`${options.output} already exists; pass --force to overwrite it.`);
         process.exit(1);
     }
-    const content = (0, init_1.renderInitWorkflow)({
+    let unpinned = [];
+    let content = (0, init_1.renderInitWorkflow)({
         version: (0, version_1.readVersion)(),
         contract: options.contract,
         upload: options.upload
     });
+    // Pin action tags to commit SHAs (`owner/repo@<sha> # v4`), as
+    // `secureci pin` would. A ref that can't be resolved keeps its tag.
+    if (options.pin) {
+        const result = await (0, pin_1.pinContent)(content, (uses) => options.offline
+            ? Promise.resolve((0, action_fetcher_1.cachedActionSha)(uses))
+            : (0, action_fetcher_1.resolveActionSha)(uses));
+        content = result.content;
+        unpinned = result.unresolved;
+    }
     fs.mkdirSync(path.dirname(output), { recursive: true });
     fs.writeFileSync(output, content);
     logger_1.logger.success(`Wrote ${options.output}`);
+    for (const problem of unpinned) {
+        logger_1.logger.warn(`${problem.uses} ${problem.reason}; left on its tag. Run \`secureci pin ${options.output}\` to pin it later.`);
+    }
     if (options.upload) {
-        logger_1.logger.info('The workflow uploads SARIF to code scanning (needs security-events: write).');
+        logger_1.logger.info('The workflow uploads SARIF to code scanning (needs actions: read and security-events: write).');
+        logger_1.logger.info('Code scanning must be enabled for the repository (Settings > Code security) for the SARIF upload to work; otherwise regenerate with --no-upload.');
     }
     logger_1.logger.info('Commit it and open a pull request to see SecureCI run.');
 }

package/dist/init.js

@@ -8,7 +8,8 @@ exports.renderInitWorkflow = renderInitWorkflow;
  *
  * The output is deterministic for a given set of options, so it can be
  * regenerated and diffed. With uploads on (the default) the job asks for
- * `security-events: write` and lets the action upload SARIF; with uploads off
+ * `actions: read` and `security-events: write` and lets the action upload
+ * SARIF; with uploads off
  * it keeps `contents: read` only and passes `upload-sarif: false`.
  */
 function renderInitWorkflow(options) {
@@ -31,8 +32,11 @@ function renderInitWorkflow(options) {
     ];
     // Write scopes belong on the job, not the workflow. Job-level permissions
     // replace the top-level ones, so contents: read is repeated for checkout.
+    // The SARIF upload (github/codeql-action/upload-sarif) needs actions: read
+    // to read the workflow run (required on private repositories) and
+    // security-events: write to upload the results.
     if (upload) {
-        lines.push('    permissions:', '      contents: read', '      security-events: write');
+        lines.push('    # The SARIF upload needs code scanning enabled for this repository', '    # (Settings > Code security; on private repositories this needs', '    # GitHub Code Security / Advanced Security). Without it the upload', '    # step fails: enable it, or give the secure-ci/cli step', '    # `with: upload-sarif: false` (and drop the two scopes below).', '    permissions:', '      contents: read', '      actions: read # upload-sarif reads the workflow run', '      security-events: write # upload SARIF to code scanning');
     }
     lines.push('    steps:', '      - uses: actions/checkout@v4', `      - uses: secure-ci/cli@v${options.version}`);
     const withLines = [];

package/dist/runner/builtin-actions.js

@@ -391,7 +391,7 @@ async function uploadArtifact(fsys, inputs, runId) {
         copyFile(file.host, path.join(target, ...rel.split('/')));
         digest.update(rel).update(fs.readFileSync(file.host));
     }
-    const id = String(parseInt(crypto.createHash('sha1').update(target).digest('hex').slice(0, 8), 16));
+    const id = String(parseInt(crypto.createHash('sha256').update(target).digest('hex').slice(0, 8), 16));
     return ok(`Uploaded ${files.length} file(s) as artifact "${name}" to ${target}`, {
         'artifact-id': id,
         'artifact-url': '',

package/dist/runner/docker-action.js

@@ -90,7 +90,7 @@ async function executeDockerAction(action, actionPath, step, actionInputs, calle
                 duration: Date.now() - startTime
             };
         }
-        const tag = `secureci-action-${crypto.createHash('sha1').update(actionDir).digest('hex').slice(0, 12)}`;
+        const tag = `secureci-action-${crypto.createHash('sha256').update(actionDir).digest('hex').slice(0, 12)}`;
         logger_1.logger.info(`Building Docker action image: ${action.name} (${tag})`);
         const buildResult = await containerRuntime.build(actionDir, tag, dockerfileRelative);
         if (!buildResult.success) {

package/dist/runner/job-runtime.js

@@ -285,7 +285,7 @@ function actionDirInContainer(container, actionDir) {
     let containerDir = container.actionDirs.get(actionDir);
     if (!containerDir) {
         const hash = crypto
-            .createHash('sha1')
+            .createHash('sha256')
             .update(actionDir)
             .digest('hex')
             .slice(0, 12);

package/package.json

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