ZTTP: Proxy Bastion SSH de Confiança Zero

🔗 Espelhos do Projeto: GitHub | GitLab

ZTTP é um proxy bastion SSH de Confiança Zero, auto-hospedado e reforçado, construído em Golang com gestão de chaves suportada pelo HashiCorp Vault, aplicação de políticas RBAC, gravação completa de sessões e uma TUI administrativa interativa — concebido para equipas que necessitam de acesso auditável e de confiança zero à infraestrutura de produção.

Índice

Porquê o ZTTP
Visão Geral da Arquitetura
Destaques das Funcionalidades
Pré-requisitos
Início Rápido — Servidor
Início Rápido — Cliente
Configuração
Funções e Política RBAC
Consola de Administração
Registos de Auditoria e Gravações de Sessões
Compilar a Partir do Código-Fonte
Referência do Makefile
Capturas de Ecrã e Demonstração
Estrutura do Projeto
Modelo de Segurança
Contribuir
Licença

Porquê o ZTTP

As equipas de engenharia modernas precisam de uma forma de dar aos programadores o acesso mínimo necessário para desempenharem as suas funções — nem mais, nem menos. A distribuição tradicional de chaves SSH é propensa a erros: as chaves são partilhadas, esquecidas nos portáteis e revogadas demasiado tarde.

O proxy SSH ZTTP resolve isto ao atuar como a única porta de confiança zero para a sua infraestrutura:

Problema	Solução ZTTP
Chaves SSH partilhadas nos portáteis	As chaves residem apenas no HashiCorp Vault — nunca no disco
Sem visibilidade sobre quem fez o quê	Cada tecla premida é gravada em formato `.ttyrec`
Acesso total à produção	O motor de políticas baseado em funções aplica regras por ambiente
Sem forma de parar uma sessão ativa	O endpoint gRPC de kill-switch termina qualquer sessão em direto
Acesso opaco para auditores	TUI de administração com reprodução de sessões, registos de texto e registos de ações administrativas

Visão Geral da Arquitetura

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

Serviços de infraestrutura (Docker Compose):

Serviço	Finalidade
`zttp-proxy`	O proxy bastion SSH ZTTP principal (binário Golang)
`zttp-postgres`	Banco de dados do plano de controle (usuários, servidores, políticas RBAC)
`zttp-vault`	HashiCorp Vault — armazena chaves privadas SSH
`zttp-nginx`	Serve instaladores da CLI em `/release/`
`zttp-init-audit`	Contêiner de execução única que corrige permissões de volume

Destaques de Recursos

🔐 Autenticação zero-trust — TUI de login SSH interativo com hash de senha bcrypt, limitação de taxa e bloqueio de conta após 5 tentativas falhas
🛡️ Motor de políticas RBAC — Controle de acesso por função e por ambiente com um único JOIN otimizado no PostgreSQL (sem round-trips)
🗝️ Chaves SSH respaldadas pelo Vault — Chaves privadas nunca tocam o disco; obtidas efemeramente por sessão a partir do HashiCorp Vault
📹 Gravação completa de sessões — Todas as sessões são gravadas no formato .ttyrec com quadros com carimbo de data/hora
🖥️ TUI Administrativa Interativa — Interface de terminal completa para gerenciamento de usuários, registro de servidores, concessão de acessos e revisão de logs
🔍 Visualizador de Log de Auditoria — Navegue pelas sessões por servidor, reproduza gravações ou leia logs de texto limpos diretamente do console administrativo
⚡ Kill Switch — Endpoint gRPC para encerrar instantaneamente qualquer sessão ativa
📋 Log de Ações Administrativas — Toda ação administrativa (criação de usuário, concessão de acesso, visualização de logs) é registrada em uma trilha de auditoria persistente
🌍 Cliente multiplataforma — CLI de binário único para Linux, macOS (amd64/arm64) e Windows

Pré-requisitos

Servidor (host do proxy):

Docker ≥ 24 e Docker Compose ≥ 2.20
Um IP público ou acessível na LAN na porta 2224
make (opcional, mas recomendado)

Desenvolvedor (cliente):

Qualquer cliente SSH (comando ssh)
Máquina Linux, macOS ou Windows

Início Rápido — Servidor

1. Clone o repositório

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

2. Configure seu ambiente

cp .env.example .env

Edite o .env e defina no mínimo:

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

⚠️ Nunca faça commit do seu arquivo .env. Ele está listado no .gitignore.

3. Inicie todos os serviços

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

4. Verifique se os serviços estão íntegros

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

5. Compile e publique os instaladores da CLI

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

Isso compila de forma cruzada clientes para todas as plataformas e atualiza automaticamente dist/install.sh e dist/install.ps1 com o URL correto do servidor. O contentor Nginx serve estes em http://<your-server-ip>:8555/.

Início Rápido — Cliente

Linux / macOS

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

Windows (PowerShell, executar como Administrador)

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

Conectar

Após a instalação, conecte-se ao gateway ZTTP:

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

Você verá uma tela de login de terminal. Após a autenticação, você verá uma lista de servidores aos quais está autorizado a acessar.

Configuração

Toda a configuração é feita por variáveis de ambiente (ou arquivo .env). Consulte .env.example para a referência completa.

Variável	Padrão	Descrição
`PROXY_LISTEN_ADDR`	`0.0.0.0:2222`	Endereço de bind do proxy SSH
`HTTP_LISTEN_ADDR`	`0.0.0.0:8080`	Endereço HTTP de verificação de integridade
`GRPC_LISTEN_ADDR`	`0.0.0.0:9090`	Endereço gRPC do kill-switch
`PROXY_NODE_IP`	`127.0.0.1`	IP externo embutido nos binários da CLI
`DATABASE_URL`	`postgres://zttp:...`	String de conexão do PostgreSQL
`VAULT_ADDR`	`http://localhost:8201`	URL do servidor Vault
`VAULT_TOKEN`	`dev-root-token-zttp`	Token root do Vault (apenas dev — use AppRole em produção)
`MAX_FAILED_ATTEMPTS`	`5`	Limite de bloqueio
`LOCKOUT_DURATION`	`15m`	Duração do bloqueio da conta
`RATE_LIMIT_PER_MIN`	`10`	Máximo de tentativas de login por minuto por IP
`AUDIT_LOG_DIR`	`/var/log/zttp/audit`	Caminho para o diretório de gravação de sessões
`SOC_WEBHOOK_URL`	(vazio)	Webhook opcional para alertas do SOC

zttp

Mais Populares