Introduction

For offensive security professionals, knowledge is currency. Yet, this valuable knowledge—gleaned from bug bounty reports, technical writeups, and personal lab notes—often remains scattered across markdown files and ephemeral chat sessions. A new open-source tool, Zetsu, tackles this problem head-on. Zetsu is a personal, offline Retrieval-Augmented Generation (RAG) system designed specifically for the offensive security community. It creates a private, queryable assistant from your own curated knowledge, ensuring your hard-won insights are never lost and always accessible.

What Is Zetsu?

Zetsu is a self-hosted, open-source RAG system that ingests your personal collection of security documents—writeups, lab solutions, and security blogs—and makes them searchable through natural language. Created by developer Chaelsoo and written in Python, Zetsu operates completely offline, with no cloud or SaaS dependencies, ensuring your private knowledge remains yours. Instead of manually searching through notes or trying to recall a specific command from a past engagement, you can ask Zetsu direct questions like, “how do I escalate with SeImpersonatePrivilege?” and get answers grounded in your own documented experiences, not generic web results.

The system is built around a sophisticated ingestion and query pipeline. During ingestion, it uses an LLM to perform “FARR extraction,” structuring text into discrete attack steps (Finding, Action, Reasoning, Result). When you ask a question, it uses a hybrid retrieval model (BM25 for keywords and vector search for semantics) to find the most relevant information before a cross-encoder reranks the results for maximum relevance. Zetsu can be used via a Terminal UI (TUI), a Web UI, or a command-line interface (CLI).

Why Zetsu Matters

Zetsu addresses a critical gap in the workflow of security professionals. While generic RAG frameworks and AI-powered note-taking apps exist, they are not tailored to the specific needs of offensive security research. The knowledge in this field is often procedural and highly contextual. A generic vector search might pull a random chunk of text containing a keyword, but Zetsu’s FARR extraction retrieves a complete, structured attack step, which is far more useful during an engagement.

Furthermore, the emphasis on an offline-first, self-hosted model is crucial for a security-conscious audience. It eliminates the risk of sensitive research or private notes being exposed to third-party services. By providing a tool that is not only powerful but also privacy-preserving, Zetsu empowers individuals and teams to build a compounding knowledge base that becomes more valuable with every document they add. It transforms a passive archive of notes into an active, intelligent assistant.

Key Features

• FARR Extraction: At ingest time, Zetsu uses an LLM to read your writeups and automatically extracts structured attack steps based on a “Finding, Action, Reasoning, Result” model. This means your queries return complete, logical units of information rather than disconnected text fragments.
• Hybrid Retrieval and Reranking: Zetsu combines the best of both worlds for search. It uses BM25 for precise keyword matching (like tool names or CVEs) and vector search for finding semantically similar concepts. A cross-encoder then reranks the combined results to ensure the most relevant chunks are prioritized.
• Multiple LLM Backends: The system is flexible, supporting various LLM backends including Anthropic, OpenAI-compatible APIs (like DeepSeek), and local models via Ollama. You can even use different models for the ingestion and query processes.
• Multiple Source Types: You can ingest knowledge from a wide array of sources. Zetsu supports local markdown directories, single URLs, GitHub wikis, and even Atom/RSS feeds to keep your knowledge base current.
• Dual Response Styles: Zetsu offers two distinct output modes tailored for security work. ‘Operator mode’ prioritizes exact commands for quick execution, while ‘Concept mode’ leads with the reasoning and explanation behind the technique.
• Multiple Interfaces (TUI, Web, CLI): Interact with your knowledge base in the way that best suits your workflow. Use the fast Terminal UI during an engagement, the Web UI for deeper study and review, and the CLI for scripting and automation.
• Persistent Chat History: Conversations with Zetsu are saved locally, allowing you to review past queries and their results. The history is browsable directly from the TUI.

How Zetsu Compares

Zetsu stands apart from generic RAG libraries and AI-enhanced note-taking apps by being a purpose-built application for a specific, highly technical domain.

Zetsu vs. Generic RAG Libraries: Frameworks like LangChain or LlamaIndex are powerful toolkits, but they require you to be a developer and build the entire application logic—the UI, the ingestion pipeline, the retrieval strategy—from scratch. Zetsu is a complete, ready-to-use application. You simply configure your data sources and LLM, and you have a working system with a TUI, Web UI, and CLI without writing any RAG pipeline code yourself.

