ZTTP — Zero-Trust Transparenter Proxy

Ein gehärteter, selbst gehosteter SSH-Bastion-Host mit Vault-gestützter Schlüsselverwaltung, RBAC-Richtliniendurchsetzung, vollständiger Sitzungsaufzeichnung und einer interaktiven Admin-TUI – entwickelt 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
• Build aus dem Quellcode
• Makefile-Referenz
• Screenshots & Demo
• Projektstruktur
• Sicherheitsmodell
• Mitwirken
• Lizenz

Warum ZTTP

Moderne Entwicklungsteams benötigen eine Möglichkeit, Entwicklern den minimal erforderlichen Zugriff zu gewähren, um ihre Arbeit zu erledigen – nicht mehr, nicht weniger. Die traditionelle SSH-Schlüsselverteilung ist fehleranfällig: Schlüssel werden geteilt, auf Laptops vergessen und erst Tage zu spät widerrufen.

ZTTP löst dies, indem es als einzige Tür in Ihre Infrastruktur fungiert:

Architekturübersicht

Entwickler-Laptop
      │
      │  zttp
      │  (Unter der Haube: SSH über Port 2224)
      ▼
┌─────────────────────────────────────────────────────────┐
│                     ZTTP-Proxy                          │
│                                                         │
│  ① Auth-Gate     – bcrypt/Argon2id-Login-TUI           │
│  ② RBAC-Engine   – umgebungsbewusste Richtlinienprüfung │
│  ③ Vault-Abruf   – ephemerer SSH-Schlüsselabruf        │
│  ④ Bridge        – transparenter TCP-Tunnel            │
│  ⑤ Audit-Writer  – ttyrec-Frame-Recorder               │
└──────────┬──────────────────────────────────────────────┘
           │  ssh (private IP, ephemerer Schlüssel)
           ▼
     Zielserver

Infrastrukturdienste (Docker Compose):

Funktionshighlights

• 🔐 Zero-Trust-Authentifizierung – Interaktive SSH-Login-TUI mit bcrypt-Passwort-Hashing, Rate-Limiting und Kontosperrung nach 5 fehlgeschlagenen Versuchen
• 🛡️ RBAC-Richtlinien-Engine – Rollen- und umgebungsbasierte Zugriffskontrolle mit einem einzigen optimierten PostgreSQL-JOIN (keine Round-Trips)
• 🗝️ Vault-gestützte SSH-Schlüssel – Private-Keys berühren nie die Festplatte; werden pro Sitzung ephemer aus HashiCorp Vault abgerufen
• 📹 Vollständige Sitzungsaufzeichnung – Alle Sitzungen werden im .ttyrec-Format mit Zeitstempel-Frames aufgezeichnet
• 🖥️ Interaktive Admin-TUI – Vollständige Terminal-Benutzeroberfläche für Benutzerverwaltung, Serverregistrierung, Zugriffsgewährung und Log-Prüfung
• 🔍 Audit-Log-Viewer – Sitzungen nach Server durchsuchen, Aufzeichnungen wiedergeben oder saubere Text-Logs direkt aus der Admin-Konsole lesen
• ⚡ Kill-Switch – gRPC-Endpunkt zum sofortigen Beenden jeder laufenden Sitzung
• 📋 Admin-Aktions-Log – Jede administrative Aktion (Benutzererstellung, Zugriffsgewährung, Log-Anzeige) wird in einem persistenten Audit-Trail protokolliert
• 🌍 Multiplattform-Client – Einzelnes Binary-CLI für Linux, macOS (amd64/arm64) und Windows

Voraussetzungen

Server (Proxy-Host):

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

Entwickler (Client):

• Jeder 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 setzen Sie mindestens:

PROXY_NODE_IP=<ihre-server-öffentliche-ip>
POSTGRES_PASSWORD=<ein-starkes-passwort>
VAULT_TOKEN=<ein-starker-vault-token>

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

3. Alle Dienste starten

make docker-up
# oder direkt:
docker compose -f deploy/docker-compose.yml up -d --build

4. Dienste auf Gesundheit prüfen

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

5. CLI-Installer bauen und veröffentlichen

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

Dies kompiliert Clients für alle Plattformen und aktualisiert dist/install.sh und dist/install.ps1 automatisch mit der korrekten Server-URL. Der Nginx-Container stellt diese unter http://<ihre-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
# oder direkt:
ssh -p 2224 <ihr-benutzername>@<proxy-ip>

Ihnen wird ein Terminal-Login-Bildschirm angezeigt. Nach der Authentifizierung sehen Sie eine Liste der Server, auf die Sie zugreifen dürfen.

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen (oder .env-Datei). Siehe .env.example für die vollständige Referenz.

Rollen & RBAC-Richtlinie

ZTTP verwendet ein rollenbasiertes Modell. Jeder Benutzer erhält eine Rolle; jede Rolle hat eine Richtlinie, die definiert, auf welche Server-Umgebungen sie zugreifen kann.

