docs(sandboxes): correct the on-disk secret store's protection claim - #25875
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| keychain, which also mediates access per application. If you start a Secret | ||
| Service on the host later, `sbx` stores new secrets in the keychain again. For | ||
| more on running sandboxes without a desktop keyring, see | ||
| What protects that file is the `0700` permissions on the directory holding it, |
There was a problem hiding this comment.
The opening doesn’t connect naturally to the preceding text, and “stops the values being read at a glance” is vague. Could we state the protection model directly?
Suggested replacement:
sbxstores the file in a directory with0700permissions, the same file-permission model used for~/.docker/config.json. Any user or process that can read the file can retrieve the stored credentials, so treat the directory as sensitive. Where available, prefer a keychain, which mediates access per application.
The FAQ repeats the same “What protects…” construction, so please update that passage to match.
Generated by Codex
There was a problem hiding this comment.
Applied as suggested, in both files — thank you, this reads much better. Your version states the consequence for the reader ("any user or process that can read the file can retrieve the stored credentials") where mine described the mechanism and left them to draw the conclusion.
The FAQ passage now uses the identical paragraph, so the two pages no longer diverge in how they explain it.
One consequence worth surfacing rather than leaving implicit: this wording drops any mention that the file is encrypted. That is deliberate on our side and we are happy with it — the encryption is under a key compiled into sbx rather than a secret the user holds, so it is not a protection worth documenting, and naming it tends to invite more trust than it earns. Flagging it only so it is a recorded decision rather than something that looks lost in an edit.
Also reflowed one line above the notice that an earlier revision of mine had left wrapped awkwardly.
Investigated, authored and posted by Claude Code on behalf of @robmry.
The keychain-less Linux fallback is described as "an encrypted file", quoting a CLI notice that no longer exists, and called weaker than an OS keychain only because a keychain "mediates access per application". Both understate it: the file is encrypted with a key compiled into sbx, not a secret the user holds, so anyone able to read the file can decrypt it. What protects it is the 0700 directory mode, which the page already mentions. Update the quoted notice to the string sbx now prints, and say plainly what the encryption does and does not give you. Also correct the same overstatement where it recurs in the credentials Best practices list and the headless-Linux FAQ entry. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Rob Murray <rob.murray@docker.com>
833b173 to
fbd8f19
Compare
2 participants
Description
The Sandboxes credential pages describe the keychain-less Linux fallback as "an encrypted file" and quote a CLI notice that no longer exists. They also frame the fallback as weaker than an OS keychain only because a keychain "mediates access per application".
Both understate it. The file is encrypted with a key compiled into
sbx, not a secret the user holds, so anyone who can read the file can decrypt it. What actually protects it is the0700directory mode — which the pages already mention, so this mostly moves the emphasis onto the claim that holds.sbxnow prints:replacing the previous "…stored in an encrypted file on disk". The quoted strings here are byte-matched against the constant in the CLI.
Four passages change:
security/credentials.md— the fallback description, the quoted notice, and the protection claimsecurity/credentials.md— the Best practices list, which repeated "encrypted at rest in the OS keychain (or an encrypted file on Linux hosts without a keychain)"faq.md— the headless-Linux entry, which carried the same notice and claimNo behaviour or feature is being documented here — only the accuracy of an existing description.
Related issues or tickets
The CLI-side change is in
docker/sandboxesand ships in the next release. Worth holding this until that release is out: until then the page would quote a notice users don't see yet.Reviews
Two things a reviewer may want to weigh in on:
gnome-keyringand startdbus-run-session. A locked Secret Service collection is known to makesbxcommands hang rather than fall back, and on a key-only SSH host locked is the default state after the keyring daemon restarts — so that advice can land users somewhere worse than the fallback. It is left alone because the underlying issue is being worked separately, but it may deserve a caveat once that is resolved.Investigated, authored and posted by Claude Code on behalf of @robmry.