ZTTP: Proxy bastion SSH Zero-Trust

🔗 Mirror del progetto: GitHub | GitLab

ZTTP è un proxy bastion SSH Zero-Trust self-hosted e rafforzato, scritto in Golang, con gestione delle chiavi basata su HashiCorp Vault, applicazione delle policy RBAC, registrazione completa delle sessioni e una TUI amministrativa interattiva — progettato per team che necessitano di un accesso verificabile e zero-trust all'infrastruttura di produzione.

Indice

Perché ZTTP
Panoramica dell'architettura
Funzionalità principali
Prerequisiti
Avvio rapido — Server
Avvio rapido — Client
Configurazione
Ruoli e policy RBAC
Console di amministrazione
Log di audit e registrazioni delle sessioni
Compilazione dai sorgenti
Riferimento Makefile
Screenshot e demo
Struttura del progetto
Modello di sicurezza
Contribuire
Licenza

Perché ZTTP

I team di ingegneria moderni hanno bisogno di un modo per concedere agli sviluppatori l'accesso minimo necessario per svolgere il proprio lavoro — né più né meno. La distribuzione tradizionale delle chiavi SSH è soggetta a errori: le chiavi vengono condivise, dimenticate sui laptop e revocate con giorni di ritardo.

Il proxy SSH ZTTP risolve questo problema fungendo da unica porta zero-trust verso la tua infrastruttura:

Problema	Soluzione ZTTP
Chiavi SSH condivise sui laptop	Le chiavi risiedono solo in HashiCorp Vault — mai su disco
Nessuna visibilità su chi ha fatto cosa	Ogni tasto premuto viene registrato in formato `.ttyrec`
Accesso indiscriminato alla produzione	Il motore di policy basato sui ruoli applica regole per ambiente
Nessun modo per interrompere una sessione attiva	L'endpoint gRPC kill-switch termina qualsiasi sessione attiva
Accesso opaco per i revisori	TUI amministrativa con riproduzione delle sessioni, log testuali e log delle azioni amministrative

Panoramica dell'architettura

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

Servizi infrastrutturali (Docker Compose):

Servizio	Scopo
`zttp-proxy`	Il proxy bastion SSH ZTTP principale (binario Golang)
`zttp-postgres`	Database del control-plane (utenti, server, policy RBAC)
`zttp-vault`	HashiCorp Vault — memorizza le chiavi private SSH
`zttp-nginx`	Serve gli installer CLI su `/release/`
`zttp-init-audit`	Container one-shot che corregge i permessi dei volumi

Funzionalità principali

🔐 Autenticazione zero-trust — TUI di login SSH interattiva con hashing delle password bcrypt, rate limiting e blocco dell'account dopo 5 tentativi falliti
🛡️ Motore di policy RBAC — Controllo degli accessi per ruolo e per ambiente con un singolo JOIN PostgreSQL ottimizzato (nessun round-trip)
🗝️ Chiavi SSH supportate da Vault — Le chiavi private non toccano mai il disco; vengono recuperate in modo effimero per sessione da HashiCorp Vault
📹 Registrazione completa delle sessioni — Tutte le sessioni vengono registrate in formato .ttyrec con frame timestampati
🖥️ TUI Admin interattiva — Interfaccia terminale completa per la gestione degli utenti, la registrazione dei server, la concessione degli accessi e la revisione dei log
🔍 Visualizzatore dei log di audit — Sfoglia le sessioni per server, riproduci le registrazioni o leggi i log in testo pulito direttamente dalla console di amministrazione
⚡ Kill Switch — Endpoint gRPC per terminare istantaneamente qualsiasi sessione attiva
📋 Log delle azioni amministrative — Ogni azione amministrativa (creazione utenti, concessione di accessi, visualizzazione dei log) viene registrata in un audit trail persistente
🌍 Client multipiattaforma — CLI in singolo binario per Linux, macOS (amd64/arm64) e Windows

Prerequisiti

Server (host proxy):

Docker ≥ 24 e Docker Compose ≥ 2.20
Un IP pubblico o accessibile dalla LAN sulla porta 2224
make (opzionale, ma consigliato)

Sviluppatore (client):

Qualsiasi client SSH (comando ssh)
Macchina Linux, macOS o Windows

Avvio rapido — Server

1. Clona il repository

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

2. Configura il tuo ambiente

cp .env.example .env

Modifica .env e imposta come minimo:

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

⚠️ Non committare mai il tuo file .env. È elencato in .gitignore.

3. Avvia tutti i servizi

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

4. Verifica che i servizi siano in stato di salute

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

5. Compila e pubblica gli installer della CLI

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

Questo esegue la cross-compilazione dei client per tutte le piattaforme e aggiorna automaticamente dist/install.sh e dist/install.ps1 con l'URL del server corretto. Il container Nginx li serve all'indirizzo http://<your-server-ip>:8555/.

Avvio rapido — Client

Linux / macOS

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

Windows (PowerShell, eseguire come amministratore)

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

Connessione

Una volta installato, connettiti al gateway ZTTP:

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

Ti verrà presentata una schermata di login da terminale. Dopo l'autenticazione, vedrai un elenco dei server a cui sei autorizzato ad accedere.

Configurazione

Tutta la configurazione avviene tramite variabili d'ambiente (o file .env). Consulta .env.example per il riferimento completo.

Variabile	Predefinito	Descrizione
`PROXY_LISTEN_ADDR`	`0.0.0.0:2222`	Indirizzo di bind del proxy SSH
`HTTP_LISTEN_ADDR`	`0.0.0.0:8080`	Indirizzo HTTP per l'health check
`GRPC_LISTEN_ADDR`	`0.0.0.0:9090`	Indirizzo gRPC per il kill-switch
`PROXY_NODE_IP`	`127.0.0.1`	IP esterno incorporato nei binari CLI
`DATABASE_URL`	`postgres://zttp:...`	Stringa di connessione PostgreSQL
`VAULT_ADDR`	`http://localhost:8201`	URL del server Vault
`VAULT_TOKEN`	`dev-root-token-zttp`	Token root di Vault (solo dev — usa AppRole in produzione)
`MAX_FAILED_ATTEMPTS`	`5`	Soglia di blocco
`LOCKOUT_DURATION`	`15m`	Durata del blocco dell'account
`RATE_LIMIT_PER_MIN`	`10`	Tentativi di login massimi al minuto per IP
`AUDIT_LOG_DIR`	`/var/log/zttp/audit`	Percorso della directory di registrazione delle sessioni
`SOC_WEBHOOK_URL`	(vuoto)	Webhook opzionale per gli avvisi al SOC

zttp

Più Popolari