Bitwarden 에이전트에 대한 안전한 액세스: 코딩 AI와 자격 증명 공유하기

Claude Code, Codex 또는 Cursor를 실제 API를 사용하는 워크플로우와 함께 사용할 경우, 에이전트(agent)에는 자격 증명(credentials)이 필요합니다. 여기서 문제가 발생합니다. 사용자의 비밀번호 관리자(password manager)는 이를 잠금 상태로 유지하려 하지만, 에이전트는 이를 실행해야 합니다. 채팅창에 API 키를 붙여넣으면 모델의 컨텍스트(context) 안에 남게 됩니다. .env 파일에 저장하면 에이전트에 의해 실행되는 모든 명령어가 이를 읽거나, 출력하거나, 외부로 전송할 수 있게 됩니다. 실질적인 해결책은 모델에 비밀(secret)을 노출하지 않으면서, 최소한의 범위 내에서 일시적인 액세스 권한을 부여하는 것입니다. 오늘 Apidog를 테스트해 보세요. Bitwarden의 오픈 소스 프로젝트인 Agent Access는 이를 해결하기 위한 더 안전한 방법을 제안합니다. 이 프로젝트는 자격 증명을 공유하기 위한 프로토콜, CLI (aac), 그리고 Rust 및 Python SDK를 포함합니다. 이 프로젝트의 목표는 자격 증명 제공자(credential provider)—예를 들어 Bitwarden—와 원격 소비자(consumer): 에이전트, 스크립트, CI 러너(runner) 또는 내부 도구 사이에 암호화된 터널을 생성하는 것입니다. 이 가이드에서는 Agent Access를 설치하는 방법, aac connect 및 aac run을 사용하는 방법, 그리고 Claude Code, Codex, Cursor 및 API 테스트 워크플로우에 적용하는 방법을 살펴보게 됩니다. 또한 'AI 에이전트의 API 자격 증명을 확보하는 방법'에서 설명된 위생 수칙(hygiene practices)을 보완합니다.

Agent Access란 무엇인가
Agent Access는 Bitwarden이 만든 개방형 프로토콜이자 참조 구현(reference implementation)입니다. CLI인 aac는 Noise 프로토콜을 사용하여 종단 간(end-to-end) 암호화 터널을 설정합니다. 모델은 두 부분으로 구성됩니다:

제공자(Provider): 금고(vault) 또는 자격 증명 소스에 접근할 수 있는 프로세스.
소비자(Consumer): 자격 증명을 요청하는 에이전트, 스크립트, CI 러너 또는 원격 프로세스.

소비자는 금고 전체에 대한 접근 권한을 얻지 않습니다. 오직 다음을 통해서만 자격 증명을 요청할 수 있습니다:

• 도메인 (예: github.com)
• 금고 항목 ID (vault item ID)

제공자는 무엇을 전달할지 결정합니다. 소비자는 허용된 자격 증명만을 수신합니다. Agent Access는 현재 초기 프리뷰(early preview) 단계에 있습니다.

README는 API와 프로토콜이 변경될 수 있으며, 민감한 자격 증명 (credentials)을 LLM이나 AI 에이전트에 직접 입력하는 것은 권장되지 않는다고 경고합니다. 권장되는 패턴은 aac run을 사용하는 것입니다. 이는 모델에 노출하거나 디스크에 기록하지 않고, 서브프로세스 (subprocess)의 환경 변수 (environment variables)로 비밀 값 (secrets)을 주입합니다.

AI 에이전트에게 중요한 이유
코딩 에이전트는 이제 단순히 코드만을 제안하지 않습니다. 이제 에이전트는 다음과 같은 작업을 수행할 수 있습니다:

• 저장소 (repositories) 읽기
• 테스트 실행
• API 호출
• 풀 리퀘스트 (pull requests) 생성
• 서비스 배포
• CI/CD와 상호작용

이러한 각 작업은 대개 자격 증명을 필요로 합니다. Postman의 API 키 노출 사고는 인간만이 개입할 때조차 비밀 값 관리 (secret hygiene)를 유지하는 것이 얼마나 어려운지를 보여주었습니다. 에이전트가 개입하면 위험은 더욱 커집니다. 해결책은 에이전트를 더 신뢰하는 것이 아니라, 에이전트에게 더 적은 권한을 부여하는 것입니다. Agent Access는 이 원칙을 적용합니다:

