Skip to content

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

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

alangou wants to merge 7 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.
  • OPENSHELL_SSH_REQUIRE_HOST_KEY=1 refuses those unverified connections instead. It is off by default.

Accepted risk: a config directory whose path contains ", ${, a newline, or a backslash on Unix cannot hold the known-hosts file, because ssh has no way to take such a path in UserKnownHostsFile. SSH commands fail there with SSH known-hosts path ... cannot be used. The fix is to set XDG_CONFIG_HOME to a path without them. An indirection through a second path would add code for a case no report describes.

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.
  • Set OPENSHELL_SSH_REQUIRE_HOST_KEY=1 to refuse unverified connections instead of connecting with a warning.
  • SSH commands fail when the OpenShell config directory path contains ", ${, a newline, or a backslash on Unix. Set XDG_CONFIG_HOME to a path without them.

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, and are refused when OPENSHELL_SSH_REQUIRE_HOST_KEY is set.

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

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

alangou commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test 261ba4c

OPENSHELL_SSH_REQUIRE_HOST_KEY turns the two unverified cases, a sandbox
with no published fingerprint and a caller that predates host-key
verification, from a warning into a refusal. It is off by default.

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

alangou commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

/ok to test ffc6aee

@alangou
alangou marked this pull request as ready for review November 19, 2026 13:42
@alangou

alangou commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Accepted risk ssh interprets ", \, ${ and newlines in the known-hosts path and has no portable escape for them so config directory containing them is refused. Workaround: set XDG_CONFIG_HOME to a path without them

@FrostGod FrostGod left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice work, the gate is really careful. A few general thoughts:

  • Threat model: the gateway is both the fingerprint source and the transport. Could the PR say what this actually catches? Relay routed to the wrong supervisor, stale supervisor, spoofed sshd socket? A compromised gateway isn't covered.
  • Default: should we turn OPENSHELL_SSH_REQUIRE_HOST_KEY on by default in the next major release, with an opt-out and a release note? Curious what you think.
  • macOS: could you check this on macOS too?
  • #557: not sure that one is worth doing. The gateway reaches sshd through the relay on the supervisor's own authenticated session, then a Unix socket, so there's no network hop to MITM, and the gateway issued the key in the first place. Also #557 is closed, so maybe drop it from the out-of-scope list?

Comment on lines +515 to +598
/// The server-to-client side of the `ssh-proxy` relay. Holds back the server's
/// key exchange reply until the host key in it is checked and pinned.
#[derive(Debug)]
pub struct HostKeyGate {
check: HostKeyCheck,
phase: GatePhase,
/// Bytes not yet released. Its head is the line or packet being decided.
buffer: Vec<u8>,
}

/// What the gate waits for: the identification line, then the cleartext
/// packets of a key exchange in the only order the server may send them. `ssh`
/// can discard a packet outside this order, so a gate that let one through
/// could be shown one host key while `ssh` acts on another.
#[derive(Clone, Copy, Debug)]
enum GatePhase {
Banner,
KexInit,
/// The reply, or before it the group of a group exchange.
GroupOrReply,
Reply,
NewKeys,
Done,
}

