ZTTP — Proxy Transparente de Confianza Cero

Un bastión SSH autohospedado y endurecido con gestión de claves respaldada por Vault, aplicación de políticas RBAC, grabación completa de sesiones y una TUI administrativa interactiva — diseñado para equipos que necesitan acceso auditable y de confianza cero a la infraestructura de producción.

Tabla de Contenidos

• Por qué ZTTP
• Descripción General de la Arquitectura
• Características Destacadas
• Requisitos Previos
• Inicio Rápido — Servidor
• Inicio Rápido — Cliente
• Configuración
• Roles y Política RBAC
• Consola de Administración
• Registros de Auditoría y Grabaciones de Sesiones
• Compilación desde el Código Fuente
• Referencia del Makefile
• Capturas de Pantalla y Demo
• Estructura del Proyecto
• Modelo de Seguridad
• Contribuciones
• Licencia

Por qué ZTTP

Los equipos de ingeniería modernos necesitan una forma de dar a los desarrolladores el acceso mínimo requerido para hacer su trabajo — ni más, ni menos. La distribución tradicional de claves SSH es propensa a errores: las claves se comparten, se olvidan en los portátiles y se revocan demasiado tarde.

ZTTP resuelve esto actuando como la única puerta hacia tu infraestructura:

Descripción General de la Arquitectura

Portátil del Desarrollador
      │
      │  zttp
      │  (Internamente: SSH en el puerto 2224)
      ▼
┌─────────────────────────────────────────────────────────┐
│                     Proxy ZTTP                          │
│                                                         │
│  ① Puerta de Autenticación — TUI de inicio de sesión bcrypt/Argon2id │
│  ② Motor RBAC   — verificación de política consciente del entorno    │
│  ③ Obtención de Vault — recuperación efímera de claves SSH           │
│  ④ Puente        — túnel TCP transparente                            │
│  ⑤ Escritor de Auditoría — grabador de tramas ttyrec                 │
└──────────┬──────────────────────────────────────────────┘
           │  ssh (IP privada, clave efímera)
           ▼
     Servidor de Destino

Servicios de infraestructura (Docker Compose):

Características Destacadas

• 🔐 Autenticación de confianza cero — TUI de inicio de sesión SSH interactivo con hash de contraseña bcrypt, limitación de velocidad y bloqueo de cuenta tras 5 intentos fallidos
• 🛡️ Motor de políticas RBAC — Control de acceso por rol y por entorno con un único JOIN optimizado de PostgreSQL (sin viajes de ida y vuelta)
• 🗝️ Claves SSH respaldadas por Vault — Las claves privadas nunca tocan el disco; se obtienen efímeramente por sesión desde HashiCorp Vault
• 📹 Grabación completa de sesiones — Todas las sesiones se graban en formato .ttyrec con tramas con marca de tiempo
• 🖥️ TUI administrativa interactiva — Interfaz de terminal completa para gestión de usuarios, registro de servidores, concesión de accesos y revisión de registros
• 🔍 Visor de registros de auditoría — Explora sesiones por servidor, reproduce grabaciones o lee registros de texto limpios directamente desde la consola de administración
• ⚡ Interruptor de emergencia — Endpoint gRPC para terminar cualquier sesión en vivo al instante
• 📋 Registro de acciones administrativas — Cada acción administrativa (creación de usuarios, concesión de accesos, visualización de registros) se registra en una pista de auditoría persistente
• 🌍 Cliente multiplataforma — CLI de un solo binario para Linux, macOS (amd64/arm64) y Windows

Requisitos Previos

Servidor (host del proxy):

• Docker ≥ 24 y Docker Compose ≥ 2.20
• Una IP pública o accesible desde la LAN en el puerto 2224
• make (opcional, pero recomendado)

Desarrollador (cliente):

• Cualquier cliente SSH (comando ssh)
• Máquina Linux, macOS o Windows

Inicio Rápido — Servidor

1. Clonar el repositorio

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

2. Configurar tu entorno

cp .env.example .env

Edita .env y establece como mínimo:

PROXY_NODE_IP=<ip-publica-de-tu-servidor>
POSTGRES_PASSWORD=<una-contraseña-fuerte>
VAULT_TOKEN=<un-token-de-vault-fuerte>

⚠️ Nunca hagas commit de tu archivo .env. Está listado en .gitignore.

3. Iniciar todos los servicios

make docker-up
# o directamente:
docker compose -f deploy/docker-compose.yml up -d --build

4. Verificar que los servicios estén saludables

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

5. Compilar y publicar los instaladores CLI

make release PROXY_ADDR=<ip-de-tu-servidor>:2224

Esto compila de forma cruzada los clientes para todas las plataformas y actualiza automáticamente dist/install.sh y dist/install.ps1 con la URL correcta del servidor. El contenedor Nginx sirve estos archivos en http://<ip-de-tu-servidor>:8555/.

Inicio Rápido — Cliente

Linux / macOS

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

Windows (PowerShell, ejecutar como Administrador)

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

Conectar

Una vez instalado, conéctate a la puerta de enlace ZTTP:

