LLM 요청에서 비밀값을 지키는 keyfence

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

LLM 도구가 API 키와 비밀번호를 프롬프트나 요청에 포함해 외부 제공자로 보내는 위험을 줄이기 위해 keyfence가 로컬 프록시로 요청을 먼저 검사합니다. mitmproxy 기반의 프록시는 비밀값을 발견하면 요청을 403으로 차단하거나 [REDACTED:]로 삭제하고, 플레이스홀더 모드에서는 <<SECRET_1>> 같은 값으로 치환한 뒤 응답에서 원래 값을 복원합니다. Claude Code, Cursor, Codex, Aider, curl처럼 HTTP를 사용하는 도구에 적용할 수 있으며, 비밀값 해시와 패턴 규칙, 엔트로피 검사를 함께 사용합니다. 설치에는 Python 3.12 이상과 HTTPS 검사를 위한 CA 인증서 신뢰 설정이 필요하고, 저장소에는 탐지 recall과 false positive rate를 확인하는 벤치마크 및 적용 범위의 한계가 포함되어 있습니다.

섹션별 상세

LLM 코딩 도구가 API 키나 비밀번호를 요청 본문에 포함하면 해당 값이 AI 제공자까지 전송될 수 있습니다. keyfence는 클라이언트와 제공자 사이에 로컬 프록시를 배치해 요청이 컴퓨터 밖으로 나가기 전에 검사합니다. Claude Code, Cursor, Codex, Aider, curl처럼 HTTP를 사용하는 도구를 같은 경로로 연결할 수 있다는 점이 적용 범위를 넓힙니다.

bash

pip install keyfence

keyfence import
keyfence exec -- claude
keyfence canary .env

keyfence를 설치한 뒤 환경 파일과 자격 증명 파일에서 비밀값을 등록하고, Claude를 프록시 경유로 실행하며, 가짜 비밀값을 심습니다.

bash

sudo security add-trusted-cert -d -p ssl \
  -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem

macOS에서 mitmproxy가 생성한 CA 인증서를 시스템 키체인에 신뢰할 인증서로 추가합니다.

python

python bench/run.py

비밀값 형식별 recall과 콘텐츠 유형별 false positive rate를 재현 가능한 벤치마크로 측정합니다.

keyfence는 .env와 자격 증명 파일에서 비밀값을 가져오되 원문 대신 해시를 보관하고, 패턴 규칙과 엔트로피 검사를 사용해 요청 안의 일치 값을 찾습니다. 탐지한 요청은 403으로 차단하거나 기본값인 [REDACTED:]로 바꿀 수 있으며, 플레이스홀더 모드에서는 실제 값을 <<SECRET_1>> 같은 문자열로 치환해 제공자에게 보냅니다. 제공자의 응답이 돌아오면 플레이스홀더를 원래 값으로 복원하고 스트리밍 응답에도 같은 처리를 적용합니다.

keyfence를 사용하려면 Python 3.12 이상 환경에서 pip install keyfence로 설치하고, 첫 실행 때 mitmproxy가 만든 CA 인증서를 신뢰하도록 설정해야 합니다. keyfence import는 환경 파일과 자격 증명 파일의 비밀값을 등록하고, keyfence exec -- claude는 Claude를 프록시 경유로 실행하며, keyfence canary .env는 가짜 비밀값이 외부로 전송되는지 확인합니다. HTTPS를 복호화해 검사하는 구조이므로 CA 인증서 설정이 실제 사용의 필수 단계입니다.

저장소는 단순한 차단 기능 외에 탐지 규칙, 제외 대상, 감사 로그, 환경 변수 설정, 시스템 프롬프트 고지, Docker 사용법을 문서화합니다. 벤치마크는 비밀값 형식별 recall과 콘텐츠 유형별 false positive rate를 gitleaks와 비교하고 python bench/run.py로 재현할 수 있습니다. 다만 keyfence가 다루지 않는 범위와 함께 사용해야 할 보완책도 별도 한계 항목으로 남겨 두어, 프록시만으로 모든 비밀 유출 경로를 해결한다고 보지 않습니다.

이미지 분석

Diagram
이미지는 로컬 도구가 보낸 요청이 keyfence를 거쳐 api.anthropic.com과 api.openai.com 같은 제공자로 전달되고, 응답이 반대 방향으로 돌아오는 구조를 보여줍니다. 플레이스홀더 모드에서는 요청의 실제 키가 <<SECRET_1>>로 치환되어 인터넷 경계를 넘지 않고, 제공자 응답의 플레이스홀더가 로컬에서 원래 값으로 복원됩니다.
Claude Code, Cursor, Codex, curl과 AI 제공자 사이에 keyfence가 로컬 프록시로 배치된 흐름도입니다.

용어 해설

로컬 프록시(Local Proxy): — 사용자 컴퓨터와 외부 서버 사이에서 HTTP 요청과 응답을 중계하는 구성입니다. keyfence는 이 중간 지점에서 LLM API로 전송될 요청을 검사하고, 감지한 비밀값을 차단하거나 다른 값으로 바꾼 뒤 응답에서 복원합니다. 비밀값이 인터넷으로 넘어가기 전에 통제할 수 있다는 점이 핵심입니다.
mitmproxy: — HTTP와 HTTPS 트래픽을 중간에서 가로채 검사하고 다시 전달하는 프록시 도구입니다. keyfence는 mitmproxy를 의존성으로 사용해 Claude Code, Cursor, curl 같은 클라이언트의 요청 내용을 외부 AI 제공자에 도달하기 전에 확인합니다. HTTPS 검사를 위해 로컬 CA 인증서를 신뢰하도록 설정해야 합니다.
비밀값 탐지(Secret Detection): — API 키, 비밀번호, 토큰처럼 외부에 노출되면 안 되는 문자열을 규칙과 문자열 특성으로 찾아내는 기술입니다. keyfence는 저장된 비밀값의 해시, 패턴 규칙, 엔트로피 검사를 사용해 요청 안의 비밀값을 식별합니다. 탐지 결과에 따라 요청 차단, 값 삭제, 플레이스홀더 치환을 적용합니다.
플레이스홀더 모드(Placeholder Mode): — 민감한 값을 실제 값 대신 식별 가능한 대체 문자열로 바꿔 외부 서비스에 전달하는 처리 방식입니다. keyfence는 요청의 비밀값을 <<SECRET_1>> 같은 플레이스홀더로 바꾸고, 제공자의 응답에 포함된 플레이스홀더를 원래 값으로 되돌립니다. 스트리밍 응답에도 복원이 적용됩니다.
카나리 시크릿(Canary Secret): — 유출 여부를 확인하기 위해 의도적으로 심어 두는 가짜 비밀값입니다. keyfence의 canary 명령은 .env 파일에 가짜 비밀값을 배치하고, 어떤 도구가 이를 외부로 보내면 그 사실을 확인할 수 있게 합니다. 실제 자격 증명을 노출하지 않고 전송 경로를 점검하는 용도입니다.

기술

keyfence
mitmproxy
Claude Code
Cursor
Codex
Aider
curl
gitleaks
Python

활용 사례

Claude Code와 같은 코딩 에이전트의 API 요청에서 자격 증명 보호
LLM 요청에 포함된 API 키와 비밀번호의 차단 및 삭제
플레이스홀더를 사용한 비밀값 전달과 응답 복원
가짜 비밀값을 이용한 도구별 유출 경로 점검
비밀값 탐지 규칙의 recall과 false positive rate 측정

언급된 리소스

GitHubaminueza / Keyfence

문서keyfence Documentation