0rangec3t/Black-cat

What it solves

Black cat is a specialized "skill" for Claude Code designed to automate penetration testing (red teaming) by mimicking human-like reasoning. It replaces the traditional linear pipeline (Recon $\rightarrow$ Scan $>$ Exploit) with a hypothesis-driven state machine, allowing the agent to backtrack, validate evidence, and pivot based on new discoveries.

How it works

The project implements a state machine model (RECON $\leftrightarrow$ ENUMERATE $\leftrightarrow$ VALIDATE) where failures or new signals trigger new hypotheses rather than just skipping to the next step. It uses a structured approach to manage the agent's memory and execution:

• Hypothesis-Driven Logic: Instead of running tools first, the agent identifies signals, forms a hypothesis, and then verifies it.
• Case Ledger: A ledger.jsonl file serves as the single source of truth, tracking hypotheses, evidence, and verdicts to prevent context overflow in long sessions.
• Explicit File Routing: To keep the LLM context window clean, the system only loads specific technique files (e.g., web.md, recon.md, ad.md) as needed.
• Machine Gates: A verification script (case_ledger.py) ensures that all findings are fully validated with a complete evidence chain before a final report is generated.

Who it’s for

Security researchers and penetration testers who use Claude Code and want a structured, automated framework for conducting complex red teaming engagements across web, cloud, and internal networks.

Highlights

• Comprehensive Attack Surface: Covers advanced techniques for Web (API fuzzing, SSRF, Fastjson), Active Directory (BOF-based collection, Kerberos reflection), Cloud (K8s escape, IAM backdoors), and EDR evasion.
• State Machine Architecture: Supports non-linear workflows, allowing the agent to return to previous states when new information is found.
• Automated Evidence Tracking: Automatically generates an evidence-validation.md report from the machine-readable ledger.
• Tool Degradation Chain: Handles missing tools by falling back from preferred tools to alternatives or manual API calls to avoid hallucinating command outputs.
• Context Management: Implements automatic blackboard folding for long sessions to prevent LLM context overflow.