superhackers

# Superhackers

Superhackers is a complete offensive security workflow for your coding agents, originally forked from [obra/superpowers](https://github.com/obra/superpowers) and fully rewritten for penetration testing, security assessment, and secure code review by [narlyseorg](https://github.com/narlyseorg). Built on a set of composable "skills" and initial instructions that make sure your agent uses them.

## How it works

It starts from the moment you fire up your coding agent. As soon as it sees that you're starting a security engagement, it *doesn't* just jump into trying to run exploits. Instead, it steps back and performs systematic reconnaissance to understand the target surface.

Once it's mapped out the target, it shows you the enumeration results in chunks short enough to actually read and digest. It looks for low-hanging fruit while planning deeper assessment.

After you've signed off on the assessment plan, your agent puts together an implementation plan for specific security tests. It emphasizes evidence-based verification, responsible disclosure, and systematic methodology. It avoids "spray and pray" tactics in favor of targeted, impact-driven testing.

Next up, once you say "go", it launches a *subagent-driven-testing* process, having agents work through each security task—from recon to vulnerability verification and exploit development—inspecting and reviewing their findings, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time through a complex pentest without deviating from the scope you defined.

There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has superhackers.

## Engagement Flow

```mermaid
flowchart LR
    A["security-assessment<br/><i>Planning</i>"] --> B["recon-and-enumeration<br/><i>Discover</i>"] --> C["target-specific pentesting<br/><i>webapp · api · infra · android</i>"]

    style A fill:#1a1a2e,stroke:#e94560,color:#fff
    style B fill:#1a1a2e,stroke:#0f3460,color:#fff
    style C fill:#1a1a2e,stroke:#533483,color:#fff
```

```mermaid
flowchart RL
    D["vulnerability-verification<br/><i>Confirm</i>"] --> E["exploit-development<br/><i>Prove Impact</i>"] --> F["writing-security-reports<br/><i>Document</i>"]

    style D fill:#1a1a2e,stroke:#e94560,color:#fff
    style E fill:#1a1a2e,stroke:#950740,color:#fff
    style F fill:#1a1a2e,stroke:#0f3460,color:#fff
```

## Integrated Tools

Skills reference these tools (must be installed separately):

| Category | Tools |
|----------|-------|
| **Scanning** | rustscan, nmap, nuclei, nikto, httpx |
| **Fuzzing** | ffuf, sqlmap |
| **Interception** | BurpSuite, mitmproxy |
| **Exploitation** | Metasploit (msfconsole, msfvenom) |
| **Mobile** | Frida, adb, apktool, jadx |
| **Network** | bettercap, smuggler |
| **Cracking** | john, hashcat |

**See [TOOLCHAIN.md](TOOLCHAIN.md)** for the complete tool registry, fallback chains, and platform compatibility matrix.

## Getting Started

**Two steps to be fully operational:**

### Step 1: Install the Plugin

Configure your AI assistant to use superhackers. See platform-specific guides:

| Platform | Method |
|----------|--------|
| Claude Code | `/plugin marketplace add narlyseorg/superhackers` then `/plugin install superhackers` |
| Cursor | `/plugin-add https://github.com/narlyseorg/superhackers` |
| Codex | [.codex/INSTALL.md](.codex/INSTALL.md) |
| OpenCode | [.opencode/INSTALL.md](.opencode/INSTALL.md) |

**For AI Agents:** If you are an AI coding agent installing superhackers, use the appropriate method for your platform:

- **Claude Code**: `/plugin marketplace add narlyseorg/superhackers` then `/plugin install superhackers`
- **Cursor**: `/plugin-add https://github.com/narlyseorg/superhackers`
- **Codex**: Fetch and follow the instructions at:
  `https://raw.githubusercontent.com/narlyseorg/superhackers/main/.codex/INSTALL.md`
- **OpenCode**: Fetch and follow the instructions at:
  `https://raw.githubusercontent.com/narlyseorg/superhackers/main/.opencode/INSTALL.md`

### Step 2: Install Security Tools

Skills need security tools (nmap, nuclei, sqlmap, etc.) to execute.

Run the automated setup script or follow the manual installation instructions for your platform:

**Automated Setup:**

| Platform | Script | Command |
|----------|--------|---------|
| macOS/Linux (Bash) | `setup.sh` | `bash setup.sh` |
| Windows (PowerShell) | `setup.ps1` | `powershell -ExecutionPolicy Bypass -File setup.ps1` |

**Manual Installation:** See [SETUP.md](SETUP.md) for detailed platform-specific instructions.

The AI will automatically detect which tools are available and provide appropriate alternatives.

### Verify Installation

Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "let's start recon on this target" or "run a security assessment"). The agent should automatically invoke the relevant superhackers skill.

