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

섹션별 상세

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)에 권한 제어 훅을 등록하는 방법

용어 해설

도구 사용 전 훅(PreToolUse Hook): — AI 에이전트가 외부 도구(Bash, Read 등)를 실제로 실행하기 직전에 호출되는 가로채기 메커니즘이다. 이를 통해 실행될 명령어나 매개변수를 검증하고 승인 또는 거부 결정을 내릴 수 있어 보안 계층으로 활용된다.
경로 탐색 공격(Path Traversal): — 입력값에 '../'와 같은 상위 디렉토리 이동 문자를 포함시켜 의도하지 않은 파일 시스템 영역에 접근하는 보안 취약점이다. 이 프로젝트에서는 exclude_regex를 통해 이러한 패턴을 차단한다.
쉘 인젝션(Shell Injection): — 정상적인 명령어 뒤에 세미콜론(;)이나 파이프(|) 등을 추가하여 공격자가 의도한 임의의 명령어를 실행시키는 공격이다. 에이전트가 실행하는 Bash 명령어를 정규표현식으로 제한하여 이를 방지한다.
톰엘(TOML): — Tom's Obvious Minimal Language의 약자로, 사람이 읽기 쉽도록 설계된 구성 파일 형식이다. 키-값 쌍과 테이블 구조를 사용하여 복잡한 허용/거부 규칙을 명확하게 정의하는 데 사용된다.

기술

Rust
Claude Code
GPT-4o-mini
TOML
JSON

활용 사례

위험한 Bash 명령어(rm -rf 등) 실행 방지
민감한 파일(.env, secrets) 접근 차단
특정 프로젝트 경로 외부로의 접근 제한
에이전트 활동에 대한 보안 감사 로그 생성

언급된 리소스

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