🗝️ vault-conductor

Bitwarden Secret Manager에 시크릿으로 저장된 SSH 키를 제공하는 SSH 에이전트입니다.

SSH 인증 및 Git 커밋 서명을 지원합니다.

데모

demo terminal gif

기능

SSH 클라이언트와 Bitwarden Secrets Manager 사이의 안전한 브리지 역할을 하는 Unix 도메인 소켓 서버로 SSH 에이전트 프로토콜을 구현합니다.

주요 기능:

에이전트 수명 주기: 데몬(백그라운드) 또는 포그라운드 프로세스로 실행되며 /tmp/vc-$(whoami)-ssh-agent.sock의 Unix 소켓에서 수신 대기합니다.
키 지연 로딩: SSH 키는 공식 Rust SDK를 통해 요청 시에만 Bitwarden에서 가져온 후 메모리에 캐시됩니다.
안전한 SSH 작업: SSH 클라이언트가 ID를 조회하거나 서명을 요청하면 에이전트는 ssh-agent-lib 크레이트를 사용하여 개인 키를 디스크에 노출하지 않고 요청을 처리합니다.
프로세스 관리: 백그라운드 모드는 분리된 자식 프로세스를 생성하고 PID를 추적하며 SIGTERM/SIGINT를 통한 정상 종료를 지원합니다.
보안: 소켓 권한은 0600(소유자 전용)으로 잠기고, 키는 프로세스 메모리에만 존재하며, Bitwarden API는 세밀한 시크릿 액세스 권한으로 구성할 수 있는 범위가 제한된 머신 토큰을 사용하여 호출됩니다.

내부적으로는 Tokio를 사용하여 비동기 I/O를 구현하고, ssh-key 크레이트를 사용하여 암호화 작업을 수행하며, OpenSSH 형식의 Ed25519 및 RSA 키를 모두 지원합니다.

왜 만들었나

제 필요에서 탄생했습니다. Bitwarden GUI 클라이언트의 Bitwarden SSH Agent 기능은 편리하지만, CLI만 사용하는 개발 환경에서는 무엇을 써야 할까요? CI/CD 파이프라인에서 SSH 키를 안전하게 가져와 git 커밋에 서명하려면 어떻게 해야 할까요? 개인 키를 복사하지 않고 임시 컨테이너나 VM에서 SSH 연결을 열어야 한다면? 키체인에 저장되고 로그인 세션에 묶인 암호문구를 다루지 않으려면?

그래서 개인 키를 노출하지 않고 SSH 키를 검색하여 사용할 수 있게 해주는 작은 CLI 도구를 작성했습니다.

그리고 전체 Bitwarden 볼트를 환경으로 가져오지 않도록 Bitwarden Secrets Manager를 사용하여 어떤 머신이 어떤 시크릿에 접근할 수 있는지 선택하고 세밀한 토큰 권한을 설정할 수 있습니다.

요구 사항

Bitwarden Secret Manager가 구성된 Bitwarden 계정(무료로 생성 및 설정 가능) (자체 호스팅 Bitwarden 지원 예정)
BWS에 시크릿 값으로 저장된 OpenSSH 새 형식의 Ed25519 또는 RSA SSH 키
- -----BEGIN OPENSSH PRIVATE KEY----- 및 -----END OPENSSH PRIVATE KEY----- 문자열을 포함하여 저장해야 합니다.
- 참고: 새로운 OpenSSH 개인 키 형식은 2018년 OpenSSH 7.8에서 도입되었습니다.
최근 5년 이내에 출시된 macOS 또는 Linux

설치

아래 방법 중 하나를 사용하세요.

poof

poof 사용:

poof install pirafrank/vault-conductor

원라이너 스크립트

curl -fsSL https://raw.githubusercontent.com/pirafrank/vault-conductor/main/install.sh | sh

Homebrew

brew tap pirafrank/tap
brew install vault-conductor

수동 설치

또는 최신 안정 버전을 수동으로 다운로드하여 $PATH에 넣습니다.

소스에서

cargo install --locked --git https://github.com/pirafrank/poof --tag VERSION

설정

다음을 제공해야 합니다:

BWS_ACCESS_TOKEN: 위에서 설정한 머신 토큰. 환경 변수 이름은 Bitwarden의 bws CLI 도구와 동일합니다.
BW_SECRET_IDS: 각 개인 키가 저장된 시크릿의 UUID를 쉼표로 구분한 목록. BWS 웹 앱에서 각 시크릿의 UUID를 확인할 수 있습니다(시크릿 이름 아래 확인).
BW_SERVER_ENDPOINT(선택 사항): 사용자 지정 Bitwarden 서버 엔드포인트(프로토콜 없이 호스트만). 제공하지 않으면 기본값은 bitwarden.com입니다. 유효한 예: bitwarden.eu(클라우드) 및 myvault.example.com, 192.168.1.100, vault.internal(자체 호스팅).

위 환경 변수(CI 및 DevOps 환경에 적합)로 전달하거나 구성 파일을 통해 전달할 수 있습니다:

# 기본 경로에 예제 구성 파일을 다운로드한 후 필요에 맞게 사용자 지정하세요
mkdir ~/.config/vault-conductor
curl -sSL https://github.com/pirafrank/vault-conductor/raw/refs/heads/main/config.yaml.example > ~/.config/vault-conductor/config.yaml
chmod 0600 ~/.config/vault-conductor/config.yaml

사용법

# SSH 에이전트 환경 변수를 vault-conductor 소켓으로 설정
export SSH_AUTH_SOCK="/tmp/vc-$(whoami)-ssh-agent.sock"

# 포그라운드로 시작
# (처음 사용자가 구성이 올바른지 확인할 때 권장)
vault-conductor start --fg

# 백그라운드로 에이전트 시작
vault-conductor start

# 백그라운드 에이전트 중지
vault-conductor stop

start 명령은 사용자 지정 구성 경로를 제공하는 --config 옵션도 지원합니다. 환경 변수는 항상 구성 파일보다 우선합니다.

디버그

때로는 이상한 상황을 디버그하고 가능한 한 많은 로그가 필요할 수 있습니다. 다음을 실행하여 포그라운드로 실행하고 자세한 표준 출력 로그를 확인하세요:

vault-conductor start --fg -vv

서비스로 설치

사용자 공간의 Systemd 서비스로 설치할 수 있습니다. 자세한 내용은 여기를 참조하세요.

문서

코드가 어떻게 작동하고 구성되어 있는지에 대한 다이어그램은 docs 디렉터리를 확인하세요. RSA 키를 사용하거나 에이전트를 포워딩하기 전에 보안 정책을 참조하세요.

다음 계획

여러 SSH 키 지원
자체 호스팅 Bitwarden 지원
더 나은 테스트
더 많은 설치 방법 제공(Homebrew, AUR, nix, .deb, .rpm)
Bitwarden 외 다른 제공자 지원?

이름에 대하여

vault, /voːlt/ - 지하실, 특히 귀중품을 보관하는 방

conductor, /kənˈdʌk·tər/ - 지휘자, 열이나 전기를 전도하는 것

확장하여, Bitwarden 볼트에서 개발 환경으로 귀중한 SSH 키를 전도하는 것을 의미합니다.

라이선스

이 프로젝트는 MIT 라이선스로 제공됩니다.

자세한 내용은 LICENSE 파일을 참조하세요.

vault-conductor

인기