Zetsu vs. AI Note Apps: While you can add AI-powered search to apps like Obsidian via plugins, these systems are generally less sophisticated. They typically rely on basic vector search over entire notes. Zetsu’s domain-specific FARR extraction and hybrid-retrieval with reranking provide much more relevant and structured results for its target use case. Zetsu is designed to ingest from your notes, using them as one of many sources for its dedicated knowledge base.

Getting Started: Installation

Zetsu is a Python-based application that you run locally. The installation process is straightforward and involves cloning the repository and setting up the required dependencies.

Prerequisites

• Python 3.x
• Git
• pip for installing Python packages

Installation from Source

Follow these steps to get Zetsu up and running on your local machine.

# 1. Clone the repository from GitHub
git clone https://github.com/chaelsoo/zetsu

# 2. Navigate into the project directory
cd zetsu

# 3. Install the required Python packages
pip install -r requirements.txt

Once the dependencies are installed, the next step is to configure the tool to point to your knowledge sources and LLM backend.

How to Use Zetsu

Using Zetsu involves a two-stage process: configuration and ingestion, followed by querying.

Step 1: Configuration

Before you can ingest any data, you need to edit the config.toml file. Here, you will specify your LLM backend (e.g., ‘ollama’ or ‘openai’), the model name, and define your data sources. You can add directories of markdown files, URLs, or RSS feeds.

Step 2: Ingestion

Once configured, you run the ingestion script. This process reads from your defined sources, uses the LLM to extract structured data, and builds the local search index.

python zetsu.py ingest

Step 3: Querying

After ingestion is complete, you can start asking questions using your preferred interface.

# For the Terminal User Interface
python zetsu.py tui

# For the Web User Interface (runs at localhost:8000)
python zetsu.py web

# For a single question via the Command-Line Interface
python zetsu.py ask "what are some techniques for kerberos delegation abuse"

Code Examples

Example `config.toml`

This configuration file sets up Zetsu to use a local Ollama model and ingest markdown files from a local `./docs` directory.

[llm]
backend = "ollama"
ollama_model = "mistral"

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

Example `farr` Extraction Mode

The `extract = “farr”` setting tells Zetsu to use its specialized LLM-based extraction. Other modes include `farr+narrative` for a prose summary and `headers` for simple splitting without an LLM, which is ideal for reference documents or cheat sheets.

Real-World Use Cases

• Penetration Testers: During an engagement, a tester can quickly query their Zetsu instance for commands and techniques related to a specific service they’ve discovered, getting answers grounded in their own successful past experiences.
• Bug Bounty Hunters: A hunter can feed all their past accepted reports and relevant public writeups into Zetsu. This creates a personalized assistant that can suggest attack chains for new targets based on similar technologies.
• Red Team Operators: Operators can use Zetsu as a shared knowledge base, ingesting internal wikis and after-action reports to ensure the entire team benefits from individual findings and tool configurations.
• Security Researchers: When exploring a new vulnerability class, a researcher can ingest dozens of academic papers and blog posts into Zetsu to build a deep, queryable understanding of the topic.
• Students and Trainees: Someone learning offensive security can ingest solution guides for platforms like Hack The Box or TryHackMe to create a study aid that explains concepts using examples they have already worked through.

Contributing to Zetsu

Zetsu is an open-source project that appears to be actively developed by its creator. While there is no formal `CONTRIBUTING.md` file, contributions are likely welcome. The best way to get involved is to use the tool, report any bugs or suggest new features via GitHub Issues, and engage in discussions with the maintainer before submitting a pull request for a new feature.

Community and Support

The primary hub for community and support is the official GitHub repository. The project maintainer, Chaelsoo, is also active on GitHub with several other popular security-focused projects.

• GitHub Issues: Use the Issues page on the repository for bug reports, feature requests, and technical questions.

Conclusion

Zetsu is a powerful and thoughtfully designed tool that solves a real problem for the offensive security community. It moves beyond generic AI chat by creating a persistent, compounding, and—most importantly—private knowledge base tailored to the specific needs of security professionals. Its sophisticated features like FARR extraction, hybrid retrieval, and dual response styles make it a uniquely valuable asset.

If you’re a security researcher, penetration tester, or hobbyist whose knowledge is locked away in a chaotic folder of markdown files, Zetsu offers a compelling way to unlock that value. It’s a practical step towards creating a personalized AI assistant that learns from your expertise. The best way to appreciate its power is to clone the repository, point it at your notes, and ask your first question.

Resources

• Official Zetsu GitHub Repository: The source code, documentation, and issue tracker for the project.