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

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

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

Удаление

./uninstall.sh

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

Удаление только хуков Nova-tracer из settings.json
Сохранение всех остальных хуков и настроек
Опциональную очистку каталогов .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 предоставляет два режима защиты:

Важно: Обнаружение инъекций подсказок является пассивным. Когда 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

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

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

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

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

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

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

Запустите любую сессию Claude Code — Хук SessionStart инициализирует отслеживание
Используйте Claude обычно — Все вызовы инструментов отслеживаются и сканируются
Завершите сессию — Хук 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

# Максимальный размер в КБ для вывода инструментов в отчетах
# Выводы большего размера будут усечены
output_truncation_kb: 10

# Каталог пользовательских правил NOVA
custom_rules_dir: "rules/"

Конфиг сканирования Nova-tracer

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

# Поставщик 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

Переменные окружения

# Требуется для сводок ИИ и обнаружения на уровне LLM
export ANTHROPIC_API_KEY=sk-ant-...

Пользовательские правила

Создайте файлы .nov в каталоге rules/:

rule MyCustomRule
{
    meta:
        description = "Обнаруживает мой специфический шаблон атаки"
        author = "Ваше Имя"
        severity = "high"
        category = "custom"

    keywords:
        $pattern1 = /my regex pattern/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         # Генерация сводок ИИ
│       └── config.py             # Управление конфигурацией
├── tests/                        # Комплексный набор тестов (483 теста)
└── test-files/                   # Примеры файлов с инъекциями

Устранение неполадок

Хуки не активируются

Проверьте установку: cat ~/.claude/settings.json | jq '.hooks'
Полностью перезапустите Claude Code (закройте и откройте заново)
Убедитесь, что скрипты хуков исполняемы: ls -la hooks/*.py

Отчеты не генерируются

Проверьте наличие активной сессии: ls .nova-tracer/sessions/
Убедитесь в правах на запись в каталоге проекта
Проверьте stderr на ошибки во время завершения сессии

Модели ML не загружаются

При первом запуске загружается ~1 ГБ моделей. Если возникли проблемы:

# Очистить кеш моделей и повторить
rm -rf ~/.cache/huggingface/
uv run hooks/test-nova-guard.py --samples

Сводки ИИ не работают

Проверьте ключ API: echo $ANTHROPIC_API_KEY
Убедитесь, что ai_summary_enabled: true в конфиге
В качестве запасного варианта используются сводки только по статистике

Разработка

Запуск тестов

# Запустить все тесты
uv run pytest tests/ -v

# Запустить конкретный файл тестов
uv run pytest tests/test_report_generator.py -v

# Запустить с покрытием
uv run pytest tests/ --cov=hooks/lib

Покрытие тестами

483 теста, покрывающих все функциональности
Управление сессиями, генерация отчетов, сводки ИИ
Загрузка конфигурации, скрипты установки
Проверены все критерии приемки

Лицензия

Лицензия MIT - См. LICENSE

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

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

nova-tracer

Популярное

Nova-tracer

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

Возможности

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

Установка

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

Установка

Удаление

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

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

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

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

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

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

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

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

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

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

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

Конфиг сканирования Nova-tracer

Переменные окружения

Пользовательские правила

Структура файлов

Устранение неполадок

Хуки не активируются

Отчеты не генерируются

Модели ML не загружаются

Сводки ИИ не работают

Разработка

Запуск тестов

Покрытие тестами

Лицензия