offensive-claude

Offensive Security Research Config for Claude Code

A spec-driven offensive security framework for Claude Code — structured engagement workflows based on the Cyber Kill Chain, 32 kill-chain skills (multi-file progressive-disclosure) plus a discipline layer (a SessionStart dispatcher + 6 process/discipline skills), 8 collaborative agents, and a shared 47-file vulnerability reference library. Inspired by GitHub's spec-kit, obra/superpowers, and gadievron/raptor (crash→exploitability + OSS-repo forensics).

Quick Setup

# Method 0: Install as a Claude Code plugin (recommended — auto-loads the skill dispatcher)
/plugin marketplace add hypnguyen1209/offensive-claude
/plugin install offensive-claude@offensive-claude-marketplace

Installing as a plugin registers a SessionStart hook that injects the using-offensive-claude dispatcher into every conversation, so the skill-invocation discipline (scope → finding → OPSEC) is active from the first message.

# Method 1: One-liner install (recommended)
curl -sL https://raw.githubusercontent.com/hypnguyen1209/offensive-claude/main/install.sh | bash

# Method 2: Clone + install script
git clone https://github.com/hypnguyen1209/offensive-claude.git ~/offensive-claude
cd ~/offensive-claude && bash install.sh

# Method 3: Manual copy
git clone https://github.com/hypnguyen1209/offensive-claude.git ~/offensive-claude
cp -r ~/offensive-claude/skills ~/.claude/skills
cp -r ~/offensive-claude/agents ~/.claude/agents
cp -r ~/offensive-claude/templates ~/.claude/templates
cp -r ~/offensive-claude/workflows ~/.claude/workflows
cp -r ~/offensive-claude/commands ~/.claude/commands
cp -r ~/offensive-claude/presets ~/.claude/presets
cp ~/offensive-claude/CLAUDE.md ~/.claude/CLAUDE.md

Skills and agents activate automatically — no additional configuration needed.

Engagement Workflow

Engagements follow the Cyber Kill Chain as a structured 9-phase pipeline with quality gates:

Phase 0    Phase 1    Phase 2      Phase 3     Phase 4       Phase 5       Phase 6    Phase 7       Phase 8
SCOPE  →  RECON  →  WEAPONIZE →  DELIVERY →  EXPLOIT  →  INSTALLATION →   C2    →  ACTIONS ON →  REPORT
                                                                                    OBJECTIVES

Quick Start — Web App Pentest

/engage.init web-app --client ACME
/engage.scope                           # Define targets, ROE, authorization
/engage.recon                           # Subdomain enum, port scan, tech fingerprint
/engage.weaponize                       # Select exploits, design payloads
/engage.exploit                         # Execute exploits, document findings
/engage.report                          # Generate technical report + executive summary

Orchestration Commands

Command	Phase	Action
/engage.init <preset>	—	Initialize engagement with workflow preset
/engage.scope	0	Define targets, ROE, authorization
/engage.recon	1	Passive/active reconnaissance
/engage.weaponize	2	Payload development, exploit design
/engage.deliver	3	Delivery vector execution
/engage.exploit	4	Exploitation, finding documentation
/engage.install	5	Persistence establishment
/engage.c2	6	C2 infrastructure setup
/engage.actions	7	Objectives execution, lateral movement
/engage.report	8	Report generation
/engage.status	—	Show pipeline status and progress
/engage.gate	—	Validate current phase gate
/engage.crash	4	Crash → root cause (rr) → reachability (gcov/trace) → empirical exploitability verdict
/engage.cvediff	2,4	Find a CVE's canonical fix commit(s) across sources, then scope-gated diff for root cause
/engage.scorecard	—	Calibrate model verdict trust (Wilson-bounded miss-rate) to short-circuit re-validation
/engage.threatmodel	1	Materialize / lint / drift-check the engagement threat model
/engage.memory	—	Recall prior patterns / record confirmed findings (cross-engagement learning)
/engage.pickup	—	Resume an engagement from the engine trace (skip completed steps)

Workflow Presets

Preset	Phases	Use Case
web-app	0,1,2,3,4,8	OWASP-focused web application assessment
network	0,1,2,4,5,6,7,8	Internal network penetration test
red-team	ALL (0-8)	Full adversary simulation
cloud	0,1,4,8	AWS/Azure/GCP security audit
mobile	0,1,2,4,8	Android/iOS application pentest
ad-domain	0,1,2,4,5,7,8	Active Directory domain assessment
bug-bounty	0,1,4,8	Bug bounty vulnerability hunting

Quality Gates

Each phase transition validates:

• Required artifacts exist (templates filled)
• Findings have mandatory fields (CWE, CVSS, evidence, ATT&CK ID)
• Gate PASS → suggests next phase + relevant skills
• Gate FAIL → lists missing items

Structure