• 제한된 범위의 자격 증명
• 전송 중 암호화 (encryption in transit)
• 기본적으로 디스크에 저장하지 않는 런타임 (runtime) 시점의 획득
• 프로세스가 살아있는 동안에만 자격 증명 사용 가능

다른 API 키 관리 도구들과 비교했을 때, Agent Access는 에이전트 및 자동화된 프로세스라는 특정 사례에 집중합니다.

설치
사용자의 플랫폼에 맞는 바이너리를 선택하십시오.

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
릴리스 (releases) 페이지에서 aac-windows-x86_64.zip을 다운로드하고 실행 파일을 PATH에 포함된 디렉토리에 압축 해제하십시오.

설치 확인:
aac --help

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

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

빠른 시작: 페어링 및 자격 증명 가져오기

보관함 (vault)에 접근할 수 있는 머신(보통 노트북)에서 리스너 (listener)를 실행합니다: aac listen

명령어를 실행하면 페어링 토큰 (pairing token)이 출력됩니다. 소비자 (consumer) —다른 터미널, 원격 호스트 또는 러너 (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 }

스크립트에서 이 JSON을 파싱하여 필요한 필드를 사용할 수 있습니다.

또한 보관함 아이템 ID (vault item ID)로 자격 증명을 요청할 수도 있습니다: aac connect --id <vault-item-id> --output json

--id와 --domain은 상호 배타적입니다. 둘 중 하나만 사용하세요. 보관함 아이템에 TOTP가 설정되어 있다면, 코드가 동일한 페이로드 (payload) 내에 반환됩니다.

권장 패턴: aac run

aac connect는 스크립트가 JSON을 처리할 수 있을 때 유용합니다. AI 에이전트 (AI agents)의 경우, 가장 안전한 패턴은 보통 aac run입니다. aac run은 자격 증명을 가져온 뒤, 비밀 정보 (secrets)를 환경 변수 (environment variables)로 주입하여 자식 프로세스 (child process)를 실행합니다. 이는 비밀 정보를 stdout에 출력하지 않고, 디스크에 쓰지 않으며, 에이전트의 프롬프트 (prompt)에 직접 노출하지도 않습니다.

특정 필드 주입하기:
aac run --domain example.com \ --env DB_PASSWORD = password \ --env DB_USER = username \ -- psql

이 예시에서:

• DB_PASSWORD는 password 필드를 받습니다.
• DB_USER는 username 필드를 받습니다.
• psql은 자식 프로세스로 실행됩니다.

모든 필드 주입하기:
aac run --domain example.com --env-all -- ./deploy.sh

--env-all을 사용하면, 필드들이 AAC_ 접두사와 함께 노출됩니다.

--env-all을 사용자 정의 변수와 결합하기

aac run --domain example.com \ --env-all \ --env CUSTOM_PW=password \ -- ./deploy.sh

사용 가능한 필드: username, password, totp, uri, notes, domain, credential_id

예시: 배포를 래핑(wrap)하기

다음과 같은 스크립트가 있다고 가정해 봅시다:

# run-deploy.sh
#!/usr/bin/env bash
curl -H "Authorization: Bearer $AAC_PASSWORD" \
https://api.example.com/deploy

이 스크립트를 에이전트에서 직접 실행하지 마세요. 대신 다음과 같이 래핑하십시오:

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

그 다음 에이전트에게 다음을 실행하도록 지시합니다:

./deploy.sh

모델은 명령어를 볼 수 있지만, $AAC_PASSWORD의 값은 볼 수 없습니다. 만약 에이전트가 서브프로세스(subprocess) 외부에서 해당 변수를 출력하려고 시도하더라도, 이에 접근할 수 없습니다. 비밀 값(secret)은 오직 aac run에 의해 실행된 자식 프로세스(child process)의 환경에만 존재합니다. 이는 'AI 에이전트의 API 자격 증명을 안전하게 보호하는 방법'에서 설명된 격리(isolation) 원칙을 구체적인 도구에 적용한 것과 동일합니다.

