# Clone the repository
git clone https://github.com/fr0gger/nova-claude-code-protector.git
cd nova_claude_code_protector

# Install globally (registers hooks in ~/.claude/settings.json)
./install.sh

# Restart Claude Code to activate hooks

./install.sh

./uninstall.sh

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Session                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. SessionStart Hook                                        │
│     └── Creates session JSONL file                          │
│     └── Initializes tracking with session ID                │
│                                                              │
│  2. PreToolUse Hook (Bash, Write, Edit)           [ACTIVE]  │
│     └── Scans commands BEFORE execution                     │
│     └── BLOCKS dangerous operations (rm -rf, etc.)          │
│                                                              │
│  3. PostToolUse Hook (Read, Bash, WebFetch, etc.) [PASSIVE] │
│     └── Scans tool OUTPUT for prompt injection              │
│     └── WARNS Claude if threats detected                    │
│     └── Records event with NOVA verdict                     │
│                                                              │
│  4. SessionEnd Hook                                          │
│     └── Generates interactive HTML report                   │
│     └── Creates AI-powered session summary                  │
│     └── Saves to .nova-tracer/reports/                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

# List reports for current project
ls .nova-tracer/reports/

# Open a report in your browser
open .nova-tracer/reports/session-abc123.html

# Run sample attack tests
uv run hooks/test-nova-guard.py --samples

# Test specific text
uv run hooks/test-nova-guard.py --text "ignore previous instructions"

# Test a file
uv run hooks/test-nova-guard.py --file suspicious.txt

# Interactive mode
uv run hooks/test-nova-guard.py -i

# Report output directory
# Empty = {project}/.nova-tracer/reports/ (default)
# Relative path = relative to project
# Absolute path = exact location
report_output_dir: ""

# AI-powered session summaries
# Set to false to use stats-only summaries (no API calls)
ai_summary_enabled: true

# Maximum size in KB for tool outputs in reports
# Larger outputs will be truncated
output_truncation_kb: 10

# Directory for custom NOVA rules
custom_rules_dir: "rules/"

# LLM Provider for Tier 3 detection
llm_provider: anthropic
model: claude-3-5-haiku-20241022

# Detection tiers (enable/disable)
enable_keywords: true
enable_semantics: true
enable_llm: true

# Thresholds (0.0 - 1.0)
semantic_threshold: 0.7
llm_threshold: 0.7

# Severity filter
min_severity: low  # low, medium, or high

# Required for AI summaries and LLM-tier detection
export ANTHROPIC_API_KEY=sk-ant-...

rule MyCustomRule
{
    meta:
        description = "Detects my specific attack pattern"
        author = "Your Name"
        severity = "high"
        category = "custom"

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

    semantics:
        $sem1 = "semantic description of attack" (0.75)

    llm:
        $llm1 = "Question for LLM to evaluate" (0.7)

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

nova_claude_code_protector/
├── install.sh                    # Global installation script
├── uninstall.sh                  # Removal script
├── config/
│   ├── nova-config.yaml          # NOVA scanning configuration
├── rules/
│   ├── instruction_override.nov  # Override attack rules
│   ├── roleplay_jailbreak.nov    # Jailbreak attack rules
│   ├── encoding_obfuscation.nov  # Encoding attack rules
│   └── context_manipulation.nov  # Context attack rules
├── hooks/
│   ├── session-start.py          # SessionStart hook
│   ├── pre-tool-guard.py         # PreToolUse hook (blocking)
│   ├── post-tool-nova-guard.py   # PostToolUse hook (scanning)
│   ├── session-end.py            # SessionEnd hook (reports)
│   ├── test-nova-guard.py        # Testing utility
│   └── lib/
│       ├── session_manager.py    # Session tracking logic
│       ├── report_generator.py   # HTML report generation
│       ├── ai_summary.py         # AI summary generation
│       └── config.py             # Configuration management
├── tests/                        # Comprehensive test suite (483 tests)
└── test-files/                   # Sample injection files

# Clear model cache and retry
rm -rf ~/.cache/huggingface/
uv run hooks/test-nova-guard.py --samples

# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_report_generator.py -v

# Run with coverage
uv run pytest tests/ --cov=hooks/lib