Modernizing Black Hat Python: What It Takes to Port Offensive Security Code to Python 3

Hook

The original Black Hat Python source code fails on 64-bit systems due to struct packing bugs that have been lurking since publication. This repository fixes them—and other breaking issues that make the book difficult to follow without community patches.

Context

Justin Seitz’s ‘Black Hat Python’ became a canonical resource for learning offensive security with Python, teaching everything from packet sniffing to building trojans. But the original source code, hosted by No Starch Press, uses libraries like netaddr and scapy that either stopped supporting Python 3 or were deprecated entirely. Readers attempting to follow along found themselves in dependency hell—SSH servers missing RSA keys, packet sniffers throwing struct errors, and imports that don’t exist in Python 3. EONRaider’s blackhat-python3 repository bridges that gap, converting every example to Python 3 while fixing critical bugs. It’s not just a mechanical 2to3 conversion—it’s a debugging exercise that exposes the fragility of offensive security code when dependencies shift.

Technical Insight

The most instructive fix in this repository addresses struct portability between 32-bit and 64-bit architectures in the packet sniffing examples. The original sniffer_ip_header_decode.py had issues in the definition of IP packet sizes and portability due to problems in the implementation of struct. The corrected approach appears to use explicit format characters that have defined sizes regardless of platform, preventing the sniffer from misinterpreting packet headers.

Another architectural decision involves replacing deprecated libraries while maintaining pedagogical clarity. The original code used scapy for packet manipulation. The repository switches to kamene, a Python 3-compatible fork, for examples like arper.py and mail_sniffer.py. This maintains the book’s learning trajectory—readers still learn packet manipulation techniques—but on a library that actually imports in Python 3.

The GitHub-based trojan implementation in chapter 7 required refactoring from the deprecated imp module to types. The original code dynamically imported modules from a GitHub repository to create a command-and-control channel. The updated version uses the types module and properly handles the GitHub API. The repository documentation notes that a call to the to_tree() method was added to avoid an AttributeError exception generated by the original code, and includes instructions on how to generate access tokens instead of using passwords for GitHub authentication.

Perhaps most valuable are the auxiliary files: the RSA key file (test_rsa.key) for SSH servers, wordlists (all.txt, cain.txt) for brute-force examples, and PyHook wheel files for Windows keyloggers. The original book appears to have referenced these without providing them, forcing readers to hunt for compatible versions. Including them transforms the repository from a code dump into a working learning environment.

Gotcha

The code deliberately remains ‘unoptimized’—the README explicitly states it lacks docstrings, type hints, exception handling, and context managers. This is intentional for pedagogical reasons (allowing readers to implement improvements themselves), but creates a trap: readers might internalize poor practices. The repository is educational, not a template for production tools.

Platform dependence exists for some examples. The keylogger requires PyHook, which the README indicates is Windows-specific. A wheel file (version 1.6.2) is included, though cross-platform learners will encounter limitations on certain examples. The repository mentions that ‘netaddr’ is no longer maintained and has been replaced with Python’s stdlib ipaddress module, and that ‘scapy’ has been replaced with ‘kamene’ for Python 3 compatibility.

Some examples may target specific software versions: the repository includes wordlists and configurations for tools like Joomla, though the README doesn’t specify how these examples perform against current software versions. The repository also includes Burp Suite extensions that have been reformatted for PEP8 compliance while maintaining necessary class naming conventions for that specific application.

Verdict

Use if you’re working through ‘Black Hat Python’ and need code that actually executes on Python 3, or if you’re debugging why the original No Starch Press code fails on your system—the detailed refactoring notes in the README document specific fixes for issues like struct implementation problems, missing RSA keys, and deprecated library replacements. The included auxiliary files (keys, wordlists, config templates) and fixed implementations save hours of environment setup. Also use if you’re teaching offensive security and need a reference implementation that runs without forcing students into dependency archaeology. Skip if you need production-grade penetration testing tools—the README explicitly notes the code could benefit from serious refactoring efforts and hasn’t been optimized. Skip if you require cross-platform compatibility for all examples—some tools like the PyHook-based keylogger are Windows-specific. Consider that this is a learning resource based on a 2014 book, so techniques and target software may not reflect current security landscapes.