Claude Code와 같은 AI 코딩 에이전트는 편리하지만, API Key를 대화나 파일에 실수로 노출할 위험과 항상 직면해 있습니다.
본 기사의 배경이 된 사고에서는 API Key가 포함된 명령어가 무려 약 7주(49일) 동안 아무도 눈치채지 못하게 설정 파일에 계속 저장되어 있었습니다. 게다가 발견 후 '로컬 환경이라 괜찮을 것'이라고 생각했지만, 자동 동기화 스크립트를 통해 GitHub까지 도달했다는 (혼입부터 외부 노출까지 65일) 두 막 구성의 사건이었습니다.
본 기사에서는 이 실화 인시던트를 시간 순서대로 되짚어보며, Claude Code 환경에서 API Key를 보호하는 실질적인 보안 패턴을 설명합니다. AI 코딩 에이전트를 사용하는 모든 사람에게 적용할 수 있는 내용입니다.
📝
주: 본 기사는 실제 사건을 바탕으로 재구성되었습니다. 날짜 산출 근거는 혼입일 = 혼입 커밋의 날짜, 발견일 = 조사 기록의 날짜(둘 다 당시 작업 기록)입니다. 코드 예시는 작성 시점(2026-10 / Claude Code v2.1.x)의 공식 사양을 따릅니다. 버전에 따라 저장 형식이나 훅(hook) 사양이 변경될 수 있으므로, 자세한 내용은 공식 문서를 주기적으로 확인해 주십시오.
2026-06-10 권한 팝업에서 '항상 허용' 선택
→ Discord BOT 토큰 원본 값이 포함된 전체 명령어가 settings.json의 allow 리스트에 영구 저장됨 (이 시점에서 혼입)
...
문제의 명령어는 다음과 같은 형태였습니다:
# ❌ 토큰을 커맨드라인 인수에 직접 작성함
curl -H "Authorization: Bot MTIzNDU2Nzg..." https://discord.com/api/...
여기서 중요한 것은, 이 명령어가 어디에 저장되는가입니다. Claude Code는 권한 팝업에서 '항상 허용(Always allow)'을 선택하면, 전체 명령어를 settings.json의 allow 리스트에 그대로 영구화합니다. 토큰 역시 '명령어의 일부'로서 통째로 저장됩니다.
권한 팝업 '항상 허용'
└─> settings.json의 permissions.allow에, 예를 들어 다음과 같은 항목이
토큰 원본 값이 포함된 채로 저장됨 (값은 더미, 구조는 당시 관측 기반):
...
즉, AI 에이전트에게 부여하는 '편리한 권한 설정' 자체가 비밀을 보관하는 장소가 되어버린 것입니다. 만약 설정 파일을 git으로 관리하고 있다면, 이는 그대로 커밋 대상이 됩니다.
참고로, 비밀을 명령어 인수에 작성하는 것 자체가 첫 번째 잘못된 관행입니다 (쉘 히스토리나 프로세스 목록에 남음). 본 절에서 주목해야 할 부분은, 그 위에 '편리한 권한 설정'이라는 것이 사고를 49일간의 장기 잠복으로 발전시킨 2차 피해 구조입니다.
- 혼입 시점에는 이상이 없음 (명령어는 정상적으로 작동함)
- 설정 파일 내용을 정기적으로 확인하는 운영 방식이 없었음
- '로컬 한정 git repo이며 remote가 없다'는 안도감
세 번째 안도감은 후술할 제2막(GitHub 도달)에서 무너졌습니다.
실제 경로를 포함하여, 놓치기 쉬운 4가지 경로를 정리합니다.
# ❌ Claude Code가 실행하면 API Key가 대화(Context)에 표시됨
cat ~/.claude/settings.json
AI 에이전트는 '확인을 위해 파일을 여는 것'이 일상적인 동작입니다. 설정 파일에 비밀이 있다면, 그것만으로도 대화 로그에 기록됩니다.
# ❌ 모든 환경 변수를 표시
env | grep API
# ❌ 'jq로 확인해 주세요'라는 AI의 지시대로 실행
jq . ~/.claude/settings.json # API Key가 포함됨
# ❌ 비밀이 포함된 명령어를 팝업에서 '항상 허용'
→ 전체 명령어(비밀 포함)가 settings.json에 영구화됨
→ 이후, 설정 파일을 보는 모든 사람・AI・도구가 비밀에 접근 가능해짐
이 경로의 까다로운 점은, 그 자리에서는 아무 일도 일어나지 않는다는 것입니다. 혼입하는 순간에는 이상 징후가 전혀 없었으며, '알아차릴 계기'조차 다른 버그 조사여야 했습니다.
경로 4를 물리적으로 막을 수 있는 규칙은 단 하나입니다.
curl -H "Authorization: Bot MTIzNDU2Nzg..." https://discord.com/api/...
명령줄 인수는 쉘 히스토리(shell history), 권한 허용 목록(allow list), 프로세스 목록(ps) 등 여러 장소에 평문으로 남는 형태입니다.
# 비밀은 ~/.secrets.env 에 일원 관리하고, 줄 앞에 export를 붙여둡니다
# export DISCORD_BOT_TOKEN=xxx
# 사용할 때는 source로 읽어 변수를 참조합니다
...
이렇게 하면, 허용 목록에 영구화되는 명령어에는 변수 이름만 포함됩니다. 권한을 '향후 허용'해도 안전합니다 (이 명령어가 나중에 재사용되더라도, 변수가 설정되지 않았다면 실패할 뿐 값은 노출되지 않습니다). 더 엄격하게는 헤더를 파일 경유로 전달하는 방법도 있습니다:
# curl -K 로 헤더를 설정 파일 경유로 만듭니다 (프로세스 인자나 명령어 문자열에 값이 출력되지 않음)
printf 'header = "Authorization: Bot %s"\n' "$DISCORD_BOT_TOKEN" > /tmp/.hdr && curl -K /tmp/.hdr https://discord.com/api/... && rm /tmp/.hdr
⚠️
한계 명시: 쉘이 전개한 후의 값은 /proc/<PID>/cmdline ( ps로 보이는 프로세스 인자)에 나타납니다. 더 엄격하게 하려면, 헤더를 설정 파일 경유로 전달하는 curl -K나 표준 입력(stdin)을 이용해 주세요.
💡 포인트: '비밀 값'이 어디에도 저장되지 않게 하는 것이 이상적이지만, 현실적으로는 '저장되는 장소를 하나(예: ~/.secrets.env)로 제한하는 것'이 운영상 강력합니다.
AI 에이전트에게 'API 키 설정되어 있나요?'라고 물었을 때의 안전한 확인 방법입니다.
# ✅ 키가 설정되었는지 여부만 확인
[ -n "$DISCORD_BOT_TOKEN" ] && echo "set" || echo "unset"
# ✅ 키 이름만 표시하고, 값은 가림 처리
grep -E "^((export )?[A-Z_]+)=" ~/.secrets.env | sed "s/=.*//=<REDACTED>/"
# ✅ 길이만 확인 (값의 형태가 바뀌지 않았는지의 참고 지표)
echo "len=${#DISCORD_BOT_TOKEN}"
키의 '값'을 대화, 파일, 커밋에 작성하지 않는다. 키 이름은 OK, 값은 NG — 이것이 유일한 안전 규칙입니다.
'운영 시 주의할 점'은 사람이 잊기 때문에, 명령어 실행 전에 후크(hook)로 체크합니다. Claude Code의 후크는 stdin으로 이벤트 JSON을 수신하고, exit 2로 명령어 실행을 차단하는 사양입니다 (공식 문서).
후크가 받는 이벤트는 예를 들어 다음과 같은 형태입니다:
{ "tool_name": "Bash", "tool_input": { "command": "cat ~/.secrets.env" } }
그 사양에 맞는 동작 예시 (cat 계열 읽기 차단 + jq의 화이트리스트 판별 통합):
#!/usr/bin/env python3
# check-command-safety.py — secrets 관련 파일 읽기를 차단하는 PreToolUse 후크
import json, re, sys
...
settings.json에 등록하는 예시 (Bash 도구 실행 전에 호출됨):
{
"hooks": {
"PreToolUse": [
...
도입은 3단계입니다 (macOS/Linux, POSIX 쉘 전제):
mkdir -p ~/.claude/scripts/hooks
# 위 스크립트를 ~/.claude/scripts/hooks/check-command-safety.py 로 저장
chmod +x ~/.claude/scripts/hooks/check-command-safety.py
...
⚠️
이 후크의 한계: 정규 표현식 판별은 alias cat='bat' 같은 쉘 함수, awk/sed 등을 통해 우회할 수 있습니다. 이는 '실수'를 막는 최전선일 뿐 최종 방어선은 아닙니다. 최종 방어선은 제3층(secrets.env에 집약 + 권한 제한)입니다.
초기 구현에서는 jq가 블록 대상에서 제외되었습니다. cat 계열을 막아도 jq . settings.json
전부 덤프(dump)할 수 있는, 이른바 **허점(backdoor)**입니다.
여기서 주의해야 할 것은 설계 방식입니다. **블랙리스트(‘이 쿼리는 금지’ 목록화)**는 누락된 항목으로 인한 허점을 무한히 생성하기 때문에, 이를 **화이트리스트(허용되는 쿼리와 완전 일치하는 경우만 통과시키고 나머지는 모두 차단)**로 전환합니다. 위에 있는 후크 코드의 ALLOWED_JQ_QUERIES가 그 구현이며, jq . (전체 덤프)는 차단되고, jq .model (특정 키)만 통과됩니다.
# ~/.secrets.env (단일 파일에 집약 및 git 관리 제외)
export MINIMAX_API_KEY=xxx
export DISCORD_BOT_TOKEN=xxx
...
설정 파일 자체에는 값을 쓰지 않고, ${VAR} 변수 확장 구문으로 환경 변수를 참조합니다:
{
"mcpServers": {
"brave-search": {
...
~/.secrets.env 자체는 비밀을 포함하므로, 권한(permission)을 제한합니다:
chmod 600 ~/.secrets.env # 자신 외에는 읽을 수 없음
제2막(GitHub 도달)의 교훈입니다. 이번 사고가 발생한 도달 메커니즘을 구체적으로 적자면:
SessionStart/Stop 후크의 동기화 스크립트가
설정 파일의 사본을 지식 기반 리포지토리로 ‘가공 없이 cp’
→ 그 리포지토리의 자동 커밋+푸시가 원본 값으로 채워진 사본을
...
‘올바른 마스킹 경로’와 ‘가공되지 않은 복사(cp)의 레거시 경로’가 이중으로 공존하고 있었고, 후자가 원본 값을 운반했습니다. 감사 관점은 다음과 같습니다:
체크리스트:
□ 설정 파일을 복사하는 스크립트는 모두 나열했는가
□ 각각 마스킹 처리 과정을 거쳤는가 (가공되지 않은 cp가 없는지)
...
※ git grep은 현재 작업 디렉토리(working tree)가 대상이며 히스토리는 볼 수 없습니다. 히스토리는 git log -S (픽업 문자열 검색, pick-up string search)을 사용합니다. 또한 키 이름 검색은 값이 base64로 인코딩되거나 리네임된 복사본은 탐지할 수 없다는 한계가 있습니다.
만약 API 키가 노출되었을 경우의 대응:
1. 가능하다면 악용 흔적을 보존 (서비스 측 감사 로그/접근 기록 확인 및 저장 후 다음 단계 진행)
2. 노출된 키를 로테이션(rotation) (새로운 키 발급 및 이전 키 무효화)
3. settings.json의 allow 리스트를 점검하고 혼입 엔트리를 삭제
...
처음에는 ‘대화를 종료하는 것’으로 설명하기 쉽지만, 노출된 키의 수명은 로테이션(rotation)을 통해 멈추는 것이 우선입니다. 대화 로그를 삭제하더라도 allow 리스트나 git 히스토리에 남은 값은 사라지지 않습니다.
| 교훈 | 내용 |
|---|
| ‘향후 허용’ 시 | 전체 명령어 저장 |
| ... | |
| API 키 값을 절대 대화, 파일, 명령어 인수에 쓰지 않기—이 한 줄을 AI 코딩 에이전트를 사용하기 시작한 날 설정해 두는 것이 본 기사에서 얻어갈 가장 중요한 교훈입니다. | |
- AI 에이전트 개발 환경에 비밀 정보 유출 게이트를 직접 만들어 2주간 운영했더니 오경보가 없었던 이야기 — 본 기사의 다층 방어를 CI/후크로 자동화한 속편
- Claude Code 설정의 3단계 설계 — CLAUDE.md를 어떻게 분할할 것인가 — 글로벌/프로젝트/디렉토리 사용 구분
이 글은 Claude Code와 함께 작성되었습니다.
본 기사는 개인 Zenn에서도 공개하고 있습니다.