sandbox-ci

name

sandbox-ci

description

Harden a repo's CI/cron with the read-only, no-Docker gates of the `sandbox` CLI (@jagreehal/sandbox-node) — `verify` (the sandbox boundary is committed and un-loosened), `delta` (gate only the dependency changes a PR introduces), `scan` (retroactive malware sweep over the committed lockfile), `secrets` (committed-credential tripwire), and signed `verify --sign` receipts. Use when the user wants a CI gate for supply-chain risk, a PR check for new dependencies, a scheduled malware re-scan, a committed-secret check, a "sandboxed" badge, or asks to "add sandbox to CI" / "gate dependency changes".

sandbox-ci

These commands are the CI/cron half of sandbox: read-only, no container, no Docker. Each is a tripwire — it exits non-zero on a real problem, so it drops straight into a CI step. None of them install anything.

Pick by what you're gating:

Want to gate	Command	Exits non-zero when
The boundary itself is real and committed	sandbox verify	the repo doesn't commit a genuine sandbox boundary, or a personal layer loosened it
Only what a PR's dependency change introduces	sandbox delta	an added/bumped version trips the release-age / malware / deprecation gate
Already-installed deps that turned malicious later	sandbox scan	any version in the committed lockfile is NOW flagged as malware (OSV)
Credentials committed to the repo	sandbox secrets	any API key / token / private key / db URL is found (value redacted)

Recipes

• PR check — gate only the change (low-noise, the one to reach for first):

  sandbox delta --min-release-age 7 --fail-on-advisory
  

  Diffs the lockfile against the merge base (default origin/main; --base <ref> or --base-lockfile <path> to override) and runs the gates over just the added/bumped versions. A bare sandbox check/preflight re-gates every dependency, which trips release-age on already-vetted committed packages — noise, not new risk. Use delta for PRs; reserve full check for when you're genuinely adding packages (see the sandbox-install skill).

• Scheduled malware re-scan (cron/nightly):

  sandbox scan
  

  Re-queries OSV for the versions you already have installed. Catches dependencies that turned malicious after you installed them — the gap install-time gating can't cover. No Docker.

• Committed-secret tripwire:

  sandbox secrets        # defaults to cwd; pass a path to scope it
  

  Offline, ~40 provider patterns with checksum/decode validation (Luhn, JWT) to cut noise. Reports where, never the secret. The sandbox keeps host secrets OUT of installs; this catches the other half — a key committed into the repo.

• Boundary gate (and the badge it backs):

  sandbox verify              # fail unless a real, un-loosened boundary is committed
  sandbox verify --scan       # also run the retroactive malware sweep
  sandbox verify --secrets    # also fail if a credential is committed
  

  verify --scan --secrets makes a green run mean "boundary intact AND no installed dep is currently flagged AND no secret committed." sandbox badge prints the markdown badge; --workflow sandbox.yml makes it the CI-backed verified badge.

• Signed receipts (attest a green boundary):

  sandbox keygen                                   # Ed25519 keypair: private → CI secret
  SANDBOX_SIGNING_KEY=key sandbox verify --sign     # emits a signed receipt to stdout (only if every gate passed)
  sandbox verify-receipt receipt.json --fingerprint <hex>   # verify; pin the signer
  

  --sign refuses to sign if any requested check failed, so a receipt can never attest a green boundary over a red one.

Rules

• These are tripwires — wire them to fail the job. Don't swallow the exit code; the non-zero IS the gate.
• delta for PRs, check/preflight for genuinely-new packages, scan for cron. Using a full check as a PR gate on an active project produces release-age noise on already-vetted deps; reach for delta.
• No Docker needed for any command here — they query the registry/OSV and read files. Don't add a container step.
• Tighten with the same flags as install: --min-release-age <days>, --fail-on-advisory, --fail-on-risk. The strict preset sets sensible CI defaults (sandbox init --preset strict).
• When a CI step runs the real install in the container (e.g. sandbox npm ci), add --fail-on-source-writes (config install.failOnSourceWrites, on in strict): it fails the job if the install edited your source tree outside deps/lockfiles. The edit still happened (the tree is writable) — this is a detect-and-fail tripwire, and the changed files are also in the audit log as an install.source-write event. Unlike the gates above, this one needs the container.
• A non-malware advisory never changes the exit code (same as the install path) — there's no "block on any advisory" flag. Say so plainly rather than implying one exists.
• verify is about the committed boundary, not a live run — it's how you stop a PR from quietly loosening containment for the whole team.

See docs/reference.md for the full flag list, the receipt/audit-log format, and CI workflow examples.