Zetsu

Un sistema RAG personale offline per la conoscenza della sicurezza offensiva. Ingestisci i tuoi writeup, soluzioni di lab, report di bug bounty e blog di sicurezza, poi interroga in linguaggio naturale durante gli engagement. Nessun cloud, nessun SaaS, la tua conoscenza rimane tua.

Cosa fa

ZETSU trasforma la tua conoscenza accumulata in un assistente interrogabile. Invece di fare grep tra file markdown o ricordare in quale writeup c'era quel comando certipy, chiedi naturalmente:

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

Recupera prima dalle tue note reali, poi genera una risposta basata su ciò che hai documentato, non su conoscenza generica di Internet.

Architettura

Pipeline di ingestione

Pipeline di query

Funzionalità

• Estrazione FARR: al momento dell'ingestione, un LLM legge ogni sezione dei tuoi writeup ed estrae passaggi di attacco strutturati (Finding, Action, Reasoning, Result). Ciò che recuperi è un'unità semantica, non una finestra casuale di 800 token.
• Recupero ibrido: BM25 per il matching esatto dei token (nomi di tool, numeri CVE, flag CLI) + ricerca vettoriale per similarità semantica. La fusione RRF combina entrambi.
• Re-ranker cross-encoder: riordina i chunk recuperati in base alla rilevanza effettiva prima di inviarli all'LLM.
• Due stili di risposta: Modalità Operatore fornisce comandi esatti, Modalità Concetto fornisce ragionamenti. Stesso recupero, presentazione diversa. Attiva/disattiva con Ctrl+M nella TUI.
• Backend LLM multipli: Anthropic, compatibile OpenAI (DeepSeek, ecc.) o Ollama locale. Backend separati per ingest e query.
• Tipi di sorgente multipli: file markdown locali, URL singoli, wiki GitHub, feed Atom/RSS.
• Cronologia chat persistente: salvata in ~/.zetsu/history/YYYY-MM-DD.json, consultabile con /history.
• TUI + Web UI + CLI: usa ciò che si adatta al contesto. TUI durante gli engagement, Web UI per studiare, CLI per scripting.

Installazione

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

Configura la tua chiave API:

cp .env.example .env
# modifica .env e aggiungi la tua chiave

Avvio rapido

1. Aggiungi i tuoi writeup

Metti i file .md in docs/. Esportazioni da Notion, appunti Obsidian, esportazioni da blog, qualsiasi markdown funziona.

2. Configura le sorgenti in 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. Esegui l'ingestione

python zetsu.py ingest

4. Usalo

python zetsu.py tui       # interfaccia terminale
python zetsu.py web       # browser su localhost:8000
python zetsu.py ask "how do i abuse SeImpersonatePrivilege"

Riferimento CLI

python zetsu.py ingest                 # ingestisce le sorgenti abilitate
python zetsu.py ingest --force         # cancella e ricostruisce tutto
python zetsu.py ingest --dry-run       # stima senza effettuare chiamate LLM
python zetsu.py ingest --all-sources   # abilita tutte le sorgenti ignorando il flag enabled
python zetsu.py tui                    # interfaccia terminale
python zetsu.py web                    # interfaccia web
python zetsu.py ask "query"            # CLI monouso
python zetsu.py ask "query" --style concept
python zetsu.py stats                  # statistiche del vector store

Tasti rapidi della TUI

Tipi di sorgente

Modalità di estrazione

• farr: LLM estrae passaggi di attacco discreti come JSON strutturato (Finding, Action, Reasoning, Result). Ideale per writeup con chiare catene di attacco.
• farr+narrative: come farr, più un riepilogo in prosa che cattura il ragionamento dell'autore. Ideale per blog in cui conta il processo di pensiero.
• headers: nessun LLM, si divide solo in base agli header e si mantiene il testo originale. Ideale per riferimenti di comandi e documentazione di tool.

Backend LLM

Configura in config.toml. Backend separati per ingestione (estrazione in blocco) e query (generazione):

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

[ingest]                       # tempo di ingestione
backend      = "openai"
openai_model = "deepseek-chat"
base_url     = "https://api.deepseek.com/v1"
workers      = 8               # file paralleli durante l'estrazione FARR

Backend supportati: anthropic, openai (qualsiasi API compatibile con OpenAI), ollama.

[!IMPORTANT] ChromaDB viene eseguito localmente di default, caricando l'intero indice vettoriale in RAM. Per grandi corpora (10k+ chunk) o macchine con poca memoria, si consiglia vivamente di eseguire ChromaDB come server remoto. Vedi documentazione server ChromaDB per la configurazione. Il supporto remoto in ZETSU è pianificato.

Benchmark

Valutato su 910 domande che coprono 12 categorie di sicurezza offensiva (ADCS, Kerberos, enumerazione AD, MSSQL, Sliver C2, escalation dei privilegi, attacchi web, credenziali, movimento laterale, cloud/Entra ID, OPSEC, tool).

Principali sorgenti che hanno contribuito alle risposte: writeup personali di HTB, blog di dirkjanm, ricerche di shenaniganslabs, HackTricks ADCS, wiki di Sliver, cheatsheet di netexec.

In parole semplici, devi assicurarti di aggiungere risorse buone e strutturate che desideri che il RAG ingerisca; questo progetto si concentra al 100% sull'uso di una base di conoscenza, non sulla fiducia nella memoria dell'LLM o nella sua conoscenza pre-addestrata.

Set di valutazione completo e risultati in eval/.

Riferimenti

• rank-bm25, recupero BM25
• Concetto FARR da CIPHER
• Pipeline RAG ispirata da rag-chatbot

Presto documenterò in un blog l'utilizzo e l'efficacia, rimanete sintonizzati.