Claude Code를 위한 세밀한 명령 권한 제어 훅: claude-code-permissions-hook

핵심 요약

Claude Code의 현재 권한 제어 시스템이 가진 일관성 부족 문제를 해결하기 위해 개발된 Rust 기반의 PreToolUse 훅이다. 사용자는 TOML 설정 파일을 통해 허용 및 거부 규칙을 정규표현식으로 정의하여 Bash 명령어 실행이나 파일 접근을 세밀하게 통제할 수 있다. 정적 규칙으로 판단하기 어려운 경우 LLM(GPT-4o-mini)에게 안전성 판단을 위임하는 기능을 포함하며, 모든 결정 과정을 JSON 파일로 기록하여 보안 감사를 지원한다. Anthropic의 훅 가이드라인을 준수하여 제작되었으며, Claude Code 설정에 간단히 추가하여 즉시 적용 가능하다.

배경

Rust 및 cargo 설치, Claude Code 설치 및 기본 설정 지식, 정규표현식(Regex)에 대한 이해, OpenAI API 키 (LLM 위임 기능 사용 시)

대상 독자

Claude Code를 프로덕션이나 민감한 코드베이스에서 사용하는 개발자 및 보안 엔지니어

의미 / 영향

AI 코딩 에이전트의 자율성이 높아짐에 따라 발생할 수 있는 보안 사고를 방지하기 위한 실질적인 제어 계층을 제시한다. 특히 정적 규칙과 LLM 판단을 결합한 하이브리드 보안 모델은 향후 에이전트 보안 프레임워크의 표준적인 접근 방식이 될 가능성이 크다.

섹션별 상세

Claude Code의 도구 사용을 제어하는 PreToolUse 훅으로, Anthropic의 가이드라인에 따라 Rust로 구현되었다. 현재 Claude Code의 Bash 권한 설정이 일관되지 않은 문제를 해결하기 위한 워크라운드 성격의 도구이다.

TOML 설정 파일을 통해 allow와 deny 규칙을 정의하며, 정규표현식을 사용하여 도구 입력값을 필터링한다. file_path_regex나 command_regex를 사용하여 특정 경로 접근이나 위험한 명령을 차단하고, exclude_regex로 경로 탐색(..)이나 쉘 인젝션 기호를 방지한다.

toml

[[allow]]
tool = "Bash"
command_regex = "^cargo (build|test|check|clippy|fmt|run)"
command_exclude_regex = "&|;|\\||`|\\$\\(" # Block shell injection

[[deny]]
tool = "Bash"
command_regex = "^rm .*-rf"

TOML 파일을 사용해 특정 Bash 명령어는 허용하고 위험한 삭제 명령은 거부하는 규칙 설정 예시

정적 규칙에 매칭되지 않는 모호한 상황에서 LLM(기본값 gpt-4o-mini)에게 도구 사용의 안전성 판단을 요청하는 위임 기능을 제공한다. LLM이 안전하다고 판단하면 실행을 허용하고, 그렇지 않으면 기본 권한 흐름으로 넘긴다.

도구 사용 결정 과정을 JSON 파일에 기록하는 감사 기능을 지원한다. audit_level 설정을 통해 규칙에 매칭된 항목만 기록하거나 모든 활동을 기록하도록 선택할 수 있어 사후 보안 점검과 모니터링이 용이하다.

Rust 언어로 작성되어 cargo를 통해 빌드하며, 생성된 바이너리를 Claude Code의 settings.json에 등록하여 사용한다. 설정 유효성 검사(validate) 모드와 실제 훅 실행(run) 모드를 모두 지원한다.

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/claude-code-permissions-hook run --config ~/.config/claude-code-permissions-hook.toml"
          }
        ]
      }
    ]
  }
}

Claude Code 설정 파일(.claude/settings.json)에 권한 제어 훅을 등록하는 방법

실무 Takeaway

Claude Code의 기본 권한 설정이 부족한 환경에서 정규표현식 기반의 TOML 규칙을 적용하여 위험한 Bash 명령어나 파일 접근을 사전에 차단할 수 있다.
정적 규칙으로 정의하기 어려운 복잡한 보안 판단은 LLM 위임 기능을 활성화하여 gpt-4o-mini가 실시간으로 안전성을 검토하게 함으로써 유연성과 보안성을 동시에 확보한다.
보안이 중요한 기업 환경에서는 감사 로그 수준을 'all'로 설정하여 Claude Code가 수행하는 모든 도구 호출과 권한 결정 내역을 JSON으로 추적하고 관리해야 한다.

언급된 리소스

GitHubclaude-code-permissions-hook GitHub (추정)

[[allow]] tool = "Bash" command_regex = "^cargo (build|test|check|clippy|fmt|run)" command_exclude_regex = "&|;|\\||`|\\$\\(" # Block shell injection [[deny]] tool = "Bash" command_regex = "^rm .*-rf"

{ "hooks": { "PreToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "/path/to/claude-code-permissions-hook run --config ~/.config/claude-code-permissions-hook.toml" } ] } ] } }

Claude Code를 위한 세밀한 명령 권한 제어 훅: claude-code-permissions-hook

핵심 요약

배경

대상 독자

의미 / 영향

섹션별 상세

실무 Takeaway

언급된 리소스

Claude Code를 위한 세밀한 명령 권한 제어 훅: claude-code-permissions-hook

핵심 요약

배경

대상 독자

의미 / 영향

섹션별 상세

실무 Takeaway

언급된 리소스

관련 피드

관련 토론

댓글

관련 피드

관련 토론

댓글