AI 코딩 에이전트에게 API 키를 흘리지 않는 법: 시크릿 보안 실전 체크리스트

핵심 요약: AI 에이전트 시대의 시크릿 유출은 해킹이 아니라 일상 동작으로 일어납니다 — 에이전트가 .env를 읽어 컨텍스트로 전송하거나, 디버깅하려고 키를 코드에 하드코딩하거나, 로그를 통째로 붙여넣는 순간들. 방어선은 4겹입니다: ① .gitignore + .cursorignore류로 시크릿 파일을 읽기 대상에서 제외 ② 프라이버시 모드·ZDR로 전송된 코드의 학습·보존 차단 ③ 훅으로 위험 패턴(키 형태 문자열) 감지·차단 ④ MCP·클라우드 에이전트의 권한 최소화. 습관 하나가 더 중요합니다 — 에이전트에게 진짜 키가 필요한 경우는 거의 없습니다.

이 글에서 다루는 내용: 유출이 일어나는 4가지 경로, 도구별 차단 설정, 훅 기반 자동 감시, 이미 흘렸을 때 대처.

유출은 이렇게 일어난다

경로 1 — 컨텍스트 전송: "설정 관련 버그 고쳐줘" 한마디에 에이전트가 .env를 읽고, 내용이 모델 서버로 전송됩니다. 경로 2 — 하드코딩: 에이전트가 테스트를 통과시키려고 환경변수 대신 실제 값을 코드에 박아넣고, 그게 커밋됩니다. 경로 3 — 로그·붙여넣기: 오류 로그나 curl 명령에 토큰이 포함된 채 프롬프트로 들어갑니다. 경로 4 — 외부 연결: MCP 서버·클라우드 에이전트에 넓은 권한을 줘서, 시크릿에 접근 가능한 도구가 늘어납니다. 전부 "누가 뚫은" 게 아니라 정상 동작의 부산물이라는 점이 핵심입니다.

1겹: 읽기 자체를 막기

Cursor는 .cursorignore에 등록된 파일을 컨텍스트·인덱싱에서 제외합니다. .env, *.pem, credentials/ 등을 넣어두세요(.gitignore는 커밋만 막을 뿐 에이전트 읽기는 못 막습니다 — 둘 다 필요합니다). Claude Code는 권한 설정으로 특정 파일·명령 접근을 거부 목록에 올릴 수 있습니다. 원칙은 같습니다: 에이전트가 읽을 수 없으면 흘릴 수도 없다.

2겹: 전송된 것의 보호

읽기를 다 막을 수는 없으니, 전송되는 코드의 처리 방침을 확인합니다. Cursor 프라이버시 모드(학습·보존 차단, 상세 글), 팀이라면 Teams 이상에서 강제 설정. Claude도 구독 사용자의 코드를 기본적으로 학습에 쓰지 않지만, 회사 코드라면 조직 정책과 ZDR 계약 여부를 확인하는 것이 먼저입니다.

3겹: 훅으로 자동 감시

사람의 주의력 대신 패턴 매칭을 씁니다. 셸 실행 전 훅에서 명령에 키 형태 문자열(sk-, ghp_, AKIA 등 접두사)이 포함되면 차단하고, 커밋 전에 gitleaks 같은 스캐너를 돌리는 훅을 걸면 하드코딩 사고를 커밋 단계에서 잡습니다. 훅 설정 방법 자체는 도구별 글(Claude Code 훅 레시피)을 참고하세요.

4겹: 연결 권한 최소화

MCP 서버에는 필요한 최소 권한의 토큰만 발급해 물리고(읽기만 필요하면 read-only), 신뢰할 수 없는 MCP 서버는 애초에 연결하지 않습니다(MCP 보안 가이드). 클라우드 에이전트는 저장소 접근 범위를 프로젝트 단위로 좁히세요.

그리고 가장 싼 방법: 애초에 안 주기

돌아보면 에이전트에게 진짜 키가 필요했던 적이 거의 없습니다. 외부 API 연동 코드는 가짜 키로 개발하고 mock으로 테스트하면 되고, 실제 키는 사람이 배포 환경에만 넣으면 됩니다. 제 규칙은 "에이전트 작업 저장소의 .env에는 전부 더미 값"입니다 — 이렇게 하면 위의 4겹이 뚫려도 나가는 건 dummy-key-1234입니다. 한 번은 에이전트가 만든 코드에 .env 값이 하드코딩된 채 커밋될 뻔했는데, 더미 값 정책 덕에 사고가 아니라 리뷰 코멘트로 끝났습니다.

이미 흘렸다면

순서는 셋: 즉시 해당 키 폐기·재발급 → 커밋됐다면 저장소 히스토리에서 제거(BFG 등)하되 재발급이 먼저(히스토리 정리는 유출 대응이 아니라 뒷정리입니다) → 사용 로그에서 이상 사용 확인. 유출 시점부터 재발급까지의 시간이 피해 크기를 결정합니다.

자주 묻는 질문 (FAQ)

Q. .gitignore에 있으면 안전한 것 아닌가요?

A. 아닙니다. .gitignore는 커밋만 막습니다. 에이전트는 로컬 파일을 읽을 수 있으므로 .cursorignore 같은 도구별 제외 설정이 별도로 필요합니다.

Q. 프라이버시 모드를 켜면 키를 읽혀도 되나요?

A. 안 됩니다. 학습·보존을 막을 뿐 전송 자체는 일어나고, 하드코딩·커밋 같은 다른 경로는 그대로입니다. 프라이버시 모드는 여러 겹 중 하나일 뿐입니다.

Q. 팀에서 제일 먼저 할 것 하나만 꼽는다면?

A. 시크릿 파일 제외 설정(.cursorignore류)의 표준화 + pre-commit 시크릿 스캐너입니다. 비용 대비 효과가 가장 크고 도구와 무관하게 작동합니다.

한눈에 보는 요약

읽기 차단 → 전송 보호 → 훅 감시 → 권한 최소화의 4겹, 그리고 "에이전트 저장소엔 더미 값" 원칙. 유출은 사고가 아니라 기본 동작이라는 전제로 설계하면 대부분 막힙니다.

함께 보면 좋은 글

Cursor 프라이버시 모드: 내 코드는 안전할까?
MCP 보안 가이드
Claude Code 훅 레시피 5가지

참고 자료

Cursor 공식 문서 (ignore 설정)
gitleaks (시크릿 스캐너)