Python 및 Rust SDK

CLI 호출만으로 충분하지 않은 경우, Agent Access는 SDK도 제공합니다.

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에 의해 지원되므로, 저수준(low-level) 구현은 Rust로 유지됩니다. Python 애플리케이션이나 자체 도구 내에 Agent Access를 통합하고자 할 때 사용하십시오.

Rust

Rust SDK는 RemoteClient 인터페이스를 퍼스트 클래스 라이브러리(first-class library)로 노출합니다. 참조 구현체는 examples/rust-remote/에서 확인할 수 있습니다.

다음과 같은 경우에 사용하기 적합합니다:

• 내부 CLI
• 빌드 러너(build runners)
• 배포 도구
• 컴파일된 바이너리를 배포하는 서비스

이미 엔터프라이즈 관리 도구를 사용하는 팀의 경우, Agent Access는 HashiCorp Vault 또는 Azure Key Vault와 같은 통합 환경과 공존할 수 있습니다.

모든 시나리오에서 이들을 대체하는 것은 아니지만, 개발자 노트북, 로컬 스크립트 및 CI 러너 (runners)의 사례를 잘 커버합니다.

Claude Code와의 통합
Claude Code의 경우, aac run을 캡슐화하는 스크립트를 생성하십시오. 예시:

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

그 다음 Claude Code가 ./deploy.sh를 실행하도록 워크플로 (workflow)를 구성하십시오. 에이전트 (agent)가 스크립트를 호출하지만, 프롬프트 (prompt) 내에서 자격 증명 (credential)을 받지는 않습니다. 동일한 패턴을 CI로 확장할 수 있습니다. Claude Code GitHub Actions와 같은 흐름에서는 러너 (runner)가 aac를 설치하고, Vault 제공자와 페어링(pairing)하며, 작업 (job) 동안 제한된 범위의 자격 증명을 가져옵니다.

OpenAI Codex
Codex의 경우에도 동일한 접근 방식을 사용하십시오: 모델은 비밀 값 (secrets)이 아닌 스크립트를 호출합니다.

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

도구 계층 (tool layer)은 모델에 명령어를 보여주지만, API_TOKEN 값은 모델의 컨텍스트 (context) 밖에 머뭅니다. 휴대폰을 통한 Codex 게시가 Codex의 일반적인 표면을 다룬다면, 이 패턴은 자격 증명 관리에 초점을 맞춥니다.

Cursor
Cursor에서는 터미널 명령어와 Composer 흐름에 동일한 설계를 적용하십시오. 예시:

# local-contract-test.sh
#!/usr/bin/env bash
aac run --domain api.local.example.com \
--env-all \
-- npm run test :contract

Cursor는 대개 로컬 머신에서 실행되므로, 리스너 (listener)와 소비자 (consumer)가 동일한 호스트 (host)에 있을 수 있습니다.

OpenClaw
Agent Access는 즉시 사용 가능한 OpenClaw의 공식 스킬 (skill)을 포함하고 있습니다. 해당 리포지토리 (repository)에는 SKILL.md가 포함되어 있습니다. OpenClaw 스타일의 스킬을 사용하는 팀의 경우, 이 통합을 통해 스킬이 프로토콜을 인지하고, 자격 증명을 요청하며, 전체 Vault를 노출하지 않고도 하위 도구에 자격 증명을 전달할 수 있습니다. OpenClaw의 API 키 가이드는 해당 생태계 내의 더 넓은 자격 증명 컨텍스트를 다룹니다.

보안 모델
Agent Access는 세 가지 주요 개념에 기반합니다. 1.

1. 종단간 암호화 (End-to-end encryption): 소비자(Consumer)와 제공자(Provider) 사이의 트래픽은 WireGuard 및 Signal과 같은 시스템에서 사용되는 핸드셰이크(Handshake) 제품군인 Noise 프로토콜 프레임워크를 사용합니다.

