Bitwarden Agent Access의 안전한 접근: 코딩 AI 에이전트와 Vault 자격 증명 공유하기

Claude Code, Codex 또는 Cursor를 실제 API를 사용하는 워크플로우와 함께 사용한다면, 당신은 실질적인 문제를 해결해야 합니다. 에이전트에게는 자격 증명 (credentials)이 필요하지만, 당신의 비밀번호 관리자는 이를 잠가 두도록 설계되었기 때문입니다. 채팅창에 API 키를 붙여넣는 것은 모델의 컨텍스트 윈도우 (context window)에 비밀을 노출시키는 행위입니다. .env 파일에 비밀을 저장하는 것은 에이전트의 bash 도구가 해당 값을 읽고 유출 (exfiltrate)할 수 있게 만듭니다. 올바른 해결책은 에이전트에게 최소한의, 일시적이고, 범위가 제한된 (scoped) 권한을 부여하는 것입니다. 오늘 바로 Apidog를 체험해 보세요. Bitwarden의 새로운 오픈 소스 프로젝트인 Agent Access는 자격 증명 공유 프로토콜, CLI (aac), 그리고 Rust + Python SDK를 통해 이 문제를 해결하고자 합니다. 이는 비밀번호 관리자와 소비자 프로세스(에이전트, CI 러너 또는 로컬 스크립트) 사이에 암호화된 터널을 생성합니다. 소비자는 금고 (vault) 전체에 접근하지 않고, 도메인 또는 금고 항목별 범위에 따라 필요한 비밀만을 전달받습니다. 이 가이드는 Agent Access를 설치하고, aac connect 및 aac run을 사용하며, Claude Code, Codex, Cursor와 통합하고, 'AI 에이전트로부터 API 자격 증명을 보호하는 방법'에 설명된 자격 증명 위생 (credential hygiene) 패턴을 적용하는 방법을 보여줍니다.

Agent Access란 무엇인가
Agent Access는 Bitwarden이 만든 개방형 프로토콜이자 레퍼런스 구현체이지만, 다른 비밀번호 관리자들도 채택할 수 있도록 설계되었습니다. 기본 흐름은 다음과 같습니다:

1. 제공자 (provider)가 연결 요청을 대기합니다.
2. 소비자 (consumer)가 제공자에 연결합니다.
3. 소비자가 도메인 또는 금고 항목 ID별로 자격 증명을 요청합니다.
4. 제공자가 무엇을 반환할지 결정합니다.
5. 소비자는 요청된 자격 증명만을 받습니다.

CLI aac는 Noise 프로토콜을 사용하여 종단 간 (end-to-end) 암호화 터널을 생성합니다. 소비자는 전체 금고를 볼 수 없습니다. 제공자는 소비자가 자격 증명을 어떻게 사용하는지 알 수 없습니다. 양측 모두 감사 추적 (audit trails)을 유지할 수 있습니다. 이 프로젝트는 아직 초기 프리뷰 (preview) 단계입니다.

README는 “API 및 프로토콜은 변경될 수 있음”을 경고하며, “민감한 자격 증명 (credentials)을 LLM 또는 AI 에이전트에 직접 입력하는 것을 권장하지 않음”을 명시하고 있습니다. 따라서 현재 가장 유용한 표준은 aac run을 사용하는 것입니다. 이는 값을 프롬프트 (prompt), 표준 출력 (stdout) 또는 디스크에 노출하지 않고, 서브프로세스 (subprocess)에 환경 변수 (environment variables)로서 비밀 값 (secrets)을 주입합니다.

이것이 중요한 이유
AI 코딩 에이전트는 이제 단순히 코드 제안에만 국한되지 않습니다. Claude Code, Codex, Cursor 및 유사한 도구들은 저장소 (repositories)를 읽고, 테스트를 실행하며, API를 호출하고, 배포 (deploys)를 트리거합니다. 각 단계마다 자격 증명이 필요할 수 있습니다. Postman의 API 키 노출 사고는 오직 인간만이 관여할 때 자격 증명 관리 (credential hygiene)가 어떻게 실패하는지를 보여주었습니다. 에이전트가 명령을 자동으로 실행하게 되면 위험은 더욱 커집니다. 해결책은 에이전트를 더 신뢰하는 것이 아닙니다. 에이전트에게 주는 권한을 줄이는 것입니다. Agent Access는 프로토콜 수준에서 이 원칙을 적용합니다: 범위가 지정된 자격 증명 (scoped credentials); 전송 중 암호화 (encryption in transit); 런타임 검색 (runtime lookup); 프로세스가 종료될 때 비밀 값 제거. 더 넓은 옵션의 개요를 보려면 API 키 관리 도구 (API Key Management Tools)도 참조하십시오.

