AI 에이전트 시크릿 가드 설계: 커밋·파일 쓰기·로그·외부 전송으로의 유출 막기

사람 개발자도 시크릿을 실수로 커밋합니다. 그런데 AI 코딩 에이전트는 그 유출면을 더 넓힙니다. 에이전트는 파일을 쓰고, git add·git commit을 실행하고, 턴마다 프롬프트·출력을 로그로 남기고, 때로는 컨텍스트를 외부 모델·웹으로 보냅니다. 각 지점이 시크릿이 새어 나갈 수 있는 표면입니다. 그리고 시크릿은 한 번 커밋 히스토리에 들어가면 되돌리기 어렵습니다.

이 글은 AI 에이전트가 만드는 시크릿 유출면을 정리하고, 그것을 방어 심층 (Defense in Depth) 으로 막는 설계를 다룹니다. 핵심 원칙은 하나입니다 — 애초에 시크릿을 값으로 다루지 말 것. 그 위에 쓰기·커밋 가드, 다층 탐지, 로그 마스킹, 외부 전송 게이트, 그리고 유출 시 대응(회전·폐기)까지 층층이 쌓습니다.

이 글은 런타임 자격 증명 아키텍처를 다룬 AI Agent 자격 증명 관리와 짝을 이룹니다. 그 글이 "돌아가는 에이전트가 자격을 어떻게 다루는가"라면, 이 글은 "개발·실행 중에 시크릿이 저장소·로그·외부로 새는 것을 어떻게 막는가"입니다. 본문의 예시 값·경로·패턴은 합성 예시이며 특정 제품·회사와 무관합니다. 상호 참조와 공식 문서 링크만 실제 URL입니다.

1. AI 에이전트가 넓히는 시크릿 유출면

에이전트는 사람보다 더 많은 경로로 시크릿을 흘릴 수 있습니다. 대표적인 여섯 표면입니다.

1) 커밋/스테이징  : git add·commit 으로 시크릿 파일·하드코딩 키를 저장소에
2) 파일 쓰기      : 코드·설정에 시크릿을 써 넣거나, 시크릿 파일 자체를 생성
3) 프롬프트/컨텍스트: 사용자·도구가 넣은 시크릿을 에이전트가 코드·출력으로 복제
4) 로그/트랜스크립트: 턴별 프롬프트·응답을 평문 로그로 저장 → 시크릿 노출
5) 도구 인자·에러  : 도구 호출 인자나 에러 메시지에 시크릿이 실려 표면화
6) 외부 전송      : 교차검증·웹 검색 등으로 컨텍스트가 신뢰 경계 밖으로

이 여섯은 서로 다른 계층에서 막아야 합니다. 한 겹(예: 커밋 훅)만으로는 로그나 외부 전송으로 새는 것을 못 막습니다. 그래서 시크릿 가드는 여러 경계의 조합으로 설계합니다(AI Agent 보안 설계 8경계 참고).

2. 첫 번째 원칙: 값이 아니라 핸들을 넣는다

가장 강력한 방어는 시크릿을 애초에 에이전트 컨텍스트에 넣지 않는 것입니다. 에이전트가 시크릿 원문을 본 적이 없으면 평문을 직접 흘릴 가능성이 크게 줄어듭니다. (다만 원문을 몰라도 자격을 가진 실행기를 시켜 공격자가 지정한 목적지로 요청을 보내는 confused-deputy 유출은 가능하므로, 핸들에는 대상 서비스·허용 작업·수명·권한을 묶고 실행기가 목적지·요청을 검증해야 합니다.)

• 자격 증명은 환경·시크릿 매니저·브로커가 실행 시점에 주입하고, 에이전트에는 자격 증명 핸들 (Credential Handle) 이나 참조만 노출합니다.
• 도구는 "토큰 값"이 아니라 "이 토큰으로 호출해 달라는 지시"를 받도록 설계합니다(값은 실행기 안에서만).
• 예시·문서에는 실제 값 대신 자리표시자(<TOKEN>)를 씁니다.

이 "값이 아니라 핸들" 원칙은 자격 증명 관리의 Broker·단기 Token·Token Exchange와 같은 뿌리입니다. 입력 경계에서 막으면, 뒤의 모든 가드는 보조 안전망이 됩니다 — 있어야 하지만, 첫 줄에 의존하지 않습니다.

3. 쓰기 가드: 파일 쓰기·편집을 검문한다

에이전트가 파일을 쓰거나 고칠 때, 쓰기 도구에 훅을 걸어 위험한 대상을 차단합니다. 다만 에이전트는 편집 도구뿐 아니라 셸 리다이렉션·스크립트·임시 파일 후 rename·심볼릭 링크로도 파일을 바꿀 수 있으므로, 이상적으로는 모든 파일 변경을 정책 실행기로 중개하고 정규화한 최종 경로와 최종 콘텐츠를 검사해야 합니다.

차단  : .env·*.key·*-secrets.*·자격 파일, .git/ 내부 쓰기
검사  : 쓰려는 내용에 시크릿 패턴이 있으면 차단(코드에 키 하드코딩 방지)
예외  : *.example·*.template 은 문서화용이라 파일 쓰기는 허용
        단, 내용 기반 시크릿 스캔은 그대로 적용(예시 파일에 진짜 키가 들어가는 사고 방지)

핵심은 경로 기반 차단과 내용 기반 스캔을 함께 두는 것입니다. 파일명만 보면 코드 파일에 하드코딩된 키를 놓치고, 내용만 보면 시크릿 파일 생성을 놓칩니다. 쓰기 작업 자체를 "쓰기·중요·파괴" 관점에서 게이팅하는 사고는 AI Agent 승인 정책과 이어집니다.

4. 커밋 가드: staged 스캔과 체인 우회 차단

파일이 저장소에 들어가는 마지막 문은 커밋입니다. 여기서 staged diff를 스캔해 시크릿을 막습니다.

pre-commit : commit 시점의 staged 인덱스에 시크릿 패턴·고엔트로피가 있으면 차단
             (add 를 미리 해두어도 커밋 시 인덱스를 검사하므로 그대로 걸린다)
명령 은닉  : 명령 문자열만 검사받는 에이전트 정책 계층은 add·commit 을 한 줄로 묶어
             속일 수 있음 → 최종 인덱스 상태를 검사해야 함(로컬 훅의 실제 우회는
             `--no-verify` 나 훅을 거치지 않는 저수준 명령)
fail-closed: 스캔 도구가 없으면 "통과"가 아니라 차단·경고(안전 장치는 무력화되면 안 됨)

주의할 점: pre-commit·pre-push 같은 로컬 git 훅은 --no-verify로 우회될 수 있고, .git/hooks는 버전 관리되지 않아 파일 생성만으로 팀에 배포되지 않습니다. 그래서 core.hooksPath나 훅 관리자로 활성화하고, 최종 차단은 서버(예: pre-receive 훅·호스팅 시크릿 스캔) 에 둡니다. 로컬은 빠른 실수 방지, 서버는 권위적 차단 — 이 이중 구조가 원칙입니다.

5. 탐지는 한 겹이 아니다: 다층 스캔

시크릿 탐지를 정규식 하나에 맡기면, 새로운 토큰 형식이나 인코딩된 값을 놓칩니다. 탐지는 여러 신호를 겹칩니다.

탐지 신호	잡는 것	한계
정규식·알려진 토큰 형식	접두사가 뚜렷한 키·토큰	새로운/커스텀 형식은 놓침
엔트로피(무작위성)	형식 불명의 고엔트로피 문자열	휴리스틱일 뿐, 분할·변형·인코딩된 시크릿은 놓침
검증된 스캐너	널리 알려진 크리덴셜 패턴 다수	조직 고유 비밀은 규칙 추가 필요
서버 CI 스캔	로컬이 놓친 것 재포착	이미 push된 뒤라 대응 필요

로컬 가드가 1차로 막고, 최종 예방선은 서버측 push 차단(pre-receive 훅·호스팅 push protection)입니다. 일반 CI 스캔은 push 이후 탐지·경보 계층이라 저장소 유입 자체를 막지는 못하므로, 예방(pre-receive)과 탐지(CI)를 구분해야 합니다. 어느 한 층도 완벽하지 않으므로, 겹쳐서 빈틈을 줄이는 것이 목표입니다.

6. 로그·프롬프트·에러 마스킹

에이전트의 턴 로그·트랜스크립트는 관측에 유용하지만, 그 안에 프롬프트·도구 인자·에러가 평문으로 담기면 시크릿 창고가 됩니다. 저장 전에 마스킹해야 합니다.

{
  "turn": 42,
  "tool": "http_request",
  "args": {
    "url": "https://api.example.com/v1",
    "headers": { "Authorization": "Bearer <REDACTED>" }
  },
  "result": "200 OK",
  "note": "값이 아니라 마스킹된 표식만 기록"
}

원칙은 이렇습니다.

• 저장 전 마스킹 — 프롬프트·응답·도구 인자·에러·트레이스에서 시크릿을 자리표시자로 치환.
• 접근·보존 통제 — 로그 파일 권한·접근 통제·보존 기간·필요 시 암호화. 버전 관리에서 제외.
• 수집 실패 시 동작 — 마스킹 파이프라인이 실패하면 그대로 기록하지 말고 안전하게 처리.

이 주제의 상세는 AI Agent 감사 로그 설계: 추적성·개인정보 Masking과 보존 기간에서 다뤘습니다. 로그는 "무엇을 남길까"만큼 "무엇을 안 남길까"가 중요합니다.

7. 외부 전송 게이트

에이전트가 컨텍스트를 신뢰 경계 밖으로 보내는 순간이 있습니다 — 외부 LLM 교차검증, 웹 검색·페치, 서드파티 도구 호출. 여기서 시크릿이 함께 나가면 통제 불능입니다.

• 외부로 나가는 페이로드에 시크릿 스캔·마스킹을 적용하고, 걸리면 차단합니다.
• 무엇을 어디로 보내는지 egress를 명시적으로 통제합니다(임의 도메인 금지, 허용 목록).
• 신뢰할 수 없는 입력(웹·문서)이 컨텍스트에 섞여 에이전트를 조종하는 경우도 함께 봐야 합니다(Prompt Injection 방어: 신뢰 경계·데이터 표식).

외부 전송은 "편의를 위해 무심코" 일어나기 쉬우므로, 기본은 차단, 필요한 경로만 열기가 안전합니다.

8. 오탐과 탈출구: 가드를 끄지 않게

시크릿 가드는 반드시 오탐(false positive) 을 냅니다. 고엔트로피 테스트 데이터, base64 리소스, 커밋 메시지의 특정 문자열 등이 시크릿으로 오해받습니다. 이때 정당한 작업이 막혔는데 빠져나갈 문이 없으면, 사람들은 가드 자체를 꺼 버립니다. 그러면 보안은 0이 됩니다.

• 오탐에는 정식 우회 경로를 둡니다(예: 검토 후 명시적 예외, 메시지를 파일로 전달).
• 우회는 기록되게 해서, "왜 우회했는가"가 남도록 합니다.
• 규칙은 좁고 정확하게 유지해 오탐을 줄입니다. 탈출구와 정밀도는 함께 가야 합니다.

탈출구는 편의 기능이 아니라 가드를 살아 있게 하는 안전 설계의 일부입니다.

9. 유출되면? 회전·폐기가 유일한 실효 대응

가장 중요한 사실: 시크릿이 커밋되면 히스토리에 사실상 영원히 남습니다. 히스토리를 정리(force push·필터링)해도 이미 fetch·미러·CI 로그에 퍼졌을 수 있습니다. 그러므로 유출 시 유일하게 확실한 대응은 그 시크릿을 즉시 무효화하는 것입니다.

