Skip to content

chore(agent-isolation): pin bubblewrap 0.13.0 with a 1-day cooldown #1360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
potiuk merged 1 commit into from
Sep 23, 2026
Merged

chore(agent-isolation): pin bubblewrap 0.13.0 with a 1-day cooldown #1360

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/adapters/gemini.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -364,7 +364,7 @@ Apply the approved cleanup before removing the framework source so no known hook
Repeat verification after upgrades.
- **Validation scope:** native API tests cover policy decisions across four approval modes and interactive/headless execution.
The Linux adopter pilot exercised skill loading, the setup lifecycle, guard behavior, and shell/native-edit approval; interactive Plan Mode and authenticated MCP workflows remain unverified.
The pilot and live sandbox probes used bubblewrap 0.6.1, below the framework's 0.11.2 pin, so they do not establish validation with the [pinned primitives](../../tools/agent-isolation/pinned-versions.toml).
The pilot and live sandbox probes used bubblewrap 0.6.1, below the framework's 0.13.0 pin, so they do not establish validation with the [pinned primitives](../../tools/agent-isolation/pinned-versions.toml).

## Developer checks

Expand Down
31 changes: 17 additions & 14 deletions docs/setup/secure-agent-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,7 @@ The same flow, condensed to commands you run yourself:
# section: "Required tools" below. claude-code is unpinned —
# always install the latest for the newest security fixes.
sudo apt-get install --no-install-recommends \
bubblewrap=0.11.2-* socat=1.8.1.3-*
bubblewrap=0.13.0-* socat=1.8.1.3-*
npm install -g --no-save @anthropic-ai/claude-code@latest

# 2. Project-scope `.claude/settings.json`. Copy the framework's
Expand Down Expand Up @@ -273,7 +273,7 @@ The current pins live in machine-readable form in

| Tool | Pinned version | Released | Cooldown | Purpose |
|---|---|---|---|---|
| `bubblewrap` | 0.11.2 | 2026-04-23 | 7d (default) | Linux user-namespace sandbox (filesystem layer). Required on Linux; macOS uses Seatbelt instead. |
| `bubblewrap` | 0.13.0 | 2026-09-22 | 1d | Linux user-namespace sandbox (filesystem layer). Required on Linux; macOS uses Seatbelt instead. |
| `socat` | 1.8.1.3 | 2026-06-26 | 7d (default) | TCP relay for the sandbox network allowlist. Linux only. |
| `claude-code` | *(unpinned — `@latest`)* | — | none | Agent harness. Installed at the latest release so it always carries the newest permission-rule / sandbox / prompt-injection fixes; not in the pin manifest. |

Expand Down Expand Up @@ -307,25 +307,28 @@ distro. Choose whichever applies to your host.
```bash
sudo apt-get update
sudo apt-get install --no-install-recommends \
bubblewrap=0.11.2-* \
bubblewrap=0.13.0-* \
socat=1.8.1.3-*
```

> **Debian stable (bookworm) caveat.** The pinned `bubblewrap 0.11.2`
> is not available on Debian bookworm — bookworm ships an older
> `bubblewrap`, and an adopter reported the `0.11.x` line not working
> there. `0.11.x` ships in **Debian trixie**, so the supported path is
> to run the secure setup on **trixie** (or newer). If you must stay on
> bookworm, install the older distro `bubblewrap` and accept the same
> **Distro packages lag the pin.** The pinned `bubblewrap 0.13.0`
> is newer than most distributions package, so the `apt` / `dnf`
> lines above resolve only once your distribution ships it. Until
> then, build it from the
> [release tarball](https://github.com/containers/bubblewrap/releases/tag/v0.13.0)
> (`meson setup _build && meson compile -C _build && sudo meson install -C _build`),
> or install the distribution's own `bubblewrap` and accept the same
> LTS trade-off documented in the Ubuntu Noble shortcut below — the
> sandbox flags don't depend on a specific bubblewrap version (the
> `denyRead`/`allowRead` API has been stable since `0.6.x`).
> On Debian, an adopter reported the `0.11.x` line not working on
> **bookworm**, so run the secure setup on **trixie** (or newer).

