Black-cat: a hypothesis-driven red team skill for Claude Code

The problem Black-cat targets: pipeline pentesting that cannot backtrack

Most automation for offensive security follows a straight line: reconnaissance, scanning, exploitation, then a report. Each stage runs its tools and hands off to the next. Black-cat, a skill for Claude Code written in Python, rejects that shape. Its README argues that a fixed pipeline throws away information when a tool returns nothing, because a negative result is treated as a dead end rather than a new clue. The project is aimed at operators who already run Claude Code and want the assistant to reason about findings the way a human tester does, moving back to an earlier stage when the evidence points that way. If you want a push-button scanner, this is not it. The skill is built for people who will read its ledger and judge its verdicts themselves.

Reconnaissance, enumeration and validation as a state machine with back edges

The core design replaces the pipeline with three states that can loop: RECON, ENUMERATE and VALIDATE. The README describes the transitions plainly. A failed SQL injection attempt does not close the door; it becomes a signal that the target may use an ORM, which redirects the tester toward mass assignment instead. When lateral movement reaches a new host, the machine restarts RECON on that host. This is the mechanism that separates the tool from a script. Signals produce hypotheses, hypotheses get tested, and a disproof creates the next hypothesis rather than ending the run. The skill also splits its technique files, keeping one active technique file loaded by default and at most two, so the context window is not filled with unrelated material. That routing choice is deliberate, and the README ties it to keeping the model focused as the skill grows.

The append-only ledger at case/ledger.jsonl

Black-cat keeps a single machine-readable source of truth. Every hypothesis, piece of evidence and verdict is appended to case/ledger.jsonl, and the file is never rewritten in place. From that ledger the skill regenerates a human-readable report at case/evidence-validation.md, while raw responses, logs and screenshots go into case/artifacts/ with the ledger holding only relative paths, SHA-256 hashes and short summaries. A SessionStart hook defined in .claude/settings.json injects confirmed facts and active hypotheses back into the model at the start of each session, which is how the skill recovers its state after a long conversation or a context compaction. To rebuild the visual report by hand, the README documents this command:

python -X utf8 skills/pentest-redteam/scripts/case_ledger.py render case

The -X utf8 flag matters on Windows, where the default encoding otherwise mangles the Chinese blackboard output. You should see the regenerated evidence-validation.md reflect the current ledger contents.

Provisional verdicts and the verify --report gate

Version 1.1.0 added a two-tier verdict system. A finding can be recorded as provisional with only an observation and a reproduction, which lets the tester advance when a proof of concept already demonstrates the issue; the impact is filled in later during post-exploitation, and a confirmed verdict is appended after that. Before a report is produced, the skill runs a machine check:

python skills/pentest-redteam/scripts/case_ledger.py verify --report

This gate verifies that every confirmed finding has its full observation, reproduction and impact chain closed, and that no provisional verdict is left dangling. If something is missing, it errors out instead of emitting an incomplete report. That is a real constraint on the workflow, and a useful one, because it stops the assistant from writing a conclusion the evidence does not support.

Where the design makes you trust it: authorization defaults and unverified claims

Two choices deserve scrutiny. First, authorization is confirmed once when the skill loads, and after that the README states that operations outside the locked scope are performed by default unless the authorization document explicitly forbids them. That reduces interruptions, but it also means the human confirms the boundary a single time and then delegates judgement to the model for the rest of the session. On an engagement with a narrow scope, that is a decision to make carefully. Second, the README lists a long catalog of attack techniques, including named CVEs and internal reconnaissance paths specific to Chinese targets. The material describes coverage, not proof that each technique works as written. The one guard the skill does enforce is honest: its hard rule forbids fabricating command output, requiring the tester to mark a tool as failed or absent rather than inventing a result. A tool-degradation chain, preferred then alternative then manual or API then record the limitation, is documented for cases where a tool is missing.

How it differs from pipeline-style pentest skills

The honest alternative is any of the pipeline pentest skills the README positions itself against. Those bind each phase to fixed tools: reach the scan phase and you run nmap, reach exploitation and you run the matching exploit, with no path back. The practical difference is what happens on a negative result. A pipeline treats an empty sqlmap run as the absence of SQL injection and moves on. Black-cat treats it as evidence that shifts the hypothesis toward a different class of bug. Whether that pays off depends entirely on the model driving it, because the skill supplies structure and routing, not detection logic of its own. If your workflow is a compliance scan that must run the same checks every time, a pipeline is the better fit and its repeatability is a feature. Black-cat trades that repeatability for adaptive reasoning.

No license file and what that means for use

The repository ships no license. That is not a small detail. Without a license, default copyright applies, and others have no granted right to modify or redistribute the code even though the source is public. For a skill you intend to adapt to your own engagements, that gap is worth resolving with the author before you build on it. On maintenance, the last push was on 2026-08-03, and the two tagged releases, v1.0.0 and v1.1.0, landed within two days of each other at the end of July 2026. The upgrade note in the README is specific: keep the repository root .claude/settings.json when moving from v1.0.0, or Claude Code will not load the case blackboard at SessionStart, and the old engagement-tracker.md is replaced by case/ledger.jsonl.

Editorial conclusion

Adopt Black-cat if you run Claude Code for authorized red team work and want an auditable ledger plus a report gate that refuses incomplete evidence. Skip it if you need a deterministic, repeatable scanner or cannot accept a once-per-session authorization model. Before you rely on it, settle the missing license with the author and test the case_ledger.py verify --report gate against a known finding to confirm the closure logic behaves as the README describes.

Frequently asked questions

Official sources

1. 0rangec3t/Black-cat on GitHub
2. Issues
3. README
4. Releases