## Cross-Platform Support

Superhackers works on **Linux**, **macOS**, and **Windows (WSL2)** with automatic tool detection:

| Platform | Recommended Setup | Notes |
|----------|-------------------|-------|
| Linux (Kali/Ubuntu/Fedora) | Native install | Best experience, all tools supported |
| macOS | Native install | Most tools via Homebrew, full functionality |
| Windows | WSL2 + Ubuntu | Full Linux environment via WSL2; PowerShell available with limited tool support |

Not all tools are available on every platform. The [TOOLCHAIN.md](TOOLCHAIN.md) resolution protocol automatically detects available tools and provides alternatives when needed.

## Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `SUPERHACKERS_ROOT` | Plugin installation path (auto-set by platform) | Platform-dependent |
| `SUPERHACKERS_WORDLISTS` | Custom wordlists directory location | `~/wordlists/` or system paths |

The AI assistant automatically has `SUPERHACKERS_ROOT` available in session context for file operations.

## Wordlists

Many skills depend on wordlists for fuzzing, cracking, and discovery. Superhackers looks for wordlists in the following order:

1. `SUPERHACKERS_WORDLISTS` environment variable
2. `/usr/share/wordlists/` (Kali/Debian)
3. `/opt/homebrew/share/wordlists/` (macOS Homebrew)
4. `~/wordlists/` (user home)

See [wordlists/README.md](wordlists/README.md) for required wordlists and quick setup instructions.

## Uninstallation

To completely remove superhackers from your system (platform integration, tools, and configuration), follow the step-by-step guide in [UNINSTALL.md](UNINSTALL.md).

Quick removal by platform:

| Platform | Quick Remove |
|----------|-------------|
| Claude Code | `/plugin uninstall superhackers` |
| Cursor | `/plugin-remove superhackers` |
| Codex | `rm ~/.agents/skills/superhackers && rm -rf ~/.codex/superhackers` |
| OpenCode | `rm ~/.config/opencode/plugins/superhackers.js && rm -rf ~/.config/opencode/skills/superhackers` |

See [UNINSTALL.md](UNINSTALL.md) for complete removal including native tools, wordlists, environment variables, and a verification script.

## The Basic Workflow

1. **security-assessment** - Activates for engagement planning. Performs threat modeling, defines scope, maps compliance requirements, and orchestrates the overall testing strategy.

2. **recon-and-enumeration** - Activates after planning. Performs passive and active reconnaissance (OSINT, nmap, ffuf, nuclei) to map the target surface and discover entry points.

3. **target-specific-skill** - Activates based on the identified target (webapp-pentesting, api-pentesting, infra-pentesting, android-pentesting, or secure-code-review). Executes deep-dive testing for the specific technology stack.

4. **vulnerability-verification** - Activates to confirm findings. Eliminates false positives, demonstrates impact, calculates CVSS scores, and chains vulnerabilities for maximum effect.

5. **exploit-development** - Activates when verified vulnerabilities need impact demonstration. Creates and customizes exploits using Metasploit, msfvenom, or custom scripts to prove impact safely.

6. **writing-security-reports** - Activates at the conclusion of testing. Documents findings with reproducible steps, executive summaries, and actionable remediation guidance.

**The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions.

## What's Inside

### Skills Library

**Pentesting**
- **webapp-pentesting** — OWASP Top 10, XSS, SQLi, SSRF, auth bypass, deserialization
- **api-pentesting** — REST, GraphQL, gRPC, WebSocket: BOLA/IDOR, OAuth2/JWT
- **infra-pentesting** — Network, AD, credential cracking, pivoting, privesc
- **android-pentesting** — Frida hooking, SSL pinning bypass, static/dynamic analysis

**Security Analysis**
- **secure-code-review** — Source code analysis for injection, auth, crypto issues
- **security-assessment** — Planning, threat modeling, CVSS scoring, orchestration
- **assessment-orchestrator** — Multi-component assessment coordination with automatic related target discovery (APIs, subdomains, backend services)
**Supporting Skills**
- **recon-and-enumeration** — Passive/active discovery: nmap, ffuf, nuclei, httpx
- **exploit-development** — Creation and customization: Metasploit, msfvenom, evasion
- **vulnerability-verification** — False positive elimination, impact demonstration
- **writing-security-reports** — Professional documentation and remediation guidance

**Technology-Specific Skills**
- **fastapi-security** — FastAPI/Starlette/Uvicorn stack security assessment
- **firebase-security** — Firebase/Firestore/RTDB security testing
- **graphql-security** — GraphQL API security (introspection, batching, auth bypass)
- **nextjs-security** — Next.js/React SSR testing (middleware bypass, RSC, `__NEXT_DATA__`)
- **supabase-security** — Supabase/PostgREST/RLS/Storage security assessment

