Security

Security

Credentials

Passwords live only in the OS keychain (via the keyring crate). They are never written to hosts.toml, logs, or the terminal. Add them with Ctrl+K.

Keychain prompts (macOS)

macOS ties "Always Allow" to the binary's code signature. An unsigned binary is identified by its content hash, which changes on every update — so the grant is invalidated and macOS re-prompts for each host's credential after an update.

Run this once after each update to stop that:

gukab --trust-keychain

It gives the binary a stable, per-machine self-signed code-signing identity (gukab-local-signing) and signs it. Because the keychain then identifies the binary by that certificate instead of its hash, "Always Allow" stays valid across restarts and updates. Free — no Apple Developer ID.

• The signing key is generated locally, lives only in your login keychain, and is authorised for codesign only (not "all apps"); the temp key material is wiped right after import.
• Your host secrets are untouched — still one keychain entry each. This only changes how the binary is identified.
• After signing, the keychain prompts once per distinct credential (per credential_ref / send_credential), not per host — click Always Allow each time. Hosts that share a credential are covered by a single grant. Then gukab stops asking, even across close/reopen and updates.
• The first run may also ask to let codesign use the new signing key — click Always Allow there too. After future updates, just re-run the command; no further clicks needed.
• Needs /usr/bin/openssl, /usr/bin/codesign, security — all stock on macOS.

SSH private keys

When a host uses identity_file, gukab stores only the file path — never the key bytes. The key stays on disk where you keep it; the passphrase (if any) is read from the OS keychain at connect time and never written to config. On load, a key file readable by group/other triggers an OpenSSH-style warning (chmod 600 recommended) but is not blocked, since the key never leaves your own disk.

Host-key verification (trust-on-first-use)

On first connect, a server's SSH host-key SHA-256 fingerprint is recorded in ~/.config/gukab/known_hosts. On later connects, gukab refuses to connect if a known host's key has changed (possible MITM).

To accept a legitimate key change (device reimaged, replaced, etc.), remove that host's line from ~/.config/gukab/known_hosts and reconnect.

File permissions

hosts.toml, known_hosts, and session logs are written owner-only (0600), and log directories 0700. Session logs can contain sensitive command output (e.g. show running-config) — review retention for your environment. Passwords typed at prompts are not captured (the remote does not echo them).

Known advisory

RUSTSEC-2023-0071 (Marvin timing side-channel in the transitive rsa crate) has no upstream fix yet. Practical impact here is low — gukab is an SSH client and verifies RSA server signatures rather than performing RSA private-key decryption. It will be resolved when rsa ships a fix.