TORCH - Karpathy LLM based claude harness for PenetrationT

项目说明

TORCH

An AI-powered penetration testing and bug-bounty knowledge base and automation harness for Claude Code. It turns an Obsidian vault into an opinionated offensi 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- "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.

![Built for Claude Code]()
![LinkedIn]()

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 offensi 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 ne a dead end. Think HackTricks or PayloadsAllTheThings, but indexed for semantic search and driven by an autonomous AI agent.

> Authorized testing only. E 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-e, and dead-end-first gates. Single agent, refuter-; the pentest flow delivers a client report. 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 class, XSS, SQLi, SSRF, IDOR, RCE, auth bypass, OAuth/SAML federation, deserialization, cloud (AWS/Azure/GCP), Acti, local Windows and macOS pri 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 e.
- engagement-init.py (SessionStart) self-heals the engagement file set and injects a ranked next-mo.
- 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 ad).

State-first engagement model. Each engagement li targets/<name>/ (state, loot, paths, scope, killchain). next_move.py ranks what to do next, and the kill-chain board's co table (via the co skill) surfaces untested classes so nothing in scope is skipped.

Research loop (skills/research) for C 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 offensi reference organized as:

| Area | Covers |
|---|---|
| wiki/techniques/ | Acti, cloud, web, network, Linux, macOS, exploit-de, cracking, red-team, mobile/IoT, blockchain, methodology |
| wiki/payloads/ | Per- 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

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 ca 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>-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-dri, plus systematic-debugging, dispatching-parallel-agents, and letion.

context7 (optional MCP) - up-to-date library / API docs, used for 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.
E degrades gracefully: the hooks fail open and the hunt/wiki skills work without the optional
plugins, but the documented planning loop assumes superpowers.

Layout

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. Ne 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 classes, no inference-only findings.

---

License

MIT, see LICENSE.

项目信息

开发语言：Python

Star 数：330

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Karpathy LLM based claude harness for PenetrationTesting / Bugbounty using obsidian展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。