ZTTP — Proxy Transparente de Confiança Zero

Um bastion host SSH auto-hospedado e endurecido com gerenciamento de chaves baseado em Vault, aplicação de políticas RBAC, gravação completa de sessões e uma TUI administrativa interativa — projetado para equipes que precisam de acesso auditável e de confiança zero à infraestrutura de produção.

Índice

• Por que ZTTP
• Visão Geral da Arquitetura
• Destaques de Recursos
• Pré-requisitos
• Início Rápido — Servidor
• Início Rápido — Cliente
• Configuração
• Funções e Política RBAC
• Console Administrativo
• Logs de Auditoria e Gravações de Sessão
• Compilação a partir do Código-Fonte
• Referência do Makefile
• Capturas de Tela e Demonstração
• Estrutura do Projeto
• Modelo de Segurança
• Contribuindo
• Licença

Por que ZTTP

Equipes de engenharia modernas precisam de uma forma de dar aos desenvolvedores o acesso mínimo necessário para fazerem seus trabalhos — nem mais, nem menos. A distribuição tradicional de chaves SSH é propensa a erros: chaves são compartilhadas, esquecidas em laptops e revogadas tarde demais.

O ZTTP resolve isso atuando como a única porta para sua infraestrutura:

Visão Geral da Arquitetura

Laptop do Desenvolvedor
      │
      │  zttp
      │  (Por baixo dos panos: SSH na porta 2224)
      ▼
┌─────────────────────────────────────────────────────────┐
│                     Proxy ZTTP                          │
│                                                         │
│  ① Portão de Autenticação — TUI de login bcrypt/Argon2id│
│  ② Mecanismo RBAC        — verificação de política por ambiente │
│  ③ Busca no Vault        — recuperação efêmera de chave SSH │
│  ④ Ponte                 — túnel TCP transparente       │
│  ⑤ Gravador de Auditoria — gravador de quadros ttyrec   │
└──────────┬──────────────────────────────────────────────┘
           │  ssh (IP privado, chave efêmera)
           ▼
     Servidor de Destino

Serviços de infraestrutura (Docker Compose):

Destaques de Recursos

• 🔐 Autenticação de confiança zero — TUI de login SSH interativa com hash de senha bcrypt, limitação de taxa e bloqueio de conta após 5 tentativas falhas
• 🛡️ Mecanismo de política RBAC — Controle de acesso por função e por ambiente com um único JOIN otimizado do PostgreSQL (sem idas e voltas)
• 🗝️ Chaves SSH baseadas em Vault — Chaves privadas nunca tocam o disco; buscadas efemeramente por sessão no 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 Logs de Auditoria — Navegue pelas sessões por servidor, reproduza gravações ou leia logs de texto limpos diretamente do console administrativo
• ⚡ Interruptor de Emergência — Endpoint gRPC para encerrar qualquer sessão ativa instantaneamente
• 📋 Log de Ações Administrativas — Cada 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 via 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 .env e defina no mínimo:

PROXY_NODE_IP=<ip-publico-do-seu-servidor>
POSTGRES_PASSWORD=<uma-senha-forte>
VAULT_TOKEN=<um-token-vault-forte>

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

3. Inicie todos os serviços

make docker-up
# ou diretamente:
docker compose -f deploy/docker-compose.yml up -d --build

4. Verifique se os serviços estão saudáveis

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

5. Compile e publique os instaladores CLI

make release PROXY_ADDR=<ip-do-seu-servidor>:2224

Isso compila de forma cruzada os clientes para todas as plataformas e atualiza automaticamente dist/install.sh e dist/install.ps1 com a URL correta do servidor. O contêiner Nginx serve esses arquivos em http://<ip-do-seu-servidor>:8555/.

Início Rápido — Cliente

Linux / macOS

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

Windows (PowerShell, execute como Administrador)

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

Conectar

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

zttp
# ou diretamente:
ssh -p 2224 <seu-usuario>@<ip-do-proxy>

Você verá uma tela de login no terminal. Após a autenticação, 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.

Funções e Política RBAC

O ZTTP usa um modelo baseado em funções. Cada usuário recebe uma função; cada função tem uma política que define quais ambientes de servidores ela pode acessar.

Funções e atribuições de servidores são gerenciadas pelo Console Administrativo (veja abaixo). O mecanismo RBAC realiza todas as verificações em uma única consulta PostgreSQL — ele nunca expõe por que o acesso foi negado ao cliente (proteção contra enumeração).

