DOCSEARCHbyAlgolia
Submit Docs

Warpgate Documentation

repository·main·Indexed 27 days ago

https://github.com/warp-tech/warpgate

A transparent bastion host providing secure, audited access to network services including SSH, Kubernetes, MySQL, PostgreSQL, RDP, and VNC. Features include native 2FA (TOTP), SSO (OpenID Connect), session recording, and built-in brute-force protection with IP blocking and user lockout. The system includes an Admin UI and API for managing users and targets, and supports clustered deployments.

Tokens
24.5K
Snippets
52
Records
200
Agent score
92%

What's inside Warpgate

  1. Structure of a Local Test Environment

    main

    Each local testing environment subfolder follows a standardized structure:

    • docker-compose.yml: The Docker Compose configuration for the environment.
    • data/: Contains Warpgate configuration files (e.g., warpgate.yaml) and persistent data.
    • scripts/: Contains scripts used to execute tests.
    • README.md: Feature-specific instructions and documentation.

  2. Set up Login Protection local testing environment

    main

    Use the Docker Compose configuration in docker/local-testing/login-protection to test brute-force protection features including IP-based rate limiting, exponential backoff, and user account lockout.

    1. Build the Warpgate Image

    From the repository root, run:

    cd docker/local-testing/login-protection
docker compose build

    2. Start the Stack

    docker compose up -d

    This starts Warpgate and several target services:

    • Warpgate: SSH (2222), Admin UI (8888), MySQL (33306), PostgreSQL (55432)
    • Echo Server: 3000
    • SSH Target: 2223
    • MySQL Target: 3306
    • PostgreSQL Target: 5432

    3. Initialize Warpgate

    Run the setup command inside the container:

    docker exec -it warpgate-login-protection warpgate setup

    Alternatively, run with an admin token enabled:

    docker exec -it warpgate-login-protection warpgate run --enable-admin-token

    4. Access Admin UI

    Open https://localhost:8888 and use the credentials created during setup.

    cd docker/local-testing/login-protection
docker compose build
docker compose up -d
docker exec -it warpgate-login-protection warpgate setup

  4. Build Warpgate from source

    main

    To build Warpgate from the source code, ensure you have Rust, NodeJS, and NPM installed. Use just to manage tasks.

    1. Install just: cargo install just
    2. Clone the repository.
    3. Install admin UI dependencies: just npm install
    4. Build the frontend: just npm run build
    5. Build the Warpgate binary: cargo build (use --release for optimized builds).

    The resulting binary will be located in target/debug or target/release.

    cargo install just
just npm install
just npm run build
cargo build --release

  5. Get started with Warpgate

    main

    Warpgate is a bastion host for SSH, HTTPS, Kubernetes, MySQL, PostgreSQL, RDP, and VNC. It provides precise 1:1 assignment between users and services, native 2FA/SSO, and full session recording without requiring a custom client app.

    To begin using Warpgate, you can follow the official documentation for standard installation or Docker-based deployment:

    Available binaries can be found in the GitHub Releases or via Nightly Builds.

  7. Quick Start with Local Testing Environments

    main

    To spin up a local testing environment for a specific Warpgate feature, navigate to the feature's subfolder within the docker/local-testing/ directory and use Docker Compose to start the services in detached mode.

    Available environments include:

    • login-protection: Tests IP blocking, user lockout, and exponential backoff (Fail2Ban-like functionality).
    cd <feature-folder>
docker compose up -d

  8. Add a New Local Test Environment

    main

    To create a new testing environment for a Warpgate feature, follow these steps:

    1. Create a new directory: mkdir <feature-name>
    2. Copy the directory structure from an existing environment (e.g., login-protection).
    3. Customize the docker-compose.yml and data/warpgate.yaml files.
    4. Add relevant test scripts to the scripts/ directory.
    5. Provide feature-specific instructions in a new README.md.

  9. Perform an unattended setup of Warpgate

    main

    For automated environments (like CI/CD or custom Docker images), use the unattended-setup command to bypass interactive prompts. You can provide configuration via CLI flags or environment variables.

    Available Flags:

    • --data-path <path>: Directory to store app data.
    • --database-url <url>: The database connection string.
    • --http-port <port>: Port for HTTP connections.
    • --ssh-port <port>: Port for SSH connections (enables SSH listener).
    • --mysql-port <port>: Port for MySQL connections (enables MySQL listener).
    • --postgres-port <port>: Port for PostgreSQL connections (enables PostgreSQL listener).
    • --kubernetes-port <port>: Port for Kubernetes connections (enables Kubernetes listener).
    • --vnc-port <port>: Port for VNC connections (enables VNC listener).
    • --rdp-port <port>: Port for RDP connections (enables RDP listener).
    • --record-sessions <bool>: Enable or disable session recording.
    • --admin-password <password>: Password for the admin user (alternatively use WARPGATE_ADMIN_PASSWORD env var).
    • --external-host <host>: Set the external host address.

    Environment Variables:

    • WARPGATE_ADMIN_PASSWORD: Sets the admin password if not provided via flag.

  10. Run Warpgate using Docker Compose

    main

    You can deploy Warpgate using the provided Docker Compose configuration. This setup exposes the necessary ports for SSH, the Web UI, and database protocols, and persists data to a local ./data directory.

    Exposed Ports:

    • 2222: SSH service
    • 8888: Web UI / API
    • 33306: Database protocol proxy

    Data Persistence:

    • The ./data directory on the host is mounted to /data inside the container.
    services:
  warpgate:
    image: ghcr.io/warp-tech/warpgate
    ports:
      - 2222:2222
      - 8888:8888
      - 33306:33306
    volumes:
      - ./data:/data
    stdin_open: true
    tty: true

  12. Manage Recording Storage Lifecycle

    main

    The Storage system manages the lifecycle of recording files.

    • Writing: Use open_sink to obtain a RecordingSink. For S3 backends, this automatically initiates a multipart upload. You must call finalize() on the sink to complete the upload or flush the local file.
    • Cleanup: When a RecordingSink is used with S3, a RecordingSinkCleanupGuard is returned upon finalization. This guard ensures that the local scratch files used during the multipart upload are deleted from the local disk when the guard is dropped.
    • Deletion: The remove method deletes all associated recording files (NDJsonData, Index, and TcpDumpData) from either the local filesystem or S3, and attempts to clean up empty parent directories.