ZTTP — 제로 트러스트 투명 프록시

강화된 자체 호스팅 SSH 배스천 호스트 — Vault 기반 키 관리, RBAC 정책 적용, 전체 세션 녹화, 대화형 관리자 TUI를 갖추고 있으며, 감사 가능한 제로 트러스트 방식으로 프로덕션 인프라에 접근해야 하는 팀을 위해 설계되었습니다.

목차

• ZTTP를 선택해야 하는 이유
• 아키텍처 개요
• 주요 기능
• 사전 요구 사항
• 빠른 시작 — 서버
• 빠른 시작 — 클라이언트
• 구성
• 역할 및 RBAC 정책
• 관리자 콘솔
• 감사 로그 및 세션 녹화
• 소스에서 빌드
• Makefile 참조
• 스크린샷 및 데모
• 프로젝트 구조
• 보안 모델
• 기여
• 라이선스

ZTTP를 선택해야 하는 이유

현대 엔지니어링 팀은 개발자에게 업무 수행에 필요한 최소한의 접근 권한을 부여할 방법이 필요합니다 — 그 이상도 이하도 아닙니다. 기존의 SSH 키 배포 방식은 오류가 발생하기 쉽습니다. 키가 공유되고, 노트북에 잊혀진 채 남아 있으며, 철회도 너무 늦게 이루어집니다.

ZTTP는 인프라로 들어가는 단일 문 역할을 하여 이 문제를 해결합니다:

아키텍처 개요

개발자 노트북
      │
      │  zttp
      │  (내부적으로: 포트 2224의 SSH)
      ▼
┌─────────────────────────────────────────────────────────┐
│                     ZTTP 프록시                          │
│                                                         │
│  ① 인증 게이트   — bcrypt/Argon2id 로그인 TUI           │
│  ② RBAC 엔진     — 환경 인식 정책 검사                  │
│  ③ Vault 조회    — 임시 SSH 키 검색                     │
│  ④ 브리지        — 투명 TCP 터널                        │
│  ⑤ 감사 기록기   — ttyrec 프레임 레코더                 │
└──────────┬──────────────────────────────────────────────┘
           │  ssh (사설 IP, 임시 키)
           ▼
     대상 서버

인프라 서비스 (Docker Compose):

주요 기능

• 🔐 제로 트러스트 인증 — bcrypt 비밀번호 해싱, 속도 제한, 5회 실패 시 계정 잠금을 갖춘 대화형 SSH 로그인 TUI
• 🛡️ RBAC 정책 엔진 — 단일 최적화된 PostgreSQL JOIN으로 역할별, 환경별 접근 제어 (왕복 없음)
• 🗝️ Vault 기반 SSH 키 — 개인 키가 디스크에 닿지 않으며, 세션마다 HashiCorp Vault에서 임시로 가져옴
• 📹 전체 세션 녹화 — 모든 세션이 타임스탬프가 있는 프레임으로 .ttyrec 형식으로 기록됨
• 🖥️ 대화형 관리자 TUI — 사용자 관리, 서버 등록, 접근 권한 부여, 로그 검토를 위한 전체 터미널 UI
• 🔍 감사 로그 뷰어 — 서버별 세션 탐색, 녹화 재생, 관리자 콘솔에서 직접 깔끔한 텍스트 로그 읽기
• ⚡ 킬 스위치 — 모든 활성 세션을 즉시 종료하는 gRPC 엔드포인트
• 📋 관리자 작업 로그 — 모든 관리 작업(사용자 생성, 접근 권한 부여, 로그 보기)이 영구 감사 추적에 기록됨
• 🌍 다중 플랫폼 클라이언트 — Linux, macOS (amd64/arm64), Windows용 단일 바이너리 CLI

사전 요구 사항

서버 (프록시 호스트):

• Docker ≥ 24 및 Docker Compose ≥ 2.20
• 포트 2224의 공용 또는 LAN 접근 가능 IP
• make (선택 사항이지만 권장)

개발자 (클라이언트):

• 모든 SSH 클라이언트 (ssh 명령)
• Linux, macOS 또는 Windows 머신

빠른 시작 — 서버

1. 저장소 복제

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

2. 환경 구성

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에 포함되어 있습니다.

3. 모든 서비스 시작

make docker-up
# 또는 직접:
docker compose -f deploy/docker-compose.yml up -d --build

4. 서비스 상태 확인

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

5. CLI 설치 프로그램 빌드 및 배포

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

이 명령은 모든 플랫폼용 클라이언트를 크로스 컴파일하고 올바른 서버 URL로 dist/install.sh 및 dist/install.ps1을 자동 업데이트합니다. Nginx 컨테이너는 이를 http://<your-server-ip>:8555/에서 제공합니다.

빠른 시작 — 클라이언트

Linux / macOS

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

Windows (PowerShell, 관리자 권한으로 실행)

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

연결

설치가 완료되면 ZTTP 게이트웨이에 연결합니다:

zttp
# 또는 직접:
ssh -p 2224 <your-username>@<proxy-ip>

터미널 로그인 화면이 표시됩니다. 인증 후 접근 권한이 있는 서버 목록이 표시됩니다.

