Name: vctl
SKU: -

소개

vctl은 HashiCorp Vault를 기반으로 한 인프라 접근 제어 CLI 도구로, Vault 토큰 관리, 단기 SSH 인증서 발급, PostgreSQL 기반 호스트 인벤토리 관리 및 중앙 집중식 SSH 접근 감사 메타데이터 기록을 제공합니다. ghdwlsgur이 개발했으며, 로컬 데몬 없이 바이너리가 로그인, 갱신, 재인증 및 SSH 인증서 서명을 직접 처리합니다. Windows 사용자는 Chocolatey를 통해 설치할 수 있으며, Vault와 PostgreSQL을 연동하여 보안된 원격 시스템 접근을 가능하게 합니다.

상세정보

토큰 생명주기 관리

vctl은 Vault 토큰을 자동으로 갱신하고, 갱신이 불가능할 경우 AppRole을 통해 재인증합니다. 토큰은 메모리 내에서만 처리되며, 디스크에 저장되지 않아 보안 위험을 최소화합니다. vctl token 명령으로 현재 유효한 토큰을 확인할 수 있습니다.

단기 SSH 인증서 발급

정적 SSH 키 대신, vctl은 각 연결마다 메모리 내에 일시적인 ed25519 키를 생성하고 Vault의 SSH CA를 통해 단기 인증서를 발급받습니다.これにより、秘密鍵の漏洩リスクがなく、ホスト側ではVaultのSSH CAのみを信頼すればよいという仕組みになります。

중앙 집중식 호스트 인벤토리 및 감사

호스트 정보와 접근 메타데이터는 PostgreSQL에 저장되며, vctl은 이를 통해 호스트 토폴로지를 해결하고 jump 체인을 결정합니다. 모든 SSH 연결 시도는 vctl audit로 조회할 수 있는 접근 로그에 기록되며, Vault의 감사 장치와 함께 이중 보안 체계를 제공합니다.

WireGuard 터널링 (사용자 공간)

vctl wg connect 명령은 사용자 공간에서 WireGuard 터널을 생성하고 SOCKS5 프록시를 제공하여, 별도의 드라이버나 루트 권한 없이도 내부 네트워크에 접근할 수 있게 합니다. 터널 설정은 Vault에서 동적으로 읽어오며, 연결 종료 시 자동으로 정리됩니다.

다운로드·설치 방법

Windows 사용자는 관리자 권한으로 PowerShell을 열고 다음 명령을 실행하여 Chocolatey를 통해 vctl을 설치할 수 있습니다:

choco install vctl
vctl --version

설치 후, vctl --version로 버전을 확인하여 정상 설치 여부를 검증할 수 있습니다. Chocolatey 패키지가 커뮤니티 moderation 중일 경우, GitHub Releases에서 직접 windows_amd64.zip 또는 windows_arm64.zip 아카이브를 다운받아 수동으로 설치할 수도 있습니다.

기본 사용법/명령어

첫 번째 로그인은 기본적으로 GitLab SSO(OIDC)를 통해 이루어집니다. 브라우저가 열려 조직의 GitLab에서 인증을 완료하면, 토큰이 캐시되어 이후 모든 명령에서 재사용됩니다.

vctl login

로그인 후, 등록된 호스트에 SSH 연결을 시도할 수 있습니다. 호스트 이름은 PostgreSQL 인벤토리에서 해결되며, jump 체인이 자동으로 적용됩니다:

vctl ssh sre-srv-0047 vctl ssh 0047 vctl ssh

접속 기록은 다음과 같이 조회할 수 있습니다:

vctl audit vctl audit --detail vctl audit --host sre-srv-0047 vctl audit --user albert vctl audit --source-ip 192.0.2.10

Vault의 KV 시크릿을 읽으려면 다음과 같이 사용할 수 있습니다:

vctl kv gitlab-albert vctl kv search oidc --under kv/teams/sre vctl kv get kv/teams/sre/gitlab-albert --field token

시크릿 값을 환경 변수로 전달하여 자식 프로세스에서 사용하려면 vctl kv exec를 사용합니다:

vctl kv exec gitlab-albert curl -H 'PRIVATE-TOKEN: {token}' https://gitlab.example/api/v4/user

이런 경우에 유용합니다

보안이 중요한 조직에서 개발자나 SRE 엔지니어가 bastion host나 jump 서버 없이도 내부 서버에 안전하게 접근해야 할 때 유용합니다. 특히, SSH 키 관리가 복잡하거나 키 유출 위험이 높은 환경에서, 단기 인증서 기반 인증을 통해 보안 수준을 높일 수 있습니다. 또한, 모든 접근 시도가 중앙에서 기록되어 감사 및 사고 조사 시 유용한 증거 자료를 제공합니다.

지원 환경·시스템 요구사항

vctl은 Windows 10 이상, amd64 및 arm64 아키텍처에서 실행 가능합니다. 실행에는 Vault 서버(>= 1.8)와 PostgreSQL 인스턴스에 대한 네트워크 연결이 필수적이며, 인증에는 GitLab SSO, AppRole 또는 userpass 중 하나가 구성되어 있어야 합니다. 로컬 시스템에는 관리자 권한이 필요하지 않으며, 일반 사용자 권한으로 실행 가능합니다.

제한 사항·확인 사항

vctl은 PostgreSQL이 정상적으로 작동할 때 전체 기능을 제공하지만, 데이터베이스가 일시적으로 중단될 경우에도 로컬 스냅샷을 통해 vctl ssh 및 vctl list 명령은 제한적으로 계속 작동합니다. 다만, vctl sync, vctl inject, RBAC 관리 등 쓰기를伴う 작업은 PostgreSQL이 복구될 때까지 차단됩니다. 이는 데이터 무결성을 보호하기 위한 의도적인 설계입니다. 또한, 토큰 정책은 항상 Vault에서 실시간으로 조회되므로 캐시되지 않으며, 이는 보안 경계를 유지하기 위한 것입니다.

FAQ

vctl은 무료인가요?
네, vctl은 Apache-2.0 라이선스 하에 오픈소스로 제공되며, 상업적 이용을 포함한 모든 사용에 제한이 없습니다.
Windows에서만 사용할 수 있나요?
아니요, vctl은 Windows, macOS 및 Linux에서 모두 동일하게 작동합니다. 공식 바이너리는 각 플랫폼별로 GitHub Releases에서 제공됩니다.
Vault나 PostgreSQL을 직접 운영해야 하나요?
네, vctl은 외부 시스템에 의존하는 도구이므로, HashiCorp Vault와 PostgreSQL 인스턴스가 별도로 준비되어 있어야 작동합니다. 이들 시스템의 설치 및 운영은 vctl의 범위 밖입니다.

시스템 요구사항

vctl은 Vault와 PostgreSQL 인스턴스에 대한 네트워크 접근이 필요하며, 인증에는 GitLab SSO(OIDC), AppRole 또는 userpass 중 하나를 사용해야 합니다. Windows에서는 Chocolatey 패키지 관리자를 통해 설치되며, 관리자 권한이 있는 PowerShell에서 `choco install vctl` 명령을 실행해야 합니다.

vctl

소개