zttp
# o directamente:
ssh -p 2224 <tu-nombre-de-usuario>@<ip-del-proxy>

Se te presentará una pantalla de inicio de sesión de terminal. Después de la autenticación, verás una lista de servidores a los que estás autorizado a acceder.

Configuración

Toda la configuración se realiza mediante variables de entorno (o archivo .env). Consulta .env.example para la referencia completa.

Roles y Política RBAC

ZTTP utiliza un modelo basado en roles. A cada usuario se le asigna un rol; cada rol tiene una política que define a qué entornos de servidores puede acceder.

Los roles y las asignaciones de servidores se gestionan a través de la Consola de Administración (ver más abajo). El motor RBAC realiza todas las verificaciones en una sola consulta PostgreSQL — nunca expone por qué se denegó el acceso al cliente (protección contra enumeración).

Consola de Administración

Conéctate al servidor zttp-admin desde el menú de la puerta de enlace, o inicia sesión con una cuenta que tenga el rol security-admin.

La Consola de Administración proporciona:

Todas las acciones administrativas se registran en admin-actions.log dentro del volumen de auditoría.

Registros de Auditoría y Grabaciones de Sesiones

Todas las sesiones se almacenan en el volumen Docker zttp-audit-logs (/var/log/zttp/audit/ dentro del contenedor).

Visualización desde la Consola de Administración

1. Inicia sesión como security-admin
2. Selecciona Ver Registros de Auditoría
3. Selecciona un servidor de la lista
4. Selecciona una sesión
5. Elige Ver Registro de Texto (sin ANSI, legible) o Reproducir Grabación (reproducción en tiempo real)
6. Pulsa Ctrl+C para volver

Visualización desde el host (crudo)

# Listar grabaciones
sudo ls /var/lib/docker/volumes/zttp-audit-logs/_data/

# Reproducir una grabación con ttyplay
sudo ttyplay /var/lib/docker/volumes/zttp-audit-logs/_data/<id-de-sesión>.ttyrec

# Leer el registro de acciones administrativas
sudo cat /var/lib/docker/volumes/zttp-audit-logs/_data/admin-actions.log

Compilación desde el Código Fuente

Requisitos: Go 1.25+, Docker (para compilación cruzada)

# Compilar proxy + CLI para la plataforma actual
make build

# Compilación cruzada del CLI para todas las plataformas (Linux, macOS, Windows)
make release PROXY_ADDR=<ip-del-proxy>:2224

# Ejecutar pruebas
make test

# Ejecutar proxy localmente (requiere Postgres + Vault ya en ejecución)
make run-proxy

Referencia del Makefile

Capturas de Pantalla y Demo

1. Instalación

(Haz clic para reproducir la demo)

2. Inicio de Sesión Seguro

(Haz clic para reproducir la demo)

3. Agregar Servidor (Consola de Administración)

(Haz clic para reproducir la demo)

4. Conectar al Servidor (Puerta de Enlace)

(Haz clic para reproducir la demo)

5. Interruptor de Emergencia (Expulsión Administrativa)

(Haz clic para reproducir la demo)

Estructura del Proyecto

zttp/
├── cmd/
│   ├── proxy/          # Punto de entrada del servidor proxy
│   └── zttp/           # Punto de entrada del cliente CLI
├── db/
│   └── migrations/     # Migraciones de esquema de PostgreSQL
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile.proxy
│   └── vault-seed.sh   # Siembra claves SSH de prueba en Vault
├── dist/
│   ├── install.sh      # Script de instalación para Linux/macOS
│   └── install.ps1     # Script de instalación para Windows
├── internal/
│   ├── audit/          # Registro de acciones administrativas
│   ├── auth/           # Autenticación de usuarios (bcrypt, bloqueo)
│   ├── cli/            # TUI del cliente CLI y lógica de conexión
│   ├── config/         # Configuración basada en entorno
│   ├── killswitch/     # Servicio gRPC de interruptor de emergencia
│   ├── proxy/          # Proxy SSH, TUI de puerta de enlace, TUI administrativa, puente
│   ├── rbac/           # Motor de control de acceso basado en roles
│   ├── ratelimit/      # Limitación de velocidad por IP
│   ├── session/        # Seguimiento de sesiones y almacenamiento en BD
│   └── vault/          # Cliente de claves SSH de HashiCorp Vault
├── proto/              # Definiciones de protocolo gRPC
├── tools/
│   └── hashpw/         # Herramienta CLI: generar hash de contraseña bcrypt
├── .env.example        # Plantilla de configuración
├── go.mod
└── Makefile

Modelo de Seguridad

Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de características: git checkout -b feat/tu-característica
3. Realiza tus cambios, asegurando que cada archivo tenga su propio commit
4. Ejecuta las pruebas: make test
5. Abre una solicitud de fusión

Por favor, no hagas commit de:

• .env o cualquier archivo que contenga secretos
• Direcciones IP reales o hostnames de servidores de producción
• Binarios compilados (el binario zttp en la raíz está en .gitignore)

Licencia

Este proyecto es propietario. Todos los derechos reservados.

Construido con Go, PostgreSQL, HashiCorp Vault y Docker.