Metadata-Version: 2.5
Name: pwnbench
Version: 0.2.0
Summary: The all-in-one terminal workbench for CTF, bug bounty & pentest — transform data, generate payloads, track targets, and write reports without leaving your shell.
Project-URL: Homepage, https://github.com/dev-joshua-py/pwnbench
Project-URL: Repository, https://github.com/dev-joshua-py/pwnbench
Project-URL: Issues, https://github.com/dev-joshua-py/pwnbench/issues
Project-URL: Changelog, https://github.com/dev-joshua-py/pwnbench/blob/main/CHANGELOG.md
Author: dev-joshua-py
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: ai-agent,bug-bounty,cli,ctf,cyberchef,cybersecurity,hacking,hackthebox,mcp,oscp,pentest,recon,reverse-shell,security,tryhackme,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: rich>=13.0
Provides-Extra: all
Requires-Dist: mcp<3,>=2; (python_version >= '3.10') and extra == 'all'
Requires-Dist: pyperclip>=1.8; extra == 'all'
Requires-Dist: textual>=0.60; extra == 'all'
Provides-Extra: clip
Requires-Dist: pyperclip>=1.8; extra == 'clip'
Provides-Extra: dev
Requires-Dist: mcp<3,>=2; (python_version >= '3.10') and extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: textual>=0.60; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; (python_version >= '3.10') and extra == 'mcp'
Provides-Extra: tui
Requires-Dist: textual>=0.60; extra == 'tui'
Description-Content-Type: text/markdown

<div align="center">

<img src="assets/demo.svg" alt="pwnbench — the all-in-one terminal workbench for CTF, bug bounty & pentest" width="820">

<h1>pwnbench</h1>

<strong>The all-in-one terminal workbench for CTF, bug bounty &amp; pentest.</strong><br>
Transform data, crack encodings, generate payloads, track targets, and write reports — without leaving your shell.

<br><br>

