Zetsu

Um sistema RAG offline pessoal para conhecimento em segurança ofensiva. Ingira seus writeups, soluções de laboratório, relatórios de bug bounty e blogs de segurança, depois consulte-os em linguagem natural durante os engajamentos. Sem nuvem, sem SaaS, seu conhecimento permanece seu.

O que faz

ZETSU transforma seu conhecimento acumulado em um assistente consultável. Em vez de grep em arquivos markdown ou lembrar qual writeup tinha aquele comando do certipy, você pergunta naturalmente:

como faço para escalar com SeImpersonatePrivilege
o que fiz depois de obter acesso ao ADFS
configuração de socks5 pivot no sliver
explique ESC8 vs ESC4

Ele recupera primeiro das suas anotações reais e depois gera uma resposta fundamentada no que você documentou, não em conhecimento genérico da internet.

Arquitetura

Pipeline de ingestão

Pipeline de consulta

Funcionalidades

• Extração FARR: no momento da ingestão, um LLM lê cada seção dos seus writeups e extrai passos de ataque estruturados (Finding, Action, Reasoning, Result). O que você recupera é uma unidade semântica, não uma janela aleatória de 800 tokens.
• Recuperação híbrida: BM25 para correspondência exata de tokens (nomes de ferramentas, números CVE, flags de CLI) + busca vetorial para similaridade semântica. Fusão RRF combina ambos.
• Reordenador cross-encoder: reordena os chunks recuperados por relevância real antes de enviar ao LLM.
• Dois estilos de resposta: Modo Operador exibe comandos exatos primeiro, Modo Conceito exibe raciocínio primeiro. Mesma recuperação, apresentação diferente. Alterne com Ctrl+M na TUI.
• Múltiplos backends LLM: Anthropic, compatível com OpenAI (DeepSeek, etc.), ou Ollama local. Backends separados para ingestão e consulta.
• Múltiplos tipos de fonte: arquivos markdown locais, URLs únicas, wikis do GitHub, feeds Atom/RSS.
• Histórico de chat persistente: salvo em ~/.zetsu/history/YYYY-MM-DD.json, navegável com /history.
• TUI + Web UI + CLI: use o que se adequa ao contexto. TUI durante engajamentos, Web UI para estudar, CLI para scripts.

Instalação

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

Configure sua chave de API:

cp .env.example .env
# edite .env e adicione sua chave

Início rápido

1. Adicione seus writeups

Coloque arquivos .md em docs/. Exportações do Notion, anotações do Obsidian, exportações de blog, qualquer markdown funciona.

2. Configure as fontes em config.toml

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

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

3. Ingira

python zetsu.py ingest

4. Use

python zetsu.py tui       # interface de terminal
python zetsu.py web       # navegador em localhost:8000
python zetsu.py ask "como faço para abusar de SeImpersonatePrivilege"

Referência CLI

python zetsu.py ingest                 # ingira fontes habilitadas
python zetsu.py ingest --force         # limpe e reconstrua tudo
python zetsu.py ingest --dry-run       # estime sem fazer chamadas LLM
python zetsu.py ingest --all-sources   # habilite todas as fontes independentemente da flag enabled
python zetsu.py tui                    # interface de terminal
python zetsu.py web                    # interface web
python zetsu.py ask "consulta"            # CLI de uso único
python zetsu.py ask "consulta" --style concept
python zetsu.py stats                  # estatísticas do store vetorial

Atalhos da TUI

Tipos de fonte

Modos de extração

• farr: LLM extrai passos de ataque discretos como JSON estruturado (Finding, Action, Reasoning, Result). Melhor para writeups com cadeias de ataque claras.
• farr+narrative: igual ao farr, mais um resumo em prosa capturando o raciocínio do autor. Melhor para blogs onde o processo de pensamento importa.
• headers: sem LLM, apenas divide em cabeçalhos e mantém verbatim. Melhor para referências de comandos e documentação de ferramentas.

Backends LLM

Configure em config.toml. Backends separados para ingestão (extração em massa) e consultas (geração):

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

[ingest]                       # tempo de ingestão
backend      = "openai"
openai_model = "deepseek-chat"
base_url     = "https://api.deepseek.com/v1"
workers      = 8               # arquivos paralelos durante extração FARR

Backends suportados: anthropic, openai (qualquer API compatível com OpenAI), ollama.

[!IMPORTANTE] O ChromaDB é executado localmente por padrão, carregando todo o índice vetorial na RAM. Para corpora grandes (10k+ chunks) ou máquinas com pouca memória, é fortemente recomendado executar o ChromaDB como servidor remoto. Veja docs do servidor ChromaDB para configuração. Suporte remoto no ZETSU está planejado.

Benchmark

Avaliado em 910 questões cobrindo 12 categorias de segurança ofensiva (ADCS, Kerberos, enumeração AD, MSSQL, Sliver C2, escalonamento de privilégio, ataques web, credenciais, movimento lateral, cloud/Entra ID, OPSEC, ferramentas).

Principais fontes que contribuíram para as respostas: writeups pessoais de HTB, blog do dirkjanm, pesquisa do shenaniganslabs, HackTricks ADCS, wiki do Sliver, cheatsheet do netexec.

Em palavras simples, você precisa garantir a adição de recursos bons e estruturados que deseja que o RAG ingira. Este projeto foca 100% no uso de uma base de conhecimento, não confiando na memória do LLM ou no treinamento.

Dataset completo de avaliação e resultados em eval/.

Referências

• rank-bm25, recuperação BM25
• Conceito FARR de CIPHER
• Pipeline RAG inspirado por rag-chatbot

Em breve documentarei em um blog o uso e a eficácia, fique atento.