____ _ _ ____ _
/ ___| | __ _ _ _ __| | ___| __ ) _ __ __ _(_)_ __
| | | |/ _` | | | |/ _` |/ _ \ _ \| '__/ _` | | '_ \
| |___| | (_| | |_| | (_| | __/ |_) | | | (_| | | | | |
\____|_|\__,_|\__,_|\__,_|\___|____/|_| \__,_|_|_| |_|
Pentest & bug-bounty knowledge base + AI automation harness
An AI-powered penetration testing and bug-bounty knowledge base and automation harness for Claude Code. It turns an Obsidian vault into an opinionated offensive-security workflow: a searchable wiki of 500+ hacking technique pages, per-vulnerability "hunt" skills, deterministic hooks that fire the right skill at the right moment, and a state-first engagement model that stops you (and the model) from repeating work.
ClaudeBrain is a red-team / bug-bounty second brain built on Andrej Karpathy's LLM Wiki pattern: a persistent, AI-maintained knowledge base the model synthesizes each new source into over time, instead of re-deriving from raw documents on every query. Concretely, an offensive-security wiki, an agentic hunt-skill library, and a Model Context Protocol (MCP) search layer, wired together so Claude Code always checks the knowledge base before it attacks and never repeats a dead end. Think HackTricks or PayloadsAllTheThings, but indexed for semantic search and driven by an autonomous AI agent.
Authorized testing only. Everything here assumes a legal engagement: a signed penetration test, a bug-bounty program in scope, or your own lab / CTF. You are responsible for staying in scope and within the rules of engagement.
If ClaudeBrain saves you time on an engagement, a star helps other pentesters and bug-bounty hunters find it.
- Features
- The knowledge base
- What ships vs what stays private
- Requirements
- Quickstart
- Plugins and MCP servers
- Layout
- The model underneath
- Safety and boundaries
- License
- Wiki-first methodology. 500+ markdown technique pages indexed by
qmdfor semantic and keyword search over an MCP server (wiki-search). Every hunt skill queries the wiki before attacking, so knowledge compounds instead of scattering. - Hunt skills (
skills/hunt/hunt-*): one per vulnerability class, XSS, SQLi, SSRF, IDOR, RCE, auth bypass, OAuth/SAML federation, deserialization, cloud (AWS/Azure/GCP), Active Directory, local Windows and macOS privilege escalation, API (OWASP API Top 10), LLM/AI, ICS/OT, request smuggling, cache poisoning, and more. Each is wiki-first, out-of-band-gated for blind bugs, and emits a uniform FIND finding schema. - Deterministic automation (hooks). Plain Python that fires on Claude Code lifecycle events:
hunt-trigger.py(UserPromptSubmit) matches your prompt againstskills/hunt/triggers.jsonand loads the matching hunt skill.recon-capture.py(PostToolUse) fingerprints discovered tech againstscripts/playbook.json, routes to targeted tests, and auto-captures results into engagement state and PoC evidence.engagement-init.py(SessionStart) self-heals the engagement file set and injects a ranked next-move summary.scope-guard.py(PreToolUse) denies a command that targets an out-of-scope host or uses rules-of-engagement-forbidden tooling (deterministic enforcement; a.enforce-offmarker downgrades it to advisory).
- State-first engagement model. Each engagement lives under
targets/<name>/(state,loot,paths,scope,coverage). Analyzers (next_move.py,coverage.py) rank what to do next and surface untested vulnerability classes so nothing in scope is skipped. - Research loop (
skills/research) for CVE discovery on binaries, libraries, and repos, with its own persistent state underraw/research/. - Hard client-data boundary. Every client specific stays under
targets/(git-ignored);scripts/check-leaks.shgates tracked files before you ever push.
The wiki/ corpus is the heart of ClaudeBrain and it is fully committed, clone it and you get the whole library, not an empty shell. It is a living offensive-security reference organized as:
| Area | Covers |
|---|---|
wiki/techniques/ |
Active Directory, cloud, web, network, Linux, macOS, exploit-dev, OSINT, cracking, red-team, mobile/IoT, blockchain, methodology |
wiki/payloads/ |
Per-vulnerability-class payload arsenals the hunt skills pull from |
wiki/tools/ |
Per-tool references (nmap, ffuf, nuclei, httpx, sqlmap, BloodHound, netexec, ...) |
wiki/cheatsheets/ |
Quick-reference command sheets and default-credential tables |
Pages are cross-linked Obsidian-style and indexed for semantic search, so "SSRF to cloud metadata" or "ESC1 ADCS" resolves to the right page in one query. The wiki grows every engagement through the learn skill, which distills generic, client-free lessons back into it.
The wiki and the entire harness are public. Only client data and per-machine state are held back by .gitignore:
| Tracked (ships, safe to push) | Git-ignored (stays private) |
|---|---|
wiki/ the full 500+ page corpus |
targets/ client engagements and findings |
skills/, scripts/, setup/, docs/, tests/ |
CLAUDE.local.md machine hostnames and paths |
CLAUDE.md, README.md, LICENSE |
session/, raw/ local working state |
targets/TARGETS.md the generic engagement playbook |
.claude/, .obsidian/, runtime stamps and caches |
The client-data boundary is a hard rule. Hosts, credentials, findings, and engagement narrative live only under targets/, which git ignores wholesale (with the single generic playbook whitelisted). Run bash scripts/check-leaks.sh before your first push, it scans tracked files for engagement markers, private IPs, and emails.
- Linux or WSL,
bash,python3(3.10+) - Claude Code CLI
- Node.js >= 18 and bun
qmd(installed by the bootstrap viabun install -g @qmd/cli), which provides thewiki-searchMCP server viaqmd mcp
git clone <this-repo> ClaudeBrain
cd ClaudeBrain
# One-time, per-machine setup. NOTE: bootstrap.sh mutates ~/.claude: it writes a
# CLAUDE.md include, symlinks the hooks, registers the MCP servers, and installs
# qmd + the official Claude plugins. Read it first; it is aggressive by design.
bash setup/bootstrap.sh
# Build the search index (re-run after adding wiki pages)
qmd update
# Restart Claude Code so it loads the hooks, skills, and MCP servers.
# Start an engagement (pentest | bugbounty | ctf)
bash setup/new-engagement.sh acme pentest
# Run the test suite
python3 -m pytest -q
# Before any push, run the leak gate
bash scripts/check-leaks.shbootstrap.sh self-locates the vault; if it cannot, set OBSIDIAN_VAULT (and QMD_VAULT for the search index) to the repo root. Per-machine paths go in the git-ignored CLAUDE.local.md, copy CLAUDE.local.example.md to create it. See docs/setup.md for the full walkthrough.
ClaudeBrain runs on Claude Code plus a set of plugins and MCP servers. setup/bootstrap.sh
installs the core set for you; the rest are referenced by the workflow and installed separately.
Installed by bootstrap.sh:
- qmd - the semantic + keyword search engine over
wiki/(bun install -g @qmd/cli); registers thewiki-searchMCP (qmd mcp). - caveman - terse-output / prose-compression mode; also registers the
caveman-shrinkMCP (a token-compressedwiki-search). - ponytail - "lazy senior dev" engineering-discipline mode (pushes for the simplest working solution; governs code, not prose), from marketplace
DietrichGebert/ponytail. - Official Claude Code plugins: code-review, claude-md-management, skill-creator, frontend-design (
claude plugins install <name>@claude-plugins-official).
Install separately (referenced by the harness):
- superpowers (recommended) - the planning / execution / debugging workflow the CLAUDE.md loop routes to:
brainstorming->writing-plans->subagent-driven-development, plussystematic-debugging,dispatching-parallel-agents, andverification-before-completion. - context7 (optional MCP) - up-to-date library / API docs, used for vendor-default and dependency lookups.
- gsd (optional) - the
pause-worksession-end helper. - burp-mcp (optional MCP) - drives Burp Suite for the
hunt-burpworkflow.
Install plugins from Claude Code's plugin marketplace (/plugin), and MCP servers with claude mcp add.
Everything degrades gracefully: the hooks fail open and the hunt/wiki skills work without the optional
plugins, but the documented planning loop assumes superpowers.
CLAUDE.md top-level instructions loaded by Claude Code
wiki/ 500+ page technique corpus (ships; semantic + keyword indexed)
skills/ hunt-* skills, research / disclosure, hooks/, meta-skills
scripts/ next_move, coverage, find-lint, check-leaks, index / lint tooling
setup/ bootstrap, install-hooks, install-skills, new-engagement / research, templates
docs/ workflows, page-types, setup, sharing (client-data boundary), conventions
tests/ pytest suite for the automation
targets/ engagements (git-ignored; client data lives ONLY here)
Full annotated tree in docs/layout.md. Start with docs/workflows.md for the day-to-day flow and docs/sharing.md for the client-data boundary rules.
ClaudeBrain is a harness, the intelligence it orchestrates is a large language model (Claude). If you want to understand what an LLM actually is under the hood, tokens, attention, training, and inference, the clearest from-scratch implementations on the internet are Andrej Karpathy's:
- nanoGPT a minimal, readable GPT training and finetuning codebase; the canonical "here is a transformer, end to end."
- nanochat a full ChatGPT-style pipeline (pretraining, supervised finetuning, RL, and inference with a web UI) in one hackable repo.
- Neural Networks: Zero to Hero the video series that builds an LLM line by line, from
microgradup to a GPT.
Those repos show you the engine; ClaudeBrain shows you how to point that engine at a target and keep it disciplined.
- Client and engagement data (hosts, credentials, findings) lives only under
targets/, which is git-ignored. Never write it intowiki/,docs/,skills/, or commit messages. scripts/check-leaks.shscans tracked files for engagement markers and flags emails and private IPs before you publish. Run it before any push.- The hunt skills enforce out-of-band confirmation for blind vulnerability classes, no inference-only findings.
MIT, see LICENSE.