Zetsu

Персональная офлайн RAG-система для знаний в сфере атакующей безопасности. Импортируйте ваши writeup'ы, лабораторные решения, отчеты о баг-баунти и блоги по безопасности, затем задавайте вопросы на естественном языке в ходе пентестов. Никакого облака, никакого SaaS – ваши знания остаются вашими.

Что это делает

ZETSU превращает накопленные знания в помощника, которому можно задавать вопросы. Вместо того чтобы искать grep'ом по markdown-файлам или вспоминать, в каком writeup'е была та команда для certipy, вы просто спрашиваете:

how do i escalate with SeImpersonatePrivilege
what did i do after getting ADFS access
sliver socks5 pivot setup
explain ESC8 vs ESC4

Система сначала ищет в ваших реальных заметках, а затем генерирует ответ, основанный на задокументированном вами опыте, а не на общих интернет-знаниях.

Архитектура

Конвейер импорта (ingestion)

Конвейер запросов (query)

Возможности

• FARR-извлечение: во время импорта LLM читает каждый раздел ваших writeup'ов и извлекает структурированные шаги атаки (Finding, Action, Reasoning, Result). Вы получаете семантический блок, а не случайное окно из 800 токенов.
• Гибридный поиск: BM25 для точного совпадения токенов (имена инструментов, номера CVE, флаги CLI) + векторный поиск для семантического сходства. RRF-фузия объединяет оба подхода.
• Cross-encoder реранжировщик: переупорядочивает найденные блоки по реальной релевантности перед отправкой в LLM.
• Два стиля ответов: Режим Operator выводит точные команды, режим Concept – логику рассуждений. Один и тот же поиск, разная подача. Переключение по Ctrl+M в TUI.
• Несколько LLM-бэкендов: Anthropic, совместимые с OpenAI (DeepSeek и др.), или локальный Ollama. Раздельные бэкенды для импорта и запросов.
• Несколько типов источников: локальные markdown-файлы, одиночные URL, GitHub-вики, Atom/RSS-ленты.
• Постоянная история чатов: сохраняется в ~/.zetsu/history/YYYY-MM-DD.json, доступна по команде /history.
• TUI + Web UI + CLI: используйте то, что подходит к контексту. TUI – во время пентестов, Web UI – для изучения, CLI – для скриптов.

Установка

git clone https://github.com/chaelsoo/zetsu
cd zetsu
pip install -r requirements.txt

Настройте ваш API-ключ:

cp .env.example .env
# отредактируйте .env и добавьте ваш ключ

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

1. Добавьте ваши writeup'ы

Поместите .md файлы в docs/. Экспорты из Notion, заметки Obsidian, экспорты блогов – любой markdown подойдёт.

2. Настройте источники в config.toml

[llm]
backend      = "openai"
openai_model = "deepseek-chat"
base_url     = "https://api.deepseek.com/v1"

[[sources]]
type    = "markdown_dir"
path    = "./docs"
name    = "my_writeups"
extract = "farr"
enabled = true

3. Запустите импорт (ingest)

python zetsu.py ingest

4. Используйте

python zetsu.py tui       # терминальный интерфейс
python zetsu.py web       # браузер на localhost:8000
python zetsu.py ask "how do i abuse SeImpersonatePrivilege"

Справка по CLI

python zetsu.py ingest                 # импорт включённых источников
python zetsu.py ingest --force         # очистить и перестроить всё
python zetsu.py ingest --dry-run       # примерная оценка без вызовов LLM
python zetsu.py ingest --all-sources   # включить все источники независимо от флага enabled
python zetsu.py tui                    # терминальный интерфейс
python zetsu.py web                    # веб-интерфейс
python zetsu.py ask "query"            # разовый запрос через CLI
python zetsu.py ask "query" --style concept
python zetsu.py stats                  # статистика векторного хранилища

Горячие клавиши TUI

Типы источников

Режимы извлечения

• farr: LLM извлекает отдельные шаги атаки в виде структурированного JSON (Finding, Action, Reasoning, Result). Лучше всего подходит для writeup'ов с чёткими цепочками атак.
• farr+narrative: то же, что и farr, плюс прозаическое резюме, отражающее ход мыслей автора. Лучше всего для блогов, где важен процесс рассуждения.
• headers: без LLM, просто разбивка по заголовкам и сохранение текста как есть. Лучше всего для справочников по командам и документации инструментов.

LLM-бэкенды

Настройка в config.toml. Раздельные бэкенды для импорта (массовое извлечение) и запросов (генерация):

[llm]                          # время запроса
backend      = "openai"
openai_model = "deepseek-chat"
base_url     = "https://api.deepseek.com/v1"

[ingest]                       # время импорта
backend      = "openai"
openai_model = "deepseek-chat"
base_url     = "https://api.deepseek.com/v1"
workers      = 8               # параллельная обработка файлов при FARR-извлечении

Поддерживаемые бэкенды: anthropic, openai (любой API, совместимый с OpenAI), ollama.

[!IMPORTANT] По умолчанию ChromaDB запускается локально, что загружает весь векторный индекс в оперативную память. Для больших корпусов (10k+ блоков) или машин с ограниченной памятью настоятельно рекомендуется запускать ChromaDB как удалённый сервер. См. документацию ChromaDB server по настройке. Поддержка удалённого режима в ZETSU запланирована.

Бенчмарк

Оценка проведена на 910 вопросах, покрывающих 12 категорий атакующей безопасности (ADCS, Kerberos, перечисление AD, MSSQL, Sliver C2, повышение привилегий, веб-атаки, учётные данные, латеральное перемещение, облако/Entra ID, OPSEC, инструменты).

Основные источники, внесшие вклад в ответы: личные writeup'ы с HTB, блог dirkjanm, исследования shenaniganslabs, HackTricks ADCS, вики Sliver, шпаргалка netexec.

Простыми словами: нужно убедиться, что вы добавили хорошие и структурированные ресурсы, которые RAG будет импортировать. Этот проект на 100% сфокусирован на использовании базы знаний, а не на доверии памяти LLM или её обученным данным.

Полный набор данных для оценки и результаты в eval/.

Ссылки

• rank-bm25, поиск по BM25
• Концепция FARR из CIPHER
• RAG-пайплайн вдохновлён rag-chatbot

В ближайшее время я напишу в блоге об использовании и эффективности системы, следите за обновлениями.