---
title: "nah — Claude Code용 컨텍스트 인식 권한 가드"
published: 2026-03-11T23:26:25.000Z
canonical: https://jeff.news/article/437
---
# nah — Claude Code용 컨텍스트 인식 권한 가드

Claude Code의 도구별 허용/거부 방식의 한계를 해결하는 오픈소스 보안 가드로, 명령어가 실제로 수행하는 동작을 기준으로 컨텍스트 인식 분류를 수행함

## 왜 필요한가

- Claude Code의 기본 권한 시스템은 도구(tool)별 허용/거부 방식인데, 이게 현실에서 안 돌아감. 파일 삭제가 어떤 때는 괜찮고 어떤 때는 치명적이니까. `git checkout`도 마찬가지임
- `--dangerously-skip-permissions` 옵션을 쓰면 편하긴 한데, 추적 안 되는 파일 날리거나 키 유출시키거나 멀웨어 깔리는 건 감수해야 함
- **nah**는 도구 호출(tool call)이 실행되기 **전에** 가로채서, 명령어 이름이 아니라 **실제로 뭘 하는지** 기준으로 분류하는 오픈소스 가드임 (MIT 라이선스)

> [!TIP]
> 같은 `rm` 명령이라도 `rm dist/bundle.js`(프로젝트 내부)는 허용, `rm ~/.bashrc`(프로젝트 외부)는 확인 요청으로 처리됨. 컨텍스트가 정책을 결정하는 구조임.

## 작동 방식

- 모든 도구 호출은 먼저 **결정론적 구조 분류기(deterministic structural classifier)**를 거침. LLM 없이 밀리초 단위로 판단함
- 분류기가 결정 못 하는 애매한 경우에만 선택적으로 LLM에 넘김. LLM이 없거나 응답 불가면 사용자에게 직접 물어봄
- 지원 LLM 프로바이더: Ollama, OpenRouter, OpenAI, Anthropic, Snowflake Cortex

## 가드 대상 도구 7종

- **Bash**: 명령어 구조 분류 — 액션 타입, 파이프 구성, 셸 언래핑까지 분석
- **Read**: 민감 경로 탐지 (`~/.ssh`, `~/.aws`, `.env` 등)
- **Write**: 경로 + 프로젝트 경계 + 콘텐츠 검사 (비밀정보, 유출 페이로드, 파괴적 내용)
- **Edit**: 교체 문자열에 대한 경로 + 콘텐츠 검사
- **Glob / Grep**: 민감 디렉터리 스캐닝이나 프로젝트 외부 인증정보 검색 패턴 차단
- **MCP 도구**: 서드파티 툴 서버(`mcp__*`)에 대한 범용 분류

## 정책 체계

- 23개 내장 액션 타입이 있고, 각각 기본 정책이 있음:
  - **allow**: `filesystem_read`, `git_safe`, `package_run` 등
  - **context**: 경로/프로젝트 상황 보고 결정 — `filesystem_write`, `filesystem_delete`, `network_outbound` 등
  - **ask**: 항상 사용자에게 확인 — `git_history_rewrite`, `git_remote_write` 등
  - **block**: 무조건 차단 — `obfuscated` (예: `base64 -d | bash`)
- 프리셋 3단계: `full`(기본, 포괄적), `minimal`(핵심만), `none`(빈 상태에서 직접 구성)

> [!IMPORTANT]
> 프로젝트 `.nah.yaml`로 정책을 **강화**할 수는 있지만, **완화**는 불가능함. 악성 레포가 `.nah.yaml`로 위험 명령을 허용 목록에 넣는 건 원천 차단됨. 전역 설정만 완화 권한이 있음.

## 설치와 사용

- `nah install`로 `settings.json`에 등록하면 모든 Claude 세션에 자동 적용. `nah uninstall`로 제거
- `nah claude`로 훅을 인라인 전달해서 해당 프로세스에만 적용하는 것도 가능
- 보안 데모 내장: 8개 위협 카테고리에 걸친 25개 라이브 케이스로 테스트 가능 (원격 코드 실행, 데이터 유출, 난독화 명령 등). 약 5분 소요

## 핵심 포인트

- 결정론적 구조 분류기가 밀리초 단위로 판단, 애매한 경우만 선택적 LLM 폴백
- Bash, Read, Write, Edit, Glob, Grep, MCP 도구 등 7종 가드
- 23개 내장 액션 타입과 allow/context/ask/block 4단계 정책
- 프로젝트 .nah.yaml로 정책 강화만 가능, 완화는 전역 설정에서만 허용
- 8개 위협 카테고리 25개 케이스의 보안 데모 내장

## 인사이트

AI 코딩 에이전트의 권한 관리 문제를 명령어 이름이 아닌 실제 동작 기준으로 해결하는 접근이 인상적. 프로젝트 설정으로 정책 완화를 차단한 보안 설계도 실용적임