TORCH

     )
    ( (
   ) ) (
  ( ( ) )                                          T   O   R   C   H
   ) (*)                             ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
    )|(                              Targeted Offensive Recon & Compromise 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: autonomous campaign drivers (/pt-workflow, /bb-workflow, /ctf-workflow) that run a whole engagement end to end, 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.

TORCH 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 TORCH saves you time on an engagement, a star helps other pentesters and bug-bounty hunters find it.

---

Contents

• Features
• The knowledge base
• What ships vs what stays private
• Requirements
• Quickstart
• Plugins and MCP servers
• Layout
• The model underneath
• Safety and boundaries
• License

---

Features

• Autonomous engagement workflows (/pt-workflow, /bb-workflow, /ctf-workflow): the headline capability, run a whole pentest, bug-bounty program, or boot-to-root box end to end with no operator approvals. A deterministic driver (scripts/campaign.py) owns pass state, builds a kill-chain board from recon, and prints the exact next action (which skill + tool) every turn, enforcing the wiki-first, tool-first, typed-evidence, and dead-end-first gates. Single agent, refuter-verified; the pentest flow delivers a client report. Verify the driver is wired up on a new machine with /campaign-health.
• Wiki-first methodology. 500+ markdown technique pages indexed by qmd for 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 against skills/hunt/triggers.json and loads the matching hunt skill.
  • recon-capture.py (PostToolUse) fingerprints discovered tech against scripts/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-off marker downgrades it to advisory).
• State-first engagement model. Each engagement lives under targets/<name>/ (state, loot, paths, scope, killchain). next_move.py ranks what to do next, and the kill-chain board's coverage table (via the coverage skill) surfaces 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 under raw/research/.
• Hard client-data boundary. Every client specific stays under targets/ (git-ignored); scripts/check-leaks.sh gates tracked files before you ever push.

---

The knowledge base (500+ pages ship with the repo)

The wiki/ corpus is the heart of TORCH 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.

---

What ships vs what stays private

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.

---

Requirements

• Linux or WSL, bash, python3 (3.10+)
• Claude Code CLI
• Node.js >= 18 and bun
• qmd (installed by the bootstrap via bun install -g @qmd/cli), which provides the wiki-search MCP server via qmd mcp

Quickstart

git clone <this-repo> TORCH
cd TORCH

# 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

# Then, inside Claude Code, drive the whole engagement autonomously with the matching workflow:
#   /pt-workflow    pentest (client-report deliverable)
#   /bb-workflow    bug-bounty program
#   /ctf-workflow   CTF / boot-to-root box

# Run the test suite
python3 -m pytest -q

# Before any push, run the leak gate
bash scripts/check-leaks.sh

bootstrap.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.

---

Plugins and MCP servers

TORCH 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 the wiki-search MCP (qmd mcp).
• caveman - terse-output / prose-compression mode; also registers the caveman-shrink MCP (a token-compressed wiki-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, plus systematic-debugging, dispatching-parallel-agents, and verification-before-completion.
• context7 (optional MCP) - up-to-date library / API docs, used for vendor-default and dependency lookups.
• gsd (optional) - the pause-work session-end helper.
• burp-mcp (optional MCP) - drives Burp Suite for the hunt-burp workflow.

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.

Layout

CLAUDE.md         top-level instructions loaded by Claude Code
wiki/             500+ page technique corpus (ships; semantic + keyword indexed)
skills/           hunt-* skills, workflow/ (campaign drivers, triage / evidence / coverage), research / disclosure / burp, hooks/, meta-skills
scripts/          campaign (autonomous workflow driver), next_move, 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.

---

The model underneath

TORCH 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 micrograd up to a GPT.

Those repos show you the engine; TORCH shows you how to point that engine at a target and keep it disciplined.

---

Safety and boundaries

• Client and engagement data (hosts, credentials, findings) lives only under targets/, which is git-ignored. Never write it into wiki/, docs/, skills/, or commit messages.
• scripts/check-leaks.sh scans 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.

---

License

MIT, see LICENSE.