Infisical/agent-vault 딥다이브
— 에이전트에게 API 키를 주지 않는 법

1프로젝트 한줄 요약

Agent Vault가 노리는 지점이 정확히 여기다. 프롬프트 인젝션을 막으려고 하는 게 아니라 — 그건 근본적으로 어렵다 — 인젝션이 성공하더라도 훔쳐 갈 물건 자체를 그 방에 두지 않는 쪽으로 문제를 우회한다. 에이전트가 속아서 환경변수를 통째로 출력해도, 나오는 건 __anthropic_api_key__라는 무의미한 문자열이다.

2왜 주목받는가

"시크릿 관리 도구는 이미 널렸는데 왜 또?"가 당연한 첫 반응이다. 답은 기존 도구들이 전부 "시크릿을 돌려주는(return)" 모델이라는 데 있다. 애플리케이션이 볼트에 물어보면 볼트가 값을 준다. 그 순간부터 값은 애플리케이션 손에 있고, 애플리케이션이 LLM 에이전트라면 그 값은 프롬프트 인젝션 사거리 안에 들어온다.

2-1. 대안들과의 정면 비교

2-2. 침습성이 거의 없다

실무에서 이게 채택률을 가른다. Agent Vault를 붙이는 데 에이전트 코드를 한 줄도 고칠 필요가 없다. HTTPS_PROXY 환경변수는 30년 된 표준이라 curl, Python requests, Node fetch, Go http.Client가 전부 알아서 존중한다. 그래서 Claude Code, Codex, Cursor, opencode, Hermes, OpenClaw, nanoclaw 각각에 대한 quickstart 문서가 존재하는데, 내용은 사실상 전부 "환경변수 두 개 꽂으세요"다.

2-3. 그냥 "보안 도구"가 아니라 완성형 제품

단순 프록시를 넘어서 실제 팀이 쓸 만한 살이 붙어 있다는 점이 트렌딩에 오른 이유다.

만든 곳이 Infisical이라는 점도 신뢰에 기여한다. 이미 오픈소스 시크릿 매니저로 자리 잡은 회사라, "에이전트 시대용 두 번째 제품"이라는 맥락이 자연스럽다. 릴리스는 goreleaser로 자동화돼 있고 GitHub Actions build provenance attestation과 cosign 서명까지 붙는다 — 공급망 보안을 신경 쓰는 팀이라는 신호다.

3기술 스택 전체 지도

3-1. 백엔드 (Go 1.25 / 빌드 이미지 golang:1.26.4-alpine)

3-2. 프론트엔드 (web/)

React 19.2 + @tanstack/react-router SPA, 빌드는 Vite 8, 스타일은 Tailwind CSS 4, 언어는 TypeScript 6. 여기서 흥미로운 건 배포 방식이다 — 빌드 산출물(web/dist)이 Go 바이너리 안에 임베드(internal/server/webdist)된다. 즉 관리 UI를 서빙하는 별도 웹서버가 없다. Go 바이너리 하나가 API도 프록시도 UI도 전부 처리한다.

3-3. 인프라 / 배포

4아키텍처 심화 분석

이 장이 이 문서의 심장이다. HTTPS 요청 하나가 에이전트 프로세스에서 출발해 진짜 API 서버에 도착할 때까지, Agent Vault 내부에서 벌어지는 13단계를 따라간다. 세 지점에 주목하자 — 세션 인증(누구냐), 자격증명 주입(진짜 키 갈아 끼우기), 감사 로그(무슨 일이 있었나).

4-1. 핵심 설계 패턴 ① — 키가 절대 새지 않는 메커니즘

이 구조가 성립하려면 진짜 키가 흘러갈 수 있는 모든 경로를 막아야 한다. 코드는 그걸 여러 겹으로 처리한다.

• 진짜 키는 forwardRequest 안, 서버 프로세스 메모리에서만 잠깐 존재하고 요청이 나가면 사라진다.
• 주입 헤더를 담는 InjectResult.Headers에는 코드 주석으로 "SECRET 값 — 절대 로그 금지"가 박혀 있다.
• 에이전트 토큰(Proxy-Authorization)은 브로커 전용 헤더로 분류돼 업스트림으로 절대 전달되지 않는다 — 에이전트 토큰과 진짜 API 키는 완전히 분리된 두 신뢰 도메인이다.
• 세션 토큰은 crypto/rand 256비트로 만들고 SHA-256 해시만 DB에 저장. 원본은 발급 시 딱 한 번만 노출된다.

4-2. 핵심 설계 패턴 ② — MITM TLS를 어떻게 처리하나

