Skip to content

feat(cli): verify sandbox SSH host keys - #5703

Draft
alangou wants to merge 3 commits into
mainfrom
feat/verify-sandbox-ssh-host-keys/alangou
Draft

alangou wants to merge 3 commits into
mainfrom
feat/verify-sandbox-ssh-host-keys/alangou

Conversation

@alangou

@alangou alangou commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The CLI, the TUI, and generated SSH config entries accepted any SSH host key from a sandbox. They now check it against the fingerprint the gateway publishes, so a connection that reaches the wrong SSH server fails before authentication.

Related Issue

Follow-on to #3835 (item 4 of its design, "CLI and TUI verify against the fingerprint"). #3835 is closed, so this PR needs its own tracking issue before it leaves draft.

Changes

  • ssh runs with StrictHostKeyChecking=yes against one known-hosts file per sandbox, under <config>/openshell/known_hosts/<gateway>/. Other trust sources are disabled.
  • ssh-proxy reads the host key from the server's key exchange reply. It pins the key only when its SHA-256 fingerprint equals the published one, and withholds the reply otherwise. It accepts only the exact cleartext sequence a server sends before NEWKEYS.
  • New module openshell_core::ssh_host_key owns the fingerprint format, the pin file, the ssh options, and the relay check. sandbox_ssh_args cannot be called without it.
  • No protobuf change. No dependency on the OpenSSH version.
  • Existing setups keep working. A sandbox with no published fingerprint, an SSH config entry from an earlier release, and a client started before the upgrade all connect without verification and print a warning.

Out of scope: the gateway's own SSH client for ExecSandbox (#557), and a readable multi-line refusal in the TUI, which stays a one-line status.

Release Notes

OpenShell clients now verify the sandbox SSH host key on every SSH connection they open.

  • A sandbox with no published fingerprint cannot be verified. The connection proceeds with a warning. Upgrade the gateway, or stop and start the sandbox, to get a fingerprint.
  • SSH config entries generated by earlier releases keep working without verification. Each connection prints a warning with the command that regenerates the entry.

Testing

  • Checks appropriate to the affected code and behavior pass
  • Unit tests added/updated (if applicable)
  • E2E tests added/updated (if applicable)

Ran on Linux with OpenSSH 10.0p2: cargo test for openshell-core, openshell-cli, and openshell-tui, cargo clippy --all-targets -D warnings on the same crates, cargo fmt --check, and the lockfile check.

ssh_proxy_host_key_integration runs the real ssh binary through the built openshell ssh-proxy against a russh server: the published key connects, another key is refused before any command runs, a stale pin is replaced, and ssh refuses a key missing from its own known-hosts file. Two of these run with a % in the config directory. The same file checks that a caller without the new flags, and a gateway that publishes nothing, are relayed with a warning.

Not run locally: the E2E suites, macOS, and OpenSSH 8.x. The existing conformance test ssh_host_identity_stable_across_stop_start_and_new_on_recreate exercises the relay check against a real supervisor in CI.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

The CLI, the TUI, and generated SSH config entries accepted any SSH host key. They now run ssh with StrictHostKeyChecking=yes against a per-sandbox known-hosts file. The ssh-proxy relay reads the host key from the server's key exchange reply, pins it only when its SHA-256 fingerprint equals the one the gateway published, and withholds the reply otherwise.

A sandbox with no published fingerprint is refused unless OPENSHELL_SSH_ALLOW_UNVERIFIED_HOST_KEY=1 is set. SSH config entries generated by earlier releases are refused with the command that regenerates them.

Signed-off-by: Adrien Langou <alangou@nvidia.com>
@copy-pr-bot

copy-pr-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@github-actions github-actions Bot added the state:accepted A maintainer decided OpenShell should pursue this issue label Nov 18, 2026
@github-actions

Copy link
Copy Markdown

Restore the base shape of the SSH option and proxy-command helpers where the feature does not need a new one, fold duplicate tests into tables, and drop tests that repeat a proof at a more expensive level. No change to what is verified or refused.

Signed-off-by: Adrien Langou <alangou@nvidia.com>
@alangou alangou added the test:e2e Requires end-to-end coverage label Nov 18, 2026
@github-actions

Copy link
Copy Markdown

