ZTTP: Zero-Trust-SSH-Bastion-Proxy

🔗 Projekt-Mirrors: GitHub | GitLab

ZTTP ist ein gehärteter, selbst gehosteter Zero-Trust-SSH-Bastion-Proxy, geschrieben in Golang, mit HashiCorp-Vault-gestützter Schlüsselverwaltung, RBAC-Richtliniendurchsetzung, vollständiger Sitzungsaufzeichnung und einer interaktiven Admin-TUI — konzipiert für Teams, die auditierbaren Zero-Trust-Zugriff auf Produktionsinfrastruktur benötigen.

Inhaltsverzeichnis

Warum ZTTP
Architekturübersicht
Funktionshighlights
Voraussetzungen
Schnellstart — Server
Schnellstart — Client
Konfiguration
Rollen & RBAC-Richtlinie
Admin-Konsole
Audit-Logs & Sitzungsaufzeichnungen
Aus dem Quellcode bauen
Makefile-Referenz
Screenshots & Demo
Projektstruktur
Sicherheitsmodell
Mitwirken
Lizenz

Warum ZTTP

Moderne Engineering-Teams benötigen eine Möglichkeit, Entwicklern den minimal erforderlichen Zugriff zu gewähren, um ihre Aufgaben zu erledigen — nicht mehr und nicht weniger. Die traditionelle Verteilung von SSH-Schlüsseln ist fehleranfällig: Schlüssel werden weitergegeben, auf Laptops vergessen und Tage zu spät widerrufen.

Der ZTTP-SSH-Proxy löst dies, indem er als einzige Zero-Trust-Tür in Ihre Infrastruktur fungiert:

Problem	ZTTP-Lösung
SSH-Schlüssel auf Laptops geteilt	Schlüssel liegen ausschließlich in HashiCorp Vault — niemals auf der Festplatte
Keine Sichtbarkeit darüber, wer was getan hat	Jeder Tastendruck wird im `.ttyrec`-Format aufgezeichnet
Pauschaler Produktionszugriff	Rollenbasierte Richtlinien-Engine setzt Regeln pro Umgebung durch
Keine Möglichkeit, eine aktive Sitzung zu beenden	Kill-Switch-gRPC-Endpunkt beendet jede laufende Sitzung
Undurchsichtiger Zugriff für Auditoren	Admin-TUI mit Sitzungswiedergabe, Text-Logs und Admin-Aktions-Logs

Architekturübersicht

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

Infrastrukturdienste (Docker Compose):

Dienst	Zweck
`zttp-proxy`	Der zentrale ZTTP-SSH-Bastion-Proxy (Golang-Binary)
`zttp-postgres`	Control-Plane-Datenbank (Benutzer, Server, RBAC-Richtlinien)
`zttp-vault`	HashiCorp Vault — speichert private SSH-Schlüssel
`zttp-nginx`	Stellt CLI-Installer unter `/release/` bereit
`zttp-init-audit`	Einmaliger Container, der Volume-Berechtigungen korrigiert

Funktionshighlights

🔐 Zero-Trust-Authentifizierung — Interaktive SSH-Login-TUI mit bcrypt-Passwort-Hashing, Ratenbegrenzung und Kontosperrung nach 5 fehlgeschlagenen Versuchen
🛡️ RBAC-Richtlinien-Engine — Zugriffskontrolle pro Rolle und pro Umgebung mit einem einzigen optimierten PostgreSQL-JOIN (keine Round-Trips)
🗝️ Vault-gestützte SSH-Schlüssel — Private Schlüssel berühren niemals die Festplatte; sie werden pro Sitzung ephemer aus HashiCorp Vault abgerufen
📹 Vollständige Sitzungsaufzeichnung — Alle Sitzungen werden im .ttyrec-Format mit zeitgestempelten Frames aufgezeichnet
🖥️ Interaktive Admin-TUI — Vollständige Terminal-UI für Benutzerverwaltung, Serverregistrierung, Zugriffsgewährung und Protokollprüfung
🔍 Audit-Log-Viewer — Sitzungen nach Server durchsuchen, Aufzeichnungen wiedergeben oder saubere Textprotokolle direkt aus der Admin-Konsole lesen
⚡ Kill Switch — gRPC-Endpunkt zum sofortigen Beenden jeder laufenden Sitzung
📋 Admin-Aktionsprotokoll — Jede administrative Aktion (Benutzererstellung, Zugriffsgewährung, Protokollansicht) wird in einem persistenten Audit-Trail protokolliert
🌍 Multi-Plattform-Client — Single-Binary-CLI für Linux, macOS (amd64/arm64) und Windows

Voraussetzungen

Server (Proxy-Host):

Docker ≥ 24 und Docker Compose ≥ 2.20
Eine öffentliche oder im LAN erreichbare IP auf Port 2224
make (optional, aber empfohlen)

Entwickler (Client):

Ein beliebiger SSH-Client (ssh-Befehl)
Linux-, macOS- oder Windows-Rechner

Schnellstart — Server

1. Repository klonen

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

2. Umgebung konfigurieren

cp .env.example .env

Bearbeiten Sie .env und legen Sie mindestens Folgendes fest:

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

⚠️ Committen Sie niemals Ihre .env-Datei. Sie ist in .gitignore aufgeführt.

3. Alle Dienste starten

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

4. Überprüfen, ob die Dienste fehlerfrei laufen

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

5. CLI-Installer erstellen und veröffentlichen

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

Dies kompiliert Clients für alle Plattformen und aktualisiert automatisch dist/install.sh und dist/install.ps1 mit der korrekten Server-URL. Der Nginx-Container stellt diese unter http://<your-server-ip>:8555/ bereit.

Schnellstart — Client

Linux / macOS

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

Windows (PowerShell, als Administrator ausführen)

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

Verbinden

Nach der Installation verbinden Sie sich mit dem ZTTP-Gateway:

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

Sie sehen einen Terminal-Anmeldebildschirm. Nach der Authentifizierung sehen Sie eine Liste der Server, auf die Sie zugreifen dürfen.

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen (oder eine .env-Datei). Die vollständige Referenz finden Sie in .env.example.

Variable	Standardwert	Beschreibung
`PROXY_LISTEN_ADDR`	`0.0.0.0:2222`	Bind-Adresse des SSH-Proxys
`HTTP_LISTEN_ADDR`	`0.0.0.0:8080`	HTTP-Adresse für den Health-Check
`GRPC_LISTEN_ADDR`	`0.0.0.0:9090`	gRPC-Adresse für den Kill-Switch
`PROXY_NODE_IP`	`127.0.0.1`	Externe IP, die in die CLI-Binärdateien eingebettet wird
`DATABASE_URL`	`postgres://zttp:...`	PostgreSQL-Verbindungszeichenfolge
`VAULT_ADDR`	`http://localhost:8201`	Vault-Server-URL
`VAULT_TOKEN`	`dev-root-token-zttp`	Vault-Root-Token (nur für die Entwicklung — in der Produktion AppRole verwenden)
`MAX_FAILED_ATTEMPTS`	`5`	Schwellenwert für die Kontosperrung
`LOCKOUT_DURATION`	`15m`	Dauer der Kontosperrung
`RATE_LIMIT_PER_MIN`	`10`	Maximale Anmeldeversuche pro Minute pro IP
`AUDIT_LOG_DIR`	`/var/log/zttp/audit`	Pfad zum Verzeichnis der Sitzungsaufzeichnungen
`SOC_WEBHOOK_URL`	(leer)	Optionaler Webhook für SOC-Benachrichtigungen

zttp

Beliebteste