DEV Community

Cover image for Bitwarden 에이전트 접근: AI 코딩 에이전트와 안전하게 볼트 자격 증명 공유하는 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Bitwarden 에이전트 접근: AI 코딩 에이전트와 안전하게 볼트 자격 증명 공유하는 방법

실제 API와 함께 Claude Code, Codex, Cursor 같은 코딩 에이전트를 사용하면 자격 증명 처리가 곧 문제가 됩니다. API 키를 채팅에 붙여넣으면 모델 컨텍스트에 남고, .env 파일에 넣으면 에이전트가 cat으로 읽어 다른 곳으로 보낼 수 있습니다. 목표는 에이전트를 더 신뢰하는 것이 아니라, 에이전트가 볼 수 있는 비밀의 범위를 줄이는 것입니다.

오늘 Apidog를 사용해 보세요

Bitwarden의 오픈 소스 프로젝트인 Agent Access는 이 문제를 해결하기 위한 자격 증명 공유 프로토콜이자 CLI(aac)입니다. 비밀번호 관리자와 원격 프로세스(에이전트, CI 러너, 스크립트) 사이에 암호화된 터널을 만들고, 소비자는 전체 저장소가 아니라 요청한 도메인 또는 저장소 항목의 자격 증명만 받습니다.

이 글에서는 Agent Access의 구조, 설치, aac connect, aac run, Claude Code/Codex/Cursor 통합 방식, 그리고 AI 에이전트 API 자격 증명을 보호하는 방법에서 다룬 자격 증명 위생 패턴과의 연결점을 구현 중심으로 정리합니다.

Agent Access란 무엇인가

Agent Access는 Bitwarden이 만든 오픈 프로토콜 및 참조 구현입니다. Bitwarden 전용으로 닫혀 있는 도구가 아니라, 다른 비밀번호 관리자도 제공자(provider)를 구현할 수 있도록 설계되었습니다.

구성은 단순합니다.

  • Provider: 비밀번호 관리자 또는 자격 증명 저장소 쪽 프로세스
  • Consumer: 에이전트, 스크립트, CI 작업 등 자격 증명을 요청하는 프로세스
  • aac CLI: 양쪽을 연결하고, 자격 증명을 요청하거나 환경 변수로 주입하는 도구
  • 암호화 터널: Noise 프로토콜 기반 종단간 암호화

Consumer는 github.com 같은 도메인 또는 저장소 항목 ID를 기준으로 자격 증명을 요청합니다. Provider는 반환할 항목을 결정합니다. Consumer는 전체 저장소를 열람하지 못하고, Provider는 Consumer가 받은 비밀을 이후 어떻게 사용하는지 보지 못합니다.

Agent Access 구조

현재 Agent Access는 초기 미리 보기 단계입니다. README는 API와 프로토콜이 변경될 수 있다고 명시하며, 민감한 자격 증명을 LLM 또는 AI 에이전트에 직접 입력하지 말라고 권장합니다. 실제 워크플로에서는 aac run으로 자식 프로세스에만 비밀을 주입하는 패턴을 사용해야 합니다.

왜 중요한가

AI 코딩 에이전트는 이제 저장소를 읽고, 테스트를 실행하고, API를 호출하고, 배포 스크립트를 실행합니다. 이 과정에서 API 키, 배포 토큰, 데이터베이스 비밀번호가 필요해집니다.

문제는 기존 방식이 에이전트 환경에 맞지 않는다는 점입니다.

방식 문제
채팅에 API 키 붙여넣기 모델 컨텍스트에 비밀이 노출됨
.env 파일 사용 에이전트가 파일을 읽거나 출력할 수 있음
셸 환경 변수에 수동 export 세션 범위가 넓고 추적이 어려움
CI Secret 직접 노출 작업 전체에서 비밀 접근 범위가 커짐

Postman API 키 노출 사건은 사람만 관련되어도 자격 증명 위생이 얼마나 쉽게 무너지는지 보여줍니다. 에이전트가 추가되면 위험은 더 커집니다.

Agent Access의 접근 방식은 다음과 같습니다.

  1. 자격 증명을 도메인 또는 저장소 항목 단위로 범위 지정
  2. 런타임에만 가져오기
  3. 전송 중 암호화
  4. 디스크에 저장하지 않기
  5. 자식 프로세스 종료 시 함께 사라지게 하기