[![PyPI](https://img.shields.io/pypi/v/pwnbench?color=00e676&label=pypi)](https://pypi.org/project/pwnbench/)
[![Python](https://img.shields.io/pypi/pyversions/pwnbench?color=22d3ee)](https://pypi.org/project/pwnbench/)
[![CI](https://github.com/dev-joshua-py/pwnbench/actions/workflows/ci.yml/badge.svg)](https://github.com/dev-joshua-py/pwnbench/actions/workflows/ci.yml)
[![License: GPL-3.0](https://img.shields.io/badge/license-GPLv3-green.svg)](LICENSE)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-e879f9.svg)](CONTRIBUTING.md)

<sub>Created &amp; maintained by <strong>dev-joshua-py</strong></sub>

</div>

---

## Why pwnbench?

During a CTF or an engagement you bounce between a dozen tabs: CyberChef to decode a string, revshells.com for a reverse shell, a scratch file for your target notes, another for your nmap output, and a Word doc for the write-up. **pwnbench puts all of that in one fast, keyboard-driven, offline tool** — and it's built to be pipe-friendly, so it drops straight into your existing one-liners.

```bash
# decode a mystery string automatically...
echo 'V1VkNGRtVkhPWGxpU0dSNldsaG9k...' | pwnbench magic

# ...pipe a base64 blob through a recipe...
cat token.jwt | pwnbench transform -r jwt-decode

# ...grab a reverse shell and copy it to your clipboard...
pwnbench payload revshell bash -l 10.10.14.3 -p 443 | xclip -sel clip

# ...and keep your whole engagement organised.
pwnbench ws import-nmap scan.xml && pwnbench ws show
```

No cloud. No 400 MB of dependencies. **One `pip install`, one binary, pure Python.**

---

## Install

```bash
pipx install pwnbench          # recommended — isolated, always on your PATH
```

<details>
<summary>Other ways</summary>

```bash
pip install pwnbench           # into the current environment
pip install 'pwnbench[all]'    # + interactive TUI + clipboard support
pipx install pwnbench && pipx inject pwnbench textual   # add the TUI later

# from source
git clone https://github.com/dev-joshua-py/pwnbench && cd pwnbench
pip install -e '.[dev]'
```
</details>

Requires **Python 3.9+**. Works on Linux, macOS, Windows and WSL.

---

## The four modules

pwnbench is one tool with four tightly-integrated modules. Findings you record in the **workspace** flow straight into a **report**; the **transform** engine powers the **magic** solver.

| | Module | What it does |
|---|---|---|
| 🧪 | **`transform`** / **`magic`** | A CyberChef-in-your-terminal: chain encode/decode/hash/cipher ops, or auto-solve unknown strings. |
| 💣 | **`payload`** / **`cheatsheet`** | Reverse shells, listeners, msfvenom builders, web test vectors and quick-reference notes. |
| 🗂️ | **`ws`** | Track scope, targets, ports & notes per engagement — with nmap import. |
| 📄 | **`report`** | Turn your findings into a polished Markdown / HTML report. |

---

### 🧪 `transform` — the terminal data multitool

Chain operations with `|`, exactly like a CyberChef recipe, but in your shell:

```bash
pwnbench transform 'Hello' -r 'to-base64 | rot13'
pwnbench transform 'SGVsbG8=' -r 'from-base64 | to-hex' --steps
pwnbench transform 'password' -r ntlm          # NTLM hash (pure-Python MD4)
echo -n 'admin:admin' | pwnbench transform -r to-base64   # pipe-friendly
```

**50+ operations** across encodings (base64/32/58/85, hex, url, html, binary, decimal, morse), text & classic ciphers (rot13/47, caesar, vigenère, atbash, rail-fence, XOR), hashing (md5, sha-family, blake2, crc32, **ntlm/md4**), compression (gzip, zlib) and formats (**jwt-decode**, json). List them all with `pwnbench transform --list`.

Everything works on **raw bytes** internally, so chains like `from-base64 | xor 0x2a | from-gzip` are byte-accurate.

### ✨ `magic` — the auto-decoder / CTF solver

Don't know what encoding you're looking at? Let pwnbench figure it out. It recursively tries every common encoding, every ROT/Atbash/reverse, **every Caesar shift and every single-byte XOR key**, then ranks the results by how much they look like a flag or English text.

<div align="center"><img src="assets/magic.svg" alt="pwnbench magic auto-decoder" width="720"></div>

```bash
pwnbench magic 'synt{ebg13_vf_gbb_rnfl}'
pwnbench magic 'Vm0wd2QyUXlVWGxWV0d4V...'      # peels layered base64 automatically
cat mystery.bin | pwnbench magic -n 10          # show the top 10 candidates
```

### 💣 `payload` — reverse shells & test vectors

> ⚠️ **For authorized testing, CTFs and education only.** These are standard, publicly documented techniques; use them only against systems you own or have explicit permission to test.

<div>

```bash
pwnbench payload revshell bash -l 10.10.14.3 -p 443
pwnbench payload revshell python3 -l 10.10.14.3 -p 443 -e url    # url-encoded
pwnbench payload revshell powershell -l 10.10.14.3 -p 443 -e powershell  # -e base64 blob
pwnbench payload listener socat-tty -p 443       # matching listener for a full TTY
pwnbench payload msfvenom windows-x64 -l 10.10.14.3 -p 443
pwnbench payload web sqli                         # curated SQLi test strings
pwnbench payload revshell --list                  # ~20 shells: bash, nc, python, php, perl, ruby, socat, awk, lua, node, powershell, ...
```

Plus **cheatsheets** for the things you always forget:

```bash
pwnbench cheatsheet shell-stabilize      # the Ctrl-Z / stty raw -echo dance
pwnbench cheatsheet linux-privesc
pwnbench cheatsheet file-transfer
pwnbench cheatsheet --list
```
</div>

### 🗂️ `ws` — your engagement workspace

Stop keeping targets in a messy text file. Track scope, hosts, ports and notes per project — and **import nmap XML directly**.

<div align="center"><img src="assets/workspace.svg" alt="pwnbench workspace dashboard" width="820"></div>

```bash
pwnbench ws new hackthebox-lab
pwnbench ws scope add '*.lab.htb'                 # supports wildcards
pwnbench ws scope check admin.lab.htb             # instant in/out-of-scope answer (great for bug bounty!)
nmap -sC -sV -oX scan.xml 10.10.10.3
pwnbench ws import-nmap scan.xml                  # hosts + ports imported & merged
pwnbench ws checklist                             # per-target methodology checklist
pwnbench ws show                                  # the dashboard above
```

### 📄 `report` — findings in, report out

Record findings as you go, then render a professional report in seconds:

```bash
pwnbench finding add 'SQLi in login' -s high --cvss 8.1 \
    --target 10.10.10.3 --desc '...' --impact '...' --remediation '...'

pwnbench report build --format html -o report.html   # self-contained, prints to PDF
pwnbench report build > report.md                    # Markdown to stdout
```

The HTML report is a single self-contained file (inline CSS, severity badges, CVSS, a TOC) that prints cleanly to PDF from any browser.

### 🖥️ `tui` — the interactive dashboard

Prefer buttons to flags? `pwnbench tui` launches an interactive [Textual](https://textual.textualize.io/) dashboard tying transform, payloads and your workspace together (`pip install 'pwnbench[tui]'`).

---

## 🤖 Use pwnbench from any AI agent (MCP)

pwnbench speaks the [**Model Context Protocol**](https://modelcontextprotocol.io) — so Claude Desktop, Cursor, or any MCP client can call it directly. Ask your assistant *"decode this base64 blob"*, *"give me a Python reverse shell for 10.10.14.3:443"*, or *"is admin.acme.com in scope?"* and it runs the real pwnbench tools under the hood.

```bash
pip install 'pwnbench[mcp]'      # needs Python 3.10+
pwnbench mcp                      # stdio server, for desktop clients
pwnbench mcp --transport http     # or streamable-HTTP on 127.0.0.1:8765
```

Point a client at it — e.g. in Claude Desktop's `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pwnbench": { "command": "pwnbench", "args": ["mcp"] }
  }
}
```

Ten tools are exposed: `transform`, `magic`, `list_operations`, `reverse_shell`, `list_reverse_shells`, `listener`, `web_vectors`, `cheatsheet`, `scope_check` and `workspace_summary` — your whole workbench, now driveable by an LLM.

---

## Command reference

```
pwnbench transform  (t)   run a recipe pipeline over data      pwnbench ws new|use|list|show
pwnbench magic      (m)   auto-detect & decode a string        pwnbench ws scope add|list|check|rm
pwnbench payload    (p)   revshell|bindshell|listener|         pwnbench ws target add|list|show|set|rm
                          msfvenom|web                         pwnbench ws port add
pwnbench cheatsheet (cs)  quick-reference notes                pwnbench ws note add|list
pwnbench finding    add|list|show|rm                           pwnbench ws checklist
pwnbench report     build [--format md|html] [-o FILE]         pwnbench ws import-nmap FILE
pwnbench tui              interactive dashboard
```

Every command has `-h`. Workspaces live in `~/.pwnbench/` (override with `PWNBENCH_HOME`).

---

## Design notes

- **Pure Python, one runtime dependency** ([`rich`](https://github.com/Textualize/rich)). `pipx install` never needs a compiler.
- **Pipe-first.** Decorative output goes to *stderr*; the actual result goes to *stdout* as raw bytes, so pwnbench slots into `|` chains and `$(...)` substitutions.
- **Offline & private.** Nothing is sent anywhere. Your targets and findings stay on your disk.
- **Extensible.** Adding a transform op is one decorated function; adding a payload is one line of data.

---

## Contributing

Contributions are very welcome — new operations, payloads, cheatsheets, report templates, or magic-solver improvements. See **[CONTRIBUTING.md](CONTRIBUTING.md)**. Good first issues are labeled [`good first issue`](https://github.com/dev-joshua-py/pwnbench/labels/good%20first%20issue).

```bash
pip install -e '.[dev]'
ruff check src tests && pytest      # what CI runs
```

## Disclaimer

pwnbench is a tool for **authorized** security testing, CTF competitions and education. You are responsible for complying with all applicable laws and for having explicit permission before testing any system. The author accepts no liability for misuse.

## Author &amp; ownership

pwnbench is designed, written and maintained by **dev-joshua-py**.

**Copyright © 2026 dev-joshua-py. All rights reserved where not granted by the license below.**

This is my work. You're welcome to use it, learn from it and build on it — the license makes that explicit — **but you must keep the credit and play by the rules:**

- 🔒 **Licensed under the [GNU GPL-3.0](LICENSE).** If you copy, modify or redistribute pwnbench (or any part of it), your version must **stay open source under the same license and keep this attribution**. You may not take this code, strip my name off it, and ship it as your own or as a closed-source product.
- ✍️ **Credit is not optional.** Don't repackage, rebrand or re-upload this project as if it were yours. Forks and derivatives must clearly credit the original author and link back to this repository.
- ⚖️ Plagiarism — passing my work off as your own — is a licence violation and I *will* pursue takedowns for it.

If you want to use pwnbench in a way the GPL doesn't allow, open an issue and ask — I'm reasonable.

## License

Licensed under the **GNU General Public License v3.0 or later** — see [LICENSE](LICENSE). Copyright © 2026 dev-joshua-py.

<div align="center"><sub>If pwnbench saves you a few tabs, consider leaving a ⭐ — it genuinely helps.</sub></div>
