# 克隆仓库
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 "ignore previous instructions"

# 测试文件
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/"

# 三级检测的 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, or high

# AI 摘要和 LLM 层级检测必需
export ANTHROPIC_API_KEY=sk-ant-...

rule MyCustomRule
{
    meta:
        description = "检测我的特定攻击模式"
        author = "你的名字"
        severity = "high"
        category = "custom"

    keywords:
        $pattern1 = /my regex pattern/i
        $pattern2 = "exact string match"

    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