AI 에이전트와 LLM 서버 사이에서 시크릿·PII를 자동으로 보호하는 로컬 프록시 가드
코딩 에이전트(claude code, codex, gemini 등)는 작업을 수행하기 위해 .env 파일, 소스코드, 고객 데이터를 그대로 외부 LLM 서버에 전송합니다.
한 번 전송된 데이터는 외부 서버 로그에 영구 저장되며, 개발자는 이를 인지조차 하지 못합니다.
실제 발생한 사례
| 사례 | 내용 |
|---|---|
| CVE-2025-59536 | 악성 레포 클론만으로 Claude Code를 통해 AWS 키 유출 |
| CVE-2026-21852 | ANTHROPIC_BASE_URL 조작으로 API 키 탈취 |
| 삼성 2023 | 임직원이 ChatGPT에 내부 소스코드 입력 → 유출 → 전사 AI 도구 사용 금지 |
법적 리스크
한국 개인정보보호법 제28조의8(국외 이전)에 따르면, 이름·전화번호·주민번호 등 PII를 정보주체의 동의·고지 없이 외국 서버로 전송하는 것은 법적 주의를 요합니다. 개발자의 일상적인 워크플로우에서 매번 동의 절차를 밟는 것은 현실적으로 불가능합니다.
- 시크릿·API 키를 매일 다루는 개인 개발자
- AI 도구 도입을 검토 중인 기업 보안팀
- 한국 PII의 외국 서버 전송이 부담스러운 국내 기업
[사용자 + AI 에이전트]
│ HTTPS
▼
[AgentGuard 로컬 프록시] ← HTTPS_PROXY 환경변수로 트래픽 인터셉트
│ HTTPS (가짜값으로 치환된 요청)
▼
[LLM 서버 (Anthropic / Gemini)]
│ HTTPS (가짜값이 포함된 응답)
▼
[AgentGuard 로컬 프록시] ← 원본값으로 복원
│
▼
[사용자] ← 원본값이 복원된 응답
가로챔 메커니즘: HTTPS_PROXY 환경변수 + 로컬 CA 신뢰 (mitmproxy 표준)
에이전트 종류에 무관하게 모든 표준 HTTP 클라이언트는 HTTPS_PROXY를 인식합니다.
Module A가 중앙 오케스트레이터로, 모든 모듈 호출을 A가 조율합니다.
| 모듈 | 파일 | 역할 |
|---|---|---|
| A — Proxy Core | agentguard/proxy/ |
mitmproxy 기반 TLS 인터셉터. 요청/응답 흐름 조율, JSON 파싱·재조립, stream: false 강제 |
| B — Detection | agentguard/detector/ |
정규식 + Presidio + 한국어 커스텀 3-stack 탐지 엔진 |
| C — Tokenizer | agentguard/tokenizer.py |
Format-preserving 가짜값 생성, AES-256-GCM 암호화 SQLite 매핑 저장 |
| D — TUI | agentguard/tui.py |
Rich 기반 실시간 치환/복원 모니터링 화면 |
단순 플레이스홀더([NAME], [PHONE]) 대신 형식이 같은 가짜값을 생성합니다.
LLM이 형식적으로 유효한 데이터로 인식하여 답변 품질이 유지됩니다.
| 원본 | 가짜 | 방식 |
|---|---|---|
AKIAIOSFODNN7EXAMPLE |
AKIAAF4YAPH389ADE6NB |
AWS 키 형식 그대로 |
김민수 |
박지훈 |
Faker ko_KR |
010-1234-5678 |
010-8273-4019 |
한국 휴대폰 형식 |
900101-1234567 |
850230-1456789 |
체크섬 통과 + 실존 불가능 날짜 |
시크릿 / API 키: AWS Access Key · Secret Key, GitHub Token, OpenAI · Anthropic · Google API Key, Private Key
한국 PII: 이름, 전화번호, 주민등록번호(체크섬 검증), 사업자등록번호, 카카오·네이버 API 키
일반 PII: 이메일, IP 주소, 신용카드, URL
외부 Tool Call 데이터 유출 가능성
현재 AgentGuard는 사용자 ↔ Claude (LLM 서버) 간의 메시지 통신에서 PII 마스킹을 수행합니다. 그러나 Claude가 외부 서버의 Tool(예: 웹 검색, 코드 실행 환경, 서드파티 API)을 호출할 때 발생하는 트래픽은 현재 TLS 인터셉트 범위 밖에 있어 데이터 유출 위험이 남아 있습니다.
[사용자] ──(가드 O)──> [Claude] ──(가드 X)──> [외부 Tool 서버]
그 외 한계
| 한계 | 현황 |
|---|---|
| 스트리밍 응답 | MVP는 stream: false 강제 (실시간 타이핑 효과 없음) |
| 의미적 민감 데이터 | 패턴이 없는 맥락 기반 민감정보는 탐지 불가 |
| 완벽한 복원율 | LLM이 응답에서 토큰을 변형할 경우 퍼지 매칭으로 보완 (95~98%) |
AgentGuard 패키지를 설치하면, 사용자는 기존과 동일하게 AI 에이전트와 상호작용합니다. 백그라운드 프로그램이 자동으로 가드 역할을 수행하며, 사용자는 별도의 변경 없이 보호를 받습니다.
[패키지 설치 후 사용자 경험]
사용자: "이 .env 파일로 배포해줘"
(AgentGuard가 백그라운드에서 자동으로 민감정보 마스킹)
AI 에이전트: "배포 완료했습니다"
(AgentGuard가 응답의 가짜값을 원본으로 자동 복원)
→ 사용자 입장에서는 평소와 동일한 경험
→ 실제로는 진짜 시크릿·PII가 외부 서버에 단 한 번도 전송되지 않음
v2 로드맵
- Tool Call 트래픽 인터셉트 확장
- Sliding-window 기반 실시간 스트리밍 복원
- ML 기반 의미적 민감정보 탐지
agentguard init자동 설치 (CA 등록 + 환경변수 설정 자동화)- cmux 네이티브 통합
pip install agentguard# 소스에서 설치
git clone https://github.com/molcham/agentguard
cd agentguard
uv sync
# 테스트
uv run pytest tests/ -v
# 데모 실행
AGENTGUARD_DEBUG_DB=1 uv run python demo_tokenizer.pyMIT License — LICENSE 참고