ZTTP: Zero-Trust SSH Bastion Proxy

🔗 Project Mirrors: GitHub | GitLab

ZTTP is a hardened, self-hosted Zero-Trust SSH bastion proxy built in Golang with HashiCorp Vault-backed key management, RBAC policy enforcement, full session recording, and an interactive admin TUI — designed for teams who need auditable, zero-trust access to production infrastructure.

Why ZTTP
Architecture Overview
Feature Highlights
Prerequisites
Quick Start — Server
Quick Start — Client
Configuration
Roles & RBAC Policy
Admin Console
Audit Logs & Session Recordings
Building from Source
Makefile Reference
Screenshots & Demo
Project Structure
Security Model
Contributing
License

Why ZTTP

Modern engineering teams need a way to give developers the minimum access required to do their jobs — no more, no less. Traditional SSH key distribution is error-prone: keys get shared, forgotten on laptops, and revoked days too late.

The ZTTP SSH proxy solves this by acting as the single zero-trust door into your infrastructure:

Problem	ZTTP Solution
SSH keys shared on laptops	Keys live only in HashiCorp Vault — never on disk
No visibility into who did what	Every keystroke is recorded in `.ttyrec` format
Blanket production access	Role-based policy engine enforces per-environment rules
No way to stop an active session	Kill-switch gRPC endpoint terminates any live session
Opaque access for auditors	Admin TUI with session playback, text logs, and admin action logs

Architecture Overview

Developer Laptop
      │
      │  zttp
      │  (Under the hood: SSH over port 2224)
      ▼
┌─────────────────────────────────────────────────────────┐
│                     ZTTP Proxy                          │
│                                                         │
│  ① Auth Gate     — bcrypt/Argon2id login TUI           │
│  ② RBAC Engine   — environment-aware policy check      │
│  ③ Vault Fetch   — ephemeral SSH key retrieval         │
│  ④ Bridge        — transparent TCP tunnel              │
│  ⑤ Audit Writer  — ttyrec frame recorder               │
└──────────┬──────────────────────────────────────────────┘
           │  ssh (private IP, ephemeral key)
           ▼
     Target Server

Infrastructure services (Docker Compose):

Service	Purpose
`zttp-proxy`	The core ZTTP SSH bastion proxy (Golang binary)
`zttp-postgres`	Control-plane database (users, servers, RBAC policies)
`zttp-vault`	HashiCorp Vault — stores SSH private keys
`zttp-nginx`	Serves CLI installers at `/release/`
`zttp-init-audit`	One-shot container that fixes volume permissions

Feature Highlights

🔐 Zero-trust authentication — Interactive SSH login TUI with bcrypt password hashing, rate limiting, and account lockout after 5 failed attempts
🛡️ RBAC policy engine — Per-role, per-environment access control with a single optimized PostgreSQL JOIN (no round-trips)
🗝️ Vault-backed SSH keys — Private keys never touch disk; fetched ephemerally per session from HashiCorp Vault
📹 Full session recording — All sessions are recorded in .ttyrec format with timestamped frames
🖥️ Interactive Admin TUI — Full terminal UI for user management, server registration, access grants, and log review
🔍 Audit Log Viewer — Browse sessions by server, replay recordings, or read clean text logs directly from the admin console
⚡ Kill Switch — gRPC endpoint to terminate any live session instantly
📋 Admin Action Log — Every administrative action (user creation, access grants, log viewing) is logged to a persistent audit trail
🌍 Multi-platform client — Single-binary CLI for Linux, macOS (amd64/arm64), and Windows

Prerequisites

Server (proxy host):

Docker ≥ 24 and Docker Compose ≥ 2.20
A public or LAN-accessible IP on port 2224
make (optional, but recommended)

Developer (client):

Any SSH client (ssh command)
Linux, macOS, or Windows machine

Quick Start — Server

1. Clone the repository

git clone https://gitlab.com/Nihal799/zttp.git
cd zttp

2. Configure your environment

cp .env.example .env

Edit .env and set at minimum:

PROXY_NODE_IP=<your-server-public-ip>
POSTGRES_PASSWORD=<a-strong-password>
VAULT_TOKEN=<a-strong-vault-token>

⚠️ Never commit your .env file. It is listed in .gitignore.

3. Start all services

make docker-up
# or directly:
docker compose -f deploy/docker-compose.yml up -d --build

4. Verify services are healthy

make docker-ps
curl http://localhost:8080/healthz

5. Build and publish the CLI installers

make release PROXY_ADDR=<your-server-ip>:2224

This cross-compiles clients for all platforms and auto-updates dist/install.sh and dist/install.ps1 with the correct server URL. The Nginx container serves these at http://<your-server-ip>:8555/.

Quick Start — Client

Linux / macOS

curl -fsSL http://<proxy-ip>:8555/install.sh | bash

Windows (PowerShell, run as Administrator)

irm http://<proxy-ip>:8555/install.ps1 | iex

Connect

Once installed, connect to the ZTTP gateway:

zttp
# or directly:
ssh -p 2224 <your-username>@<proxy-ip>

You will be presented with a terminal login screen. After authentication, you'll see a list of servers you are authorized to access.

Configuration

All configuration is via environment variables (or .env file). See .env.example for the full reference.

Variable	Default	Description
`PROXY_LISTEN_ADDR`	`0.0.0.0:2222`	SSH proxy bind address
`HTTP_LISTEN_ADDR`	`0.0.0.0:8080`	Health check HTTP address
`GRPC_LISTEN_ADDR`	`0.0.0.0:9090`	Kill-switch gRPC address
`PROXY_NODE_IP`	`127.0.0.1`	External IP baked into CLI binaries
`DATABASE_URL`	`postgres://zttp:...`	PostgreSQL connection string
`VAULT_ADDR`	`http://localhost:8201`	Vault server URL
`VAULT_TOKEN`	`dev-root-token-zttp`	Vault root token (dev only — use AppRole in prod)
`MAX_FAILED_ATTEMPTS`	`5`	Lockout threshold
`LOCKOUT_DURATION`	`15m`	Duration of account lockout
`RATE_LIMIT_PER_MIN`	`10`	Max login attempts per minute per IP
`AUDIT_LOG_DIR`	`/var/log/zttp/audit`	Path to session recording directory
`SOC_WEBHOOK_URL`	(empty)	Optional webhook for SOC alerting

Roles & RBAC Policy

ZTTP uses a role-based model. Each user is assigned a role; each role has a policy that defines which server environments it can access.

Role	Access
`security-admin`	Full access to all environments + Admin Console
`sre-tier1`	All environments including production
`sre-tier2`	Staging and development only
`dev`	Development environment only
`readonly`	Development environment, restricted command set

Roles and server assignments are managed through the Admin Console (see below). The RBAC engine performs all checks in a single PostgreSQL query — it never exposes why access was denied to the client (enumeration protection).

Admin Console

Connect to the zttp-admin server from the gateway menu, or log in with an account that has the security-admin role.

The Admin Console provides:

zttp

Populaires