`sbx kit pack`, `sbx kit push --sign`, and `sbx kit verify`

You wrote a v2 mixin that installs tree and drops a HELLO.md into the workspace. A colleague wants it without cloning your repository, and your security team wants to know who signed it. The sbx kit commands cover both, as long as the kit is v1 or v2.

When you finish this section, you can validate and pack a v2 kit, and describe what push --sign attaches to the manifest. You can also verify a signature and add a mixin to a running sandbox.

spec.yaml and files/

Mixin (v2): a directory with a spec.yaml whose schemaVersion is "2" and kind is mixin, plus an optional files/ tree. The capture kit wrote one:

schemaVersion: "2"
kind: mixin
name: hello-mixin
description: Installs tree and adds a greeting file to the workspace.
setup:
  install:
    - command: apt-get update && apt-get install -y tree
      user: "0"
      description: Install tree
permissions:
  network:
    allow:
      - example.com

files/workspace/HELLO.md holds one line, and sbx kit inspect reports it as a workspace file with mode 420 (the capture). The v2 grammar is the one the built-in agents use, and its normative text lives in SPEC-v2.md of docker/sbx-kits-contrib.

validate and pack

sbx kit validate REFERENCE accepts a directory, a ZIP, or a git reference, and --json reports a verdict and warnings:

{
  "reference": "./fixtures/kits/hello-mixin",
  "kind": "directory",
  "valid": true,
  "warnings": []
}

$ sbx kit pack ./fixtures/kits/hello-mixin -o $CAPTURE/work/hello-mixin.zip
Packed artifact to $CAPTURE/work/hello-mixin.zip
[exit 0]

$ zip listing of work/hello-mixin.zip (size, name)
       0  files/
       0  files/workspace/
      22  files/workspace/HELLO.md
     297  spec.yaml

For pack, the directory must hold a valid spec.yaml and can hold a files/ directory. The same ZIP validates with kind: "zip" (the capture). A v3 directory fails both commands, as the descriptor section showed. Figure 4.3 draws the whole path, with the steps the capture kit did not run in dashed boxes.

sign, push --sign, and pull

The capture kit ran none of these three, because it has no registry and no signing identity. The help text is the source. sbx kit sign is keyless by default, with an OIDC token from the CI provider or a browser login. It never reads a token from SIGSTORE_ID_TOKEN, so a process that can set an environment variable cannot choose the token. With --key it signs with an unencrypted PEM private key. For a local directory, it writes a detached signature bundle to kit.sig.bundle next to spec.yaml.

sbx kit push DIRECTORY REFERENCE chooses the artifact form from schemaVersion: a ZIP for "1", a tar+gzip layer with the spec in the config blob for "2". With --sign, the push signs the manifest and attaches the Sigstore bundle to the kit as an OCI referrer. Every push also attaches a SLSA provenance attestation as an OCI referrer, and that provenance is signed only with --sign. --tlog-upload=false keeps a private kit out of the Rekor log. For pull, the registry must support HTTPS.

The same command signs a published v3 image by reference. A v3 kit that you share as a source directory or a Git reference cannot be signed.

verify, provenance, and the settings that admit a kit

sbx kit verify takes --key PUB for a key, or --certificate-identity with --certificate-oidc-issuer for a keyless signature. --insecure-ignore-tlog accepts a private keyless signature, and the flag changes nothing for a key-based verification. sbx kit provenance REFERENCE prints the attestation, and it reports an attestation as VERIFIED only when it verifies and its subject matches the digest of the kit.

Six settings decide what a sandbox accepts, all at their defaults on the recording host:

kit.allowExtractedAgents             true                               bool     default             Admit the pinned kit references that replace fo…
kit.allowLocalKits                   true                               bool     default             Allow installing kits from local directories or…
kit.allowedSources                   ["docker.io/"]                     json     default             JSON array of allowed kit source prefixes (e.g.…
kit.ignoreTransparencyLog            false                              bool     default             Verify keyless kit signatures without requiring…
kit.requireSignature                 false                              bool     default             Require a valid signature from a trusted signer…
kit.trustedSigners                   [{"identityRegexp":"^.*@docker\…   json     default             JSON array of trusted signer policies (key-base…

When kit.requireSignature is true, sbx rejects unsigned kits, signatures that do not match kit.trustedSigners, and ZIP kits. The default kit.trustedSigners policy trusts Docker employee identities that end in @docker.com, attested by the Google issuer. The settings table lists the environment variable of each key.

kit add and the builder

sbx kit add SANDBOX REFERENCE recreates the container with the mixin added, and it keeps the volumes that kits own, such as agent session state, across the swap. The capture shows the accepted case and the refused one:

$ sbx kit add m101-demo ./fixtures/kits/env-mixin
Recreating sandbox "m101-demo" to apply augmented kit list...
  Swap container m101-demo-swap-<id> started (id=<sha256>).
Kit "env-mixin" added to sandbox "m101-demo"
[exit 0]

$ sbx exec m101-demo sh -c 'env | grep M101_FROM_KIT'
M101_FROM_KIT=yes
[exit 0]

$ sbx kit add m101-demo ./fixtures/kits/hello-mixin
error: kit "hello-mixin" declares files, which the kit-add recreate flow does not yet apply; recreate the sandbox from scratch via `sbx rm` + `sbx create --kit` to use this kit
[exit 1]

Sandboxes created before the recreate-aware label are refused with an error, and long-running@1 cannot be added this way. sbx create shell --kit ./fixtures/kits/hello-mixin applied the same mixin in full: one install command, one workspace file, and one allow rule (the captures).

Source-form builds of v3 kits run in a shared builder sandbox named sbx-kit-builder, which sbx creates on first use. sbx kit builder status reports it, and history passes through to docker buildx history:

$ sbx kit builder status
Builder:      not created (the first source-form kit build creates it)
Builder kit:  docker.io/docker/sbx-kit-builder:1
Kit registry: 127.0.0.1:5411 — reachable
[exit 0]