ZTTP — Proxy Trasparente Zero-Trust

Un bastion host SSH self-hosted e rinforzato con gestione delle chiavi basata su Vault, applicazione delle policy RBAC, registrazione completa delle sessioni e una TUI amministrativa interattiva — progettato per team che necessitano di accesso verificabile e zero-trust all'infrastruttura di produzione.

Indice

• Perché ZTTP
• Panoramica dell'Architettura
• Caratteristiche Principali
• Prerequisiti
• Avvio Rapido — Server
• Avvio Rapido — Client
• Configurazione
• Ruoli e Policy RBAC
• Console Amministrativa
• Log di Audit e Registrazioni delle Sessioni
• Compilazione dal Sorgente
• 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 dare agli sviluppatori l'accesso minimo necessario per svolgere il loro 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.

ZTTP risolve questo problema fungendo da unica porta verso la tua infrastruttura:

Panoramica dell'Architettura

Laptop dello Sviluppatore
      │
      │  zttp
      │  (Sotto il cofano: SSH sulla porta 2224)
      ▼
┌─────────────────────────────────────────────────────────┐
│                     Proxy ZTTP                          │
│                                                         │
│  ① Gate di Autenticazione — TUI di login bcrypt/Argon2id│
│  ② Motore RBAC          — controllo policy per ambiente │
│  ③ Recupero da Vault    — recupero chiave SSH effimera  │
│  ④ Bridge               — tunnel TCP trasparente        │
│  ⑤ Scrittore di Audit   — registratore frame ttyrec     │
└──────────┬──────────────────────────────────────────────┘
           │  ssh (IP privato, chiave effimera)
           ▼
     Server di Destinazione

Servizi infrastrutturali (Docker Compose):

Caratteristiche Principali

• 🔐 Autenticazione zero-trust — TUI di login SSH interattiva con hash delle password bcrypt, limitazione della frequenza e blocco dell'account dopo 5 tentativi falliti
• 🛡️ Motore di policy RBAC — Controllo degli accessi per ruolo e per ambiente con una singola JOIN PostgreSQL ottimizzata (nessun round-trip)
• 🗝️ Chiavi SSH basate su Vault — Le chiavi private non toccano mai il disco; 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 amministrativa interattiva — Interfaccia terminale completa per la gestione degli utenti, la registrazione dei server, la concessione degli accessi e la revisione dei log
• 🔍 Visualizzatore di Log di Audit — Sfoglia le sessioni per server, riproduci le registrazioni o leggi log testuali puliti direttamente dalla console amministrativa
• ⚡ Kill Switch — Endpoint gRPC per terminare istantaneamente qualsiasi sessione live
• 📋 Log delle Azioni Amministrative — Ogni azione amministrativa (creazione utenti, concessione accessi, visualizzazione log) viene registrata in una traccia di audit persistente
• 🌍 Client multipiattaforma — CLI a binario singolo 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=<ip-pubblico-del-tuo-server>
POSTGRES_PASSWORD=<una-password-forte>
VAULT_TOKEN=<un-token-vault-forte>

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

3. Avvia tutti i servizi

make docker-up
# oppure direttamente:
docker compose -f deploy/docker-compose.yml up -d --build

4. Verifica che i servizi siano sani

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

5. Compila e pubblica gli installer CLI

make release PROXY_ADDR=<ip-del-tuo-server>:2224

Questo compila in modo incrociato i client per tutte le piattaforme e aggiorna automaticamente dist/install.sh e dist/install.ps1 con l'URL corretto del server. Il container Nginx li serve all'indirizzo http://<ip-del-tuo-server>:8555/.

Avvio Rapido — Client

Linux / macOS

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

Windows (PowerShell, esegui come Amministratore)

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

Connettiti

Una volta installato, connettiti al gateway ZTTP:

zttp
# oppure direttamente:
ssh -p 2224 <tuo-username>@<ip-proxy>

Ti verrà presentata una schermata di login a 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.

Ruoli e Policy RBAC

ZTTP utilizza un modello basato sui ruoli. A ogni utente viene assegnato un ruolo; ogni ruolo ha una policy che definisce a quali ambienti server può accedere.

