From 638c40d5d150b2dc66f6c450844c7a40d59abc7d Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 29 Jun 2026 10:05:43 +0200 Subject: [PATCH 1/2] docs(sandboxes): document kit install-source allowlist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit sbx v0.34 (docker/sandboxes#3566) restricts which sources a kit can be installed from via two new settings, secure by default: - kit.allowedSources (default ["docker.io/"]) — host/path prefixes for remote refs; ["*"] is the escape hatch. - kit.allowLocalKits (default true) — toggle for local dir/ZIP installs. This is a breaking change for installs from non-Docker Hub sources (for example git+https://github.com/docker/...), and it is undocumented on the docs site. Document it in the kits page, add a troubleshooting entry for the "source is not in your allowlist" failure, and note the supply-chain control in the security model. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../manuals/ai/sandboxes/customize/kits.md | 37 +++++++++++++++++++ .../manuals/ai/sandboxes/security/_index.md | 5 +++ .../manuals/ai/sandboxes/troubleshooting.md | 21 +++++++++++ 3 files changed, 63 insertions(+) diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md index 8aeb1596d0d3..ab7410880329 100644 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ b/content/manuals/ai/sandboxes/customize/kits.md @@ -443,6 +443,43 @@ For Docker Hub, include the full `docker.io` prefix. See > Without stored credentials, pulls from non-Docker Hub registries are > anonymous and private kits fail to pull. +### Restrict kit sources + +`sbx` restricts which sources a kit can install from. A kit's install +commands run with root privileges inside the sandbox, so limiting where kits +come from reduces supply-chain risk. By default, only kits hosted on Docker +Hub (`docker.io/`) are allowed. Loading a kit from any other source — a Git +repository or a different registry — fails: + +```console +$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale" +ERROR: resolve kits: kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale" cannot be installed — its source is not in your allowlist. +``` + +To allow another publisher, add its host or host/path prefix to the +`kit.allowedSources` setting. The setting replaces the whole list, so include +the entries you want to keep: + +```console +$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]' +``` + +Entries match as prefixes on a path-segment boundary, so `github.com/docker/` +allows `github.com/docker/sbx-kits-contrib` but not `github.com/docker-evil/kit`. +To remove the restriction and allow any remote source, set the list to +`["*"]`. This isn't recommended. + +Installing from a local directory or ZIP file is governed separately by the +`kit.allowLocalKits` setting, which defaults to `true`. Set it to `false` to +require a remote source: + +```console +$ sbx settings set kit.allowLocalKits false +``` + +For non-interactive use, both settings have environment-variable equivalents: +`DOCKER_SANDBOXES_KIT_ALLOWED_SOURCES` and `DOCKER_SANDBOXES_KIT_ALLOW_LOCAL`. + ## Packaging and distribution The `sbx kit` subcommands validate, inspect, and publish kits: diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 50919e94faf4..2991f9bcf81a 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -86,6 +86,11 @@ The default allowed domains include broad wildcards. Some defaults like see the full list of active rules, and remove entries you don't need. See [Default security posture](defaults/). +Kits run install commands with root privileges inside the sandbox. To limit +supply-chain risk, `sbx` restricts kit installs to an allowlist of sources +that defaults to Docker Hub only. See +[Restrict kit sources](../customize/kits.md#restrict-kit-sources). + ## Organization-wide control On a single developer's machine, security and policy are configured locally — diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index c3fb70579219..ad50929dafb5 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -54,6 +54,27 @@ If `sbx policy allow` doesn't unblock the request, your organization may manage sandbox policies centrally and take precedence over local rules. See [Organization governance](governance/org.md). +## Kit fails to install: source not in allowlist + +If loading a kit fails with a message like its source is not in your +allowlist: + +```console +$ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale" +ERROR: resolve kits: kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale" cannot be installed — its source is not in your allowlist. +``` + +`sbx` restricts kit installs to an allowlist of sources, which defaults to +Docker Hub (`docker.io/`) only. Add the kit's publisher to the +`kit.allowedSources` setting, keeping the entries you want to retain: + +```console +$ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]' +``` + +Then run the command again. For details, including how to allow local kits or +any remote source, see [Restrict kit sources](customize/kits.md#restrict-kit-sources). + ## SSH and other non-HTTP connections fail Non-HTTP TCP connections like SSH can be allowed by adding a policy rule for From 81a6acc5ba5571f82f2c7ca730ea3bb260717966 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Mon, 29 Jun 2026 10:11:53 +0200 Subject: [PATCH 2/2] docs(sandboxes): tighten kit-source wording Co-Authored-By: Claude Opus 4.8 (1M context) --- content/manuals/ai/sandboxes/customize/kits.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md index ab7410880329..0e66ef55a47a 100644 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ b/content/manuals/ai/sandboxes/customize/kits.md @@ -448,8 +448,7 @@ For Docker Hub, include the full `docker.io` prefix. See `sbx` restricts which sources a kit can install from. A kit's install commands run with root privileges inside the sandbox, so limiting where kits come from reduces supply-chain risk. By default, only kits hosted on Docker -Hub (`docker.io/`) are allowed. Loading a kit from any other source — a Git -repository or a different registry — fails: +Hub (`docker.io/`) are allowed. Loading a kit from any other source fails: ```console $ sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vale"