ts-ssh: Tailscale용 간단한 SSH/SCP 클라이언트

tsnet을 사용하여 Tailscale 네트워크에 연결하는 간소화된 명령줄 SSH 클라이언트 및 SCP 유틸리티입니다. 전체 Tailscale 데몬이 필요하지 않습니다. 단순성을 염두에 두고 설계되었으며, ts-ssh는 최소한의 플래그와 최대의 명확성으로 표준 ssh 명령을 모방합니다.

설계 철학: 기능보다는 단순성. 마치 ssh처럼, 하지만 Tailscale 위에서 작동합니다.

기능 (Features)

🚀 핵심 기능 (Core Functionality)

• Userspace Tailscale 연결: tsnet을 사용하여 데몬 불필요
• 표준 SSH 구문: 일반적인 ssh와 동일하게 작동
• SCP 파일 전송: 파일 작업을 위한 간단한 -scp 플래그
• 대화형 SSH 세션: 전체 PTY 지원
• SOCKS5 동적 포트 포워딩: 프록시 지원을 위한 -D 플래그 (VSCode Remote SSH와 호환)
• 안전한 호스트 키 검증: ~/.ssh/known_hosts 사용
• 다중 인증 방식: SSH 키, 비밀번호 프롬프트
• 유연한 사용자 이름 지원: 사용자 이름에 마침표(예: first.last) 포함 가능

🛠️ 기술적 기능 (Technical Features)

• 크로스 플랫폼: Linux, macOS (Intel/ARM), Windows, FreeBSD, OpenBSD
• 빠른 시작 속도: 프레임워크나 복잡한 초기화 과정 없음
• 조합 가능(Composable): 스크립트 및 자동화에서 완벽하게 작동
• 명확한 오류 처리 및 유용한 피드백 제공
• 엔터프라이즈급 보안 기능 내장
• 양자내성 암호화 (Post-quantum cryptography) 지원

전제 조건 (Prerequisites)

• Go: 버전 1.18 이상 (go version으로 확인)
• Tailscale 계정: 활성화된 Tailscale 계정
• 대상 노드 (Target Node): SSH 서버가 실행되는 Tailscale 네트워크 내의 장치

설치 (Installation)

go install 사용 (권장)

go install github.com/derekg/ts-ssh@latest

• $GOPATH/bin 또는 $HOME/go/bin이 시스템의 PATH에 포함되어 있는지 확인하십시오.*

수동 빌드 (Manual Build)

1. 저장소 클론:
   복사

git clone https://github.com/derekg/ts-ssh.git
cd ts-ssh

