wardenssh

README

WardenSSH 🛡️

Cross-Platform SSH Management TUI with native Bitwarden & Vaultwarden Integration

WardenSSH is a modern, cross-platform Terminal User Interface (TUI) application designed to manage SSH host connections and private keys seamlessly. Built using tview + tcell with an embedded terminal emulator (tvxterm).

The core security guarantee of WardenSSH is Zero-Disk-Footprint: private keys stored in Bitwarden/Vaultwarden are never written to disk. Keys are decrypted strictly in RAM at rest and served directly to ssh via an in-process SSH agent.

---

✨ Features

• 🔐 Native Bitwarden / Vaultwarden Integration: Direct in-process integration with Bitwarden Password Manager API (supports custom fields and multi-vault).
• 🔒 Zero-Disk-Footprint Security: Private keys remain encrypted at rest in your vault and exist only in RAM during execution. Served dynamically to ssh via an in-process agent.
• ⚡ Multi-Source Host Aggregation: Aggregate SSH hosts from multiple Bitwarden vaults alongside your local ~/.ssh/config.
• 🔍 Instant Fuzzy Search & Scoping: Lightning-fast filtering by host name, alias, or source scope (Tab cycle between all sources, individual vaults, or ~/.ssh/config).
• 🖥️ Embedded Terminal + Split Panes: Host list on the left, live SSH terminal on the right. Press Ctrl+B or Esc to move focus between panes.
• 🔄 Parallel Session Management: Run multiple concurrent SSH sessions — new hosts open in the right pane while previous sessions keep running in the background (yield-and-switch).
• 🔑 Secure OS Keyring Storage: Vault refresh tokens are stored securely in your operating system's native keyring (Windows Credential Manager, macOS Keychain, Linux Secret Service).
• 🌐 Cross-Platform: Full support for Linux, macOS, and Windows (utilizing Windows ConPTY and Named Pipes).
• 🔌 Graceful Offline Mode: Unreachable vaults degrade gracefully without breaking access to local ~/.ssh/config hosts.

---

🏗️ Architecture & How It Works

WardenSSH acts as the TUI Host Launcher, Vault Client, and In-Process SSH Agent simultaneously. No external bw CLI binary or OS ssh-agent service is required.

                  ┌─────────────────────────────────────┐
                  │   Bitwarden / Vaultwarden Server    │
                  └──────────────────┬──────────────────┘
                                     │ Encrypted Sync (HTTPS)
                                     ▼
┌────────────────────────────────────────────────────────────────────────┐
│ WardenSSH (Single Binary Process)                                      │
│                                                                        │
│  ┌────────────────────┐   Decrypted    ┌────────────────────────────┐  │
│  │ Native Vault Client│ ─────────────> │ RAM Key Cache              │  │
│  └────────────────────┘   (In-RAM)     └─────────────┬──────────────┘  │
│                                                      │                 │
│  ┌────────────────────┐                ┌─────────────▼──────────────┐  │
│  │ tview TUI Launcher │                │ In-Process SSH Agent       │  │
│  │ (split panes +     │                └─────────────┬──────────────┘  │
│  │  tvxterm terminal) │                              │                 │
│  └────────────────────┘                              │                 │
└──────────────────────────────────────────────────────┼─────────────────┘
                                                       │ SSH_AUTH_SOCK
                                                       │ (Named Pipe / Unix Socket)
                                                       ▼
                                         ┌───────────────────────────┐
                                         │  ssh Client (OpenSSH)     │
                                         └───────────────────────────┘

1. Vault Sync & Key Decryption: On host connection, the required SSH private key is decrypted on-demand into memory.
2. In-Process Agent: WardenSSH serves an ssh-agent protocol server on a local pipe/socket (\\.\pipe\wardenssh-agent on Windows, unix socket on Linux/macOS).
3. Execution: WardenSSH sets SSH_AUTH_SOCK and spawns ssh, enabling public-key authentication without writing key files to the filesystem.

---

🚀 Installation

Prerequisites

• Go 1.26+
• OpenSSH client (ssh) installed and available in your PATH.

Installing via go install

The easiest way to install the latest release:

go install github.com/ac-kurniawan/wardenssh@latest

Verify the installed version:

wardenssh -version

Alternatively, clone the repository and build manually:

git clone https://github.com/ac-kurniawan/wardenssh.git
cd wardenssh
go build -o wardenssh .

---

🏁 Quick Start

Launch WardenSSH by running:

wardenssh

On first launch, WardenSSH will guide you through setting up your Bitwarden or Vaultwarden vault connections.

--no-keyring Fallback

If running in a headless environment without an OS keyring service available, use the --no-keyring flag to prompt for master passwords interactively on launch:

wardenssh --no-keyring

---

⚙️ Configuration

Configuration is stored in ~/.ssh/wardenssh.json. This file contains only non-sensitive preferences and connection parameters. No secrets or tokens are stored in this file.

