[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93338":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":17,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},93338,"Zetsu","Chaelsoo\u002FZetsu","Chaelsoo","A personal RAG system for offensive security knowledge","",null,"Python",151,8,109,0,42,3,64.06,false,"master",true,[],"2026-07-22 04:02:08","\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fzetsu.jpg\" width=\"320\" alt=\"ZETSU\">\n\u003C\u002Fp>\n\nA personal offline RAG system for offensive security knowledge. Ingest your writeups, lab solutions, bug bounty reports, and security blogs, then query them in natural language during engagements. No cloud, no SaaS, your knowledge stays yours.\n\n\n## What it does\n\nZETSU turns your accumulated knowledge into a queryable assistant. Instead of grepping through markdown files or remembering which writeup had that certipy command, you ask naturally:\n\n```\nhow do i escalate with SeImpersonatePrivilege\nwhat did i do after getting ADFS access\nsliver socks5 pivot setup\nexplain ESC8 vs ESC4\n```\n\nIt retrieves from your actual notes first, then generates an answer grounded in what you've documented, not generic internet knowledge.\n\n\n## Architecture\n\n### Ingestion pipeline\n\n![Ingestion pipeline](assets\u002Fingestion.png)\n\n### Query pipeline\n\n![Query pipeline](assets\u002Fquery.png)\n\n\n## Features\n\n- **FARR extraction:** at ingest time, an LLM reads each section of your writeups and extracts structured attack steps (Finding, Action, Reasoning, Result). What you retrieve is a semantic unit, not a random 800-token window.\n- **Hybrid retrieval:** BM25 for exact token matching (tool names, CVE numbers, CLI flags) + vector search for semantic similarity. RRF fusion combines both.\n- **Cross-encoder reranker:** reorders retrieved chunks by actual relevance before sending to the LLM.\n- **Two response styles:** Operator mode leads with exact commands, Concept mode leads with reasoning. Same retrieval, different presentation. Toggle with `Ctrl+M` in TUI.\n- **Multiple LLM backends:** Anthropic, OpenAI-compatible (DeepSeek, etc.), or local Ollama. Separate backends for ingest and query.\n- **Multiple source types:** local markdown files, single URLs, GitHub wikis, Atom\u002FRSS feeds.\n- **Persistent chat history:** saved to `~\u002F.zetsu\u002Fhistory\u002FYYYY-MM-DD.json`, browsable with `\u002Fhistory`.\n- **TUI + Web UI + CLI:** use what fits the context. TUI during engagements, Web UI for studying, CLI for scripting.\n\n\n## Installation\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fchaelsoo\u002Fzetsu\ncd zetsu\npip install -r requirements.txt\n```\n\nSet up your API key:\n\n```bash\ncp .env.example .env\n# edit .env and add your key\n```\n\n\n## Quick start\n\n**1. Add your writeups**\n\nDrop `.md` files into `docs\u002F`. Notion exports, Obsidian notes, blog exports, anything markdown works.\n\n**2. Configure sources in `config.toml`**\n\n```toml\n[llm]\nbackend      = \"openai\"\nopenai_model = \"deepseek-chat\"\nbase_url     = \"https:\u002F\u002Fapi.deepseek.com\u002Fv1\"\n\n[[sources]]\ntype    = \"markdown_dir\"\npath    = \".\u002Fdocs\"\nname    = \"my_writeups\"\nextract = \"farr\"\nenabled = true\n```\n\n**3. Ingest**\n\n```bash\npython zetsu.py ingest\n```\n\n**4. Use it**\n\n```bash\npython zetsu.py tui       # terminal UI\npython zetsu.py web       # browser at localhost:8000\npython zetsu.py ask \"how do i abuse SeImpersonatePrivilege\"\n```\n\n\n## CLI reference\n\n```bash\npython zetsu.py ingest                 # ingest enabled sources\npython zetsu.py ingest --force         # wipe and rebuild everything\npython zetsu.py ingest --dry-run       # estimate without making LLM calls\npython zetsu.py ingest --all-sources   # enable all sources regardless of enabled flag\npython zetsu.py tui                    # terminal UI\npython zetsu.py web                    # web UI\npython zetsu.py ask \"query\"            # one-shot CLI\npython zetsu.py ask \"query\" --style concept\npython zetsu.py stats                  # vector store stats\n```\n\n\n## TUI keybindings\n\n| Key | Action |\n|-----|--------|\n| `Enter` | Send query |\n| `Ctrl+M` | Toggle Operator \u002F Concept mode |\n| `Ctrl+Y` | Copy last response to clipboard |\n| `Ctrl+L` | Clear session |\n| `Ctrl+C` | Quit |\n| `\u002Fhelp` | Show commands |\n| `\u002Fstats` | Vector store + history stats |\n| `\u002Fhistory` | Today's past queries |\n| `\u002Fclear` | Clear session |\n\n\n## Source types\n\n| Type | Use for | Extract mode |\n|------|---------|--------------|\n| `markdown_dir` | Your writeups, notes | `farr` |\n| `markdown_file` | Single markdown file | `farr` |\n| `url` | Tool wikis, reference pages | `headers` |\n| `atom` | Security blogs with feeds | `farr+narrative` |\n\n### Extract modes\n\n- **`farr`:** LLM extracts discrete attack steps as structured JSON (Finding, Action, Reasoning, Result). Best for writeups with clear attack chains.\n- **`farr+narrative`:** same as farr, plus a prose summary capturing the author's reasoning. Best for blogs where the thought process matters.\n- **`headers`:** no LLM, just split on headers and keep verbatim. Best for command references and tool documentation.\n\n---\n\n## LLM backends\n\nConfigure in `config.toml`. Separate backends for ingestion (bulk extraction) and queries (generation):\n\n```toml\n[llm]                          # query time\nbackend      = \"openai\"\nopenai_model = \"deepseek-chat\"\nbase_url     = \"https:\u002F\u002Fapi.deepseek.com\u002Fv1\"\n\n[ingest]                       # ingest time\nbackend      = \"openai\"\nopenai_model = \"deepseek-chat\"\nbase_url     = \"https:\u002F\u002Fapi.deepseek.com\u002Fv1\"\nworkers      = 8               # parallel files during FARR extraction\n```\n\nSupported backends: `anthropic`, `openai` (any OpenAI-compatible API), `ollama`.\n\n\n> [!IMPORTANT]\n> ChromaDB is run locally by default, which loads the full vector index into RAM. For large corpora (10k+ chunks) or memory-constrained machines, it is strongly recommended to run ChromaDB as a remote server instead. See [ChromaDB server docs](https:\u002F\u002Fdocs.trychroma.com\u002Fproduction\u002Fchroma-server\u002Fclient-server-mode) for setup. Remote support in ZETSU is planned.\n\n## Benchmark\n\nEvaluated across 910 questions covering 12 offensive security categories\n(ADCS, Kerberos, AD enumeration, MSSQL, Sliver C2, privilege escalation,\nweb attacks, credentials, lateral movement, cloud\u002FEntra ID, OPSEC, tools).\n\n| Metric | Result |\n|--------|--------|\n| Questions answered | 910 \u002F 910 (100%) |\n| Answers with code\u002Fcommands | 842 \u002F 910 (93%) |\n| Context gaps (model admitted missing info) | 66 \u002F 910 (7.3%) |\n| Avg retrieval time | 68ms |\n| Avg total response time | 3.8s |\n\nTop sources contributing to answers: personal HTB writeups, dirkjanm blog, shenaniganslabs research, HackTricks ADCS, Sliver wiki, netexec cheatsheet.\n\nIn simple words, you need to make sure to add good & structured resources that you want the RAG to ingest, this project focueses 100% on using a knowledge base, not trusting the LLM's memory or trained on knowledge.\n\nFull evaluation dataset and results in [`eval\u002F`](eval\u002F).\n\n## References\n\n- [rank-bm25](https:\u002F\u002Fgithub.com\u002Fdorianbrown\u002Frank_bm25), BM25 retrieval\n- FARR concept from [CIPHER](https:\u002F\u002Fgithub.com\u002Fibndias\u002FCIPHER)\n- RAG pipeline inspired by [rag-chatbot](https:\u002F\u002Fgithub.com\u002Fumbertogriffo\u002Frag-chatbot)\n\n> I will be documenting in a blog the usage and how effective it is very soon, stay tuned.\n","Zetsu 是一个面向攻防安全人员的本地化 RAG（检索增强生成）知识管理系统，专为离线使用设计。它支持从 Markdown 写作、漏洞报告、CTF 解题笔记、安全博客等私有资料中提取结构化攻击步骤（FARR），结合 BM25 与向量混合检索、交叉编码器重排序，并对接多种 LLM 后端生成精准回答。提供 TUI、Web 和 CLI 三种交互方式，所有数据全程本地处理，不依赖云端服务。适用于红队演练、渗透测试复盘、漏洞研究知识沉淀等需快速回溯个人实战经验的场景。",2,"2026-07-16 02:30:09","CREATED_QUERY"]