nihal799/zttp제로 트러스트 SSH 배스천 프록시로, Vault 기반 키 관리, RBAC 정책 적용, 전체 세션 녹화, 그리고 프로덕션 인프라에 대한 감사 가능한 접근을 위한 관리자 TUI를 제공합니다.
ZTTP는 Golang으로 구축된 강화된 자체 호스팅 제로 트러스트 SSH 배스천 프록시로, HashiCorp Vault 기반 키 관리, RBAC 정책 적용, 전체 세션 녹화, 대화형 관리자 TUI를 갖추고 있으며, 프로덕션 인프라에 대한 감사 가능한 제로 트러스트 접근이 필요한 팀을 위해 설계되었습니다.
현대의 엔지니어링 팀은 개발자에게 업무 수행에 필요한 최소한의 접근 권한을 부여할 방법이 필요합니다 — 그 이상도, 그 이하도 아닙니다. 전통적인 SSH 키 배포는 오류가 발생하기 쉽습니다: 키가 공유되고, 노트북에 방치되며, 며칠 늦게 폐기됩니다.
ZTTP SSH 프록시는 인프라로 향하는 단일 제로 트러스트 관문 역할을 함으로써 이 문제를 해결합니다:
| 문제 | ZTTP 솔루션 |
|---|---|
| 노트북에서 공유되는 SSH 키 | 키는 HashiCorp Vault에만 존재 — 디스크에 저장되지 않음 |
| 누가 무엇을 했는지에 대한 가시성 부재 | 모든 키 입력이 .ttyrec 형식으로 기록됨 |
| 전면적인 프로덕션 접근 | 역할 기반 정책 엔진이 환경별 규칙을 적용 |
| 활성 세션을 중단할 방법 없음 | Kill-switch gRPC 엔드포인트가 모든 라이브 세션을 종료 |
| 감사자를 위한 불투명한 접근 | 세션 재생, 텍스트 로그, 관리자 작업 로그를 갖춘 관리자 TUI |
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
인프라 서비스 (Docker Compose):
| 서비스 | 용도 |
|---|---|
zttp-proxy | 핵심 ZTTP SSH 배스천 프록시 (Golang 바이너리) |
zttp-postgres | 컨트롤 플레인 데이터베이스 (사용자, 서버, RBAC 정책) |
zttp-vault | HashiCorp Vault — SSH 개인 키 저장 |
zttp-nginx | /release/에서 CLI 설치 프로그램 제공 |
zttp-init-audit | 볼륨 권한을 수정하는 일회성 컨테이너 |
.ttyrec 형식으로 녹화됨서버 (프록시 호스트):
2224에서 공용 또는 LAN 접근 가능한 IPmake (선택 사항이지만 권장)개발자 (클라이언트):
ssh 명령)git clone https://gitlab.com/Nihal799/zttp.git
cd zttp
cp .env.example .env
.env를 편집하고 최소한 다음을 설정하세요:
PROXY_NODE_IP=<your-server-public-ip>
POSTGRES_PASSWORD=<a-strong-password>
VAULT_TOKEN=<a-strong-vault-token>
⚠️
.env파일을 절대 커밋하지 마세요. 이 파일은.gitignore에 나열되어 있습니다.
make docker-up
# or directly:
docker compose -f deploy/docker-compose.yml up -d --build
make docker-ps
curl http://localhost:8080/healthz
make release PROXY_ADDR=<your-server-ip>:2224
이것은 모든 플랫폼용 클라이언트를 크로스 컴파일하고 dist/install.sh 및 dist/install.ps1을 올바른 서버 URL로 자동 업데이트합니다. Nginx 컨테이너는 이를 http://<your-server-ip>:8555/에서 제공합니다.
curl -fsSL http://<proxy-ip>:8555/install.sh | bash
irm http://<proxy-ip>:8555/install.ps1 | iex
설치가 완료되면 ZTTP 게이트웨이에 연결합니다:
zttp
# or directly:
ssh -p 2224 <your-username>@<proxy-ip>
터미널 로그인 화면이 표시됩니다. 인증 후에는 접근 권한이 부여된 서버 목록이 표시됩니다.
모든 구성은 환경 변수(또는 .env 파일)를 통해 이루어집니다. 전체 참조는 .env.example을 참고하세요.
| 변수 | 기본값 | 설명 |
|---|---|---|
PROXY_LISTEN_ADDR | 0.0.0.0:2222 | SSH 프록시 바인드 주소 |
HTTP_LISTEN_ADDR | 0.0.0.0:8080 | 상태 확인 HTTP 주소 |
GRPC_LISTEN_ADDR | 0.0.0.0:9090 | 킬 스위치 gRPC 주소 |
PROXY_NODE_IP | 127.0.0.1 | CLI 바이너리에 내장되는 외부 IP |
DATABASE_URL | postgres://zttp:... | PostgreSQL 연결 문자열 |
VAULT_ADDR | http://localhost:8201 | Vault 서버 URL |
VAULT_TOKEN | dev-root-token-zttp | Vault 루트 토큰 (개발 전용 — 운영 환경에서는 AppRole 사용) |
MAX_FAILED_ATTEMPTS | 5 | 잠금 임계값 |
LOCKOUT_DURATION | 15m | 계정 잠금 지속 시간 |
RATE_LIMIT_PER_MIN | 10 | IP당 분당 최대 로그인 시도 횟수 |
AUDIT_LOG_DIR | /var/log/zttp/audit | 세션 녹화 디렉터리 경로 |
SOC_WEBHOOK_URL | (비어 있음) | SOC 알림용 선택적 웹훅 |
ZTTP는 역할 기반 모델을 사용합니다. 각 사용자에게는 역할이 할당되며, 각 역할에는 접근할 수 있는 서버 환경을 정의하는 정책이 있습니다.
| 역할 | 접근 권한 |
|---|---|
security-admin | 모든 환경에 대한 전체 접근 + Admin Console |
sre-tier1 | 프로덕션을 포함한 모든 환경 |
sre-tier2 | 스테이징 및 개발 환경만 |
dev | 개발 환경만 |
readonly | 개발 환경, 제한된 명령 집합 |
역할 및 서버 할당은 Admin Console(아래 참조)을 통해 관리됩니다. RBAC 엔진은 모든 검사를 단일 PostgreSQL 쿼리로 수행하며, 클라이언트에게 접근이 거부된 이유를 절대 노출하지 않습니다(열거 방지).
게이트웨이 메뉴에서 zttp-admin 서버에 연결하거나, security-admin 역할을 가진 계정으로 로그인하세요.
Admin Console은 다음을 제공합니다:
| 메뉴 옵션 | 설명 |
|---|---|
| Add User | 역할 할당과 함께 새 사용자 생성 |
| Add Server | 대상 서버 등록 (호스트명, IP, 환경, SSH 사용자) |
| Manage Server Access | 특정 서버에 대한 사용자 접근 권한 부여 또는 취소 |
| View Users | 모든 사용자와 해당 역할 목록 표시 |
| View Servers | 등록된 모든 서버 목록 표시 |
| View Audit Logs | 세션 탐색, 녹화 재생, 텍스트 로그 열람 |
| [ Back ] | 서버 게이트웨이로 돌아가기 |
모든 관리자 작업은 감사 볼륨 내의
admin-actions.log에 기록됩니다.
모든 세션은 zttp-audit-logs Docker 볼륨(컨테이너 내부의 /var/log/zttp/audit/)에 저장됩니다.
security-admin으로 로그인Ctrl+C 누르기# List recordings
sudo ls /var/lib/docker/volumes/zttp-audit-logs/_data/
# Play a recording with ttyplay
sudo ttyplay /var/lib/docker/volumes/zttp-audit-logs/_data/<session-id>.ttyrec
# Read admin actions log
sudo cat /var/lib/docker/volumes/zttp-audit-logs/_data/admin-actions.log
요구 사항: Go 1.25+, Docker(교차 컴파일용)
# Build proxy + CLI for current platform
make build
# Cross-compile CLI for all platforms (Linux, macOS, Windows)
make release PROXY_ADDR=<proxy-ip>:2224
# Run tests
make test
# Run proxy locally (requires Postgres + Vault already running)
make run-proxy
| 명령어 | 설명 |
|---|---|
make build | 현재 플랫폼용 프록시 및 CLI 빌드 |
make release | 모든 플랫폼용 CLI 바이너리 크로스 컴파일 |
make release-docker | Docker 컨테이너 내부에서 크로스 컴파일 (snap/WSL 문제 회피) |
make docker-up | 모든 Docker Compose 서비스 시작 |
make docker-down | 모든 서비스 중지 및 볼륨 삭제 |
make docker-logs | 프록시 로그 실시간 출력 |
make docker-ps | 컨테이너 상태 표시 |
make test | 모든 Go 테스트 실행 |
make migrate | 데이터베이스 마이그레이션 적용 |
make seed | 개발 데이터 시드 |
make hashpw PW=mypassword | 수동 DB 시딩용 bcrypt 해시 생성 |
make clean | 컴파일된 바이너리 및 빌드 캐시 제거 |