Nova-tracer

Мониторинг агентов и видимость

Безопасность мониторинга и защита от инъекций подсказок для Claude Code с использованием NOVA Framework.

Возможности

• Отслеживание сессий — Захватывает все использования инструментов с временными метками и метаданными
• Обнаружение инъекций подсказок — Трехуровневое сканирование (ключевые слова, семантическое ML, LLM) - пассивный мониторинг с предупреждениями
• Блокировка опасных команд — Активно предотвращает разрушительные операции до их выполнения
• Трассировка MCP и навыков — Отслеживает вызовы MCP-серверов и вызовы навыков агентов с детальными разбивками
• Интерактивные HTML-отчеты — Визуальная временная шкала, трассировка разговора и раскрываемые детали событий
• Сводки на основе ИИ — Интеллектуальные сводки сессий через Claude Haiku
• Настраиваемость — Пользовательские расположения отчетов, пороги обнаружения и правила

Быстрый старт

# Клонировать репозиторий
git clone https://github.com/fr0gger/nova-claude-code-protector.git
cd nova_claude_code_protector

# Установить глобально (регистрирует хуки в ~/.claude/settings.json)
./install.sh

# Перезапустите Claude Code для активации хуков

Вот и все! Nova-tracer теперь будет защищать все ваши сессии Claude Code.

Установка

Предварительные требования

• Python 3.10+
• UV - Менеджер пакетов Python (установка)
• jq - Обработчик JSON (установить через brew install jq на macOS)

Установка

./install.sh

Установщик выполнит:

1. Проверку наличия всех предварительных требований
2. Регистрацию четырех хуков Nova-tracer в ~/.claude/settings.json
3. Сохранение любых существующих хуков, которые вы могли настроить
4. Установку прав на выполнение скриптов хуков

Удаление

./uninstall.sh

Удалятор выполнит:

1. Удаление только хуков Nova-tracer из settings.json
2. Сохранение всех остальных хуков и настроек
3. Опциональную очистку каталогов .nova-tracer/

Как это работает

Nova-tracer регистрирует четыре хука Claude Code, которые работают вместе:

┌─────────────────────────────────────────────────────────────┐
│                    Сессия Claude Code                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Хук SessionStart                                         │
│     └── Создает файл сессии JSONL                           │
│     └── Инициализирует отслеживание с идентификатором сессии│
│                                                              │
│  2. Хук PreToolUse (Bash, Write, Edit)            [АКТИВНЫЙ] │
│     └── Сканирует команды ДО выполнения                     │
│     └── БЛОКИРУЕТ опасные операции (rm -rf и т.д.)          │
│                                                              │
│  3. Хук PostToolUse (Read, Bash, WebFetch и др.) [ПАССИВНЫЙ]│
│     └── Сканирует ВЫВОД инструментов на предмет инъекций    │
│     └── ПРЕДУПРЕЖДАЕТ Claude при обнаружении угроз          │
│     └── Записывает событие с вердиктом NOVA                 │
│                                                              │
│  4. Хук SessionEnd                                           │
│     └── Генерирует интерактивный HTML-отчет                 │
│     └── Создает сводку сессии на основе ИИ                  │
│     └── Сохраняет в .nova-tracer/reports/                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Активная и пассивная защита

Nova-tracer предоставляет два режима защиты:

Режим	Хук	Поведение	Случай использования
АКТИВНЫЙ	PreToolUse	Блокирует выполнение до его начала	Опасные команды (rm -rf /, sudo rm и т.д.)
ПАССИВНЫЙ	PostToolUse	Предупреждает Claude после прочтения контента	Инъекции подсказок в файлах, веб-страницах, выводе команд

Важно: Обнаружение инъекций подсказок является пассивным. Когда Nova-tracer обнаруживает инъекцию подсказки в файле или веб-странице, контент уже был прочитан Claude. Nova-tracer отправляет предупреждение Claude, советуя относиться к содержимому с подозрением, но не предотвращает просмотр вредоносного содержимого Claude.

Это ограничение архитектуры хука PostToolUse — он выполняется после того, как инструмент отработал. Активная блокировка инъекций подсказок потребовала бы сканирования контента до того, как Claude его прочитает, что потребовало бы двукратного чтения файлов (один раз для сканирования, второй для Claude).

Что активно блокируется:

• Разрушительные команды: rm -rf /, sudo rm -rf, mkfs
• Опасные операции: dd if=... of=/dev/, форк-бомбы
• Экфильтрация учетных данных: curl ... | sh, чтение ~/.ssh/id_rsa

О чем пассивно предупреждается:

• Инъекции подсказок в файлах (инструмент Read)
• Инъекции подсказок на веб-страницах (инструмент WebFetch)
• Инъекции подсказок в выводе команд (инструмент Bash)
• Инъекции подсказок в ответах инструментов MCP

Трехуровневое обнаружение

Уровень	Метод	Скорость	Обнаруживает
Ключевые слова	Регекс-шаблоны	~1мс	Известные шаблоны атак, точные фразы
Семантика	ML-сходство	~50мс	Перефразированные атаки, вариации
LLM	Оценка ИИ	~500-2000мс	Сложные, новые атаки

Обнаруживаемые категории атак

• Переопределение инструкций — "Игнорируй все предыдущие инструкции", поддельные системные подсказки
• Джейлбрейк/Ролевая игра — Попытки DAN, переключение личности
• Кодирование/Обфускация — Base64, hex, Unicode, Leetspeak
• Манипуляция контекстом — Ложные заявления авторитета, скрытые инструкции

Использование

Автоматическая защита

После установки Nova-tracer работает автоматически:

1. Запустите любую сессию Claude Code — Хук SessionStart инициализирует отслеживание
2. Используйте Claude обычно — Все вызовы инструментов отслеживаются и сканируются
3. Завершите сессию — Хук SessionEnd генерирует HTML-отчет

Просмотр отчетов

Отчеты сохраняются в каталог .nova-tracer/reports/ каждого проекта:

# Список отчетов для текущего проекта
ls .nova-tracer/reports/

# Открыть отчет в браузере
open .nova-tracer/reports/session-abc123.html

Возможности отчета

Интерактивный HTML-отчет включает:

• Сводка сессии — Длительность, количество инструментов, события безопасности
• Сводка ИИ — Интеллектуальное описание в 2-3 предложения
• Временная шкала событий — Визуальное хронологическое представление всех вызовов инструментов
• Фильтрация — Фильтр по типу инструмента или вердикту NOVA (разрешено/предупреждено/заблокировано)
• Раскрываемые детали — Нажмите на любое событие, чтобы увидеть полный ввод/вывод
• Детали вердикта Nova-tracer — Серьезность, совпавшие правила, время сканирования

Ручное тестирование

Протестируйте обнаружение Nova-tracer без запуска Claude Code:

# Запустить образцы тестов атак
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

Конфигурация

Nova-tracer работает с разумными настройками по умолчанию, но вы можете настроить поведение.

Конфиг защиты Nova-tracer

Отредактируйте config/nova-tracer.yaml:

# Каталог вывода отчетов
# Пусто = {project}/.nova-tracer/reports/ (по умолчанию)
# Относительный путь = относительно проекта
# Абсолютный путь = точное расположение
report_output_dir: ""

# Сводки сессий на основе ИИ
# Установите false для использования сводок только по статистике (без вызовов API)
ai_summary_enabled: true