# Nova-tracer Skill

Adopt this skill: https://proskills.md/skills/automation/nova-tracer-skill

Page: https://proskills.md/skills/automation/nova-tracer-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .gitignore
upstream: https://github.com/nova-hunting/nova-tracer/blob/HEAD/.gitignore

Content is not inlined in the catalog. Read the upstream file: https://github.com/nova-hunting/nova-tracer/blob/HEAD/.gitignore

## File: LICENSE
upstream: https://github.com/nova-hunting/nova-tracer/blob/HEAD/LICENSE

Content is not inlined in the catalog. Read the upstream file: https://github.com/nova-hunting/nova-tracer/blob/HEAD/LICENSE

## File: README.md
upstream: https://github.com/nova-hunting/nova-tracer/blob/HEAD/README.md

````text
# Nova-tracer
### Agent Monitoring and Visibility

Security monitoring and prompt injection defense for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) using the [NOVA Framework](https://github.com/fr0gger/nova-framework).

## Features

- **Session Tracking** - Captures all tool usage with timestamps and metadata
- **Prompt Injection Detection** - Three-tier scanning (keywords, semantic ML, LLM) - *passive monitoring with warnings*
- **Dangerous Command Blocking** - Actively prevents destructive operations before execution
- **MCP & Skills Tracing** - Tracks MCP server calls and Agent Skills invocations with detailed breakdowns
- **Interactive HTML Reports** - Visual timeline, conversation trace, and expandable event details
- **AI-Powered Summaries** - Intelligent session summaries via Claude Haiku
- **Configurable** - Custom report locations, detection thresholds, and rules

## Quick Start

```bash
# 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
```

That's it! Nova-tracer will now protect all your Claude Code sessions.

## Installation

### Prerequisites

- **Python 3.10+**
- **UV** - Python package manager ([install](https://docs.astral.sh/uv/))
- **jq** - JSON processor (install via `brew install jq` on macOS)

### Install

```bash
./install.sh
```

The installer will:
1. Verify all prerequisites are installed
2. Register four Nova-tracer hooks in `~/.claude/settings.json`
3. Preserve any existing hooks you may have configured
4. Make hook scripts executable

### Uninstall

```bash
./uninstall.sh
```

The uninstaller will:
1. Remove only Nova-tracer hooks from settings.json
2. Preserve all other hooks and settings
3. Optionally clean up `.nova-tracer/` directories

## How It Works

Nova-tracer registers four Claude Code hooks that work together:

```
┌─────────────────────────────────────────────────────────────┐
│                    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/                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### Active vs Passive Protection

Nova-tracer provides two modes of protection:

| Mode | Hook | Behavior | Use Case |
|------|------|----------|----------|
| **ACTIVE** | PreToolUse | Blocks execution before it happens | Dangerous commands (`rm -rf /`, `sudo rm`, etc.) |
| **PASSIVE** | PostToolUse | Warns Claude after content is read | Prompt injection in files, web pages, command output |

**Important:** Prompt injection detection is **passive**. When Nova-tracer detects a prompt injection in a file or web page, the content has already been read by Claude. Nova-tracer sends a warning message to Claude advising it to treat the content with suspicion, but does not prevent Claude from seeing the malicious content.

This is a limitation of the PostToolUse hook architecture - it runs *after* the tool executes. Active blocking of prompt injections would require scanning content before Claude reads it, which would involve reading files twice (once to scan, once for Claude).

**What gets actively blocked:**
- Destructive commands: `rm -rf /`, `sudo rm -rf`, `mkfs`
- Dangerous operations: `dd if=... of=/dev/`, fork bombs
- Credential exfiltration: `curl ... | sh`, reading `~/.ssh/id_rsa`

**What gets passively warned:**
- Prompt injection in files (Read tool)
- Prompt injection in web pages (WebFetch tool)
- Prompt injection in command output (Bash tool)
- Prompt injection in MCP tool responses

### Three-Tier Detection

| Tier | Method | Speed | Catches |
|------|--------|-------|---------|
| **Keywords** | Regex patterns | ~1ms | Known attack patterns, exact phrases |
| **Semantics** | ML similarity | ~50ms | Paraphrased attacks, variations |
| **LLM** | AI evaluation | ~500-2000ms | Sophisticated, novel attacks |

### Attack Categories Detected

- **Instruction Override** - "Ignore all previous instructions", fake system prompts
- **Jailbreak/Role-Playing** - DAN attempts, persona switching
- **Encoding/Obfuscation** - Base64, hex, Unicode, leetspeak
- **Context Manipulation** - False authority claims, hidden instructions

## Usage

### Automatic Protection

Once installed, Nova-tracer works automatically:

1. **Start any Claude Code session** - SessionStart hook initializes tracking
2. **Use Claude normally** - All tool calls are monitored and scanned
3. **End your session** - SessionEnd hook generates an HTML report

### View Reports

Reports are saved to each project's `.nova-tracer/reports/` directory:

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

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

### Report Features

The interactive HTML report includes:

- **Session Summary** - Duration, tool counts, security events
- **AI Summary** - Intelligent 2-3 sentence description
- **Event Timeline** - Visual chronological view of all tool calls
- **Filtering** - Filter by tool type or NOVA verdict (allowed/warned/blocked)
- **Expandable Details** - Click any event to see full input/output
- **Nova-tracer Verdict Details** - Severity, matched rules, scan time

### Manual Testing

Test Nova-tracer detection without running Claude Code:

```bash
# 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
```

## Configuration

Nova-tracer works with sensible defaults, but you can customize behavior.

### Nova-tracer Protector Config

Edit `config/nova-tracer.yaml`:

```yaml
# 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/"
```

### Nova-tracer Scanning Config

Edit `config/nova-config.yaml`:

```yaml
# 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
```

### Environment Variables

```bash
# Required for AI 
````

## File: SKILL.md
upstream: https://github.com/nova-hunting/nova-tracer/blob/HEAD/SKILL.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/nova-hunting/nova-tracer/blob/HEAD/SKILL.md

## File: install.sh
upstream: https://github.com/nova-hunting/nova-tracer/blob/HEAD/install.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/nova-hunting/nova-tracer/blob/HEAD/install.sh

## File: uninstall.sh
upstream: https://github.com/nova-hunting/nova-tracer/blob/HEAD/uninstall.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/nova-hunting/nova-tracer/blob/HEAD/uninstall.sh