일반적인 API 키 관리 도구가 넓은 범위의 키 관리를 다룬다면, Agent Access는 에이전트와 CI 러너가 비밀을 안전하게 소비하는 구간에 초점을 맞춥니다.

설치

플랫폼에 맞는 바이너리를 설치합니다.

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/
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

Windows x86_64

최신 릴리스 페이지에서 aac-windows-x86_64.zip을 다운로드한 뒤, PATH에 포함된 디렉터리에 압축을 해제합니다.

설치를 확인합니다.

aac --help
Enter fullscreen mode Exit fullscreen mode

Bitwarden CLI(bw)가 PATH에 있으면 aac는 기본 자격 증명 제공자로 Bitwarden을 사용합니다. 실험만 하려면 --provider example을 사용해 내장 데모 제공자를 실행할 수 있습니다.

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

먼저 자격 증명 저장소가 있는 컴퓨터에서 리스너를 실행합니다.

aac listen
Enter fullscreen mode Exit fullscreen mode

리스너는 페어링 토큰을 출력합니다.

다른 셸, 원격 컴퓨터, 또는 CI 러너에서 해당 토큰으로 연결합니다.

aac connect --token <pairing-token> --domain github.com --output json
Enter fullscreen mode Exit fullscreen mode

예상 응답은 다음과 같습니다.

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

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

도메인 대신 저장소 항목 ID로 요청하려면 --id를 사용합니다.

aac connect --id <vault-item-id> --output json
Enter fullscreen mode Exit fullscreen mode

주의할 점:

  • --domain과 --id는 동시에 사용할 수 없습니다.
  • 저장소 항목에 TOTP가 있으면 동일한 응답 페이로드에 포함됩니다.
  • JSON을 stdout으로 출력하므로, 로그에 남지 않도록 호출 위치를 조심해야 합니다.

핵심 패턴: aac run으로 환경 변수 주입하기

aac connect는 JSON을 직접 다룰 때 유용합니다. 하지만 AI 에이전트와 함께 쓸 때는 보통 aac run이 더 안전합니다.

aac run은 다음 순서로 동작합니다.

  1. Provider에서 자격 증명을 가져옵니다.
  2. 지정한 필드를 환경 변수로 매핑합니다.
  3. 자식 프로세스를 실행합니다.
  4. 비밀을 stdout이나 파일에 쓰지 않습니다.
  5. 자식 프로세스가 끝나면 비밀도 사라집니다.

특정 필드만 주입하기 

aac run \
  --domain example.com \
  --env DB_PASSWORD=password \
  --env DB_USER=username \
  -- psql
Enter fullscreen mode Exit fullscreen mode

위 명령은 저장소의 password 필드를 DB_PASSWORD로, username 필드를 DB_USER로 매핑한 뒤 psql을 실행합니다.

모든 필드를 AAC_ 접두사로 주입하기 

aac run --domain example.com --env-all -- ./deploy.sh
Enter fullscreen mode Exit fullscreen mode

예를 들어 다음과 같은 환경 변수가 자식 프로세스에 전달됩니다.

AAC_USERNAME
AAC_PASSWORD
AAC_TOTP
AAC_URI
AAC_NOTES
AAC_DOMAIN
AAC_CREDENTIAL_ID
Enter fullscreen mode Exit fullscreen mode

기본 매핑과 사용자 정의 매핑 함께 사용하기 

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

사용 가능한 필드는 다음과 같습니다.

  • username
  • password
  • totp
  • uri
  • notes
  • domain
  • credential_id

AI 에이전트에는 이 패턴이 가장 중요합니다. 에이전트는 실제 비밀 값이 아니라 다음과 같은 명령만 보게 됩니다.

aac run --domain api.stripe.com --env-all -- ./deploy.sh
Enter fullscreen mode Exit fullscreen mode

모델 컨텍스트에는 API 키가 들어가지 않습니다. 비밀은 ./deploy.sh 자식 프로세스 환경에만 존재합니다.

이 방식은 AI 에이전트 API 자격 증명을 보호하는 방법에서 다룬 “에이전트에는 최소한의 범위만 제공한다”는 원칙을 실제 명령어로 구현한 형태입니다.

Python 및 Rust SDK 사용

CLI만으로 부족한 경우 SDK를 사용할 수 있습니다. 예를 들어 자체 애플리케이션이나 내부 개발자 도구에 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()
Enter fullscreen mode Exit fullscreen mode