2. 실행 파일 빌드:
```bash
go build -o ts-ssh .

크로스 컴파일 (Cross-Compilation)

# macOS (Apple Silicon)
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -o ts-ssh-darwin-arm64 .

...

사용법 (Usage)

Usage: ts-ssh [options] [user@]host[:port] [command...] 
       ts-ssh -scp source dest

...

예시 (Examples)

기본 SSH 작업 (Basic SSH Operations)

# 호스트에 연결하기
ts-ssh hostname

...

SCP 파일 전송 (SCP File Transfer)

# 파일 업로드
ts-ssh -scp file.txt hostname:/tmp/
ts-ssh -scp file.txt user@hostname:/remote/path/
...

고급 사용법 (Advanced Usage)

# 버전 정보 확인
ts-ssh --version

...

SOCKS5 동적 포트 포워딩 (SOCKS5 Dynamic Port Forwarding)

-D 플래그를 사용하여 SSH 터널을 통해 연결을 전달하기 위한 SOCKS5 프록시를 설정할 수 있습니다. 이는 VSCode Remote SSH와 같은 도구에 특히 유용합니다.

# localhost:1080에서 SOCKS5 프록시 시작하기
ts-ssh -D 1080 hostname

...

보안 참고 사항 (Security Notes):

• localhost, 127.0.0.1, 또는 ::1에 바인딩하는 것은 안전합니다 (프록시가 로컬에서만 접근 가능).
• 0.0.0.0 또는 특정 네트워크 IP에 바인딩하는 것은 프록시를 귀하의 네트워크에 노출시킵니다.
• 이 도구는 non-localhost 주소에 바인딩할 때 경고합니다.

PTY 할당 비활성화 (Disable PTY Allocation)

-T 플래그를 사용하여 pseudo-terminal(가상 터미널) 할당을 비활성화합니다. 이는 비대화형 명령어 및 자동화에 유용합니다:

# PTY 없이 명령어 실행하기 (ssh -T와 유사)
ts-ssh -T hostname

### 🔒 보안 기능
- **현대적인 SSH 키 지원**: 레거시 RSA 키보다 Ed25519 우선 적용
- **호스트 키 검증**: `~/.ssh/known_hosts`를 통한 포괄적인 검증
- **TTY 보안**: 하이재킹 공격을 방지하는 다층적 유효성 검사
- **프로세스 보호**: 프로세스 목록 및 환경 변수에서의 자격 증명 마스킹
- **원자 파일 작업 (Atomic File Operations)**: 파일 처리 시 경쟁 조건(Race condition) 방지
- **크로스 플랫폼 보안**: Windows/macOS/Linux용 플랫폼별 구현
- **양자 내성 암호화 (Post-Quantum Cryptography)**: 미래 지향적인 암호화 지원

### ⚠️ 보안 경고
- **`-insecure` 플래그**: 호스트 키 검사를 비활성화합니다 - **주의해서 사용하세요**
- MITM 공격이 우려되지 않는 신뢰할 수 있는 네트워크에서만 사용하십시오.
- 프로그램은 불안전 모드(insecure mode)로 진행하기 전에 경고 메시지를 표시할 것입니다.

자세한 보안 정보는 [보안 문서](docs/security/)를 참조하세요.

## 아키텍처

ts-ssh는 단순성과 보안을 염두에 두고 구축되었습니다:

ts-ssh/
├── main.go # ~457 라인 - 메인 CLI 로직
├── constants.go # ~52 라인 - 상수
...

**총합**: ~4,656 라인 (이전 버전에 비해 69% 축소)

### 설계 원칙
- **단일 책임 원칙 (Single responsibility)**: 각 함수는 하나의 일을 잘 수행합니다.
- **최소한의 추상화 (Minimal abstraction)**: 과도한 엔지니어링을 피합니다.
- **명확한 명명 규칙 (Clear naming)**: 함수 이름이 그 기능을 설명합니다.
- **암시적보다 명시적인 것이 낫다 (Explicit is better than implicit)**: 마법 같은 코드를 사용하지 않습니다.

## 테스트

단위 테스트, 통합 테스트 및 E2E 시나리오를 포함하는 440개 이상의 포괄적인 테스트 스위트:

```bash
# 모든 테스트 실행
go test ./...

...

테스트 커버리지:

• 전체: 35.5%
• 보안 모듈: 69.4%
• 오류 처리: 84.6%
• 플랫폼 유틸리티: 100%
• 핵심 파싱 함수: 95-100%

표준 SSH와의 비교

ts-ssh는 표준 SSH와 똑같이 작동하지만, Tailnet을 통해 연결합니다:

역사적 배경 (Historical Context)

이번 버전은 ts-ssh 코드베이스의 대폭 간소화를 보여줍니다:

• 이전: 듀얼 CLI 모드, 11개 언어 국제화(internationalization), Charmbracelet UI 프레임워크, 여러 하위 명령어 등을 포함하여 약 15,000줄
• 이후: 표준 SSH를 모방하는 단순 플래그 기반 CLI로 약 4,656줄

기존의 복잡한 코드는 참고용으로 _old_complex/에 보존되어 있습니다.

제거된 기능:

• ❌ 듀얼 CLI 모드 (현대형/레거시)
• ❌ Charmbracelet Fang, Lipgloss, Huh (UI 프레임워크)
• ❌ Spf13 Cobra (명령어 프레임워크)
• ❌ 11개 언어 국제화 시스템
• ❌ 다중 호스트 작업 (list, exec, multi, copy, pick)
• ❌ Tmux 통합

유지된 기능:

• ✅ 표준 구문을 사용한 SSH 연결
• ✅ SCP 파일 전송
• ✅ 모든 보안 기능
• ✅ 양자 내성 암호화 (Post-quantum cryptography)
• ✅ 크로스 플랫폼 지원
• ✅ Tailscale tsnet 통합

기여 (Contributing)

기여를 환영합니다! 다음 사항을 확인해 주세요:

• 코드는 Go의 모범 사례(best practices)를 따릅니다.
• 새로운 기능에 대한 테스트가 포함됩니다.
• 문서가 업데이트됩니다.
• 단순하게 유지하세요 - 복잡성을 추가하는 것을 피하세요.

라이선스 (License)

이 프로젝트는 MIT License 하에 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

지원 (Support)

• 이슈(Issues): https://github.com/derekg/ts-ssh/issues
• 토론(Discussions): https://github.com/derekg/ts-ssh/discussions

단순함을 위해 ❤️로 제작되었습니다