feat: add ssh tool for remote command execution over SSH

[imaustink]

Summary

• Adds tools/ssh, a container Tool that runs a remote command over SSH, mirroring tools/kubectl-readonly/tools/github's shape (allowlist + config + spawn wrapper + messaging + redaction, with tests).
• Target resolution and command restriction are each independent, individually optional inputs, composable per deployment (tools/ssh/src/target.ts, src/allowlist.ts, src/sshconfig.ts):
  • SSH_ALLOWED_HOSTS -- an explicit user@host[:port] allowlist restricting which resolved targets may be dialed at all.
  • SSH_CONFIG -- ssh_config(5)-shaped Host/HostName/User/Port blocks for alias resolution (e.g. kube0 -> ubuntu@192.168.1.59), the same way an operator's own ~/.ssh/config works. At least one of SSH_ALLOWED_HOSTS/SSH_CONFIG is required at startup.
  • SSH_ALLOWED_COMMANDS -- unset keeps the curated read-only diagnostic default (df, ps, journalctl, systemctl status, docker ps/logs/inspect, ip addr show, ...; systemctl/docker restricted to read-only subcommands, ip/find reject their write/exec forms specifically); a comma-separated list substitutes a custom set; "*" disables the command allowlist entirely for a deployment that accepts that risk.
• The remote-shell-injection charset check (every token restricted to ^[A-Za-z0-9._\-/:=@,]+$) is unconditional in every mode, including "*" -- OpenSSH hands the remote argv to the target's own login shell unless it forces a fixed command, so this is what actually prevents ;/|/`/$(...) injection regardless of which top-level command is allowed.
• Wires it into charts/community-components (Tool/ServiceAccount templates, values.yaml defaults, a fail guard requiring at least one target-resolution input, values-ci-all.yaml for full-catalog CI validation) and .github/workflows/release.yml's build matrix.
• Enables it in values-production.yaml against the operator's home/bastion/console/printcam/airvinyl/airbuddy homelab boxes (aliased via a copy of ~/.ssh/config, with allowedHosts populated from the same list as the actual enforced boundary) -- deliberately excludes the kube0-8/db1-3 cluster nodes, since allowedCommands: "*" gives this tool write access to anything it reaches and those are this repo's own production infrastructure. Uses the operator's own id_rsa as a temporary shared credential pending rotation to a dedicated, scoped key (flagged inline in the values file and tools/ssh/README.md's "Choosing a credential" section).

Review history

• An automated review caught three real issues, all fixed and verified against a real kind cluster + kubectl apply --dry-run=server (not just helm template): ip/find allowed unrestricted write/exec forms despite the "read-only" claim; CI was red because values-ci-all.yaml never enabled sshTool; and allowedHosts being empty meant the sshConfig alias list wasn't actually an enforced boundary (any literal user@host would resolve).
• console's IP changed (192.168.1.83 -> .71, confirmed same box via host-key fingerprint match) mid-review; updated everywhere. Its id_rsa authorization is still outstanding on the operator's end -- flagged inline, not blocking this PR.

Test plan

• npm run typecheck --workspace=ssh
• npm run test --workspace=ssh (48/48 passing across allowlist.test.ts/sshconfig.test.ts/target.test.ts)
• npm run build --workspace=ssh
• helm lint charts/community-components
• helm template against values.yaml defaults (disabled), a custom host list, SSH_CONFIG-only, both together, and values-production.yaml as-is -- all render cleanly; the fail guard rejects neither-input-set.
• helm template community-components -f values-ci-all.yaml, verified against validate-crds.yml's literal "every template rendered" assertion.
• Real kind cluster + kubectl apply --dry-run=server against the full rendered catalog (CEL validation included) -- passes for the ssh Tool CR.
• Real in-cluster ToolRun against a homelab host once ssh-tool-secrets is created (command in the values-production.yaml comment) and console's key authorization is resolved.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fg8b9pPWm91nLbDnB6ECJh

[k5s-bot]

🤖 Starting work on this now. Watch live or take over the session here: https://claude.ai/code/session_012RcHQ8DZay6svwBFRZMwhY

[k5s-bot]

Solid, well-documented tool that closely mirrors the existing tool shape, and the local-vs-remote-shell reasoning behind the charset guard is exactly right. Three things to address before merge, in priority order:

1. The read-only guarantee doesn't hold — ip and find are allowlisted with no subcommand/flag restriction, so ip link set … down, ip route del …, and find … -delete/-fprint all pass validation (inline on allowlist.ts).
2. CI is red — the validate job fails because the two new templates aren't enabled in values-ci-all.yaml (inline on tool-ssh.yaml).
3. Production ships with no real target boundary — with allowedHosts empty, the sshConfig alias list isn't enforced; literal user@host targets bypass it (inline on values-production.yaml).

The remaining CI checks (Node, Go) are green as of this review.

[k5s-bot]

ip and find break the "strictly read-only" guarantee. Unlike systemctl/docker, neither is subcommand-restricted, and their state-changing forms fit SAFE_TOKEN, so these all pass validateCommand (verified against this logic):

• ip link set eth0 down, ip route del default, ip addr add 10.0.0.9/24 dev eth0
• find /tmp/x -delete, find / -name foo -fprint /etc/cron.d/x

With the production admin key (values-production.yaml) this is remote write / network-DoS / arbitrary-file-write, not diagnostics.

🤖 Prompt to fix this with an AI agent

