Introduction to Warpgate
Relevant source files
The following files were used as context for generating this wiki page:
Warpgate is a smart bastion host designed for Linux that facilitates secure access to SSH, HTTPS, MySQL, and PostgreSQL services. Unlike traditional jump hosts, Warpgate forwards connections directly to the target host while recording every session for later review. It is written in 100% safe Rust and operates as a single binary with no external dependencies, making it suitable for deployment in DMZ environments.
Sources: README.md:1-15
Core Functionality
Warpgate acts as a protocol-aware proxy. It accepts incoming connections using specifically formatted credentials, authenticates the user against a local database or external provider, and then establishes a connection to the final target host. The system supports native 2FA (TOTP) and SSO (OpenID Connect).
The following diagram illustrates the high-level connection flow through the Warpgate bastion:
Protocol Support and Session Recording
Warpgate provides specific handlers for different protocols to ensure transparent proxying and recording:
- SSH: Handles key-based or password authentication and can record terminal sessions.
- HTTPS: Presents a target selection UI and proxies traffic to internal URLs.
- Databases (MySQL/PostgreSQL): Supports secure proxying to database instances.
- Web Admin: A built-in Svelte-based interface for managing users, roles, and targets.
Sources: README.md:10-14, warpgate-web/src/admin/Target.svelte:114-160
System Architecture
Warpgate is structured as a modular Rust project. The core logic is housed in warpgate-core, while protocol-specific implementations are separated into dedicated crates.
| Component | Description |
|---|---|
warpgate-core | Contains the primary service logic, authentication handlers, and database migrations. |
warpgate-admin | Implements the administrative API and OpenAPI schemas. |
warpgate-protocol-* | Individual crates for SSH, HTTP, MySQL, and PostgreSQL protocol handling. |
warpgate-db-entities | Defines the database schema using Sea-ORM. |
warpgate-web | The frontend Svelte application for the Admin and Gateway UIs. |
Sources: warpgate-core/Cargo.toml, warpgate/Cargo.toml:35-42, README.md:65-71
Data Flow for Connection Establishment
When a client initiates a connection, Warpgate follows a specific sequence to validate and route the request:
Configuration and Setup
Warpgate uses a YAML configuration file (default: /etc/warpgate.yaml). The initial setup is typically performed using the setup or unattended-setup commands.
Key Setup Parameters
During setup, the following critical components are initialized:
- Database URL: Usually a local SQLite database stored in
/var/lib/warpgate/db. - Listen Endpoints: Specific IP and port bindings for each enabled protocol.
- TLS Certificates: Self-signed certificates generated for HTTPS and database encryption if not provided.
- Admin User: A default
adminuser is created with a user-defined password.
Sources: warpgate/src/commands/setup.rs:77-105, warpgate/src/commands/setup.rs:220-255, warpgate/src/main.rs:28-40
CLI Commands
The main binary supports several subcommands for lifecycle management:
Sources: warpgate/src/main.rs:28-85
Security Model
Warpgate operates on a trust model where specific inputs are considered trusted:
- Contents of the connected database.
- The configuration file (provided permissions are locked down).
- Authenticated administrative HTTP requests.
The system enforces security by connecting both parties only after local authentication and authorization checks. It does NOT trust traffic coming from target hosts until it has been processed through the proxy.
Sources: SECURITY.md:12-23
Conclusion
Warpgate serves as a secure, auditable gateway for infrastructure access. By combining protocol-specific proxying with session recording and unified authentication, it provides a centralized point of control for SSH, Web, and Database access without requiring specialized client software.
Sources: README.md:5-15, README.md:52-57