설치
사용 중인 플랫폼에 맞는 바이너리 (binary)를 선택하십시오.

macOS Apple Silicon
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-aarch64.tar.gz | tar xz && sudo mv aac /usr/local/bin/

macOS Intel
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-x86_64.tar.gz | tar xz && sudo mv aac /usr/local/bin/

Linux x86_64
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-linux-x86_64.tar.gz | tar xz && sudo mv aac /usr/local/bin/

Windows x86_64
최신 버전 페이지에서 aac-windows-x86_64.zip을 다운로드하고 바이너리를 PATH에 포함된 디렉토리에 압축 해제하십시오.

그 후, 설치를 확인합니다:
aac --help

Bitwarden CLI (bw)가 PATH에 있는 경우, aac는 이를 기본 자격 증명 제공자 (credential provider)로 사용합니다.

Bitwarden 없이 테스트하려면 데모 제공자 (demonstration provider)를 사용하세요: aac --provider example --help

빠른 시작: 페어링 및 자격 증명 검색
금고 (vault)가 있는 머신(보통 노트북)에서 리스너 (listener)를 실행합니다: aac listen
명령어가 페어링 토큰 (pairing token)을 출력합니다. 다른 터미널, 원격 머신 또는 CI 러너 (runner)에서 해당 토큰을 사용하여 연결하고 도메인별로 자격 증명을 요청합니다: aac connect --token <pairing-token> --domain github.com --output json

응답 예시:

{ "credential" : { "notes" : null , "password" : "alligator5" , "totp" : null , "uri" : "https://github.com" , "username" : "example" }, "domain" : "github.com" , "success" : true }

금고 내 아이템 ID로 검색하려면 다음을 사용하세요:
aac connect --id <vault-item-id> --output json

--domain과 --id 중 하나만 사용해야 합니다. 두 방식은 상호 배타적 (mutually exclusive)입니다. 금고 아이템에 TOTP가 설정되어 있는 경우, JSON 페이로드 (payload)에 코드도 함께 반환됩니다.

환경 변수에 비밀 정보를 주입하려면 aac run을 사용하세요
aac connect는 스크립트가 JSON을 처리할 수 있을 때 유용합니다. AI 에이전트 (AI agents)의 경우, 가장 안전한 표준 방식은 aac run입니다. 이 방식은 자격 증명을 검색한 후, 비밀 정보를 환경 변수 (environment variables)로 주입하여 자식 프로세스 (child process)를 실행합니다. 값은 터미널에 출력되지 않고, 디스크에 기록되지 않으며, 에이전트의 트랜스크립션 (transcription)에도 나타나지 않습니다.

특정 필드 주입하기
aac run --domain example.com --env DB_PASSWORD=password --env DB_USER=username -- psql
이 예시에서: DB_PASSWORD는 password 필드를 받고, DB_USER는 username 필드를 받으며, psql은 서브프로세스 (subprocess)로 실행됩니다.

모든 필드 주입하기
aac run --domain example.com --env-all -- deploy.sh
--env-all을 사용하면 필드들이 AAC_ 접두사 (prefix)와 함께 주입됩니다.

--env-all과 사용자 정의 변수 조합하기
aac run --domain example.com --env-all --env CUSTOM_PW=password -- deploy.sh

사용 가능한 필드: username, password, totp, uri, notes, domain, credential_id. 이것이 에이전트와 함께 사용하기 위해 권장되는 표준 방식입니다.

모델은 aac run --domain api.stripe.com --env-all -- ./deploy.sh 명령어를 볼 수 있지만, 실제 키는 볼 수 없습니다. 만약 에이전트가 $STRIPE_API_KEY와 같은 변수 값을 요청하더라도, 비밀 값(secret)이 aac run에 의해 호출된 서브프로세스(subprocess)로 제한되었기 때문에 직접 접근할 수 없습니다. 이는 'AI 에이전트로부터 API 자격 증명을 보호하는 방법 (How to Protect API Credentials from AI Agents)'에서 설명된 격리 원칙이 구체적인 도구로 적용된 사례입니다.

Python 및 Rust용 SDK

CLI만으로 충분하지 않다면, 애플리케이션에 Agent Access를 직접 통합할 수 있습니다.

Python

from agent_access import RemoteClient

client = RemoteClient("python-remote")
client.connect(token="ABC-DEF-GHI")
cred = client.request_credential("example.com")
print(cred.username, cred.password)
client.close()

