TORCH: an Obsidian wiki and hook harness that keeps Claude Code disciplined on engagements

What TORCH is, and the premise it states

TORCH describes itself as an AI-powered penetration testing and bug-bounty knowledge base and automation harness for Claude Code. It turns an Obsidian vault into an offensive-security workflow: autonomous campaign drivers, a searchable wiki, per-vulnerability hunt skills, Python hooks that fire on lifecycle events, and an engagement state model designed to stop repeated work.

The README opens with an authorized-testing notice. Everything assumes a legal engagement: a signed penetration test, a bug-bounty program in scope, or the operator's own lab or CTF machine. Staying in scope and inside the rules of engagement is placed on the user.

This review stays on that side of the line. It describes the architecture, the enforcement points and the limits. It does not reproduce any technique page, payload or attack procedure from the corpus.

The corpus ships, and it is indexed

The wiki is the part worth judging first, because knowledge bases often arrive empty. Here the corpus is committed to the repository, so a clone produces the whole library rather than a scaffold awaiting content. The README counts over 500 pages, organised into technique areas covering Active Directory, cloud, web, network, Linux, macOS, exploit development, OSINT, cracking, red team, mobile and IoT, blockchain and methodology, plus payload references, per-tool references and cheatsheets.

What makes it more than a folder of markdown is the retrieval layer. Pages are cross-linked in Obsidian style and indexed for semantic and keyword search by a tool called qmd, exposed to the agent as a wiki-search MCP server. The README gives the intended effect: a query such as SSRF to cloud metadata or an ADCS escalation name resolves to the right page in one step.

The corpus is also meant to grow. A learn skill distils generic, client-free lessons from each engagement back into the wiki, which is the same compounding pattern the README credits to Karpathy's LLM Wiki idea.

Hunt skills and the finding schema

Hunt skills live one per vulnerability class. The README lists coverage for cross-site scripting, SQL injection, server-side request forgery, insecure direct object references, remote code execution, authentication bypass, OAuth and SAML federation, deserialization, cloud platforms, Active Directory, local privilege escalation on Windows and macOS, the OWASP API Top 10, LLM and AI targets, industrial control systems, request smuggling and cache poisoning, among others.

Three properties are consistent across them. Each queries the wiki before any testing, so technique knowledge is retrieved rather than recalled. Each is gated for out-of-band confirmation on blind vulnerability classes, so a blind bug is not reported from inference alone. And each emits findings in one uniform schema.

That last property matters more than it sounds. A single finding shape is what lets the reporting and triage tooling treat results from different classes the same way, and it is what makes the coverage board meaningful.

Where enforcement actually happens

The interesting engineering sits in four Python scripts bound to lifecycle events.

On prompt submission, a trigger script matches the prompt against a trigger file and loads the matching hunt skill. After a tool runs, a capture script fingerprints discovered technology against a playbook file, routes to targeted tests, and writes results into engagement state. At session start, an init script repairs the engagement file set and injects a ranked next-move summary.

The fourth one is the safety control. A scope guard runs before tool use and denies commands that target an out-of-scope host or use tooling forbidden by the rules of engagement. The README calls this deterministic enforcement, and it also documents the escape hatch: a marker file downgrades the guard from enforcement to advisory. Anyone adopting this should treat that marker as a controlled change rather than a convenience flag.

A caveat applies to the rest: the README states the hooks fail open, so a broken hook does not stop work.

Engagement state and the campaign driver

Each engagement gets its own directory holding state, collected material, paths, scope and a kill-chain board. A ranking script decides what to attempt next, and a coverage skill surfaces vulnerability classes that have not been tested, so classes in scope are less likely to be skipped.

Campaigns can be driven end to end by workflow commands for penetration tests, bug-bounty programs and CTF machines. A deterministic driver script owns pass state, builds the kill-chain board from reconnaissance, and prints the next action each turn, enforcing gates the README names as wiki-first, tool-first, typed-evidence and dead-end-first. The pentest flow produces a client report, and a health command verifies the driver is wired up on a new machine.

There is also a research loop for CVE discovery against binaries, libraries and repositories, with its own persistent state directory.

Setting it up

Requirements are Linux or WSL with bash and Python 3.10 or newer, the Claude Code CLI, Node.js 18 or newer plus bun, and a search tool installed globally through bun.

Installation begins by cloning the repository into a directory named TORCH. The per-machine bootstrap is the step to read before running it: the README warns that the script modifies the Claude configuration directory, symlinks the hooks, registers the MCP servers and installs the search tool alongside official plugins, and describes itself as aggressive by design. After it completes, the search index is built and rebuilt whenever wiki pages are added, and Claude Code is restarted so the hooks, skills and servers load.

Engagements are then scaffolded by name and type, and the matching workflow command drives them from inside Claude Code. The test suite runs under pytest. If the bootstrap cannot locate the vault, two environment variables point at the repository root, and per-machine paths belong in a git-ignored local file created from the shipped example.

Plugins, servers and degradation

The bootstrap installs a core set: the search engine and its MCP server, a prose-compression mode with a token-compressed variant of the same search, an engineering-discipline mode, and four official plugins for code review, configuration management, skill authoring and interface design.

A second group is referenced by the workflow but installed separately. A planning and execution plugin is recommended, because the documented loop routes brainstorming, plan writing and subagent-driven development through it, along with systematic debugging and verification before completion. Optional additions cover up-to-date library documentation, a session-end helper, and a Burp Suite MCP server for proxy-driven testing.

The README is clear about the failure model: everything degrades gracefully, the hooks fail open, and the hunt and wiki skills work without the optional plugins. The documented planning loop, however, assumes the recommended plugin is present.

Boundaries, licence and open questions

The client-data rule is stated as hard. Hosts, credentials, findings and narrative belong only under the engagement directory, which git ignores wholesale apart from one generic playbook. A leak gate scans tracked files for engagement markers, private addresses and email addresses, and the README says to run it before any push:

bash scripts/check-leaks.sh

Compared with static references such as HackTricks or PayloadsAllTheThings, which the README names as the nearest analogues, the difference is retrieval and agency: those are references a human searches, while this corpus is semantically indexed and driven by an agent that is required to query it before acting.

The open questions are governance rather than capability. Workflows are described as running with no operator approvals, the scope guard can be downgraded to advisory by a marker file, and the hooks fail open. It is MIT licensed with no published releases and the most recent commit on 2026-09-01, so versioned upgrades are not part of the deal.

Editorial conclusion

TORCH belongs in the hands of people running signed penetration tests, in-scope bug-bounty programs or their own labs, which is the boundary the README states up front. It earns attention for two reasons: the wiki is committed rather than promised, so a clone yields a real corpus, and the automation is deterministic Python on lifecycle events rather than instructions the model can ignore. Verify four things before relying on it. Confirm the scope guard is actually enforcing, because a marker file downgrades it to advisory. Confirm the client-data boundary holds, since the leak gate only scans tracked files and client material must live under the ignored engagement directory. Confirm the planned plugins are installed, because the hooks fail open and the documented planning loop assumes one of them. And confirm the environment, since Linux or WSL, Python 3.10 or newer, Node 18 and bun are all required before the bootstrap runs.

Frequently asked questions

Official sources

1. Encod3d-Sec/TORCH on GitHub
2. Issues
3. License: MIT
4. README