Zetsu

Un système RAG hors ligne personnel pour la connaissance en sécurité offensive. Ingérez vos writeups, solutions de labos, rapports de bug bounty et blogs de sécurité, puis interrogez-les en langage naturel lors de vos engagements. Pas de cloud, pas de SaaS, vos connaissances restent les vôtres.

Ce qu'il fait

ZETSU transforme vos connaissances accumulées en un assistant interrogeable. Au lieu de parcourir des fichiers markdown ou de vous rappeler quel writeup contenait cette commande certipy, vous demandez naturellement :

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

Il récupère d'abord dans vos notes réelles, puis génère une réponse fondée sur ce que vous avez documenté, et non sur des connaissances génériques d'Internet.

Architecture

Pipeline d'ingestion

Pipeline de requête

Fonctionnalités

• Extraction FARR : lors de l'ingestion, un LLM lit chaque section de vos writeups et extrait des étapes d'attaque structurées (Finding, Action, Reasoning, Result). Ce que vous récupérez est une unité sémantique, pas une fenêtre aléatoire de 800 tokens.
• Récupération hybride : BM25 pour la correspondance exacte de tokens (noms d'outils, numéros CVE, drapeaux CLI) + recherche vectorielle pour la similarité sémantique. La fusion RRF combine les deux.
• Re-ordonnancement par cross-encoder : réordonne les chunks récupérés par pertinence réelle avant de les envoyer au LLM.
• Deux styles de réponse : le mode Operator privilégie les commandes exactes, le mode Concept privilégie le raisonnement. Même récupération, présentation différente. Basculez avec Ctrl+M dans la TUI.
• Plusieurs backends LLM : Anthropic, compatible OpenAI (DeepSeek, etc.), ou Ollama local. Backends séparés pour l'ingestion et l'interrogation.
• Plusieurs types de sources : fichiers markdown locaux, URLs uniques, wikis GitHub, flux Atom/RSS.
• Historique persistant des conversations : sauvegardé dans ~/.zetsu/history/YYYY-MM-DD.json, consultable avec /history.
• TUI + Web UI + CLI : utilisez ce qui convient au contexte. TUI lors des engagements, Web UI pour étudier, CLI pour les scripts.

Installation

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

Configurez votre clé API :

cp .env.example .env
# éditez .env et ajoutez votre clé

Démarrage rapide

1. Ajoutez vos writeups

Déposez les fichiers .md dans docs/. Les exports Notion, notes Obsidian, exports de blog, tout ce qui est markdown fonctionne.

2. Configurez les sources dans 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. Ingérez

python zetsu.py ingest

4. Utilisez-le

python zetsu.py tui       # interface terminal
python zetsu.py web       # navigateur sur localhost:8000
python zetsu.py ask "how do i abuse SeImpersonatePrivilege"

Référence CLI

python zetsu.py ingest                 # ingérer les sources activées
python zetsu.py ingest --force         # tout effacer et reconstruire
python zetsu.py ingest --dry-run       # estimer sans appels LLM
python zetsu.py ingest --all-sources   # activer toutes les sources indépendamment du drapeau enabled
python zetsu.py tui                    # interface terminal
python zetsu.py web                    # interface web
python zetsu.py ask "query"            # CLI one-shot
python zetsu.py ask "query" --style concept
python zetsu.py stats                  # statistiques du vector store

Raccourcis TUI

Types de sources

Modes d'extraction

• farr : le LLM extrait des étapes d'attaque discrètes en JSON structuré (Finding, Action, Reasoning, Result). Idéal pour les writeups avec des chaînes d'attaque claires.
• farr+narrative : identique à farr, plus un résumé en prose capturant le raisonnement de l'auteur. Idéal pour les blogs où le processus de réflexion est important.
• headers : pas de LLM, juste une division sur les en-têtes et conservation textuelle. Idéal pour les références de commandes et la documentation d'outils.

Backends LLM

Configurez dans config.toml. Backends séparés pour l'ingestion (extraction en masse) et les requêtes (génération) :

[llm]                          # temps de requête
backend      = "openai"
openai_model = "deepseek-chat"
base_url     = "https://api.deepseek.com/v1"

[ingest]                       # temps d'ingestion
backend      = "openai"
openai_model = "deepseek-chat"
base_url     = "https://api.deepseek.com/v1"
workers      = 8               # fichiers en parallèle lors de l'extraction FARR

Backends supportés : anthropic, openai (toute API compatible OpenAI), ollama.

[!IMPORTANT] ChromaDB est exécuté localement par défaut, ce qui charge l'intégralité de l'index vectoriel en RAM. Pour les grands corpus (10k+ chunks) ou les machines à mémoire limitée, il est fortement recommandé d'exécuter ChromaDB en tant que serveur distant à la place. Voir la documentation du serveur ChromaDB pour la configuration. Le support distant dans ZETSU est prévu.

Benchmark

Évalué sur 910 questions couvrant 12 catégories de sécurité offensive (ADCS, Kerberos, AD enumeration, MSSQL, Sliver C2, escalade de privilèges, attaques web, credentials, mouvement latéral, cloud/Entra ID, OPSEC, outils).

Sources principales contribuant aux réponses : writeups personnels HTB, blog de dirkjanm, recherche de shenaniganslabs, HackTricks ADCS, wiki Sliver, antisèche netexec.

En termes simples, vous devez vous assurer d'ajouter des ressources bonnes et structurées que vous souhaitez que le RAG ingère. Ce projet se concentre à 100 % sur l'utilisation d'une base de connaissances, sans faire confiance à la mémoire du LLM ou à sa connaissance entraînée.

Jeu de données d'évaluation complet et résultats dans eval/.

Références

• rank-bm25, récupération BM25
• Concept FARR issu de CIPHER
• Pipeline RAG inspiré par rag-chatbot

Je vais documenter dans un blog l'utilisation et son efficacité très bientôt, restez à l'écoute.