Skip to content

Security

Jump to bottom
Mehdi edited this page Sep 2, 2026 · 4 revisions

Security

SSH Pilot is built around a simple rule: your passwords and passphrases should never live as plain text in the app’s UI layer, config files, or logs. Storage uses real credential vaults. Autofill uses OpenSSH’s official askpass path — not typing secrets into the terminal stream.

This page explains why that design is secure. For how to choose and set up a backend, see Credentials.

The Short Version

Concern How SSH Pilot handles it
Where passwords are stored In your chosen vault (system keyring, KeePass, Bitwarden/Vaultwarden, or pass) — not in ~/.ssh/config or app preferences as plaintext
How OpenSSH receives a password Via SSH_ASKPASS (a short-lived helper), the same mechanism desktop SSH tools use
Does the GUI hold a password dump? No. The window process does not enumerate decrypted credentials for normal use
Do secrets appear in logs? No. Diagnostic output is sanitized; askpass helpers print only the secret to OpenSSH on stdout, never diagnostics mixed with it
Can you avoid storing passwords? Yes — use SSH keys + agent, hardware keys (PKCS#11), or SSH Agent Only storage

Secure Storage (Not a Homegrown Password File)

When you check Save password, SSH Pilot does not write the secret into its settings JSON or into your SSH config. It stores it through a credential backend you control:

Backend Why it is trustworthy
System keyring (libsecret) Uses GNOME Keyring / KDE Wallet (or the macOS Keychain via keyring). Secrets are encrypted by the OS and typically unlock with your login session.
KeePass (.kdbx) Industry-standard encrypted database; unlocked only with your master password (and optional key file).
Bitwarden / Vaultwarden Encrypted vault; SSH Pilot talks to the vault through the CLI/rbw agent. See Bitwarden & Vaultwarden.
pass Classic Unix password store protected by your GPG key.
SSH Agent Only Nothing persistent for passwords — authentication relies on keys already in the agent.

Automatic mode picks an available backend (usually the system keyring on Linux desktops). You can lock vaults after inactivity (Settings > Security > Vault lock timeout) so cached access does not last forever.

SSH Pilot also keeps connection metadata (nickname, host, user) separate from secret values. Normal APIs and UI lists show hosts and status — not decrypted passwords.

Secure Autofill (Askpass, Not Fake Typing)

OpenSSH needs a password or key passphrase at connect time. SSH Pilot supplies it the way OpenSSH expects:

  1. OpenSSH sets SSH_ASKPASS and asks for a secret
  2. A small helper talks to SSH Pilot’s daemon over a local socket (token-protected)
  3. If a matching secret exists in your vault (or was staged for this connect), it is returned once
  4. If not, you get a secure dialog; optionally save it to the vault for next time
  5. The helper clears its copy after handing the secret to OpenSSH

Why this matters

  • No fake terminal typing for login passwords on the native SSH path. Secrets are not pasted into the PTY as if you typed them (which would expose them to terminal scrollback and recording).
  • One-shot staging. Session passwords held for a pending connect live in memory for a single askpass consumption — they are not left on disk as a standing cache.
  • Daemon-owned secrets. Connect-time lookup and vault lifecycle run in the daemon. The GTK frontend does not walk a list of decrypted passwords.
  • OTP / MFA still work. When OpenSSH asks for a verification code, askpass shows a challenge dialog instead of inventing a stored password.
  • Hardware keys and agents. PKCS#11 and SSH agent flows stay on the OpenSSH path; see Key Management.

What Is Never Done

SSH Pilot’s security model deliberately avoids:

  • Storing login passwords in plaintext preference files
  • Putting passwords on process command lines (where other users can see them in ps)
  • Returning secret values in ordinary API responses or connection list payloads
  • Shipping passwords inside normal log lines (diagnostics redact sensitive fields)
  • Requiring a cloud account — local keyring / KeePass / pass / agent-only all work offline

Backups that include secrets are explicit export operations. Archives can be passphrase-protected; Bitwarden backups use vault secure notes. See Backup.

Practical Hardening Tips

  1. Prefer SSH keys over passwords when the server allows it — deploy with Key Management, then stop saving login passwords.
  2. Use the system keyring on a single trusted machine for the smoothest and still OS-backed experience.
  3. Use KeePass or Bitwarden if you need portable or multi-device secrets — and unlock only when you need them.
  4. Enable vault lock timeout if you step away from the desk often.
  5. Choose SSH Agent Only (plus a hardware key if you have one) for maximum minimalism — nothing password-like is persisted by SSH Pilot.
  6. Isolated Mode keeps SSH Pilot’s config/keys separate from ~/.ssh if you want a sandbox; passwords still use the same credential backend. See Isolated Mode.
  7. Plugins run with your user permissions — only install plugins you trust (Plugins).

Reporting Security Issues

If you believe you found a vulnerability in credential handling, askpass, or backup export:

  1. Prefer a private report via GitHub Security Advisories when available, or open a carefully redacted GitHub Issue
  2. Do not attach real passwords, private keys, or vault dumps
  3. Include OS, SSH Pilot version, and steps to reproduce with dummy credentials

For connection/askpass troubleshooting (without secrets), see Troubleshooting.

Next Steps

Clone this wiki locally