Python 모듈은 PyO3 기반입니다. 내부적으로는 Rust 구현과 동일한 Noise 프로토콜을 사용합니다.

실제 코드에서는 print()로 비밀번호를 출력하지 말고, 필요한 프로세스나 API 클라이언트 초기화에만 전달하세요.

Rust

Rust SDK는 RemoteClient 인터페이스를 라이브러리로 제공합니다. 참조 구현은 저장소의 examples/rust-remote/ 아래에 있습니다.

Rust 소비자는 다음과 같은 경우에 적합합니다.

  • 자체 CLI 도구
  • 빌드 러너
  • 배포용 단일 바이너리
  • 내부 자동화 서비스

이미 API 툴링을 운영하는 팀이라면 Agent Access SDK는 HashiCorp Vault 또는 Azure Key Vault 통합과 함께 사용할 수 있습니다. Agent Access가 엔터프라이즈 비밀 저장소를 대체하는 것은 아니지만, 개발자 노트북과 CI 러너에서 에이전트가 비밀을 소비하는 경로를 좁히는 데 적합합니다.

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

핵심은 에이전트가 직접 비밀을 읽게 하지 않고, 에이전트가 호출하는 스크립트 내부에서 aac run을 사용하는 것입니다.

Claude Code

배포 스크립트를 aac run으로 감쌉니다.

# deploy.sh
#!/usr/bin/env bash
set -euo pipefail

aac run \
  --domain prod.example.com \
  --env-all \
  -- ./run-deploy.sh
Enter fullscreen mode Exit fullscreen mode

실행 권한을 추가합니다.

chmod +x deploy.sh
Enter fullscreen mode Exit fullscreen mode

Claude Code에는 API 키나 배포 토큰을 제공하지 않습니다. 대신 다음 명령만 실행하게 합니다.

./deploy.sh
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 Claude Code는 배포 명령을 실행할 수 있지만, 실제 비밀 값은 모델 컨텍스트에 들어가지 않습니다.

Claude Code GitHub Actions 통합에서도 같은 방식으로 적용할 수 있습니다.

  1. GitHub Actions 러너에 aac 설치
  2. 제어 평면에서 실행되는 Provider와 페어링
  3. 테스트 또는 배포 단계에서 aac run 사용
  4. 작업 단위로 범위가 지정된 자격 증명만 주입

OpenAI Codex

Codex CLI에서도 동일한 패턴을 사용합니다. 모델이 직접 비밀을 다루지 않고, 모델이 실행하는 스크립트가 aac run을 통해 자격 증명을 받게 합니다.

예시:

# test-api.sh
#!/usr/bin/env bash
set -euo pipefail

aac run \
  --domain staging.example.com \
  --env API_TOKEN=password \
  -- npm run test:api
Enter fullscreen mode Exit fullscreen mode

Codex에는 다음 명령만 허용합니다.

./test-api.sh
Enter fullscreen mode Exit fullscreen mode

휴대폰으로 Codex 사용하기에서 다룬 Codex 사용 범위가 넓어질수록, 이런 방식의 자격 증명 격리가 더 중요해집니다.

Cursor

Cursor의 터미널 명령이나 Composer 워크플로에서도 동일합니다.

# local-check.sh
#!/usr/bin/env bash
set -euo pipefail

aac run \
  --domain dev.example.com \
  --env-all \
  -- npm run test
Enter fullscreen mode Exit fullscreen mode

Cursor는 로컬 편집에 강하므로, 리스너와 소비자가 같은 머신에서 실행되는 구성이 흔합니다.

aac listen
Enter fullscreen mode Exit fullscreen mode

다른 터미널에서 Cursor가 호출할 스크립트를 실행합니다.

./local-check.sh
Enter fullscreen mode Exit fullscreen mode

OpenClaw

Agent Access는 공식 OpenClaw 스킬도 제공합니다. SKILL.md 파일은 Agent Access 저장소에 포함되어 있습니다.

OpenClaw 스타일 스킬을 사용하는 팀이라면 이 통합이 가장 직접적입니다. 스킬이 프로토콜 형태를 알고, 자격 증명을 가져와서 필요한 다운스트림 도구에 전달합니다.

관련 생태계의 자격 증명 관리 흐름은 OpenClaw API 키 가이드에서 더 자세히 다룹니다.