**Technique Reference Guides**
- `webapp-pentesting/auth-bypass-techniques.md` — Authentication and authorization bypass payloads
- `webapp-pentesting/business-logic-domains.md` — Domain-specific business logic testing
- `webapp-pentesting/sqli-techniques.md` — SQL injection technique reference
- `webapp-pentesting/ssrf-techniques.md` — Server-side request forgery techniques
- `webapp-pentesting/xss-techniques.md` — Cross-site scripting payload reference

**Meta & Infrastructure**
- **writing-security-skills** — Create new security skills following best practices
- **using-superhackers** — Introduction to the offensive security skills system
- **dispatching-parallel-agents** — Parallel execution of independent security tasks
- **using-git-worktrees** — Isolated workspaces for exploit development
- **finishing-an-engagement** — Engagement completion, evidence archival, cleanup

### Agents

| Agent | Purpose |
|-------|---------|
| **security-reviewer** | Senior security reviewer for finding validation, exploit code review, and report QA |

### Commands

| Command | Purpose |
|---------|---------|
| `/assess` | Plan and execute a full security assessment (orchestrates all skills) |
| `/scan` | Start reconnaissance and enumeration on a target |
| `/report` | Write a professional security report documenting findings |

### Operational Scripts

Helper scripts in `scripts/` for engagement automation:

| Script | Purpose |
|--------|---------|
| `capability-check.sh` | Pre-engagement tool capability verification |
| `engagement-init.sh` | Engagement directory structure and state file scaffolding |
| `preflight.sh` | Pre-flight checks per engagement type |
| `run-tool.sh` | Tool execution wrapper with auto-validation |
| `validate-output.sh` | Scan output validation (catches silent failures) |

### Project Files

| File | Purpose |
|------|---------|
| `TOOLCHAIN.md` | Tool resolution protocol for AI assistants |
| `SETUP.md` | Installation guide for users (Native/WSL2) |
| `setup.sh` | Automated installation script for macOS/Linux |
| `setup.ps1` | Automated installation script for Windows (PowerShell) |
| `wordlists/README.md` | Wordlist management guide |

## Philosophy

- **Evidence-based verification** — Always confirm exploitability before reporting
- **Responsible disclosure** — Operate within defined scope and ethical guidelines
- **Scope compliance** — Never exceed the boundaries of the engagement
- **Systematic methodology** — Process-driven testing over "spray and pray"
- **False-positive elimination** — Provide high-signal results to stakeholders

## Legal Disclaimer

**Superhackers is provided strictly for authorized security testing, educational purposes, and lawful security research.** By using this software, you acknowledge and agree to the following:

1. **Authorization Required.** You must obtain explicit, written authorization from the system owner before conducting any security testing. Unauthorized access to computer systems is illegal under the Computer Fraud and Abuse Act (CFAA), the Computer Misuse Act, and equivalent legislation worldwide.

2. **User Responsibility.** You are solely and entirely responsible for ensuring that your use of this software complies with all applicable local, state, national, and international laws and regulations. The determination of legality rests exclusively with you.

3. **No Liability.** The authors, contributors, and maintainers of this project accept **no responsibility or liability whatsoever** for any misuse, damage, legal consequences, or any other harm arising from the use or misuse of this software. This includes, but is not limited to, direct, indirect, incidental, special, consequential, or punitive damages of any kind.

4. **No Warranty.** This software is provided "as is" without warranty of any kind, express or implied. The authors make no representations regarding the accuracy, completeness, or suitability of this software for any particular purpose.

5. **Indemnification.** By using this software, you agree to indemnify and hold harmless the authors, contributors, and maintainers from and against any and all claims, damages, losses, liabilities, costs, and expenses (including reasonable attorneys' fees) arising from your use or misuse of this software.

6. **Ethical Use.** This software is designed to help security professionals improve the security posture of systems they are authorized to test. Any use of this software for malicious purposes, unauthorized access, or any activity that violates applicable law is strictly prohibited and expressly condemned by the authors.

**If you do not agree with these terms, do not use this software.**

## Contributing

Skills live directly in this repository. To contribute:

1. Fork the repository
2. Create a branch for your skill
3. Follow the `writing-security-skills` skill for creating and testing new skills
4. Submit a PR

See [docs/testing.md](docs/testing.md) for the test suite and validation procedures.

## Updating

Skills update automatically when you update the plugin:

```bash
/plugin update superhackers
```

## License

MIT License - see LICENSE file for details

## Support

- **Issues**: https://github.com/narlyseorg/superhackers/issues