**Fedora / RHEL (dnf)**:

```bash
sudo dnf install \
bubblewrap-0.11.2 \
bubblewrap-0.13.0 \
socat-1.8.1.3
```

Expand All @@ -343,10 +346,10 @@ npm install -g --no-save @anthropic-ai/claude-code@latest

### Distro-specific shortcut — Linux Mint 22.x / Ubuntu 24.04 Noble

The pinned versions above (bubblewrap `0.11.2`, socat `1.8.1.3`) are
The pinned versions above (bubblewrap `0.13.0`, socat `1.8.1.3`) are
the *upstream* releases that have aged past the framework's 7-day
cooldown. **They are not in Ubuntu Noble's main repos** — Noble
ships `bubblewrap 0.9.0` (`0.9.0-1ubuntu0.1`) and
ships `bubblewrap 0.9.0` (`0.9.0-1ubuntu0.3`) and
`socat 1.8.0.0` (`1.8.0.0-4build3`).

Both Noble-shipped versions pre-date the framework's pins by months
Expand All @@ -361,7 +364,7 @@ If you accept the trade-off, install via apt:
```bash
sudo apt-get update
sudo apt-get install --no-install-recommends \
bubblewrap=0.9.0-1ubuntu0.1 \
bubblewrap=0.9.0-1ubuntu0.3 \
socat=1.8.0.0-4build3
```

Expand All @@ -370,7 +373,7 @@ sandbox flags don't depend on a specific bubblewrap version (the
`denyRead`/`allowRead` API has been stable since `0.6.x`).

The framework's `tools/agent-isolation/check-tool-updates.sh` will
still report upstream `0.11.2` / `1.8.1.3` as the pinned versions —
still report upstream `0.13.0` / `1.8.1.3` as the pinned versions —
that's the manifest's view of what's *upstream-current*, not what
your distro shipped. If you want to silence the drift, override the
manifest locally with a `pinned-versions.local.toml` (gitignored)
Expand Down
17 changes: 11 additions & 6 deletions tools/agent-isolation/pinned-versions.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,16 @@

# When this file was last touched. The check script uses this as the
# minimum age the entries below claim to satisfy.
pinned_at = "2026-07-08"
pinned_at = "2026-09-23"

[tools.bubblewrap]
version = "0.11.2"
released = "2026-04-23"
version = "0.13.0"
released = "2026-09-22"
# Shorter than the 7-day default so 0.13.0 could be adopted a day
# after release; it carries the 0.12.0 sandbox-setup symlink fix
# (GHSA-pxhw-h44j-8pfx). Raise it back to the default if a later
# release needs a fix-forward.
cooldown_days = 1
purpose = """
Linux user-namespace sandbox. The strongest layer of credential
isolation: enforces the `denyRead` / `allowRead` filesystem rules
Expand All @@ -80,10 +85,10 @@ upstream_releases = "https://api.github.com/repos/containers/bubblewrap/releases
# Install commands per distro (use the package manager's syntax for
# requesting a specific version where supported). See
# `docs/setup/secure-agent-setup.md` for adopter-facing install steps.
install.apt = "apt-get install --no-install-recommends bubblewrap=0.11.2-*"
install.dnf = "dnf install bubblewrap-0.11.2"
install.apt = "apt-get install --no-install-recommends bubblewrap=0.13.0-*"
install.dnf = "dnf install bubblewrap-0.13.0"
install.brew = "# macOS does not need bubblewrap; it uses Seatbelt."
install.from_source = "https://github.com/containers/bubblewrap/releases/tag/v0.11.2"
install.from_source = "https://github.com/containers/bubblewrap/releases/tag/v0.13.0"

[tools.socat]
version = "1.8.1.3"
Expand Down