ret2win 1.3.4

 ██████╗ ███████╗████████╗██████╗ ██╗    ██╗██╗███╗   ██╗
 ██╔══██╗██╔════╝╚══██╔══╝╚════██╗██║    ██║██║████╗  ██║
 ██████╔╝█████╗     ██║    █████╔╝██║ █╗ ██║██║██╔██╗ ██║
 ██╔══██╗██╔══╝     ██║   ██╔═══╝ ██║███╗██║██║██║╚██╗██║
 ██║  ██║███████╗   ██║   ███████╗╚███╔███╔╝██║██║ ╚████║
 ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝ ╚══╝╚══╝ ╚═╝╚═╝  ╚═══╝
  

Automated CTF Return-to-Win Exploitation Toolkit & Interactive TUI

Supercharge your binary exploitation workflow. Zero-guesswork crash analysis, checksec auditing, stack alignment hunting, colorized payload breakdowns, and instant remote flag captures.

---

⚡ Overview

Ret2Win is a modern binary exploitation toolkit engineered specifically for CTF players, security researchers, and exploit developers.

In traditional CTF competitions, solving a classic ret2win challenge typically involves repeated manual steps:

1. Running checksec on the binary.
2. Disassembling symbols with objdump, readelf, or Ghidra to spot target functions.
3. Launching GDB, generating cyclic patterns, crashing the binary, copying addresses, and running cyclic -l.
4. Calculating stack padding, hunting lone ret gadgets for 16-byte stack alignment (movaps crash prevention), and drafting an exploit script.

Ret2Win completely automates this lifecycle. It analyzes the ELF binary, detects checksec mitigations, locates win functions, fuzzes the exact offset using native core dumps (with automatic GDB fallback), crafts the payload, guarantees 16-byte stack alignment, and either drops you into an interactive shell or generates a standalone, clean solve.py script—in under 3 seconds.

Available both as a rich, split-scrolling Cyberpunk Terminal User Interface (TUI) and as a fully scriptable CLI tool.

---

🖥️ Interactive Terminal UI

Launch the interface with a single command:

ret2win

            ██████╗ ███████╗████████╗██████╗ ██╗    ██╗██╗███╗   ██╗            
            ██╔══██╗██╔════╝╚══██╔══╝╚════██╗██║    ██║██║████╗  ██║            
            ██████╔╝█████╗     ██║    █████╔╝██║ █╗ ██║██║██╔██╗ ██║            
            ██╔══██╗██╔══╝     ██║   ██╔═══╝ ██║███╗██║██║██║╚██╗██║            
            ██║  ██║███████╗   ██║   ███████╗╚███╔███╔╝██║██║ ╚████║            
            ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝ ╚══╝╚══╝ ╚═╝╚═╝  ╚═══╝            
                                                                                
  ─── Automated CTF Return-to-Win Exploitation Toolkit  •  made by -Casper ───  

╭── [ TARGET BINARY & MITIGATIONS ] ──────────╮╭── [ EXPLOIT CONFIGURATION ] ───────────────╮
│  Binary:        ./vuln                      ││  Win Target:   0x401196 (win)              │
│  Architecture:  amd64 (64-bit, little)      ││  Offset:       88 bytes ✓ Validated        │
│  Checksec:      Partial RELRO │ No Canary   ││  Stack Align:  Enabled (lone ret 0x40101a) │
│  Mitigations:   NX Enabled    │ No PIE      ││  Delivery:     stdin (Standard Input)      │
│  Win Candidate: win (0x401196)              ││  Destination:  Local Process (vuln)        │
│  Ret Gadget:    0x40101a (x86_64 16B align) ││  Payload Size: 104 bytes (payload.bin)     │
╰─────────────────────────────────────────────╯╰────────────────────────────────────────────╯
 Status: Offset verified (88 bytes). Exploit payload compiled and armed.

╭───────────────────────────────────────────────────────────────────────────────────────────╮
│                                [ MISSION CONTROL ACTIONS ]                                │
│   [1] Select/Scan Binary        [2] Auto-Detect Offset        [3] Validate Offset         │
│   [4] Set Win Address/Symbol    [5] Toggle 16B Alignment      [6] Toggle Delivery (stdin) │
│   [7] Set Exploit Destination   [8] Inspect Payload & Hexdump [9] ELF Symbol Browser      │
│   [f] Fire Exploit & solve.py   [h] Help & CTF Guide          [q] Quit Ret2Win            │
╰───────────────────────────────────────────────────────────────────────────────────────────╯