보안 모델 정리

Agent Access의 보안 모델은 세 가지로 요약할 수 있습니다.

1. Noise 기반 종단간 암호화

Consumer와 Provider 사이의 트래픽은 Noise 프로토콜 프레임워크로 암호화됩니다. Noise는 WireGuard와 Signal이 사용하는 핸드셰이크 계열입니다.

2. 범위가 지정된 자격 증명

Consumer는 요청한 도메인 또는 저장소 항목 ID에 해당하는 자격 증명만 받습니다.

가능한 것:

aac connect --domain github.com --output json
Enter fullscreen mode Exit fullscreen mode

불가능해야 하는 것:

# 전체 저장소 열거
# 모든 항목 조회
# 무관한 도메인 자격 증명 접근
Enter fullscreen mode Exit fullscreen mode

3. 기본적으로 Consumer 디스크에 비밀을 쓰지 않음

aac run은 비밀을 자식 프로세스 환경 변수로 전달합니다.

비밀이 남지 않는 곳:

  • 파일
  • stdout
  • 셸 히스토리
  • 에이전트 프롬프트
  • LLM 컨텍스트

단, 환경 변수는 자식 프로세스 안에서는 접근 가능합니다. 따라서 자식 프로세스 자체가 신뢰 가능한지 확인해야 합니다.

Agent Access가 막아주지 못하는 것

Agent Access는 모든 문제를 해결하지 않습니다.

손상된 Consumer 프로세스

에이전트나 스크립트가 악의적이거나 손상되었다면, 범위가 지정된 자격 증명도 유출될 수 있습니다. 이 경우 방어선은 프로토콜이 아니라 자격 증명의 범위 축소입니다.

예를 들어 프로덕션 전체 관리자 키가 아니라, 특정 스테이징 API 테스트에만 필요한 키를 사용해야 합니다.

손상된 Provider

Bitwarden 저장소 자체가 손상되면 Agent Access 계층은 보호 수단이 되지 않습니다. 저장소 접근 제어, MFA, 조직 정책은 별도로 관리해야 합니다.

LLM 컨텍스트에 직접 붙여넣은 비밀

README는 민감한 자격 증명을 LLM 또는 AI 에이전트에 직접 입력하지 말라고 명확히 경고합니다.

잘못된 예:

이 API 키를 사용해서 배포해줘: sk_live_xxx...
Enter fullscreen mode Exit fullscreen mode

권장 예:

aac run --domain api.example.com --env-all -- ./deploy.sh
Enter fullscreen mode Exit fullscreen mode

일반적인 워크플로: 에이전트가 코드 작성, Apidog가 계약 테스트

많은 팀은 다음 흐름으로 정착하게 됩니다.

  1. 에이전트가 코드를 작성합니다.

    Claude Code, Codex 또는 Cursor가 엔드포인트 변경 PR을 만듭니다.

  2. CI가 테스트를 실행합니다.

    CI 러너는 aac run으로 API 키를 가져오고, 스테이징 환경에 대해 테스트를 실행합니다.

  3. Apidog가 계약을 검증합니다.

    Apidog는 별도 CI 단계에서 OpenAPI 계약 테스트를 실행합니다. 이때도 자격 증명은 aac run을 통해 주입할 수 있습니다.

예시 CI 단계는 다음과 같은 형태가 됩니다.

aac run \
  --domain staging.example.com \
  --env API_TOKEN=password \
  -- npm run test:contract
Enter fullscreen mode Exit fullscreen mode

결과적으로 역할이 분리됩니다.

  • 에이전트: 코드 생성 및 수정
  • CI: 테스트 실행
  • Agent Access: 자격 증명 주입
  • Apidog: API 계약 검증
  • 비밀번호 관리자: 비밀 보관

AI 기반 변경 사항을 테스트하는 더 넓은 플레이북은 API를 호출하는 AI 에이전트를 테스트하는 방법에서 확인할 수 있습니다.

제한 사항 및 경고

