SSH host keys and read-only commands

First connection: why verify the host key?

The host-key fingerprint helps confirm that you reached the intended server. In 0.3.1, the local management page lets you save the SSH address and port, then choose “Get public fingerprint.” This performs a bounded key exchange only: no stored credentials are read, no authentication is attempted and no command runs. The value is marked as network-observed and untrusted.

Compare its SHA-256 fingerprint against an independent trusted source such as a server console or administrator. Once it matches, confirm the fingerprint into the draft resource, save it and test the connection. Investigate any later key change instead of accepting it automatically. Only an authenticated local Web session can confirm the key; MCP has no automatic trust-confirmation API.

Request a controlled SSH operation

Specify the absolute path of the remote program and its arguments separately, with a bounded read-only goal and expected output. The user reviews and approves the exact operation locally. Then create the run with an idempotency key and read filtered results by cursor. The broker uses the credential internally for authentication; it is not returned as output.

Boundary and checks

A mismatched fingerprint is rejected before authentication. After a timeout, disconnect or cancellation, inspect the remote state before assuming nothing ran. See file-transfer tasks for SFTP and troubleshooting for connection failures.

Configure a fixed target

Record the address, port, account and password or supported private-key reference in one resource. The address and account are readable metadata; the secret goes only to the OS credential store. You may first save only address and port, fetch the network-observed public fingerprint in the local console, compare it through an independent trusted channel, then confirm, save and test. The connection test authenticates and disconnects without running a command.

One read-only operation

An AI can select a saved connection from the non-secret catalog and call secretbridge_request_ssh with an absolute remote program path, separate arguments, optional absolute working directory and timeout. The request freezes host, account, fingerprint, credential reference and command. Review the real target and output scope in the local page before running, then read filtered output by cursor. A shell interpreter and its full script need explicit review; arguments are not silently joined into a command line.

The broker uses the saved SSH password or Ed25519/ECDSA private key internally. It does not accept unknown host keys automatically or turn off verification to fix connectivity. Conflicting addresses or accounts in a request and resource are rejected.

Key changes and uncertain outcomes

On host_key_rejected or any fingerprint change, confirm a legitimate key rotation through a server console or administrator, then update the local resource and request fresh approval. Timeout, disconnect and cancellation do not prove the remote command did not run. Inspect run history and the server before retrying. For single-file transfer, see SFTP and Git.