Label test:e2e applied, but pull-request/5703 does not exist yet. A maintainer needs to comment /ok to test 3cdb3a9710e393e622c35c2bb339dc206a30dbdf to mirror this PR. Once the mirror exists, re-apply the label or re-run Branch E2E Checks from the Actions tab.

@alangou

alangou commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 3cdb3a9

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. cli — No explicit risk acceptance found

openshell ssh-proxy --gateway-name G --name S now requires --known-hosts FILE, while openshell ssh-proxy --gateway URL --sandbox S --token T now requires both --host-key FINGERPRINT and --known-hosts FILE.

  • Impact: Previously generated SSH/editor entries and older running CLI/TUI launchers now exit 1 with a host-key-verification refusal instead of opening their SSH connections.
  • Action: Provide a backward-compatible transition for saved SSH entries and older launchers; documented regeneration through sandbox ssh-config or sandbox connect --editor and client restarts do not satisfy the no-break policy.
  • PR: feat(cli): verify sandbox SSH host keys #5703

2. cli — No explicit risk acceptance found

openshell sandbox connect, SSH-based exec/transfers, forwarding, and TUI connections now reject an empty CreateSshSessionResponse.host_key_fingerprint instead of connecting by default.

  • Impact: Consumers using older gateways or existing sandboxes without assigned SSH identities lose previously working SSH operations unless they change their environment or upgrade/restart infrastructure.
  • Action: Preserve the existing empty-fingerprint default under this no-break policy; the documented gateway upgrade, sandbox stop/start, and OPENSHELL_SSH_ALLOW_UNVERIFIED_HOST_KEY=1 alternatives remain mandatory consumer migrations.
  • PR: feat(cli): verify sandbox SSH host keys #5703

3. configuration — No explicit risk acceptance found

An existing setting such as XDG_CONFIG_HOME=/tmp/100% previously worked for SSH operations but now produces a rejected known-hosts path.

  • Impact: openshell sandbox connect and openshell sandbox ssh-config fail for valid existing configuration directories containing %, even with a current gateway and matching host key.
  • Action: Keep previously valid XDG paths usable through SSH-compatible escaping or pin-path indirection rather than requiring an undocumented configuration-directory relocation.
  • PR: feat(cli): verify sandbox SSH host keys #5703
Review details
  • Execution: complete
  • Candidate: PR #5703 (732ff5f6e4b24494f986ab867c59268b890da539)
  • Baseline: 8424e1dddd36d8884017b0648508063428672a16 (8424e1dddd36d8884017b0648508063428672a16)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

Address the compatibility review of the host key verification change.

A sandbox with no published fingerprint connects with a warning instead of
being refused, so gateways that predate sandbox SSH identities keep working.
The OPENSHELL_SSH_ALLOW_UNVERIFIED_HOST_KEY opt-out is no longer needed.

SSH config entries and running clients from an earlier release keep
working: ssh-proxy relays without a check and warns, since their ssh
accepts any host key anyway.

A '%' in the config directory is escaped for ssh instead of rejected.

Harden the relay gate: an identification line is at most 255 bytes, so
the gate and every ssh release hand over to packets at the same byte, and
a group exchange reply is accepted only after its group.

Signed-off-by: Adrien Langou <alangou@nvidia.com>
@alangou

alangou commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test ee95035

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. configuration — No explicit risk acceptance found

SSH operations previously accepted XDG_CONFIG_HOME/HOME paths containing double quotes, Unix backslashes, or literal '${', but now reject them as unusable known-hosts paths.

  • Impact: Existing users of these configuration directories lose openshell sandbox connect, forwarding, and sandbox ssh-config with an SSH known-hosts path ... cannot be used error.
  • Action: Preserve existing XDG_CONFIG_HOME/HOME paths through an SSH-safe pin-path indirection rather than requiring configuration relocation under this no-break policy.
  • PR: feat(cli): verify sandbox SSH host keys #5703
Review details
  • Execution: complete
  • Candidate: PR #5703 (1d7e15fccd96400166be6574c8def6a439a615c7)
  • Baseline: 8424e1dddd36d8884017b0648508063428672a16 (8424e1dddd36d8884017b0648508063428672a16)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

state:accepted A maintainer decided OpenShell should pursue this issue test:e2e Requires end-to-end coverage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant