Gemini CLI 훅(Hook)으로 AI 에이전트 실행 전에 ‘보안 브레이크’ 달기

― AI 에이전트 제어·보안·정책 자동화를 위한 핵심 메커니즘 ―

Gemini CLI 훅이란 무엇인가

Gemini CLI의 훅(Hook) 은 AI 에이전트가 동작하는 라이프사이클의 특정 지점에 사용자 정의 스크립트를 “동기적으로” 실행할 수 있도록 하는 기능입니다.

300x250

핵심 포인트는 다음과 같습니다.

• 에이전트의 행동 이전/이후에 개입 가능
• 훅이 완료될 때까지 에이전트는 대기
• 훅 결과(JSON 응답)에 따라
  • 작업 허용(allow)
  • 작업 차단(deny)
  • 프롬프트/응답/도구 변경
  • 컨텍스트 주입
• 단순 자동화가 아니라 정책 강제 수단

즉, “AI가 뭔가 하기 전에 보안·정책·검증을 먼저 통과시킨다”는 개념입니다.

왜 훅이 중요한가 (특히 기업·보안 환경)

일반적인 LLM 기반 CLI는 다음 문제가 있습니다.

• AI가 파일을 마음대로 수정
• API Key, 비밀정보를 그대로 파일에 기록
• rm, curl, bash 같은 위험 명령 실행
• 프롬프트 인젝션에 취약

훅은 이를 사전에 차단하는 ‘가드레일’ 역할을 합니다.

기존 AI CLI	Gemini CLI + Hook
결과 위주	과정 통제
사후 검증	사전 차단
사용자 책임	정책 자동 강제
로그 없음	중앙 로깅 가능

훅의 전체 구조 (아키텍처 관점)

사용자 입력
   ↓
[ SessionStart Hook ]
   ↓
[ BeforeAgent Hook ]
   ↓
에이전트 계획 수립
   ↓
[ BeforeModel Hook ]
   ↓
LLM 요청
   ↓
[ AfterModel Hook ]
   ↓
도구 선택
   ↓
[ BeforeTool Hook ]
   ↓
도구 실행
   ↓
[ AfterTool Hook ]
   ↓
[ AfterAgent Hook ]
   ↓
세션 종료
   ↓
[ SessionEnd Hook ]

✔️ 각 단계마다 완전히 다른 목적의 훅을 설계할 수 있습니다.

훅 이벤트 전체 분류 체계

세션(Session) 이벤트

세션 단위 초기화·정리용

이벤트	의미	활용 포인트
SessionStart	세션 시작	정책 로딩, 컨텍스트 주입
SessionEnd	세션 종료	로그 저장, 리소스 정리

보안 활용

• 프로젝트 보안 정책 문서 자동 로드
• 사용자 인증 상태 초기화
• 세션 단위 감사 로그 생성

에이전트(Agent) 이벤트

사용자 입력과 에이전트 판단을 통제

이벤트	개입 시점	보안 활용
BeforeAgent	입력 직후	위험 프롬프트 차단
AfterAgent	루프 종료	결과 검증·재시도

보안 활용

• “모든 파일 삭제해줘” 같은 입력 차단
• 특정 키워드 포함 프롬프트 deny
• 출력이 정책 위반이면 재시도 강제

모델(Model) 이벤트

LLM 요청·응답을 직접 조작

이벤트	개입 시점	활용
BeforeModel	LLM 호출 전	프롬프트 수정, 모델 변경
AfterModel	응답 후	민감 정보 제거

보안 활용

• 시스템 프롬프트에 정책 강제 삽입
• PII, 토큰, 내부 정보 마스킹
• 특정 요청은 로컬 모델로 전환

도구(Tool) 이벤트

실제 위험 행위가 발생하는 지점

이벤트	개입 시점	핵심 보안 역할
BeforeTool	실행 전	차단의 핵심
AfterTool	실행 후	결과 로깅·검증

보안 활용

• 파일 쓰기 전 내용 검사
• bash, rm, curl 제한
• 외부 네트워크 접근 차단

훅의 동작 방식 (기술적 메커니즘)

입력/출력 규칙

• 훅 스크립트는 stdin으로 JSON 입력
• stdout으로 JSON 출력
• stderr는 로깅 전용

제어 방식

{
  "decision": "allow | deny",
  "reason": "차단 사유",
  "systemMessage": "에이전트에게 전달할 메시지"
}

종료 코드

exit code	의미
0	정상 처리 (JSON 기반 제어)
2	즉시 강제 차단 (긴급)

보안 정책 주입의 핵심 패턴

비밀키·민감정보 차단 (가장 대표적)

BeforeTool + write_file / replace

#!/usr/bin/env bash
input=$(cat)
content=$(echo "$input" | jq -r '.tool_input.content // .tool_input.new_string // ""')

if echo "$content" | grep -qE 'api[_-]?key|password|secret|AKIA[0-9A-Z]{16}'; then
  echo '{"decision":"deny","reason":"비밀정보 탐지","systemMessage":"환경변수 사용 권장"}'
  exit 0
fi

echo '{"decision":"allow"}'

✔️ 효과

• 코드에 비밀정보 하드코딩 원천 차단
• 에이전트가 스스로 수정 유도

위험 명령 차단

BeforeAgent / BeforeTool

• rm -rf
• curl 외부 전송
• chmod 777
• bash 무제한 실행

{"decision":"deny","reason":"고위험 명령어 정책 위반"}

조직 정책 강제

• 사용자 홈(~/.gemini)
• 프로젝트(.gemini)
• 시스템(/etc/gemini-cli)

중앙 정책 예

• PII 로그 금지
• 외부 API 호출 제한
• 특정 도구 사용 불가

컨텍스트 주입 & 지능형 제어

동적 컨텍스트 주입

• Git 로그
• 프로젝트 상태
• 이전 세션 요약

AI가 “지금 맥락”을 이해한 상태로 동작

도구 필터링 (RAG 스타일)

• 프롬프트 의도 분석
• 관련 없는 도구 전부 제거

{ "mode": "NONE" }

✔️ 공격 표면 최소화

훅 설정 및 운영 관리

설정 위치

• 프로젝트: .gemini/settings.json
• 사용자: ~/.gemini/settings.json
• 조직: /etc/gemini-cli/settings.json

관리 포인트

• /hooks 명령으로 상태 확인
• 여러 훅 결과는 union 방식 병합
• 타임아웃 기본 60초 (DoS 방지)

실무에서 권장 조합 패턴

보안 중심 표준 템플릿

SessionStart  → 정책 로드
BeforeAgent  → 프롬프트 검증
BeforeModel  → 시스템 정책 주입
BeforeTool   → 실제 위험 차단
AfterTool    → 결과 로깅
AfterAgent   → 최종 검증
SessionEnd   → 감사 로그 저장

👉 “AI는 자유롭게 생각하되, 행동은 통제한다”는 구조

Gemini CLI 훅은 단순 커스터마이징 기능이 아니라
AI 에이전트를 ‘조직의 통제 하에 두기 위한 정책 실행 엔진’입니다.

특히 보안·운영·감사 요구사항이 있는 환경에서는 훅이 없는 AI CLI는 사실상 실무 사용이 어렵다고 봐도 무방합니다.