68 lines
2.9 KiB
Markdown
68 lines
2.9 KiB
Markdown
---
|
|
phase: 260504-bw4
|
|
plan: 01
|
|
subsystem: sandbox/ssh
|
|
tags: [ssh, bwrap, security, opt-in]
|
|
dependency_graph:
|
|
requires: []
|
|
provides: [ssh-agent-forwarding, ssh-key-mounts, sandbox-ssh-awareness]
|
|
affects: [claudebox.sh, README.md]
|
|
tech_stack:
|
|
added: []
|
|
patterns: [opt-in SSH via bwrap --bind/--ro-bind, conditional SANDBOX.md generation]
|
|
key_files:
|
|
modified:
|
|
- claudebox.sh
|
|
- README.md
|
|
decisions:
|
|
- SSH is opt-in: no keys or sockets cross the sandbox boundary without explicit flags
|
|
- --with-ssh validation: silently degrades to no-op with warning if ssh-agent is not running
|
|
- SANDBOX.md uses unquoted heredoc with pre-composed variables for conditional content
|
|
- known_hosts mounted once if either SSH mechanism is active (shared between --with-ssh and --ssh-key)
|
|
metrics:
|
|
duration: 8min
|
|
completed: 2026-05-04
|
|
tasks: 3
|
|
files: 2
|
|
---
|
|
|
|
# Quick Task 260504-bw4: Add SSH Support to claudebox Summary
|
|
|
|
One-liner: Opt-in SSH via `--with-ssh` (agent socket forwarding) and `--ssh-key` (explicit key file mounts), with audit/dry-run/SANDBOX.md integration and README documentation.
|
|
|
|
## Tasks Completed
|
|
|
|
| Task | Name | Commit | Files |
|
|
|------|------|--------|-------|
|
|
| 1 | Implement --with-ssh and --ssh-key flag parsing + bwrap mounts | 41ebf10 | claudebox.sh |
|
|
| 2 | Make SANDBOX.md conditional on SSH activation | e9154fd | claudebox.sh |
|
|
| 3 | Document SSH support in README.md | b2aeb2f | README.md |
|
|
|
|
## What Was Built
|
|
|
|
**claudebox.sh** now accepts two new flags:
|
|
|
|
- `--with-ssh`: validates `$SSH_AUTH_SOCK` is a real socket, adds `--bind $SSH_AUTH_SOCK $SSH_AUTH_SOCK` and `--setenv SSH_AUTH_SOCK` to bwrap args, degrades gracefully with a warning if no agent is running.
|
|
- `--ssh-key <path>`: repeatable, validates file exists+readable, mounts key (and `.pub` if present) read-only into `~/.ssh/<basename>` inside the sandbox.
|
|
- When either mechanism is active: `--dir ~/.ssh` is added, and `~/.ssh/known_hosts` is mounted read-only if it exists on the host.
|
|
- Audit display shows SSH mounts in the Mounts section.
|
|
- `--dry-run` output mirrors all SSH bwrap flags.
|
|
- SANDBOX.md is now generated conditionally: no-SSH mode lists SSH keys in restrictions and recommends HTTPS; SSH-active mode drops that restriction, adds a `## SSH` section describing which mechanisms are active, and says SSH remotes work.
|
|
|
|
**README.md** gains two flag table rows and a `## SSH` section covering both mechanisms, bash/fish agent setup, the agent-lifetime caveat, explicit key usage, and the known_hosts note.
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written.
|
|
|
|
## Threat Flags
|
|
|
|
No new threat surface introduced. SSH flags are opt-in and explicitly documented. The agent socket bind is scope-limited to `--bind $SSH_AUTH_SOCK $SSH_AUTH_SOCK` (only the socket path the user explicitly opts into). Key files are read-only.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- claudebox.sh: FOUND
|
|
- README.md: FOUND
|
|
- 41ebf10 (Task 1): FOUND
|
|
- e9154fd (Task 2): FOUND
|
|
- b2aeb2f (Task 3): FOUND
|