1) 폐기·비활성화(revoke)   → 노출된 자격을 즉시 무효화 (최우선)
2) 대체 발급·배포(rotate)  → 새 자격 발급·배포 (가용성 위해 폐기와 순서 조정 가능)
3) 영향·이력 조사          → 어디에 퍼졌나 + 노출 기간의 사용 이력·파생 세션 무효화
4) 히스토리 정리·통지      → 노출 위치 삭제는 보조, 필요 시 영향 통지
5) 재발 방지               → 어느 가드가 왜 놓쳤는지 → 규칙·테스트 보강

"히스토리에서 지웠으니 됐다"는 가장 위험한 착각입니다. 노출된 자격은 이미 노출된 것으로 간주하고 무효화하는 것이 원칙입니다. 다만 폐기는 향후 악용을 막을 뿐, 이미 발생한 접근·데이터 탈취·발급된 세션을 되돌리지는 못하므로 사용 이력 조사와 파생 세션 무효화가 함께 필요합니다. 자격을 단기·회전 가능하게 설계해 두면(자격 증명 관리), 이 대응이 훨씬 가벼워집니다.

10. 가드를 검증하는 네거티브 테스트

시크릿 가드는 틀리면 조용히 위험합니다(막는 줄 알았는데 안 막음). 그래서 "가드가 실제로 막는가"를 네거티브 테스트 (Negative Test) 로 검증합니다.

• 알려진 형식의 가짜 시크릿을 일부러 심어 커밋·쓰기·외부 전송을 시도 → 가드가 차단하는지 확인.
• git add && commit 체인 우회를 시도 → 여전히 막히는지.
• 스캔 도구가 없는 상황을 흉내 → fail-closed로 차단되는지("skip=pass"가 아님).
• 로그·에러에 시크릿을 흘려 → 마스킹되는지.

이런 "공격을 흉내 내는 테스트"는 MCP Server 보안 체크리스트의 네거티브 테스트 매트릭스와 같은 발상입니다. 막는다고 주장하는 것과 막는지 테스트하는 것은 다릅니다.

11. 체크리스트와 마무리

[ ] 시크릿을 값이 아니라 핸들/참조로 다뤄 에이전트 컨텍스트에서 뺐는가
[ ] 파일 쓰기 가드가 경로 차단 + 내용 스캔을 함께 하는가
[ ] 커밋 가드가 staged 스캔 + 체인 우회 차단 + fail-closed 인가
[ ] 탐지를 정규식·엔트로피·검증 스캐너·서버 CI로 다층화했는가
[ ] 로그·프롬프트·도구 인자·에러를 저장 전 마스킹하는가
[ ] 외부 전송에 스캔·마스킹·egress 통제를 적용했는가
[ ] 오탐 탈출구가 있고, 그 우회가 기록되는가
[ ] 유출 대응이 "히스토리 정리"가 아니라 "회전·폐기" 우선인가
[ ] 네거티브 테스트로 가드가 실제로 막는지 검증하는가

정리하면, AI 에이전트의 시크릿 가드는 한 겹의 커밋 훅이 아니라, 입력 경계부터 외부 전송까지 이어지는 층위입니다. 첫 줄은 언제나 "값이 아니라 핸들" — 에이전트가 원문을 본 적이 없으면 평문 직접 유출이 크게 줄어듭니다. 그다음 쓰기·커밋 가드로 저장소를, 마스킹으로 로그를, egress 게이트로 외부를 막고, 그래도 새면 폐기·회전과 사용 이력 조사로 피해를 제한합니다(이미 일어난 접근은 되돌릴 수 없으니 예방이 최선). 그리고 이 모든 가드는 네거티브 테스트로 살아 있음을 증명해야 합니다.

함께 읽으면 좋은 글: AI Agent 자격 증명 관리, AI Agent 감사 로그 설계, AI Agent 보안 설계 8경계, Prompt Injection 방어, MCP Server 보안 체크리스트.