BYOB: A Python Post-Exploitation Framework for Security Education and Research

What BYOB Is and Who It Is For

Post-exploitation frameworks exist on a spectrum from production-hardened commercial tools to open educational projects. BYOB sits firmly in the educational category. The README describes it as 'an open-source post-exploitation framework for students, researchers and developers' and leads with a disclaimer that the project should be used for authorized testing or educational purposes only.

The design rationale is explicitly stated: the framework lets students and developers implement their own code and add features without having to write a command-and-control server or remote administration tool from scratch. It is a teaching scaffold for understanding how C2 infrastructure works at the implementation level.

The two main parts are a console-based application under the `byob/` directory and a web GUI under `web-gui/`. Both connect to the same underlying agent and module system, but the web GUI adds a point-and-click dashboard and a Docker-based payload generator. For questions or help, the README directs users to the wiki at github.com/malwaredllc/byob/wiki and to the project's Discord server. The GPL-3.0 license means the source code must remain open if distributed, and modifications must carry the same license terms.

Agent Architecture: Disk-Free Operation and Remote Imports

The BYOB client is built around a set of design principles documented in the README. The first and most unusual is that the client never writes anything to disk. The README states that 'not even temporary files' are created because remote imports allow arbitrary code to be dynamically loaded into memory from the server. Zero IO system calls are made during module execution.

The remote import mechanism works by serving Python packages from the C2 server over the network. The client uses only the Python standard library directly; all third-party packages are imported remotely at runtime. This means the agent can use libraries not installed on the target machine, and the payload size stays small regardless of how many modules are loaded.

The client can be compiled with a standalone Python interpreter into a portable binary executable. On Windows, this produces a binary that runs without Python installed on the target. On macOS, the README documents bundling into a standalone application. The payload is encrypted with a random 256-bit key that exists only in a separately generated stager.

The Web GUI: Dashboard, Payload Generator, and Terminal Emulator

The web GUI provides three main components. The dashboard displays a control panel with an interactive map showing connected client machines and provides point-and-click execution of post-exploitation modules.

The payload generator uses Docker containers and Wine servers to compile executable payloads for any selected platform and architecture. The README describes this as 'black magic involving Docker containers and Wine servers.' Communication between the generated payload and the C2 server is encrypted with AES-256 after a session key is established via Diffie-Hellman IKE, following the RFC 2409 Internet Key Exchange specification.

The terminal emulator in the web interface provides direct shell access to connected clients from the browser, maintaining the ability to run arbitrary commands even when using the graphical interface.

The Twelve Post-Exploitation Modules

BYOB ships 12 modules that are remotely importable by connected clients. The README lists them with their Python module paths:

Persistence (`byob.modules.persistence`) establishes persistence using five different methods. Packet Sniffer (`byob.modules.packetsniffer`) captures network traffic and uploads a .pcap file. Escalate Privileges (`byob.modules.escalate`) attempts UAC bypass to gain unauthorized administrator access. Port Scanner (`byob.modules.portscanner`) scans the local network for online devices and open ports. Keylogger (`byob.modules.keylogger`) records keystrokes and window titles. Screenshot (`byob.modules.screenshot`) captures the current desktop. Outlook (`byob.modules.outlook`) reads, searches, and uploads emails from a local Outlook installation. Process Control (`byob.modules.process`) lists, searches, kills, and monitors running processes. iCloud (`byob.modules.icloud`) checks for a logged-in iCloud account on macOS.

The README also documents that any Python script, module, or package copied to `./byob/modules/` on the server automatically becomes remotely importable by all connected clients. The README provides a module template in that directory to guide custom module development.

Encryption and Server Architecture

The core security module (`byob.core.security`) implements Diffie-Hellman IKE and three encryption modes: AES-256-OCB, AES-256-CBC, and XOR-128. The key exchange uses Diffie-Hellman IKE (RFC 2409) to establish a symmetric key over an untrusted network without transmitting the key in cleartext.

The server component maintains a persistent SQLite database that stores identifying information about connected client machines. This allows sessions to persist through disconnections of arbitrary duration, enabling long-term access without requiring a client to re-execute the payload. The README calls this out as enabling 'long-term reconnaissance.'

All Python packages installed locally on the C2 server are automatically available for clients to import remotely. This means the server operator controls which capabilities are accessible to any connected client through what they install on the server.

Anti-Analysis and Evasion Features

BYOB documents several techniques for evading analysis, which are described in the README as features of the client:

The client blocks processes with names of known antivirus products from spawning. The README describes this as a counter-measure against antivirus analysis. The client also detects virtual machines and sandboxes and aborts execution if one is detected, preventing automated analysis environments from running the payload.

Reverse TCP connections are used to bypass firewalls. The README notes that 'the default filter configurations primarily block incoming connections,' and outbound reverse connections from the client to the C2 server bypass those filters.

These features are documented as educational examples of how evasion techniques work rather than production-ready capabilities. The README frames the framework explicitly as for students and researchers studying these mechanisms.

BYOB vs Metasploit

Metasploit is the most widely used penetration testing framework and covers both initial exploitation and post-exploitation through a large library of pre-built modules. The difference is purpose and depth. Metasploit is a production tool with a stable release cycle, professional support, and thousands of modules built by contributors over many years. BYOB is an educational scaffold designed to show how C2 infrastructure is built from the ground up.

BYOB has no initial exploitation modules; it assumes the operator already has a foothold and covers post-exploitation from that point. Metasploit's Meterpreter covers comparable post-exploitation territory with more capabilities and more mature evasion techniques.

For students who want to understand how an agent communicates with a C2, how remote imports work, or how to write a module that captures keystrokes, BYOB provides readable Python source code organized to make those mechanisms inspectable.

The project structure separates concerns cleanly. The `byob/` directory holds the console application and all module code. The `web-gui/` directory holds the web interface separately. The `byob/core/` subdirectory contains the shared utilities, security primitives, and server logic. This separation means a student can study just the encryption module (`byob.core.security`) or just the persistence module (`byob.modules.persistence`) without needing to understand the full system. The module template in `byob/modules/` provides the interface contract that a new module must satisfy to integrate with the remote import mechanism.

The README states the project has coverage tracking set up via Coveralls, and the repository includes a `.coveragerc` configuration file. The `.travis.yml` file shows the project's historical CI configuration, though current CI integration is tracked in the `.github/` workflows directory.

Editorial conclusion

BYOB suits security students and researchers who want to understand post-exploitation mechanics from the implementation side, not just from a user interface. Using it against systems you do not own or lack written authorization to test is illegal; the README's disclaimer is explicit on this point. Before running the web GUI, confirm you have Docker and Wine available on the host. The framework does not provide initial access exploits; BYOB assumes a foothold already exists and covers what happens afterward.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. malwaredllc/byob on GitHub
4. README