ret2win ➜

Colorized Payload Inspection

Ret2Win visually dissects and displays the structure of the generated buffer:

  00000000:  41 41 41 41 41 41 41 41  41 41 41 41 41 41 41 41   AAAAAAAAAAAAAAAA
  ...
  00000050:  41 41 41 41 41 41 41 41  1a 10 40 00 00 00 00 00   AAAAAAAA..@.....
  00000060:  96 11 40 00 00 00 00 00                            ..@.....

  Breakdown:
  • 0x00 - 0x57 [88 bytes] : Cyclic Padding ('A' * 88)
  • 0x58 - 0x5F [ 8 bytes] : Lone `ret` Gadget (0x40101a) [16-Byte Stack Alignment]
  • 0x60 - 0x67 [ 8 bytes] : Target `win()` Address (0x401196)

---

🚀 Installation

Ret2Win can be installed via PyPI, the universal installer script, or directly from source.

Method 1: Install from PyPI (Simplest)

Ret2Win is officially published on PyPI: https://pypi.org/project/ret2win/

Install globally via pipx or inside a virtual environment:

# Recommended for CLI tools on modern Linux (PEP 668)
pipx install ret2win

# Or via standard pip in your active environment
pip install ret2win

---

Method 2: Universal Automated Installer (Recommended for Local Git Repo)

Clone the repository and run the installer:

git clone https://github.com/Vishal-07-R/Ret2Win.git
cd Ret2Win
./install.sh

Installer Options:

./install.sh                # User-space install (~/.local/share/ret2win and ~/.local/bin/ret2win)
./install.sh -y             # Silent, non-interactive automated install
sudo ./install.sh --system  # System-wide install for all users (/usr/local/bin/ret2win)
./install.sh --dev          # Developer symlink mode (links directly to active repo)
./install.sh --check        # Audit system dependencies and coredump configuration
./install.sh --uninstall    # Clean uninstallation of Ret2Win and launcher links

---

Method 3: From Source (git)

Using pipx (Isolated user application):

pipx install .

Using pip with Virtual Environment:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .

---

Distribution Prerequisites

Ret2Win utilizes standard Linux tools for binary inspection and crash capturing. The install.sh script will automatically offer to install these for you:

Arch Linux / CachyOS / Manjaro

sudo pacman -S python python-pip gdb wl-clipboard xclip qemu-user qemu-user-binfmt

Debian / Ubuntu / Kali / Parrot OS

sudo apt update
sudo apt install python3 python3-pip python3-venv gdb wl-clipboard xclip qemu-user qemu-user-static

Fedora / RHEL

sudo dnf install python3 python3-pip python3-virtualenv gdb wl-clipboard xclip qemu-user-static

Termux (Android)

On Android/Termux, upstream psutil rejects Android during PyPI source builds, and unicorn (required by pwntools) compiles native C-extensions requiring cmake and clang. Install Termux's pre-compiled and native build dependencies first:

pkg update && pkg install -y clang cmake make pkg-config libffi openssl binutils python-psutil python-cryptography
pip install ret2win

(Tip: Run ret2win --diagnostics after installation to audit your environment).

---

⚡ Core Dump Optimization (Zero-Guesswork Offset Finding)

To let Ret2Win automatically calculate buffer overflow offsets using native Linux core dumps without GDB delay:

1. Enable unlimited core dumps in your shell:

   ulimit -c unlimited
   

   (Add ulimit -c unlimited to your ~/.bashrc or ~/.zshrc so it is always active).

2. (Optional) If running on Ubuntu/Debian with Apport or systemd-coredump:

   sudo sysctl -w fs.suid_dumpable=1
   

   Note: Even if core dumping is restricted by your kernel, Ret2Win automatically falls back to an integrated GDB crash tracing engine seamlessly.

---

📖 CLI Usage & Command Reference

Ret2Win can be driven completely headless in automation pipelines, CTF scripts, or CI/CD testing.

Command-Line Arguments