Python 모듈은 PyO3를 사용하여 핵심 구현을 Rust로 유지하며, Noise 프로토콜의 동일한 베이스를 재사용합니다.

Rust
Rust SDK는 RemoteClient 인터페이스를 퍼스트 클래스 라이브러리(first-class library)로 제공합니다. 참조 구현은 다음을 확인하세요: examples/rust-remote/.
다음과 같은 항목을 작성할 때 이 옵션을 사용하십시오: CLI, 빌드 러너(build runners), 컴파일된 바이너리가 필요한 서비스, 내부 도구에 내장된 자격 증명 소비자.

이미 비밀 관리 도구를 사용 중인 팀의 경우, Agent Access는 HashiCorp Vault 또는 Azure Key Vault와 같은 통합 환경과 공존할 수 있습니다. 이는 엔터프라이즈 수준의 이러한 금고(vaults)를 대체하는 것이 아니라, 개발자의 노트북, 로컬 스크립트 및 CI 러너(runners)에 유용합니다.

AI 코딩 에이전트와 통합하기

Claude Code
aac run 호출을 캡슐화하는 스크립트를 생성합니다. 배포 예시:

# deploy.sh
#!/usr/bin/env bash
aac run --domain prod.example.com --env-all -- ./run-deploy.sh

그 다음:

1. deploy.sh를 프로젝트에 추가합니다.
2. 실행 가능하도록 설정합니다.
3. Claude Code가 ./deploy.sh를 호출하도록 설정합니다.
4. 비밀 값은 프롬프트(prompt) 외부에 유지합니다.

chmod +x deploy.sh

Claude Code의 GitHub Actions 통합은 CI(지속적 통합)에서도 동일한 패턴을 사용할 수 있습니다: 러너(runner)에 aac를 설치하고, Bitwarden Vault 제공자와 페어링한 다음, 작업(job) 시점에 자격 증명(credentials)을 주입합니다.

OpenAI Codex
동일한 패턴이 Codex CLI에서도 작동합니다. 모델이 키를 직접 보도록 허용하는 대신, Codex가 스크립트를 호출하도록 만드세요:

# test-api.sh
#!/usr/bin/env bash
aac run --domain staging.example.com --env API_TOKEN = password -- ./run-api-tests.sh

Codex는 스크립트 호출만을 봅니다. 비밀 값은 자식 프로세스(child process) 내에 제한됩니다. 귀하의 전화기에 관한 Codex 게시물은 Codex의 더 넓은 표면을 다루지만, 여기에서의 초점은 명령 실행 중 자격 증명을 보호하는 것입니다.

Cursor
터미널 명령 및 Cursor의 Composer 흐름에서는 aac run으로 캡슐화된 동일한 스크립트를 사용하세요. Cursor는 일반적으로 로컬에서 실행되므로, 일반적인 흐름은 다음과 같습니다: 노트북에서 aac listen을 실행하고, deploy.sh, test-api.sh 또는 seed-db.sh와 같은 스크립트를 생성한 다음, Cursor가 이러한 스크립트를 호출하도록 하여 비밀 값을 모델의 컨텍스트(context) 외부에 유지하는 것입니다.

OpenClaw
Agent Access에는 즉시 사용할 수 있는 공식 OpenClaw 기능(skill)이 포함되어 있습니다. 해당 리포지토리에는 SKILL.md가 포함되어 있습니다. OpenClaw 생태계에서 기능(skill)을 사용하는 팀의 경우, 이는 더 직접적인 통합이 됩니다: 해당 기능이 프로토콜 형식을 알고, 자격 증명을 검색하여, 기능 자체에서 노출하는 다운스트림(downstream) 도구에 전달합니다. OpenClaw API 키 가이드도 참조하십시오.

실무적인 관점에서의 보안 모델
이 흐름을 채택하기 전에 다음 세 가지 속성을 확인하십시오:

1. Noise를 통한 종단간 암호화 (End-to-end encryption)
   소비자(consumer)와 제공자(provider) 사이의 트래픽은 WireGuard 및 Signal에서 사용하는 것과 동일한 핸드셰이크(handshake) 제품군인 Noise 프로토콜 프레임워크(Noise protocol framework)로 암호화됩니다.

2. 범위가 지정된 자격 증명 (Scoped credentials)
   소비자는 도메인 또는 Vault의 아이템 ID를 요청합니다. Vault 전체를 열거하지 않습니다.

3. 기본적으로 디스크에 비밀 값 저장 안 함
   aac run을 사용하면 비밀 값은 자식 프로세스로 환경 변수(environment variables)로서 전달됩니다.