구성

모든 구성은 환경 변수(또는 .env 파일)를 통해 이루어집니다. 전체 참조는 .env.example을 참조하세요.

역할 및 RBAC 정책

ZTTP는 역할 기반 모델을 사용합니다. 각 사용자에게는 역할이 할당되며, 각 역할에는 접근할 수 있는 서버 환경을 정의하는 정책이 있습니다.

역할 및 서버 할당은 관리자 콘솔을 통해 관리됩니다 (아래 참조). RBAC 엔진은 모든 검사를 단일 PostgreSQL 쿼리로 수행하며, 클라이언트에게 접근이 거부된 이유를 절대 노출하지 않습니다 (열거 방지).

관리자 콘솔

게이트웨이 메뉴에서 zttp-admin 서버에 연결하거나 security-admin 역할이 있는 계정으로 로그인하세요.

관리자 콘솔에서 제공하는 기능:

모든 관리자 작업은 감사 볼륨 내의 admin-actions.log에 기록됩니다.

감사 로그 및 세션 녹화

모든 세션은 zttp-audit-logs Docker 볼륨(컨테이너 내부의 /var/log/zttp/audit/)에 저장됩니다.

관리자 콘솔에서 보기

1. security-admin으로 로그인
2. 감사 로그 보기 선택
3. 목록에서 서버 선택
4. 세션 선택
5. 텍스트 로그 보기 (ANSI 제거, 읽기 가능) 또는 녹화 재생 (실시간 재생) 선택
6. Ctrl+C를 눌러 돌아가기

호스트에서 보기 (원시)

# 녹화 목록
sudo ls /var/lib/docker/volumes/zttp-audit-logs/_data/

# ttyplay로 녹화 재생
sudo ttyplay /var/lib/docker/volumes/zttp-audit-logs/_data/<session-id>.ttyrec

# 관리자 작업 로그 읽기
sudo cat /var/lib/docker/volumes/zttp-audit-logs/_data/admin-actions.log

소스에서 빌드

요구 사항: Go 1.25+, Docker (크로스 컴파일용)

# 현재 플랫폼용 프록시 + CLI 빌드
make build

# 모든 플랫폼용 CLI 크로스 컴파일 (Linux, macOS, Windows)
make release PROXY_ADDR=<proxy-ip>:2224

# 테스트 실행
make test

# 프록시 로컬 실행 (Postgres 및 Vault가 이미 실행 중이어야 함)
make run-proxy

Makefile 참조

스크린샷 및 데모

1. 설치

(데모 재생하려면 클릭)

2. 보안 로그인

(데모 재생하려면 클릭)

3. 서버 추가 (관리자 콘솔)

(데모 재생하려면 클릭)

4. 서버 연결 (게이트웨이)

(데모 재생하려면 클릭)

5. 킬 스위치 (관리자 강제 종료)

(데모 재생하려면 클릭)

프로젝트 구조

zttp/
├── cmd/
│   ├── proxy/          # 프록시 서버 진입점
│   └── zttp/           # CLI 클라이언트 진입점
├── db/
│   └── migrations/     # PostgreSQL 스키마 마이그레이션
├── deploy/
│   ├── docker-compose.yml
│   ├── Dockerfile.proxy
│   └── vault-seed.sh   # 테스트 SSH 키를 Vault에 시드
├── dist/
│   ├── install.sh      # Linux/macOS 설치 스크립트
│   └── install.ps1     # Windows 설치 스크립트
├── internal/
│   ├── audit/          # 관리자 작업 로깅
│   ├── auth/           # 사용자 인증 (bcrypt, 잠금)
│   ├── cli/            # CLI 클라이언트 TUI 및 연결 로직
│   ├── config/         # 환경 기반 구성
│   ├── killswitch/     # gRPC 킬 스위치 서비스
│   ├── proxy/          # SSH 프록시, 게이트웨이 TUI, 관리자 TUI, 브리지
│   ├── rbac/           # 역할 기반 접근 제어 엔진
│   ├── ratelimit/      # IP별 속도 제한
│   ├── session/        # 세션 추적 및 DB 저장소
│   └── vault/          # HashiCorp Vault SSH 키 클라이언트
├── proto/              # gRPC 프로토콜 정의
├── tools/
│   └── hashpw/         # CLI 도구: bcrypt 비밀번호 해시 생성
├── .env.example        # 구성 템플릿
├── go.mod
└── Makefile

보안 모델

기여

1. 저장소를 포크하세요
2. 기능 브랜치를 생성하세요: git checkout -b feat/your-feature
3. 변경 사항을 만들고 각 파일이 자체 커밋을 갖도록 하세요
4. 테스트 실행: make test
5. 병합 요청을 여세요

다음은 커밋하지 마세요:

• .env 또는 비밀을 포함한 모든 파일
• 프로덕션 서버의 실제 IP 주소 또는 호스트 이름
• 컴파일된 바이너리 (루트의 zttp 바이너리는 .gitignore 처리됨)

라이선스

이 프로젝트는 독점 소프트웨어입니다. 모든 권리 보유.

Go, PostgreSQL, HashiCorp Vault 및 Docker로 구축되었습니다.