가장 기술적으로 까다로운 부분이다. HTTPS를 중간에서 들여다보려면 TLS를 한 번 끊어야 하는데, 그러려면 api.anthropic.com인 척하는 인증서가 필요하다. Agent Vault는 이걸 즉석에서 만든다.

에이전트 쪽에서 이 루트 CA를 신뢰하게 만드는 것도 세심하다. 언어 런타임마다 CA 인증서를 찾는 환경변수가 제각각이라, Agent Vault는 SSL_CERT_FILE·NODE_EXTRA_CA_CERTS·REQUESTS_CA_BUNDLE·CURL_CA_BUNDLE·GIT_SSL_CAINFO·DENO_CERT를 한꺼번에 세팅해준다. 이건 몰래 하는 공격이 아니라, 양쪽이 합의한 의도적 MITM이라는 점이 핵심이다.

4-3. 핵심 설계 패턴 ③ — 서비스 매칭 스코어링

요청이 들어오면 "이 호스트/경로에 어떤 자격증명을 붙일까"를 정해야 한다. 규칙이 여러 개 겹칠 수 있으니(*.github.com vs api.github.com), 가장 구체적인 규칙이 이기도록 점수를 매긴다. nginx의 location 매칭과 똑같은 종류의 문제다.

Auth 타입은 5종이다 — bearer(Authorization: Bearer), basic(Basic 인증), api-key(임의 헤더), custom({{ KEY }} 플레이스홀더), passthrough(자격증명 주입 없이 호스트 allowlist·TLS 가로채기·감사로그만). 특히 치환(Substitution)은 헤더뿐 아니라 URL 경로·쿼리·바디·웹소켓 프레임까지 스캔할 수 있는데, 이건 In 필드로 스코프를 명시해야만 켜지는 opt-in 보안 경계다.

4-4. 나머지 방어층들

5디렉토리 구조 해부

6학습 포인트

6-1. 실제 코드 발췌

서비스 정의 (YAML)

services:
  - name: api-anthropic-com
    host: api.anthropic.com
    auth:
      type: api-key
      key: ANTHROPIC_KEY
      header: x-api-key

CLI 사용 흐름

# 서비스 규칙을 vault에 등록
agent-vault vault service set -f stripe-services.yaml --vault my-vault

# 에이전트를 프록시 아래에서 실행 (환경변수 자동 주입)
agent-vault run -- claude
agent-vault vault run -- agent

"주입값이 항상 이긴다" 보안 불변식 (internal/brokercore)

// inject.Headers 키를 미리 벗겨내는 것이 "주입값이 항상 이긴다"
// 보안 불변식을 지킨다. 성능 최적화가 아니다.
func ApplyInjection(src, dst http.Header, inject *InjectResult, extraStrip ...string) {
    strip := make(map[string]bool, len(extraStrip)+len(inject.Headers))
    // ... 클라이언트 헤더 복사 + hop-by-hop/브로커 헤더 제거 ...
    for k, v := range inject.Headers {
        dst.Set(k, v)  // Set = 덮어쓰기. 에이전트가 보낸 값은 무시된다
    }
}

SNI별 leaf 인증서 즉석 발급 (internal/mitm/connect.go)

tlsConf := &tls.Config{
    MinVersion: tls.VersionTLS12,
    NextProtos: []string{"http/1.1"},
    GetCertificate: func(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {
        sni := hello.ServerName
        if sni == "" { sni = host }
        return p.ca.MintLeaf(sni)  // 이 도메인용 인증서를 지금 만든다
    },
}

클라우드 메타데이터 무조건 차단 (internal/netguard)

var alwaysBlocked = []net.IPNet{
    parseCIDR("169.254.169.254/32"), // AWS/GCP/Azure IMDS
    parseCIDR("fd00:ec2::254/128"),  // AWS IMDSv2 IPv6
}

6-2. 이 저장소에서 배울 수 있는 기술

7시스템 요구사항

설치 및 실행

# 설치
curl --proto '=https' --tlsv1.2 -fsSL https://get.agent-vault.dev | sh

# 서버 기동
export AGENT_VAULT_MASTER_PASSWORD=your-password
agent-vault server -d

# 에이전트 실행
agent-vault run -- claude

Docker

docker run -it -p 14321:14321 -p 14322:14322 \
  -e AGENT_VAULT_MASTER_PASSWORD=your-password \
  -v agent-vault-data:/data infisical/agent-vault

8직접 해볼 수 있는 실습 과제

9심화 학습 로드맵

10핵심 키워드 사전

11참고 링크