impl HostKeyGate {
/// Feed bytes read from the gateway; returns the bytes that may be written
/// to `ssh` now. Lines are released whole up to the `SSH-` identification
/// line. Then exactly these packets are released whole, in this order:
/// KEXINIT, the group of a group exchange if there is one, the key
/// exchange reply once its Ed25519 host key is pinned, and NEWKEYS.
/// Everything after NEWKEYS passes through.
///
/// On an error nothing from this call is released, and every later call
/// fails on the same line or packet.
pub fn push(&mut self, chunk: &[u8]) -> Result<Vec<u8>, HostKeyError> {
self.buffer.extend_from_slice(chunk);
let mut released = Vec::new();
while let Some(len) = self.releasable()? {
released.extend(self.buffer.drain(..len));
}
Ok(released)
}

/// The length of the buffer's head that may be released, or `None` when
/// deciding needs more bytes. An error leaves the head in place.
fn releasable(&mut self) -> Result<Option<usize>, HostKeyError> {
match self.phase {
GatePhase::Banner => {
let head = &self.buffer[..self.buffer.len().min(MAX_BANNER_LINE_LEN)];
let Some(newline) = head.iter().position(|&byte| byte == b'\n') else {
return if head.len() == MAX_BANNER_LINE_LEN {
Err(HostKeyError::Malformed("identification line is too long"))
} else {
Ok(None)
};
};
if head.starts_with(b"SSH-") {
self.phase = GatePhase::KexInit;
}
Ok(Some(newline + 1))
}
GatePhase::Done => Ok((!self.buffer.is_empty()).then_some(self.buffer.len())),
awaited => {
let Some((length, rest)) = self.buffer.split_first_chunk::<4>() else {
return Ok(None);
};
let length = usize::try_from(u32::from_be_bytes(*length))
.ok()
.filter(|length| PACKET_LENGTHS.contains(length))
.ok_or(HostKeyError::Malformed("packet length is out of range"))?;
let Some(packet) = rest.get(..length) else {
return Ok(None);
};
let padding = usize::from(packet[0]);
let (message, fields) = packet
.get(1..length.saturating_sub(padding))
.and_then(<[u8]>::split_first)
.ok_or(HostKeyError::Malformed("packet padding leaves no payload"))?;
self.phase = self.check.phase_after(awaited, *message, fields)?;
Ok(Some(4 + length))
}
}
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The gate is careful, but it's a hand-written SSH packet parser in the CLI. If CreateSshSessionResponse returned the public key and not just the fingerprint, we could write known_hosts directly and let ssh do the whole check. Was that ruled out only to avoid a proto change?

Comment on lines +257 to +264
fn under(config_dir: &Path, target: &SandboxSshTarget<'_>) -> Result<Self, HostKeyError> {
let alias = host_key_alias(target.sandbox, target.workspace);
// A gateway reached by its endpoint alone is named by its URL.
let gateway = target.gateway.replace(
|ch: char| !ch.is_ascii_alphanumeric() && !matches!(ch, '.' | '-' | '_'),
"_",
);
let path = config_dir.join("known_hosts").join(&gateway).join(&alias);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pin is keyed by sandbox name, but the docs (overview.mdx:890) say "pin it to the sandbox ID". Fine, since the gateway rewrites it anyway, but let's make the wording match.

// user as is, and a returned error would be reformatted as
// a report.
eprintln!("openshell: {refusal}");
std::process::exit(1)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

process::exit(1) from inside the async relay skips cleanup. Probably fine for a ProxyCommand, but returning a dedicated error and exiting from main would be tidier.

.collect::<Vec<_>>()
.join("\n");
Ok(format!(
"Host {host_alias}\n User sandbox\n{options}\n ControlMaster no\n ControlPath none\n ControlPersist no\n LogLevel ERROR\n ServerAliveInterval 15\n ServerAliveCountMax 3\n ProxyCommand {proxy_cmd}\n"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why add ControlMaster no to the generated config? Each alias is already per sandbox, so sharing was safe. VS Code Remote users may lose multiplexing. Looks unrelated to host-key checks; split it out?


fn host_alias(name: &str, workspace: &str) -> String {
format!("openshell-{name}.{workspace}")
fn stale_ssh_config_warning(gateway: Option<&str>, workspace: &str, sandbox: &str) -> String {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We own the managed include file (install_ssh_config), so we could silently rewrite stale blocks there on the next sandbox connect. That would leave the warning only for hand-pasted entries.

Comment thread crates/openshell-cli/src/main.rs Resolved
disable_raw_mode().into_diagnostic()?;

// Step 8: Spawn SSH as child process and wait.
if let Some(warning) = unverified_warning {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This prints just before ssh takes the terminal, so it's easy to miss. Show it in the status bar too? Same at L1181.

A generated entry has one host alias per sandbox, so a shared connection
never reaches another sandbox. Stop disabling ControlMaster there.

Also name the missing flags in the ssh-proxy warning, note that the
gateway issues only Ed25519 host keys, and document that the fingerprint
is read per connection and that unverified connections are allowed by
default.

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

Copy link
Copy Markdown

Compatibility review (advisory)

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

1. configuration — Risk explicitly accepted

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

  • Impact: Existing users of these directories lose sandbox connect, forwarding, transfers, and sandbox ssh-config with an 'SSH known-hosts path ... cannot be used' error.

  • Action: Retain existing paths through an SSH-safe pin location for v0.1.10; accepted XDG_CONFIG_HOME relocation does not satisfy the patch no-break policy.

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

  • Acceptance: comment

Review details
  • Execution: complete
  • Candidate: PR #5703 (8be354e70798d17737f3eb25d24a22d69405b997)
  • Baseline: ed8a0d98acee9b7f9e4efe004bc6a748524406b7 (ed8a0d98acee9b7f9e4efe004bc6a748524406b7)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

The host alias of an entry names the sandbox and the workspace, not the
gateway. With a user's persistent ControlMaster, ssh reused a connection
opened to one gateway's sandbox for the entry of the same sandbox name
on another gateway, and ran no host key check. Restore the three options
that turn sharing off for the entry.

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

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.

2 participants