{
  "vaults": [
    {
      "name": "personal",
      "server": "https://vw.example.com",
      "email": "user@example.com"
    },
    {
      "name": "work",
      "server": "https://vaultwarden.company.com",
      "email": "employee@company.com"
    }
  ],
  "custom_fields": {
    "host": "host",
    "user": "user",
    "port": "port",
    "proxyjump": "proxyjump"
  },
  "keyring": true
}

Bitwarden Vault Item Structure

To have an SSH Key item from Bitwarden/Vaultwarden appear in your WardenSSH host list:

1. Create an item of type SSH Key (Type 5) in your vault.
2. Store your private key in the standard SSH Key field.
3. Add a Custom Field named host (value: target hostname or IP address).
4. (Optional) Add Custom Fields for user, port, and proxyjump.

---

⌨️ Controls & Shortcuts

Host List (left pane)

Key / Shortcut	Action
↑ / ↓	Navigate host list
Enter	Connect to selected host
Tab	Cycle source filter scope (All → Vaults → ~/.ssh/config)
Type any text	Fuzzy filter hosts
Esc	Clear filter — or open the quit confirmation modal when the filter is empty
q / Ctrl+C	Open the exit confirmation modal
Ctrl+B	Move focus to the terminal pane (when a session is running)

Terminal pane (right)

Key / Shortcut	Action
Mouse click-drag	Select terminal text; copied to the OS clipboard on release
Ctrl+C (with a selection)	Copy the selection to the OS clipboard
Ctrl+C (no selection)	Forwarded to the remote shell as SIGINT
Ctrl+B	Return focus to the host list (session keeps running)
Esc	Forwarded to the remote shell (e.g. exits insert mode in vim)
All other keys	Forwarded to the remote shell

Copy reaches the OS clipboard via the native Wayland/X11 tool (wl-copy/xclip/xsel) when available, falling back to the OSC 52 escape sequence. On Windows the Win32 clipboard API is used. Terminals built on VTE (e.g. GNOME Terminal) do not support OSC 52, so copy there requires wl-clipboard/xclip to be installed.

Sessions

Action	Result
Enter on a new host	Opens a new session in the right pane; previous sessions keep running in the background
Enter on the active host	Opens a disconnect confirmation modal (y/Enter = disconnect, n/Esc = cancel)
Enter on a background host	Switches the right pane to that session (no duplicate spawn)
Session exits	Only that host's green dot clears; the most recent remaining session becomes active

Modals

Key	Action
k / Enter	Kill all sessions & quit
d	Detach sessions & quit
c / Esc	Cancel / dismiss

---

🔒 Security Model

WardenSSH is built with strict zero-trust local hygiene:

• Zero-Disk-Footprint: Private keys reside only in vault storage at rest and in volatile process RAM during active sessions. Keys are never written to ~/.ssh/, /tmp, or any local disk file.
• In-Memory Passphrases: Key passphrases are prompted interactively and cached only in session memory.
• Secure Keyring Auth: Vault session refresh tokens are saved in OS-level credential stores (Windows Credential Manager, macOS Keychain, Linux Secret Service).
• Master Password Required Each Launch: A refresh token alone cannot derive the vault symmetric key, so WardenSSH always prompts for the master password on startup.
• Read-Only SSH Config: WardenSSH parses ~/.ssh/config as a read-only data source and never modifies your local SSH configuration files.
• No Disk Logging: Diagnostics and errors are written strictly to stderr. No key material, hostnames, or connection metadata are logged to disk.

---

🌐 Cross-Platform Support

OS	Agent Socket / Pipe	OS Keyring Backend	PTY Engine
Linux	Unix Domain Socket	Secret Service API / libsecret	go-pty
macOS	Unix Domain Socket	macOS Keychain	go-pty
Windows	Named Pipe (\\.\pipe\...)	Windows Credential Manager	ConPTY (go-pty)

---

🧪 Testing

The CI pipeline (go test ./...) runs on every push to main across Linux, macOS, and Windows (see .github/workflows/test.yml):

go build ./...   # compile
go vet ./...     # static checks
go test ./...    # all tests

Key test areas:

• Agent protocol — every message type (list, sign, add, remove) plus malformed/oversized inputs (go test -run TestAgent).
• Crypto — Bitwarden test vectors, byte-identical to bw CLI output (go test -run TestCrypto).
• Vault client — mock-server tests for login/sync (go test -run TestVault).
• TUI — model state transitions, multi-session pane lifecycle, quit/disconnect modals.

The e2e harness (e2e/) drives the real binary via tmux against a live Vaultwarden + sshd and is run manually — it requires infrastructure that CI does not provision.

---

📄 License

This project is licensed under the MIT License.

Documentation

Overview

Command wardenssh is the WardenSSH launcher entrypoint. v0 wiring:

• load ~/.ssh/wardenssh.json (non-secret config; first run -> defaults)
• build the merged host list from ~/.ssh/config (file source) and the vault client (real vault auth via TUI setup modal, or FakeClient when no vaults are configured)
• start the in-process ssh-agent on a platform pipe and run the tview/tvxterm launcher