Amnezia-Web-Panel/SSH_HOST_KEYS.md

Trusted SSH host keys

v1.7.8 — web enrollment and migration

Administrators can open a server page and use SSH host key → Inspect SSH key, including when statistics/protocol loading fails. Unknown and changed keys have distinct warnings; the server list no longer equates TCP reachability with trusted SSH. Inspection performs SSH key exchange only: no username, password, private key or agent authentication is sent.

Server-list refreshes check TCP reachability and local pin presence only, not live SSH identity (ssh_verified: false); use Inspect SSH key to check the current fingerprint. Refreshing a list never starts an extra SSH key exchange. Inspection uses the same pinned-algorithm preference as Paramiko SSHClient, so an existing RSA pin is not falsely reported changed merely because the server also offers Ed25519 or ECDSA.

Compare the displayed algorithm and SHA256 fingerprint with an independent VPS console (use the matching /etc/ssh/ssh_host_*_key.pub, not necessarily Ed25519). For replacement, investigate why the old fingerprint changed. Tick the explicit verification checkbox, then Trust key and retry. The page reloads and retries normal operations with a fresh connection and reset cooldown. No VPN clients, VPN keys or configurations are changed.

Confirmation is signed, expires after five minutes, binds the server UID, host, port and exact candidate key, and re-probes before saving. Restarting the panel invalidates outstanding confirmations. A changed candidate or endpoint requires a fresh inspection. Only admins (not support users) may use these POST endpoints; session/Bearer access controls and same-origin browser checks apply.

Confirmations also bind the previous trust entries: a concurrent administrator change requires re-inspection rather than silently overwriting that decision. Endpoint edits are serialized with confirmation in the panel process. Modern browsers' same-origin Fetch Metadata permits TLS-terminating reverse proxies; older browsers require the proxy to preserve the external request origin.

The default file is ssh_known_hosts beside the resolved DATA_FILE: beside app.py for source installs, beside the executable for frozen installs, and /app/data/ssh_known_hosts for the supplied Docker Compose deployment. Override with SSH_KNOWN_HOSTS_FILE. A missing file can be created by enrollment; its parent must be writable. Read-only mounts/files produce an explicit error; make the persistent trust location writable if web enrollment is desired.

Updates are serialized within the panel process and use atomic file replacement. Other endpoints (including aliases on shared lines) are preserved; hashed entries and nonstandard ports are supported. Conflicting system ~/.ssh/known_hosts entries are never silently overridden: correct them independently as the panel OS user, then inspect again. Run one panel writer per trust file; external editors or multiple processes are not coordinated by the in-process lock.

Existing manually enrolled entries keep working. The manual procedure below is still supported for read-only/operator-managed trust. RejectPolicy remains in force; there is no automatic trust-on-first-use fallback.

SSH connections reject unknown or changed host keys before password/public-key authentication. There is no automatic first-use enrollment. Existing SSH user keys and passwords are still supported; server host trust is a separate check.

Upgrade prerequisite: enroll every managed SSH endpoint manually before upgrade or use the administrator recovery controls after upgrade. Until enrollment, operations fail closed. Do not restore AutoAddPolicy as a workaround.

Paramiko loads the panel process user's ~/.ssh/known_hosts and a persistent panel trust file, defaulting to ssh_known_hosts beside DATA_FILE (normally /app/data/ssh_known_hosts in Docker). Set SSH_KNOWN_HOSTS_FILE to use another file. An explicitly configured missing, unreadable or malformed file is an error. Bind-mount an operator-managed file read-only, or place it in the existing persistent data volume; do not rely on an ephemeral container layer. Restrict write access to trusted operators and ensure the panel user can read it.

Initial enrollment

1. Obtain the endpoint's public host key and SHA256 fingerprint using an independent trusted channel, such as the VPS provider console or an existing independently verified administrative SSH session. On the endpoint:

   ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256
   cat /etc/ssh/ssh_host_ed25519_key.pub
   

   These are public host keys, never client private keys.

2. Confirm the fingerprint independently. ssh-keyscan can collect a candidate but cannot authenticate it: never pipe its output directly into trusted known_hosts without comparing fingerprints through the independent channel.

3. Add an OpenSSH known_hosts line to a private candidate trust file:

   node.example.test ssh-ed25519 <verified-public-key-base64>
   [node.example.test]:2222 ssh-ed25519 <verified-public-key-base64>
   

   Use the exact configured SSH hostname/IP and port. A non-default port requires [host]:port. Enroll all aliases actually used by the panel. Hostnames do not replace fingerprint verification; DNS changes cannot enroll another key.

4. Validate with ssh-keygen -lf <candidate> -E sha256, preserve a backup, and install the verified file atomically with restricted permissions. Mount or configure it for the panel, then test a read-only SSH operation.

Controlled rotation and failures

A changed key is rejected; do not approve it based on the error message alone. Verify the new fingerprint independently, schedule rotation, back up the trust file, replace the relevant verified entry atomically, and reconnect/restart the panel during the agreed window. Existing pooled SSH transports keep the host identity verified at their original handshake until disconnected; changing the file does not revoke an already-open transport. Paramiko reloads trust on each new handshake. Remove stale entries from both system and panel trust stores; system entries can take precedence over the panel file.

If verification fails or the endpoint is unavailable, the operation fails and the normal connection backoff applies. No trust file is rewritten by the panel. Restore only a previously verified backup when rolling back trust configuration. No VPN configuration, host key or user SSH key is regenerated by this feature.