SSH Protocol Proxies
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate acts as a smart SSH bastion host that facilitates secure access to internal infrastructure without requiring specialized client applications. Unlike a traditional jump host, Warpgate forwards connections directly to the target host while providing session recording, centralized authentication, and management through a web interface.
The SSH protocol implementation in Warpgate is built using the russh crate and supports native 2FA, SSO, and session replay capabilities. It is designed to be a single-binary solution with no external dependencies, written entirely in safe Rust.
Sources: README.md:12-22, warpgate-protocol-ssh/src/lib.rs:20-22
Architecture and Components
The SSH proxy system is comprised of several key components that handle the lifecycle of an SSH connection, from initial listener binding to target host communication.
SSH Protocol Server
The SSHProtocolServer is the primary entry point for the SSH module. It is responsible for initializing the necessary key infrastructure (host and client keys) and starting the server listener on a configured ListenEndpoint.
Sources: warpgate-protocol-ssh/src/lib.rs:24-40
Key Management
Warpgate manages several types of SSH keys:
- Host Keys: Used by Warpgate to identify itself to connecting users.
- Client Keys: Used by Warpgate to authenticate itself against target hosts.
- Known Hosts: A list of trusted target host keys to prevent Man-in-the-Middle (MITM) attacks.
Sources: warpgate-protocol-ssh/src/lib.rs:30-31, warpgate-web/src/admin/config/SSHKeys.svelte:31-35
Connection Flow
The following diagram illustrates the high-level flow when a user connects to a target via the SSH proxy.
Target Configuration and Authentication
Targets are configured via the Admin UI, where administrators define how Warpgate should connect to the downstream SSH server.
Authentication Modes
Warpgate supports two primary authentication methods when connecting to a target SSH host:
- PublicKey: Warpgate uses its own generated private keys. The corresponding public keys must be added to the target's
authorized_keysfile. - Password: Warpgate uses a stored password to authenticate against the target.
Sources: warpgate-web/src/admin/Target.svelte:150-170, warpgate-web/src/admin/config/SSHKeys.svelte:33-35
Configuration Parameters
| Parameter | Type | Description |
|---|---|---|
host | String | The hostname or IP address of the destination SSH server. |
port | Integer | The port number on the destination server (default: 22). |
username | String | The username to use on the target host (optional). |
allowInsecureAlgos | Boolean | Whether to allow older/insecure SSH algorithms for legacy devices. |
hostKeyVerification | Enum | Mode for verifying target host keys: AutoAccept, AutoReject, or Prompt. |
| Sources: warpgate-web/src/admin/Target.svelte:135-175, warpgate-protocol-ssh/src/lib.rs:67-93, warpgate/src/commands/setup.rs:140-155 |
Connection Strings and Credentials
Warpgate uses a specific credential format to route users to the correct target host through the proxy.
Username Formatting
To connect through Warpgate, the SSH username must follow a specific pattern:
- Standard:
<username>:<target_name> - Ticket-based:
ticket-<ticket_secret>(used for temporary, one-time access)
Sources: warpgate-web/src/common/protocols.ts:13-19
Example Command
An example SSH command for a user named alice connecting to a target named production-db would be:
ssh alice:production-db@warpgate-host -p 2222
Sources: warpgate-web/src/common/protocols.ts:21-23, warpgate-web/src/common/ConnectionInstructions.svelte:36-39
Verification and Testing
Warpgate includes a test_target function to verify connectivity and host keys before finalizing a target configuration.
Setup and Key Generation
During the initial installation via warpgate setup, the system generates the necessary cryptographic identity for the SSH protocol.
- Host Key Generation: Warpgate generates unique SSH host keys (RSA, Ed25519) stored in the configured
ssh.keysdirectory. - Client Key Generation: Separate keys used by Warpgate when acting as a client to target hosts.
- Listener Configuration: The administrator specifies the
ListenEndpoint(e.g.,[::]:2222) where the SSH proxy will accept connections.
Sources: warpgate/src/commands/setup.rs:247-248, warpgate/src/commands/setup.rs:140-155
Summary
SSH Protocol Proxies in Warpgate provide a secure, auditable gateway for SSH traffic. By intercepting connections and requiring a <user>:<target> credential format, Warpgate can enforce centralized authentication policies (like 2FA) and record all terminal activity, regardless of whether the target host natively supports these features. The system maintains high security standards by managing host key verification and providing clear instructions for authorized_keys configuration.
Sources: README.md:12-25, warpgate-protocol-ssh/src/lib.rs:20-40