현재 적용 전에 확인해야 할 제약은 다음과 같습니다.

  • 초기 미리 보기입니다.

    API와 프로토콜은 변경될 수 있습니다. 프로덕션 워크플로를 v0 프로토콜에 강하게 고정하지 마세요.

  • 기본 Provider는 Bitwarden CLI입니다.

    기본 사용에는 bw가 필요합니다. 먼저 Bitwarden CLI를 설치하세요.

  • 테스트에는 데모 Provider를 사용할 수 있습니다.

    실험 중에는 --provider example을 전달할 수 있습니다.

  • 아직 설정 파일 중심 도구가 아닙니다.

    현재는 플래그 기반 호출이 중심입니다. 반복 호출은 셸 스크립트로 감싸는 편이 좋습니다.

  • LLM 프롬프트에 비밀을 붙여넣지 마세요.

    Agent Access를 설치했더라도 채팅 창에 API 키를 복사하면 보호할 수 없습니다.

자주 묻는 질문

Agent Access는 무료인가요?

네. CLI, SDK, 프로토콜은 Bitwarden GitHub 조직에서 오픈 소스로 제공됩니다. 단, Bitwarden을 저장소로 사용하는 경우 Bitwarden 사용 비용은 별도로 적용됩니다.

Bitwarden 외 다른 비밀번호 관리자와도 작동하나요?

프로토콜은 벤더 중립적으로 설계되었습니다. 현재 참조 구현은 Bitwarden 지원과 예시 Provider를 포함합니다. 다른 벤더가 자체 Provider를 구현할 수 있습니다.

비밀번호 관리자 없이 사용할 수 있나요?

테스트 목적이라면 가능합니다.

aac connect --provider example --domain test.com --output json
Enter fullscreen mode Exit fullscreen mode

프로덕션에서는 실제 Provider가 필요합니다. 현재 기본 경로는 Bitwarden입니다.

Consumer 프로세스에 네트워크 액세스가 필요한가요?

Consumer는 Provider 리스너에 도달해야 하므로 네트워크 접근이 필요합니다. 리스너와 Consumer가 같은 호스트에 있으면 로컬 전용 구성도 가능합니다.

.env 파일과 어떻게 다른가요?

.env 파일은 디스크에 저장됩니다. 실수로 저장소에 커밋될 수 있고, 에이전트가 읽을 수도 있습니다.

aac run은 비밀을 자식 프로세스 환경에만 전달합니다. 파일에 쓰지 않고, 프로세스 종료 후 사라집니다.

HashiCorp Vault 또는 AWS Secrets Manager를 대체하나요?

아니요. 엔터프라이즈 비밀 저장소는 대규모 서비스 간 비밀 관리에 적합합니다. Agent Access는 개발자 노트북, 에이전트, CI 러너가 비밀을 안전하게 소비하는 흐름에 초점을 맞춥니다.

Anthropic, OpenAI 또는 다른 에이전트 벤더가 직접 통합할 예정인가요?

아직 발표된 내용은 없습니다. 현재 가장 실용적인 통합 방식은 에이전트가 호출하는 스크립트를 aac run으로 감싸는 것입니다.

버그를 보고하거나 기여하려면 어떻게 해야 하나요?

GitHub 저장소에서 이슈, PR, 프로토콜 논의를 진행할 수 있습니다.

직접 테스트해 보기

가장 작은 종단간 루프는 다음과 같습니다.

먼저 리스너를 실행합니다.

aac listen
Enter fullscreen mode Exit fullscreen mode

다른 터미널에서 데모 Provider로 요청합니다.

aac connect \
  --provider example \
  --domain test.com \
  --output json
Enter fullscreen mode Exit fullscreen mode

JSON이 반환되면 기본 흐름이 동작하는 것입니다.

다음 단계는 다음 순서로 진행하세요.

  1. 데모 Provider 대신 Bitwarden CLI(bw)를 연결합니다.
  2. 실제 도메인 또는 저장소 항목 ID로 자격 증명을 요청합니다.
  3. aac connect 출력이 로그에 남지 않도록 합니다.
  4. 배포, 테스트, API 호출 스크립트를 aac run으로 감쌉니다.
  5. Claude Code, Codex, Cursor에는 비밀이 아닌 스크립트 실행 권한만 제공합니다.

API 테스트 워크플로에서는 Agent Access를 Apidog와 함께 사용하면 역할을 깔끔하게 분리할 수 있습니다. 비밀번호 관리자는 비밀을 보관하고, Agent Access는 런타임에만 주입하며, Apidog는 계약을 테스트하고, 에이전트는 비밀을 보지 않은 상태로 코드를 수정합니다.

Top comments (0)