16 KiB
16 KiB
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 260504-bw4 | 01 | execute | 1 |
|
true |
|
|
Purpose: Today the sandbox blocks all SSH. Real workflows need it for git remotes. The right answer is opt-in agent forwarding (--with-ssh) plus explicit key file mounting (--ssh-key), with audit visibility so the user always sees what crossed the boundary.
Output: Updated claudebox.sh implementing both flags, audit + dry-run + SANDBOX.md integration, and an updated README.md documenting setup and usage.
Flag parsing pattern (lines 9-20):
while (( $# > 0 )); do
case "$1" in
--yes|-y) SKIP_AUDIT=true ;;
...
*) CLAUDE_ARGS+=("$1") ;;
esac
shift
done
Audit data structure (lines 240-245): AUDIT_SANDBOX_KEYS / AUDIT_HOST_KEYS / AUDIT_EXTRA_KEYS arrays + parallel _VALS assoc arrays. SSH mounts are mounts, not env vars — they belong in the print_audit Mounts: section (line 361), not in the env arrays. SSH_AUTH_SOCK is an env var — it should go through ENV_ARGS via the AUDIT_HOST_KEYS path.
SANDBOX.md generation (lines 185-222): single heredoc with 'SANDBOXEOF' (literal). To make it conditional we either (a) split it into pieces, or (b) generate it without a quoted heredoc and use bash conditionals. Approach: keep the static parts as a heredoc, then append a conditional "SSH" subsection before writing the "Git" section, OR rewrite as cat <<SANDBOXEOF (unquoted) with a ${SSH_RESTRICTIONS_NOTE} placeholder. Prefer the placeholder approach for readability.
Dry-run output (lines 405-451): mirrors BWRAP_ARGS construction. Any new bwrap flags added to BWRAP_ARGS must also be emitted in the dry-run echo block.
BWRAP_ARGS construction (lines 453-494): conditional mounts (CLAUDE_JSON_MOUNT, CREDS_MOUNT) are appended after the base array. SSH mounts follow the same pattern.
Task 1: Implement --with-ssh and --ssh-key flag parsing + bwrap mounts claudebox.sh - `--with-ssh` sets WITH_SSH=true. If $SSH_AUTH_SOCK is set and is a socket on the host, add `--bind $SSH_AUTH_SOCK $SSH_AUTH_SOCK` to BWRAP_ARGS and `--setenv SSH_AUTH_SOCK $SSH_AUTH_SOCK` to ENV_ARGS. If the var is unset or the path is not a socket, print a warning to stderr and continue without forwarding. - `--ssh-key ` is repeatable. Each value is appended to a SSH_KEYS array. Path is expanded (`~` -> $HOME) and validated: file must exist and be readable; otherwise exit 1 with an error. - When WITH_SSH=true OR SSH_KEYS is non-empty: add `--dir $HOME/.ssh` to BWRAP_ARGS so the sandbox has a real ~/.ssh directory inside the home tmpfs. - For each key in SSH_KEYS: add `--ro-bind $HOME/.ssh/`. If `.pub` exists on the host, also `--ro-bind .pub $HOME/.ssh/.pub`. - When SSH is active AND `~/.ssh/known_hosts` exists on the host: add `--ro-bind $HOME/.ssh/known_hosts $HOME/.ssh/known_hosts` exactly once (shared between both mechanisms). - The dry-run block (lines 405-451) emits the same SSH lines so `claudebox --dry-run --with-ssh --ssh-key ~/.ssh/id_ed25519` prints them. 1. In the flag-parsing `case` block (around line 10), add: ```bash --with-ssh) WITH_SSH=true ;; --ssh-key) shift $# -gt 0 || { echo "Error: --ssh-key requires a path" >&2; exit 1; } SSH_KEYS+=("${1/#\~/$HOME}") ;; ``` Initialize `WITH_SSH=false` and `SSH_KEYS=()` near the top with the other flag defaults.2. After argument parsing, add a validation+resolution block that:
- For each path in SSH_KEYS: resolve to absolute, verify exists+readable, replace array entry with absolute path, error+exit if missing.
- If WITH_SSH=true: check `[[ -v SSH_AUTH_SOCK && -S "$SSH_AUTH_SOCK" ]]`. If not, print `${YELLOW}Warning: --with-ssh given but SSH_AUTH_SOCK is unset or not a socket; agent will not be forwarded.${RESET}` and set WITH_SSH=false. (Color vars are defined later — move this block to AFTER the ANSI block at line 107, or use plain text.)
- Compute `SSH_ACTIVE=true` if WITH_SSH=true OR ${#SSH_KEYS[@]} > 0; else false.
- Compute `KNOWN_HOSTS_MOUNT=true` if SSH_ACTIVE && `[[ -f $HOME/.ssh/known_hosts ]]`.
3. Where ENV_ARGS is built (after line 256): if WITH_SSH=true, append `--setenv SSH_AUTH_SOCK $SSH_AUTH_SOCK` and add to AUDIT_HOST_KEYS/VALS so it shows in the audit's `[>]` section.
4. Where BWRAP_ARGS is assembled (lines 453-487), after the existing conditional mounts (CLAUDE_JSON, CREDS) and before the trailing `--ro-bind GITCONFIG_TMP ...` line, insert:
```bash
if [[ "$SSH_ACTIVE" == true ]]; then
BWRAP_ARGS+=(--dir "$HOME/.ssh")
if [[ "$WITH_SSH" == true ]]; then
BWRAP_ARGS+=(--bind "$SSH_AUTH_SOCK" "$SSH_AUTH_SOCK")
fi
for key in "${SSH_KEYS[@]}"; do
base=$(basename "$key")
BWRAP_ARGS+=(--ro-bind "$key" "$HOME/.ssh/$base")
if [[ -f "${key}.pub" ]]; then
BWRAP_ARGS+=(--ro-bind "${key}.pub" "$HOME/.ssh/$base.pub")
fi
done
if [[ "$KNOWN_HOSTS_MOUNT" == true ]]; then
BWRAP_ARGS+=(--ro-bind "$HOME/.ssh/known_hosts" "$HOME/.ssh/known_hosts")
fi
fi
```
5. Mirror all of (4) in the dry-run echo block (after the CREDS_MOUNT block around line 444, before the GITCONFIG line at 445), printing the same flags as quoted strings.
6. Update the audit display (`print_audit`, around line 361) to emit additional Mounts lines when SSH_ACTIVE:
- `agent <socket-path> (read-write, --with-ssh)` if WITH_SSH
- For each key: `ssh-key <path> (read-only)`; add ` + .pub` line if pub exists
- `known_hosts <path> (read-only)` if KNOWN_HOSTS_MOUNT
```markdown
## SSH
SSH is opt-in. By default no keys or agent socket cross the sandbox boundary, which means git push/pull over SSH remotes won't work. Two mechanisms are available — pick whichever matches your workflow.
### `--with-ssh` (agent forwarding)
Forwards `$SSH_AUTH_SOCK` into the sandbox so any keys loaded in your ssh-agent are usable inside. Your private key files are never mounted; only the agent socket is.
Start an agent before launching claudebox. The agent dies with the shell that started it, so don't expect it to survive across terminals.
Bash:
```bash
eval "$(ssh-agent)"
ssh-add ~/.ssh/id_ed25519
claudebox --with-ssh
```
Fish:
```fish
eval (ssh-agent -c)
ssh-add ~/.ssh/id_ed25519
claudebox --with-ssh
```
If `--with-ssh` is passed but no agent is running, claudebox warns and continues without forwarding.
### `--ssh-key <path>` (explicit key files)
Mounts a specific private key (and matching `.pub`, if present) read-only into the sandbox at `~/.ssh/<basename>`. Repeatable — pass it multiple times for multiple keys.
```bash
claudebox --ssh-key ~/.ssh/id_ed25519
claudebox --ssh-key ~/.ssh/id_work --ssh-key ~/.ssh/id_personal
```
Prefer this when you don't have an agent running, or when you want to scope exactly which keys the sandbox can use regardless of what's loaded in the agent.
### known_hosts
When either flag is active, `~/.ssh/known_hosts` is mounted read-only (if it exists) so SSH host verification works without prompting.
Both flags can be combined.
```
bash -n claudebox.sh— syntax valid.nix build(ornix flake check) succeeds — shellcheck via writeShellApplication passes.claudebox --dry-run(no SSH flags) — output contains no--bind $SSH_AUTH_SOCK, no~/.sshmounts.- With agent running:
eval "$(ssh-agent)" && claudebox --dry-run --with-ssh— output contains--bind <socket> <socket>and--setenv SSH_AUTH_SOCK .... claudebox --dry-run --ssh-key ~/.ssh/id_ed25519(assuming key exists) — output contains--dir $HOME/.ssh,--ro-bind <key> $HOME/.ssh/id_ed25519, and.pubbind if present.claudebox --dry-run --ssh-key /nonexistent— exits non-zero with clear error.- SANDBOX.md content matches SSH state (verify by inspecting
~/.claudebox/SANDBOX.mdafter a dry run with and without flags). - README renders correctly (visual or
, glow README.md).
<success_criteria>
- All three tasks complete and
<done>criteria met. - Both flags work in isolation, together, and respect missing-input failure modes.
- Audit display + dry-run + SANDBOX.md all reflect SSH state consistently.
- README documents the feature for both bash and fish users.
- No regressions: running
claudeboxwithout any SSH flag behaves exactly as before. </success_criteria>