Console Administrativo

Conecte-se ao servidor zttp-admin pelo menu do gateway, ou faça login com uma conta que tenha a função security-admin.

O Console Administrativo oferece:

Todas as ações administrativas são registradas em admin-actions.log dentro do volume de auditoria.

Logs de Auditoria e Gravações de Sessão

Todas as sessões são armazenadas no volume Docker zttp-audit-logs (/var/log/zttp/audit/ dentro do contêiner).

Visualização pelo Console Administrativo

1. Faça login como security-admin
2. Selecione Ver Logs de Auditoria
3. Selecione um servidor da lista
4. Selecione uma sessão
5. Escolha Ver Log de Texto (sem ANSI, legível) ou Reproduzir Gravação (reprodução em tempo real)
6. Pressione Ctrl+C para voltar

Visualização pelo host (bruto)

# Listar gravações
sudo ls /var/lib/docker/volumes/zttp-audit-logs/_data/

# Reproduzir uma gravação com ttyplay
sudo ttyplay /var/lib/docker/volumes/zttp-audit-logs/_data/<id-da-sessao>.ttyrec

# Ler o log de ações administrativas
sudo cat /var/lib/docker/volumes/zttp-audit-logs/_data/admin-actions.log

Compilação a partir do Código-Fonte

Requisitos: Go 1.25+, Docker (para compilação cruzada)

# Compilar proxy + CLI para a plataforma atual
make build

# Compilar CLI de forma cruzada para todas as plataformas (Linux, macOS, Windows)
make release PROXY_ADDR=<ip-do-proxy>:2224

# Executar testes
make test

# Executar proxy localmente (requer Postgres + Vault já em execução)
make run-proxy

Referência do Makefile

Capturas de Tela e Demonstração

1. Instalação

(Clique para reproduzir a demonstração)

2. Login Seguro

(Clique para reproduzir a demonstração)

3. Adicionar Servidor (Console Administrativo)

(Clique para reproduzir a demonstração)

4. Conectar ao Servidor (Gateway)

(Clique para reproduzir a demonstração)

5. Interruptor de Emergência (Ejeção Administrativa)

(Clique para reproduzir a demonstração)

Estrutura do Projeto

zttp/
├── cmd/
│   ├── proxy/          # Ponto de entrada do servidor proxy
│   └── zttp/           # Ponto de entrada do cliente CLI
├── db/
│   └── migrations/     # Migrações de esquema do PostgreSQL
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile.proxy
│   └── vault-seed.sh   # Semeia chaves SSH de teste no Vault
├── dist/
│   ├── install.sh      # Script de instalação Linux/macOS
│   └── install.ps1     # Script de instalação Windows
├── internal/
│   ├── audit/          # Registro de ações administrativas
│   ├── auth/           # Autenticação de usuários (bcrypt, bloqueio)
│   ├── cli/            # TUI do cliente CLI e lógica de conexão
│   ├── config/         # Configuração baseada em ambiente
│   ├── killswitch/     # Serviço gRPC de interruptor de emergência
│   ├── proxy/          # Proxy SSH, TUI do gateway, TUI administrativa, ponte
│   ├── rbac/           # Mecanismo de controle de acesso baseado em funções
│   ├── ratelimit/      # Limitação de taxa por IP
│   ├── session/        # Rastreamento de sessões e armazenamento no banco
│   └── vault/          # Cliente de chaves SSH do HashiCorp Vault
├── proto/              # Definições de protocolo gRPC
├── tools/
│   └── hashpw/         # Ferramenta CLI: gerar hash de senha bcrypt
├── .env.example        # Modelo de configuração
├── go.mod
└── Makefile

Modelo de Segurança

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de recurso: git checkout -b feat/sua-funcionalidade
3. Faça suas alterações, garantindo que cada arquivo tenha seu próprio commit
4. Execute os testes: make test
5. Abra um merge request

Por favor, não faça commit de:

• .env ou qualquer arquivo contendo segredos
• Endereços IP reais ou hostnames de servidores de produção
• Binários compilados (o binário zttp na raiz está no .gitignore)

Licença

Este projeto é proprietário. Todos os direitos reservados.

Construído com Go, PostgreSQL, HashiCorp Vault e Docker.