Zetsu

Ein persönliches, offline RAG-System für sicherheitsrelevantes Wissen aus dem Offensivbereich. Erfasse deine Write-ups, Übungslösungen, Bug-Bounty-Berichte und Sicherheitsblogs – und stelle während Engagements Fragen in natürlicher Sprache. Keine Cloud, kein SaaS, dein Wissen bleibt deins.

Was es macht

ZETSU verwandelt dein gesammeltes Wissen in einen abfragbaren Assistenten. Statt durch Markdown-Dateien zu grepgen oder sich zu erinnern, welches Write-up diesen certipy-Befehl enthielt, fragst du einfach:

wie eskalierende ich mit SeImpersonatePrivilege
was habe ich nach dem ADFS-Zugriff gemacht
sliver socks5 pivot setup
erkläre ESC8 vs ESC4

Es ruft zuerst aus deinen eigenen Notizen ab und generiert dann eine Antwort, die auf dem basiert, was du dokumentiert hast – nicht auf allgemeinem Internetwissen.

Architektur

Erfassungspipeline

Abfragepipeline

Funktionen

• FARR-Extraktion: Ein LLM liest bei der Erfassung jeden Abschnitt deiner Write-ups und extrahiert strukturierte Angriffsschritte (Finding, Action, Reasoning, Result). Du erhältst eine semantische Einheit, kein zufälliges 800-Token-Fenster.
• Hybride Abfrage: BM25 für exaktes Token-Matching (Toolnamen, CVE-Nummern, CLI-Flags) + Vektorsuche für semantische Ähnlichkeit. RRF-Fusion kombiniert beide.
• Cross-Encoder-Reranker: Ordnet gefundene Chunks vor der LLM-Anfrage nach tatsächlicher Relevanz neu.
• Zwei Antwortstile: Operator-Modus liefert zuerst die exakten Befehle, Konzept-Modus zuerst die Begründung. Gleiche Abfrage, andere Darstellung. Umschalten mit Ctrl+M in der TUI.
• Mehrere LLM-Backends: Anthropic, OpenAI-kompatibel (DeepSeek, etc.) oder lokales Ollama. Getrennte Backends für Erfassung und Abfrage.
• Mehrere Quelltypen: lokale Markdown-Dateien, einzelne URLs, GitHub-Wikis, Atom/RSS-Feeds.
• Beständiger Chat-Verlauf: gespeichert unter ~/.zetsu/history/YYYY-MM-DD.json, durchsuchbar mit /history.
• TUI + Web-UI + CLI: Nutze, was zum Kontext passt. TUI während Engagements, Web-UI zum Lernen, CLI für Skripte.

Installation

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

Richte deinen API-Schlüssel ein:

cp .env.example .env
# .env bearbeiten und deinen Schlüssel eintragen

Schnellstart

1. Write-ups hinzufügen

.md-Dateien in docs/ ablegen. Notion-Exporte, Obsidian-Notizen, Blog-Exporte – alles, was Markdown ist, funktioniert.

2. Quellen in config.toml konfigurieren

[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. Erfassen

python zetsu.py ingest

4. Nutzen

python zetsu.py tui       # Terminal-UI
python zetsu.py web       # Browser unter localhost:8000
python zetsu.py ask "wie kann ich SeImpersonatePrivilege missbrauchen"

CLI-Referenz

python zetsu.py ingest                 # aktivierte Quellen erfassen
python zetsu.py ingest --force         # Alles löschen und neu aufbauen
python zetsu.py ingest --dry-run       # Schätzung ohne LLM-Aufrufe
python zetsu.py ingest --all-sources   # Alle Quellen aktivieren, unabhängig vom enabled-Flag
python zetsu.py tui                    # Terminal-UI
python zetsu.py web                    # Web-UI
python zetsu.py ask "query"            # Einmalige CLI
python zetsu.py ask "query" --style concept
python zetsu.py stats                  # Vektor-Store-Statistiken

TUI-Tastenkürzel

Quelltypen

Extraktionsmodi

• farr: LLM extrahiert einzelne Angriffsschritte als strukturiertes JSON (Finding, Action, Reasoning, Result). Am besten für Write-ups mit klaren Angriffsketten.
• farr+narrative: Wie farr, plus eine Prosa-Zusammenfassung, die den Gedankengang des Autors erfasst. Am besten für Blogs, bei denen der Denkprozess wichtig ist.
• headers: Kein LLM – nur Aufteilung anhand von Überschriften und wörtliche Übernahme. Am besten für Befehlsreferenzen und Tool-Dokumentationen.

LLM-Backends

Konfiguriere in config.toml. Getrennte Backends für die Erfassung (Massenextraktion) und Abfragen (Generierung):

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

[ingest]                       # Erfassungszeit
backend      = "openai"
openai_model = "deepseek-chat"
base_url     = "https://api.deepseek.com/v1"
workers      = 8               # Parallele Dateien während der FARR-Extraktion

Unterstützte Backends: anthropic, openai (jede OpenAI-kompatible API), ollama.

[!IMPORTANT] ChromaDB wird standardmäßig lokal ausgeführt und lädt den gesamten Vektorindex in den Arbeitsspeicher. Bei großen Sammlungen (10.000+ Chunks) oder speicherbegrenzten Maschinen wird dringend empfohlen, ChromaDB stattdessen als Remote-Server zu betreiben. Siehe ChromaDB-Server-Dokumentation zur Einrichtung. Remote-Unterstützung in ZETSU ist geplant.

Benchmark

Ausgewertet über 910 Fragen aus 12 Kategorien der Offensiv-Sicherheit (ADCS, Kerberos, AD-Enumeration, MSSQL, Sliver C2, Privilegienerweiterung, Web-Angriffe, Credentials, laterale Bewegung, Cloud/Entra ID, OPSEC, Tools).

Wichtigste Quellen für die Antworten: persönliche HTB-Write-ups, dirkjanm-Blog, shenaniganslabs-Forschung, HackTricks ADCS, Sliver-Wiki, netexec-Spickzettel.

Einfach gesagt: Du musst sicherstellen, dass du gute und strukturierte Ressourcen einfügst, die das RAG erfassen soll – dieses Projekt konzentriert sich zu 100 % auf die Nutzung einer Wissensdatenbank und vertraut nicht auf das Gedächtnis des LLM oder auf antrainiertes Wissen.

Vollständiger Evaluierungsdatensatz und Ergebnisse in eval/.

Referenzen

• rank-bm25, BM25-Abfrage
• FARR-Konzept aus CIPHER
• RAG-Pipeline inspiriert von rag-chatbot

Ich werde in einem Blog-Beitrag die Nutzung und Effektivität in Kürze dokumentieren – bleibt dran.