shellcode_tools: The Unix Philosophy Applied to Exploit Development

Hook

The most valuable security tools aren't always the ones with the most features—sometimes a 200-line Python script that does exactly one thing beats an entire framework.

Context

If you've ever developed exploits or worked in offensive security, you've encountered this workflow friction: you've crafted perfect shellcode, tested it in a debugger, verified every byte—and now you need to actually deliver it. You could manually hex-encode it into a Python array, or painstakingly construct a PE/ELF wrapper by hand, or fire up a heavyweight framework just to convert formats. This tedious translation layer between raw shellcode and executable formats has historically been a manual, error-prone process.

MarioVilas created shellcode_tools to eliminate this friction. Rather than building another monolithic exploitation framework, he followed the Unix philosophy: write programs that do one thing well and work together. The toolkit provides two core utilities—bin2py for embedding binary data in Python scripts, and shellcode2exe for wrapping shellcode in native executable formats. These tools emerged from real-world pentesting needs where speed and simplicity matter more than comprehensive feature sets. For CTF players, security researchers, and exploit developers who already have working shellcode, this toolkit removes the busywork.

Technical Insight

The architecture of shellcode_tools reflects a deliberate minimalism. Rather than abstracting shellcode operations behind layers of APIs, each tool operates as a straightforward file processor: read binary input, apply format transformations, write output. This design makes the code auditable and modifications trivial—critical properties when working with security tooling.

The bin2py utility demonstrates this philosophy perfectly. At its core, it reads arbitrary binary data and generates Python source code that reconstructs that data. Here's how you'd use it to embed a raw payload:

# Convert binary shellcode to Python
# Input: raw_payload.bin (raw bytes)
# Output: payload.py (Python source)

$ python bin2py.py raw_payload.bin > payload.py

# Generated payload.py contains:
payload = (
    b"\x31\xc0\x50\x68\x2f\x2f\x73\x68"
    b"\x68\x2f\x62\x69\x6e\x89\xe3\x50"
    b"\x53\x89\xe1\xb0\x0b\xcd\x80"
)

# Now import directly in your exploit
from payload import payload
connection.send(payload)

This approach solves a common problem in exploit development: keeping payloads self-contained within Python scripts without manual hex encoding. The generated code is clean, version-controllable, and doesn't require external binary files at runtime.

The more sophisticated tool is shellcode2exe, which handles the complexity of executable format generation. Creating valid PE (Windows), ELF (Linux), or Mach-O (macOS) files requires understanding file headers, section alignment, entry points, and architecture-specific quirks. shellcode2exe abstracts this away:

# Convert shellcode to Windows executable
$ python shellcode2exe.py -i reverse_shell.bin -o payload.exe -a x86 -p windows

# Convert same shellcode to Linux executable
$ python shellcode2exe.py -i reverse_shell.bin -o payload.elf -a x64 -p linux

# The tool handles:
# - PE/ELF/Mach-O header generation
# - Section alignment and permissions
# - Entry point configuration
# - Architecture-specific details

Under the hood, shellcode2exe creates minimal executable wrappers. For PE files, it generates a tiny loader stub that allocates executable memory, copies the shellcode, and jumps to it. The ELF implementation follows a similar pattern but leverages Linux-specific executable conventions. This means the resulting executables are typically only a few KB larger than the raw shellcode—no bloated frameworks or unnecessary dependencies.

The tool's format generation logic is surprisingly straightforward when you examine the source. For PE files, it constructs the DOS header, PE signature, COFF header, optional header, and a single executable section containing the shellcode. All offset calculations are hardcoded for the minimal viable structure, which keeps the code under 300 lines. This simplicity is intentional: if you need to modify the wrapper or add obfuscation, you can understand and patch the code in an afternoon.

One underappreciated feature is how these tools compose. You can chain bin2py and shellcode2exe with standard Unix pipes, integrate them into build scripts, or wrap them in automation. The lack of state, configuration files, or complex dependencies means they work reliably across environments. Copy two Python files to a new system and you're operational—no installation, no setup, no surprises.

Gotcha

The biggest limitation is age. shellcode_tools was last actively maintained several years ago, and executable formats have evolved. Modern Windows systems use ASLR, DEP, and Control Flow Guard extensively. The PE files generated by shellcode2exe are valid but lack any evasion techniques. They'll trigger antivirus immediately and won't bypass modern exploit mitigations. If you execute a shellcode2exe-generated binary on a current Windows 10/11 system, expect DEP violations unless your shellcode explicitly handles it.

The tool also assumes you bring your own shellcode. There's no generation, encoding, or obfuscation built in. If you need NOP sleds, polymorphic encoders, or bad character avoidance, you'll handle that upstream. This is by design—shellcode_tools focuses purely on format conversion—but it means this isn't a complete exploitation toolkit. For modern offensive security work, you'd typically use this for quick prototypes or educational purposes, then graduate to msfvenom or custom tooling for production payloads. The lack of documentation beyond basic usage also means you need existing knowledge of shellcode and executable formats to use these tools effectively.

Verdict

Use if: You need quick shellcode-to-executable conversion for CTF challenges, are learning exploit development and want to understand executable formats without framework abstraction, need to embed binary payloads in Python scripts for research, or want lightweight tools you can audit and modify yourself. This toolkit excels in educational contexts and rapid prototyping where you control the target environment. Skip if: You need modern evasion techniques for current Windows/Linux systems, want comprehensive shellcode generation rather than just conversion, require active maintenance and support for new executable format features, or are conducting professional red team engagements where detection avoidance matters. For production offensive security work, msfvenom or donut are better choices despite their complexity.