Rollen und Serverzuweisungen werden über die Admin-Konsole verwaltet (siehe unten). Die RBAC-Engine führt alle Prüfungen in einer einzigen PostgreSQL-Abfrage durch – sie legt dem Client niemals offen, warum der Zugriff verweigert wurde (Enumeration-Schutz).

Admin-Konsole

Verbinden Sie sich über das Gateway-Menü mit dem zttp-admin-Server oder melden Sie sich mit einem Konto an, das die Rolle security-admin besitzt.

Die Admin-Konsole bietet:

Alle Admin-Aktionen werden in admin-actions.log im Audit-Volume protokolliert.

Audit-Logs & Sitzungsaufzeichnungen

Alle Sitzungen werden im Docker-Volume zttp-audit-logs gespeichert (/var/log/zttp/audit/ im Container).

Anzeigen über die Admin-Konsole

1. Als security-admin anmelden
2. Audit-Logs anzeigen auswählen
3. Einen Server aus der Liste auswählen
4. Eine Sitzung auswählen
5. Text-Log anzeigen (ANSI-bereinigt, lesbar) oder Aufzeichnung abspielen (Echtzeit-Wiedergabe) wählen
6. Ctrl+C drücken, um zurückzugehen

Anzeigen vom Host (roh)

# Aufzeichnungen auflisten
sudo ls /var/lib/docker/volumes/zttp-audit-logs/_data/

# Aufzeichnung mit ttyplay abspielen
sudo ttyplay /var/lib/docker/volumes/zttp-audit-logs/_data/<sitzungs-id>.ttyrec

# Admin-Aktions-Log lesen
sudo cat /var/lib/docker/volumes/zttp-audit-logs/_data/admin-actions.log

Build aus dem Quellcode

Anforderungen: Go 1.25+, Docker (für Cross-Kompilierung)

# Proxy + CLI für aktuelle Plattform bauen
make build

# CLI für alle Plattformen cross-kompilieren (Linux, macOS, Windows)
make release PROXY_ADDR=<proxy-ip>:2224

# Tests ausführen
make test

# Proxy lokal ausführen (erfordert laufende Postgres- und Vault-Instanzen)
make run-proxy

Makefile-Referenz

Screenshots & Demo

1. Installation

(Zum Abspielen der Demo klicken)

2. Sicherer Login

(Zum Abspielen der Demo klicken)

3. Server hinzufügen (Admin-Konsole)

(Zum Abspielen der Demo klicken)

4. Mit Server verbinden (Gateway)

(Zum Abspielen der Demo klicken)

5. Kill-Switch (Admin-Auswurf)

(Zum Abspielen der Demo klicken)

Projektstruktur

zttp/
├── cmd/
│   ├── proxy/          # Proxy-Server-Einstiegspunkt
│   └── zttp/           # CLI-Client-Einstiegspunkt
├── db/
│   └── migrations/     # PostgreSQL-Schema-Migrationen
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile.proxy
│   └── vault-seed.sh   # Seedet Test-SSH-Schlüssel in Vault
├── dist/
│   ├── install.sh      # Linux/macOS-Installer-Skript
│   └── install.ps1     # Windows-Installer-Skript
├── internal/
│   ├── audit/          # Admin-Aktionsprotokollierung
│   ├── auth/           # Benutzerauthentifizierung (bcrypt, Sperrung)
│   ├── cli/            # CLI-Client-TUI und Verbindungslogik
│   ├── config/         # Umgebungsbasierte Konfiguration
│   ├── killswitch/     # gRPC-Kill-Switch-Dienst
│   ├── proxy/          # SSH-Proxy, Gateway-TUI, Admin-TUI, Bridge
│   ├── rbac/           # Rollenbasierte Zugriffskontroll-Engine
│   ├── ratelimit/      # Pro-IP-Rate-Limiting
│   ├── session/        # Sitzungsverfolgung und DB-Speicher
│   └── vault/          # HashiCorp-Vault-SSH-Schlüssel-Client
├── proto/              # gRPC-Protokolldefinitionen
├── tools/
│   └── hashpw/         # CLI-Tool: bcrypt-Passwort-Hash generieren
├── .env.example        # Konfigurationsvorlage
├── go.mod
└── Makefile

Sicherheitsmodell

Mitwirken

1. Repository forken
2. Feature-Branch erstellen: git checkout -b feat/ihr-feature
3. Änderungen vornehmen und sicherstellen, dass jede Datei einen eigenen Commit erhält
4. Tests ausführen: make test
5. Merge-Request öffnen

Bitte committen Sie nicht:

• .env oder Dateien, die Geheimnisse enthalten
• Echte IP-Adressen oder Hostnamen von Produktionsservern
• Kompilierte Binaries (das zttp-Binary im Root ist .gitignored)

Lizenz

Dieses Projekt ist proprietär. Alle Rechte vorbehalten.

Erstellt mit Go, PostgreSQL, HashiCorp Vault und Docker.