# 저장소 복제
git clone https://github.com/fr0gger/nova-claude-code-protector.git
cd nova_claude_code_protector

# 전역 설치 (~/.claude/settings.json에 후크 등록)
./install.sh

# Claude Code를 다시 시작하여 후크 활성화

./install.sh

./uninstall.sh

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code 세션                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. SessionStart 후크                                        │
│     └── 세션 JSONL 파일 생성                                 │
│     └── 세션 ID로 추적 초기화                                │
│                                                              │
│  2. PreToolUse 후크 (Bash, Write, Edit)           [ACTIVE]  │
│     └── 명령어 실행 전에 스캔                                │
│     └── 위험한 작업 차단 (rm -rf 등)                         │
│                                                              │
│  3. PostToolUse 후크 (Read, Bash, WebFetch 등) [PASSIVE] │
│     └── 도구 출력에서 프롬프트 인젝션 스캔                  │
│     └── 위협이 감지되면 Claude에 경고                        │
│     └── NOVA 판정과 함께 이벤트 기록                         │
│                                                              │
│  4. SessionEnd 후크                                          │
│     └── 대화형 HTML 보고서 생성                              │
│     └── AI 기반 세션 요약 생성                               │
│     └── .nova-tracer/reports/에 저장                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

# 현재 프로젝트의 보고서 목록 보기
ls .nova-tracer/reports/

# 브라우저에서 보고서 열기
open .nova-tracer/reports/session-abc123.html

# 샘플 공격 테스트 실행
uv run hooks/test-nova-guard.py --samples

# 특정 텍스트 테스트
uv run hooks/test-nova-guard.py --text "이전 지시사항 무시"

# 파일 테스트
uv run hooks/test-nova-guard.py --file suspicious.txt

# 대화형 모드
uv run hooks/test-nova-guard.py -i

# 보고서 출력 디렉터리
# 비어 있음 = {project}/.nova-tracer/reports/ (기본값)
# 상대 경로 = 프로젝트 기준 상대 경로
# 절대 경로 = 정확한 위치
report_output_dir: ""

# AI 기반 세션 요약
# false로 설정하면 통계 전용 요약 사용 (API 호출 없음)
ai_summary_enabled: true

# 보고서 내 도구 출력 최대 크기 (KB)
# 더 큰 출력은 잘림
output_truncation_kb: 10

# 사용자 정의 NOVA 규칙 디렉터리
custom_rules_dir: "rules/"

# 계층 3 탐지를 위한 LLM 제공자
llm_provider: anthropic
model: claude-3-5-haiku-20241022

# 탐지 계층 (활성화/비활성화)
enable_keywords: true
enable_semantics: true
enable_llm: true

# 임계값 (0.0 ~ 1.0)
semantic_threshold: 0.7
llm_threshold: 0.7

# 심각도 필터
min_severity: low  # low, medium, high

# AI 요약 및 LLM 계층 탐지에 필요
export ANTHROPIC_API_KEY=sk-ant-...

rule MyCustomRule
{
    meta:
        description = "내 특정 공격 패턴 탐지"
        author = "사용자 이름"
        severity = "high"
        category = "custom"

    keywords:
        $pattern1 = /내 정규식 패턴/i
        $pattern2 = "정확한 문자열 일치"

    semantics:
        $sem1 = "공격의 의미론적 설명" (0.75)

    llm:
        $llm1 = "LLM이 평가할 질문" (0.7)

    condition:
        any of ($pattern*) or $sem1 or $llm1
}

nova_claude_code_protector/
├── install.sh                    # 전역 설치 스크립트
├── uninstall.sh                  # 제거 스크립트
├── config/
│   ├── nova-config.yaml          # NOVA 스캔 구성
├── rules/
│   ├── instruction_override.nov  # 명령어 재정의 공격 규칙
│   ├── roleplay_jailbreak.nov    # 탈옥 공격 규칙
│   ├── encoding_obfuscation.nov  # 인코딩 공격 규칙
│   └── context_manipulation.nov  # 컨텍스트 공격 규칙
├── hooks/
│   ├── session-start.py          # SessionStart 후크
│   ├── pre-tool-guard.py         # PreToolUse 후크 (차단)
│   ├── post-tool-nova-guard.py   # PostToolUse 후크 (스캔)
│   ├── session-end.py            # SessionEnd 후크 (보고서)
│   ├── test-nova-guard.py        # 테스트 유틸리티
│   └── lib/
│       ├── session_manager.py    # 세션 추적 로직
│       ├── report_generator.py   # HTML 보고서 생성
│       ├── ai_summary.py         # AI 요약 생성
│       └── config.py             # 구성 관리
├── tests/                        # 종합 테스트 스위트 (483개 테스트)
└── test-files/                   # 샘플 인젝션 파일

# 모델 캐시를 지우고 재시도
rm -rf ~/.cache/huggingface/
uv run hooks/test-nova-guard.py --samples

# 모든 테스트 실행
uv run pytest tests/ -v

# 특정 테스트 파일 실행
uv run pytest tests/test_report_generator.py -v

# 커버리지와 함께 실행
uv run pytest tests/ --cov=hooks/lib