In imaustink/agent-controller on PR #192, tools/ssh/src/allowlist.ts allowlists `ip` and `find` with no subcommand/flag restriction, so state-changing invocations (`ip link set … down`, `ip route add/del`, `ip addr add/del`, `find … -delete`, `find … -fprint/-fls/-fprintf`, `find … -exec`) pass validateCommand and violate the tool's read-only guarantee. Restrict `ip` to read-only forms only (allow object + `show`/`list`; reject `add`/`del`/`set`/`change`/`replace`/`flush`), and either drop `find` from the allowlist or reject its writing/execution action flags anywhere in argv (-delete, -exec, -execdir, -ok, -okdir, -fprint, -fprintf, -fls). Add tests in allowlist.test.ts asserting each of those write forms is rejected with BlockedCommandError. Do not change unrelated behavior.

[k5s-bot]

This PR turns CI red. .github/workflows/validate-crds.yml renders the chart with values-ci-all.yaml and asserts every file under templates/ appears in the output. tool-ssh.yaml and serviceaccount-ssh.yaml render nothing there because sshTool is disabled by default and values-ci-all.yaml was not updated to enable it, so the "Assert every template was actually rendered" step exits 1 (this is the failing validate check on the PR).

🤖 Prompt to fix this with an AI agent

In imaustink/agent-controller on PR #192, the validate-crds CI job fails because charts/community-components/templates/tool-ssh.yaml and serviceaccount-ssh.yaml render nothing under charts/community-components/values-ci-all.yaml. Add a `sshTool` block to values-ci-all.yaml with `enabled: true` and a non-empty `sshConfig` (a throwaway Host block, e.g. HostName ci-host.example.invalid / User ci) so the tool-ssh.yaml `fail` guard passes and both templates render. Verify `helm template charts/community-components -f charts/community-components/values-ci-all.yaml` includes both `# Source:` lines. Do not change unrelated behavior.

[k5s-bot]

With allowedHosts empty, the sshConfig Host list is not an enforced boundary. resolveTarget falls back to the caller's literal user@host when no Host block matches (tools/ssh/src/target.ts:91; intended per the test at target.test.ts:62). So callers aren't limited to the aliases below — root@192.168.1.59 … (note: a different user than the ubuntu this file maps kube0 to) or any literal user@host resolves and is dialed, with known_hosts pinning as the only remaining restriction. The comment above claims "sshConfig's own Host list is the only boundary," but that list restricts neither the host set nor the user. Combined with the temporary personal admin key, populating allowedHosts (which pins user+host+port) is the only thing that actually bounds this.

🤖 Prompt to fix this with an AI agent

In imaustink/agent-controller on PR #192, charts/community-components/values-production.yaml enables sshTool with allowedHosts: "" and relies on the sshConfig alias list as the boundary, but resolveTarget (tools/ssh/src/target.ts) dials any literal user@host that isn't a configured alias, so the alias list is not an authorization boundary. Set allowedHosts to a comma-separated user@host list derived from the sshConfig Host blocks in this file (e.g. austinkurpuis@166.113.38.187, ubuntu@192.168.1.59, …, pi@airvinyl.local, pi@192.168.1.218) so the resolved user+host+port must match an explicit entry. Do not change the sshConfig block or unrelated behavior.

[k5s-bot]

All three inline comments anchored to the correct file and line. Review is posted.

Summary

I reviewed PR #192 (feat: add ssh tool for read-only remote diagnostics) by checking out the branch, reading the full diff, verifying the allowlist logic against a local reproduction, and inspecting the failing CI job. Posted one review (COMMENT) with three inline comments, each carrying a self-contained fix.

Findings (most severe first):

1. Read-only guarantee is broken (tools/ssh/src/allowlist.ts:49) — ip and find are allowlisted with no subcommand/flag restriction (only systemctl/docker are restricted). I verified that ip link set eth0 down, ip route del default, ip addr add …, find … -delete, and find … -fprint /etc/cron.d/x all pass validateCommand. With the production admin key this is remote write/DoS/arbitrary-file-write, not diagnostics.

2. This PR turns CI red (charts/community-components/templates/tool-ssh.yaml:1) — the validate check is failing because validate-crds.yml asserts every template renders under values-ci-all.yaml, but the two new ssh templates render nothing there (sshTool not enabled), and that file wasn't updated. Concrete, PR-caused failure with a one-line fix.

3. No enforced target boundary in production (charts/community-components/values-production.yaml:228) — with allowedHosts empty, resolveTarget falls back to any literal user@host for non-alias targets (target.ts:91), so the sshConfig a…

---

✅ Opened pull request: imaustink/agent-controller#192

[imaustink]

Addressed all three findings:

1. ip/find read-only bypass — ip is now restricted to a read-only object+action allowlist (addr/route/link/... + show/list/get, ip's own default action), and find's write/exec primaries (-delete, -exec[dir], -ok[dir], -fprint/-fprintf/-fls) are rejected wherever they appear in argv. Added tests for the exact attack forms from the review (ip link set eth0 down, ip route del default, find ... -delete/-exec/-fprint).
2. CI red — values-ci-all.yaml now enables sshTool with a throwaway sshConfig, so both new templates render. Verified against the literal validate-crds.yml assertion, plus a real kind cluster + kubectl apply --dry-run=server (CEL validation included) locally before pushing.
3. No enforced boundary in prod — allowedHosts is now populated in values-production.yaml, derived from the sshConfig Host list, so the resolved user@host:port must match an explicit entry rather than falling back to any literal target.

Separately (not from this review — a follow-up request): added a third independent, optional input, SSH_ALLOWED_COMMANDS, so a deployment can opt into read/write (or fully unrestricted, "*") command execution instead of the curated read-only default. The remote-shell-injection charset check stays unconditional in every mode. values-production.yaml sets it to "*" for this homelab, with an inline note not to copy that setting to infrastructure that matters more.

All 48 tests passing, typecheck/build/helm-lint/helm-template clean, and a real kind-cluster dry-run apply verified locally.