2. 범위가 제한된 자격 증명 (Scoped credentials): 소비자는 도메인 또는 항목 ID(Element ID)별로 자격 증명을 요청합니다. 전체 금고(Vault)를 열람할 수는 없습니다. 예시: aac connect --domain github.com --output json. 이 호출은 다른 도메인의 자격 증명에 대한 액세스를 허용해서는 안 됩니다.

3. 기본적으로 디스크에 비밀 정보 저장 안 함 (No secrets on disk by default): aac run을 사용하면 비밀 정보(Secrets)가 자식 프로세스(Child process)로 환경 변수(Environment variables)로서 전달됩니다. 다음 항목에는 자동으로 기록되지 않습니다:

• .env 파일
• 로그(Logs)
• 셸 히스토리(Shell history)
• 표준 출력(Standard output)

Agent Access가 해결하지 못하는 문제
Agent Access는 노출을 줄이지만 모든 위험을 제거하지는 않습니다. 다음 상황에 대해서는 보호하지 못합니다:

• 침해된 소비자 (A compromised consumer): 자격 증명을 받는 프로세스가 악의적이라면 정보를 유출할 수 있습니다.
• 침해된 제공자 (A compromised provider): 사용자의 금고가 침해된 경우, Agent Access는 이를 수정할 수 없습니다.
• 프롬프트에 수동으로 붙여넣은 비밀 정보 (Secrets manually pasted into prompts): API 키를 채팅창에 복사하면 프로토콜이 더 이상 개입할 수 없습니다.
  주된 방어책은 범위(Scope)입니다. 에이전트에게는 최소한의 자격 증명만을, 가능한 최소한의 시간 동안만 제공하십시오.

일반적인 패턴: 에이전트 + CI + Apidog
AI 에이전트와 API를 사용하는 팀을 위한 실질적인 워크플로우는 다음과 같습니다:

1. 에이전트가 코드를 수정합니다: Claude Code, Codex 또는 Cursor가 엔드포인트(Endpoint)를 편집합니다.
2. 에이전트가 PR(Pull Request)을 생성합니다.
3. CI가 테스트를 실행합니다: 러너(Runner)가 aac run을 호출합니다. API 키는 테스트 프로세스에만 주입됩니다.
4. Apidog가 계약(Contract)을 검증합니다: Apidog는 별도의 단계로 OpenAPI 계약 테스트를 실행합니다. 이 또한 aac run 뒤에서 실행될 수 있습니다. 예시: aac run --domain staging-api.example.com --env API_TOKEN=password -- npm run test :contract

결과:

• 에이전트가 코드를 생성합니다.
• CI가 변경 사항을 검증합니다.
• Apidog가 계약을 확인합니다.
• 자격 증명이 모델의 컨텍스트(Context)에 들어가지 않습니다.

에이전트에 의해 생성된 변경 사항의 테스트에 대해 더 자세히 알고 싶다면, 'How to test AI agents that call their own APIs'를 참조하십시오.

현재의 한계점
실제 운영 환경(production)에서 사용하기 전에 다음 경고 사항을 유의하십시오.

조기 프리뷰 (Early Preview): API 및 프로토콜이 변경될 수 있습니다.
기본 Bitwarden 제공자 (Provider): 실제 통합을 사용하려면 먼저 Bitwarden CLI를 설치하십시오.
테스트용 데모 제공자: --provider example은 실험용이며, 운영 환경용이 아닙니다.
안정적인 설정 파일 부재: 현재는 주로 플래그(flags)를 사용하여 작업하므로, 반복되는 명령은 스크립트로 감싸는 것이 좋습니다.
수동 오류 방지 불가: 프롬프트(prompts)에 비밀 정보를 직접 붙여넣는 경우, Agent Access가 이를 보호할 수 없습니다.

구현 체크리스트
안전하게 시작하려면 다음 목록을 사용하십시오:

1. aac 설치
2. 작동 여부 확인: aac --help
3. 예시 제공자 테스트: aac listen
4. 다른 터미널에서 연결: aac connect --provider example --domain test.com --output json
5. 예시 제공자를 Bitwarden (bw)으로 교체
6. aac run을 캡슐화하는 작은 스크립트 작성
7. 에이전트 설정