I ruoli e le assegnazioni dei server vengono gestiti tramite la Console Amministrativa (vedi sotto). Il motore RBAC esegue tutti i controlli in un'unica query PostgreSQL — non espone mai il motivo per cui l'accesso è stato negato al client (protezione dall'enumerazione).

Console Amministrativa

Connettiti al server zttp-admin dal menu del gateway, oppure accedi con un account che ha il ruolo security-admin.

La Console Amministrativa offre:

Tutte le azioni amministrative vengono registrate in admin-actions.log all'interno del volume di audit.

Log di Audit e Registrazioni delle Sessioni

Tutte le sessioni vengono memorizzate nel volume Docker zttp-audit-logs (/var/log/zttp/audit/ all'interno del container).

Visualizzazione dalla Console Amministrativa

1. Accedi come security-admin
2. Seleziona Visualizza Log di Audit
3. Seleziona un server dall'elenco
4. Seleziona una sessione
5. Scegli Visualizza Log Testuale (senza ANSI, leggibile) o Riproduci Registrazione (riproduzione in tempo reale)
6. Premi Ctrl+C per tornare indietro

Visualizzazione dall'host (grezzo)

# Elenca le registrazioni
sudo ls /var/lib/docker/volumes/zttp-audit-logs/_data/

# Riproduci una registrazione con ttyplay
sudo ttyplay /var/lib/docker/volumes/zttp-audit-logs/_data/<id-sessione>.ttyrec

# Leggi il log delle azioni amministrative
sudo cat /var/lib/docker/volumes/zttp-audit-logs/_data/admin-actions.log

Compilazione dal Sorgente

Requisiti: Go 1.25+, Docker (per la compilazione incrociata)

# Compila proxy + CLI per la piattaforma corrente
make build

# Compila in modo incrociato la CLI per tutte le piattaforme (Linux, macOS, Windows)
make release PROXY_ADDR=<ip-proxy>:2224

# Esegui i test
make test

# Esegui il proxy localmente (richiede Postgres + Vault già in esecuzione)
make run-proxy

Riferimento Makefile

Screenshot e Demo

1. Installazione

(Clicca per riprodurre la demo)

2. Login Sicuro

(Clicca per riprodurre la demo)

3. Aggiungi Server (Console Amministrativa)

(Clicca per riprodurre la demo)

4. Connettiti al Server (Gateway)

(Clicca per riprodurre la demo)

5. Kill Switch (Espulsione Amministrativa)

(Clicca per riprodurre la demo)

Struttura del Progetto

zttp/
├── cmd/
│   ├── proxy/          # Punto di ingresso del server proxy
│   └── zttp/           # Punto di ingresso del client CLI
├── db/
│   └── migrations/     # Migrazioni dello schema PostgreSQL
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile.proxy
│   └── vault-seed.sh   # Inserisce chiavi SSH di test in Vault
├── dist/
│   ├── install.sh      # Script di installazione Linux/macOS
│   └── install.ps1     # Script di installazione Windows
├── internal/
│   ├── audit/          # Registrazione delle azioni amministrative
│   ├── auth/           # Autenticazione utenti (bcrypt, blocco)
│   ├── cli/            # TUI del client CLI e logica di connessione
│   ├── config/         # Configurazione basata su variabili d'ambiente
│   ├── killswitch/     # Servizio gRPC kill-switch
│   ├── proxy/          # Proxy SSH, TUI del gateway, TUI amministrativa, bridge
│   ├── rbac/           # Motore di controllo degli accessi basato sui ruoli
│   ├── ratelimit/      # Limitazione della frequenza per IP
│   ├── session/        # Tracciamento delle sessioni e store DB
│   └── vault/          # Client chiavi SSH HashiCorp Vault
├── proto/              # Definizioni del protocollo gRPC
├── tools/
│   └── hashpw/         # Strumento CLI: genera hash password bcrypt
├── .env.example        # Modello di configurazione
├── go.mod
└── Makefile

Modello di Sicurezza

Contribuire

1. Fai il fork del repository
2. Crea un branch per la funzionalità: git checkout -b feat/tua-funzionalità
3. Apporta le tue modifiche, assicurandoti che ogni file abbia il proprio commit
4. Esegui i test: make test
5. Apri una merge request

Per favore, non committare:

• .env o qualsiasi file contenente segreti
• Indirizzi IP reali o hostname di server di produzione
• Binari compilati (il binario zttp nella root è in .gitignore)

Licenza

Questo progetto è proprietario. Tutti i diritti riservati.

Realizzato con Go, PostgreSQL, HashiCorp Vault e Docker.