Argument	Type	Default	Description
--binary	PATH	None	Path to target ELF binary executable
--win-addr	HEX/SYM	None	Target win function address (e.g. 0x401196) or symbol name (win)
--offset	INT	Auto	Manually specify buffer overflow offset (skips auto-detection)
--max-len	INT	2048	Maximum De Bruijn pattern length for crash auto-detection
--align	FLAG	False	Add 16-byte stack alignment padding (lone ret) before jumping to win
--ret-gadget	HEX/SYM	Auto	Address or symbol of a lone ret instruction
--input-mode	stdin|argv	stdin	How input is delivered to vulnerable program buffer
--output	PATH	payload.bin	File path to write raw binary payload bytes
--run	FLAG	False	Spawn target binary locally, transmit payload, and open interactive shell
--remote	HOST PORT	None	Connect to remote network socket, transmit payload, and open interactive shell
--script	PATH	None	Generate a standalone, documented solve.py script and exit
--validate-offset	FLAG	False	Validate computed offset with a controlled marker crash
--diagnostics, --check	FLAG	False	Audit environment, compilers, Termux status, and dependencies
--tui	FLAG	False	Launch the interactive Terminal User Interface
--no-color	FLAG	False	Strip Rich ANSI color codes and formatting
--version	FLAG	None	Display version information and exit

---

🎯 Practical CTF Cookbooks

1. Zero-Config Local Exploit & Shell

Automatically find the offset, target the win function, and drop into an interactive shell:

ret2win --binary ./vuln --win-addr win --run

2. 64-bit Stack Alignment (movaps crash prevention)

When targeting 64-bit binaries on modern Linux distributions (Ubuntu 18.04+, Debian, Arch) where libc functions crash at movaps:

ret2win --binary ./vuln --win-addr win --align --run

3. Generate a Standalone solve.py for CTF Submission

Generate a modular, production-ready exploit script configured for the competition's remote server:

ret2win --binary ./chall --win-addr 0x401176 --align --remote 10.10.10.42 1337 --script solve.py

4. Argv-Based Vulnerability

When the target program reads input from command line arguments (argv[1]):

ret2win --binary ./cli_vuln --win-addr win --input-mode argv --run

5. Validate Offset Before Exploitation

Test and confirm the offset via canary crash marker verification before executing:

ret2win --binary ./vuln --win-addr win --validate-offset --run

---

💡 Troubleshooting & CTF Deep-Dive

1. Why does my payload crash inside system() or puts()? (Stack Alignment)

The 16-Byte Stack Alignment Rule (x86_64)

The AMD64 System V ABI mandates that before a call instruction is executed, the stack pointer (rsp) must be 16-byte aligned (rsp % 16 == 0). When a function is called, the CPU pushes the 8-byte return address onto the stack, leaving rsp aligned to 8 (mod 16).

Modern glibc implementations make extensive use of SSE instructions (such as movaps or movdqa), which require memory operands to be strictly 16-byte aligned. If the stack is misaligned when entering system(), do_system(), or puts(), the program triggers a SIGSEGV at the movaps instruction.

The Fix: Ret2Win's --align switch automatically prepends a lone ret gadget address to the payload before win(). Executing ret pops 8 bytes off the stack, re-aligning rsp to 16 bytes and allowing SSE instructions to execute without crashing.

2. Why does argv mode reject my payload? (NUL Byte Termination)

The C String Terminator Limitation

Under Linux and POSIX systems, argv[] strings passed via execve() are null-terminated C strings. If an address contains a null byte (0x00) anywhere prior to its final byte (which is standard for 64-bit addresses like 0x0000000000401196), the kernel truncates the argument at the first 0x00.

The Solution: If the binary supports reading from standard input, switch to --input-mode stdin. If argv is mandatory, choose an address or gadget free of embedded null bytes.

3. How does Ret2Win handle Position Independent Executables (PIE)?

PIE / ASLR Handling

When a binary is compiled with PIE enabled, code addresses are randomized on each execution. Static addresses shown in objdump or readelf are relative offsets (e.g. 0x1196), not runtime addresses.

The Solution: When Ret2Win detects PIE, it warns the user. In the interactive TUI, you can supply either the runtime base address or compute base + offset after leaking a pointer.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the Issues page.

1. Fork the Project (https://github.com/Vishal-07-R/Ret2Win/fork)
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

👤 Author

Casper (Vishal-07-R)

• GitHub: @Vishal-07-R
• Focus: CTF Competitions, Binary Exploitation, Reverse Engineering, Cybersecurity

Happy Hacking! May your return addresses always land true. 🚩