.env 파일에 기록되지 않으며, stdout에 출력되지도 않고, 셸 히스토리(shell history)에도 남지 않습니다. Agent Access는 다음 상황을 방어하지는 못합니다: 악의적이거나 침해된 소비자 프로세스(consumer process), 침해된 금고(vault)/공급자(provider), 사용자가 LLM 프롬프트에 비밀 값을 직접 붙여넣는 경우. 주요 방어 전략은 노출된 자격 증명(credential)의 범위(scope)와 수명(lifetime)을 줄이는 것입니다.

CI 패턴: 에이전트가 작성하고, Apidog가 테스트함
에이전트와 API를 사용하는 팀을 위한 실용적인 워크플로우:

1. 에이전트가 코드를 변경합니다. Claude Code, Codex 또는 Cursor가 엔드포인트(endpoint)를 수정하는 PR을 엽니다.
2. CI가 스위트(suite)를 실행합니다. 러너(runner)는 aac run을 사용하여 범위가 제한된 API 키를 가져오고 스테이징(staging) 환경에 대해 테스트를 실행합니다.
3. Apidog가 계약(contract)을 검증합니다. Apidog는 CI의 별도 단계에서 마찬가지로 aac run을 통해 OpenAPI 계약 테스트를 실행합니다.

스크립트 예시:

#!/usr/bin/env bash
aac run \
  --domain staging.example.com \
  --env API_TOKEN=password \
  -- ./run-contract-tests.sh

결과: 에이전트가 코드를 전송하고, API 계약이 검증되며, 키가 프롬프트에 나타나지 않고, 자격 증명이 .env에 남지 않습니다.

에이전트 테스트 플레이북에 대해서는 'How to test AI agents that call your APIs'를 참조하세요.

제한 사항
프로덕션(production) 환경에서 사용하기 전에 다음을 고려하십시오:

• 초기 미리보기(Preview): API와 프로토콜이 변경될 수 있습니다. 향후 유지보수를 고려하지 않은 채 v0 프로토콜에 의존하는 것을 피하십시오.
• 기본적으로 Bitwarden CLI 필요: 기본 공급자는 bw입니다. Bitwarden CLI를 설치하거나 테스트를 위해 --provider example을 사용하십시오.
• 아직 설정 파일 미지원: 현재 사용 방식은 플래그(flags)를 기반으로 합니다. 반복되는 워크플로우의 경우 명령어를 스크립트로 캡슐화하십시오.
• LLM의 오용을 해결하지 못함: 자격 증명을 채팅창에 복사하는 경우, 어떤 프로토콜도 노출을 막을 수 없습니다.

자주 묻는 질문(FAQ)
Agent Access는 무료인가요?
네. CLI, SDK 및 프로토콜은 Bitwarden의 GitHub 조직에서 오픈 소스(open source)로 제공됩니다. 금고로 사용하는 경우 Bitwarden 비용은 계속 지불해야 합니다.

Bitwarden 이외의 비밀번호 관리자와도 작동하나요?
이 프로토콜은 공급자 중립적(vendor-neutral)이 되도록 설계되었습니다.

참조 구현 (reference implementation)에는 Bitwarden 지원과 예시 제공자 (example provider)가 포함되어 있습니다. 다른 제공자들도 자신만의 제공자를 만들 수 있습니다. 비밀번호 관리자 없이도 사용할 수 있나요? 테스트용으로는 가능합니다: aac connect --provider example --domain test.com --output json. 프로덕션 (production) 환경에서는 실제 제공자를 사용하십시오. 컨슈머 (consumer)에게 네트워크가 필요한가요? 네. 컨슈머는 제공자의 리스너 (listener)에 도달할 수 있어야 합니다. 리스너와 컨슈머가 동일한 호스트에서 실행될 때 로컬 흐름 (local flows)이 작동합니다. .env 파일과의 차이점은 무엇인가요? .env는 디스크에 저장되어 실수로 커밋될 수 있으며, 에이전트에 의해 실행되는 모든 명령에 의해 읽힐 수 있습니다. aac run을 사용하면 비밀값 (secret)은 자식 프로세스의 메모리에 머물며 프로세스가 종료되면 사라집니다. HashiCorp Vault나 AWS Secrets Manager를 대체하나요? 아닙니다. 엔터프라이즈 금고 (enterprise vaults)는 대규모 서비스 간 (service-to-service) 비밀값 관리에 여전히 더 적합합니다. Agent Access는 다음과 같은 사례에 더 적합합니다: 개발자 노트북, 로컬 스크립트, CI 러너 (runners), 실행이 필요한 AI 에이전트