.
├── skills/                        # 32 skill modules (progressive-disclosure layout)
│   ├── recon-osint/
│   │   ├── SKILL.md               #   thin router: when-to-activate + technique map + OPSEC/detection
│   │   ├── references/            #   per-skill technique deep-dives (theory + code + detection + OPSEC)
│   │   └── scripts/               #   runnable tooling backing each technique
│   ├── coding-mastery/scripts/_lib/  # shared safety libs: scope_guard, action_guard, http_creds, redact_headers
│   ├── engagement-memory/         #   cross-engagement pattern-learning memory (support skill)
│   ├── using-offensive-claude/    #   SessionStart DISPATCHER — skill-invocation discipline
│   ├── engagement-flow/           #   process skills: sequence the kill chain,
│   ├── scope-discipline/          #   no target without authorization,
│   ├── threat-model-discipline/   #   model the attack surface + detect drift before exploiting,
│   ├── finding-discipline/        #   no [CONFIRMED] without proof,
│   ├── opsec-discipline/          #   detection/cleanup/redaction before acting,
│   ├── writing-offensive-skills/  #   authoring conventions
│   ├── exploit-development/
│   ├── ...
│   └── references/                # shared 47-file vulnerability pattern library
├── .claude-plugin/                # plugin.json + marketplace.json (install as a Claude Code plugin)
├── hooks/                         # SessionStart hook that injects the dispatcher every session
├── .devcontainer/                 # reproducible binary-analysis toolchain (rr/gdb/gcov/afl++) for the
│                                  #   crash→exploitability pipeline; scoped SYS_PTRACE/SYS_PERFMON, not --privileged
├── agents/                        # 8 collaborative sub-agents (incl. finding-validator, finding-checker)
├── engine/                        # bounded, resumable, traceable autopilot runner
│   ├── engine.py                  #   phase runner (budget + loop-detect + trace + resume; not an LLM)
│   ├── budget.py  loop_detector.py  tracer.py
│   ├── rebuttal.py                #   bounded generator↔checker rebuttal loop (default-to-skeptic)
│   └── model_scorecard.py         #   Wilson-bounded, fail-closed model-verdict trust calibration
├── tests/                         # pytest suite for the safety-critical scripts (run: pytest)
├── templates/                     # Structured templates per Kill Chain phase
│   ├── scope/                     #   scope-definition + scope.schema.json/example (machine-readable ROE)
│   ├── threat-model/              #   threat model (assets/entry-points/boundaries/ATT&CK) + drift baseline
│   └── ... (recon, weaponize, delivery, exploit, install, c2, actions, report)
├── workflows/                     # Kill Chain workflow definitions (YAML) + WORKFLOW-ENGINE.md
├── commands/                      # /engage.* orchestration slash commands (incl. memory, pickup)
├── presets/                       # Engagement type presets (7 presets)
├── .github/                       # SECURITY.md (coordinated disclosure) + CI (workflows/tests.yml)
├── TERMS.md                       # Acceptable-use policy / authorization requirement
├── CLAUDE.md                      # System prompt & behavior config
├── settings.json                  # Claude Code settings, permissions, MCP servers
├── install.sh                     # One-liner install script
└── README.md

Safety, Testing & Autonomy

The framework's safety controls are executable, not prose, and covered by an automated test suite:

Control	What it does
scope_guard.py	Enforces the engagement scope (scope.json); host parsing matches HTTP clients (userinfo/IPv6/IDN safe), fails closed
validate_findings.py	Evidence-grounding + per-class FP harness via structured proof signals; native-bug reachability bar (gcov/trace) + [EVD-XXX] citation gate (evidence_kit.py re-verifiable evidence)
safe_subprocess.py	Hardened exec for untrusted inputs/repos: shell=False, clean env, bounded+fail-closed, UTF-8 decode, git_safe() (hooks/prompt/host-config/ext-transport disabled)
action_guard.py	3-state gate (allow / require_approval / block): out-of-scope → block, safe-method policy, per-host circuit breaker
redact_headers.py	Masks Authorization/Cookie/API-key/JWT at the data boundary (fail-closed) before traffic reaches the model
finding-checker + engine/rebuttal.py	Blind artifact-only adversarial checker driving a bounded generator↔checker rebuttal loop (default-to-skeptic; EXHAUSTED/STALLED never accept)
engine/model_scorecard.py	Fail-closed model-verdict trust calibration (Wilson 95% upper-bound miss-rate) to short-circuit re-validation only on a proven track record
engagement-memory/	Persists confirmed findings as impact-ranked patterns; recalls top-N prior techniques at recon/weaponize
engine/	Bounded autopilot: hard step/time budget, loop detection, append-only trace, --resume; offensive actions stay operator-gated
tests/ + CI	pytest suite (run pytest); GitHub Actions runs it + byte-compile (skills/ + engine/) + shellcheck on every push

All safety code is adversarially red-teamed and regression-tested. See TERMS.md for the authorization requirement — every request the toolkit sends is the operator's responsibility.

Crash → Exploitability Pipeline

For native memory-corruption work, a staged-proof pipeline turns "it crashes" into a defensible, artefact-backed exploitability verdict — run via /engage.crash in the .devcontainer/ toolchain:

1. Root cause — rr deterministic record/replay reverse-steps to the corrupting write (rr_root_cause.sh, emits a trace_proof).
2. Reachability — gcov line-hit / function trace proves the vulnerable line actually ran; the harness will not mark a native bug [CONFIRMED] without a coverage_proof/trace_proof.
3. Empirical feasibility — rebuild the crash witness under permissive/distro/hardened/asan profiles and record which still fire (feasibility_profile.py); exploit_context.py then forbids /exploit from using a technique the empirical mitigation map marks blocked.
4. Path feasibility — branch guards → tri-state SAT/UNSAT (path_conditions.py, Z3 optional; a tool limit is null/manual, never a false "infeasible").

Supporting tools: evidence_kit.py (typed, re-verifiable [EVD-XXX] evidence), variant_hunt.py (one finding → all siblings, clustered by root cause), cve_diff.py (multi-source fix-commit discovery → scope-gated diff), and the incident-response repo-compromise forensics kit.

Skill-Invocation Discipline (dispatcher + process skills)

Installed as a plugin, a SessionStart hook injects the using-offensive-claude dispatcher into