bochscpu-python

Python bindings for @yrp's BochsCPU using FFI to easily and accurately emulate x86 code.

Install

bochscpu-python requires a Python environment of 3.8 or more recent only.

Via PyPI (preferred)

By far the simplest way to get things up and running is using the stable packaged version on PyPI

python -m pip install bochscpu-python

Via the generated builds

Download the latest working artifact from the repository Github Actions tab. Extract the ZIP file, install the .whl file you'll find inside the wheel folder.

python -m pip install wheel/bochscpu-$version-$os-$arch.whl

From the source repository

Fairly straight forward:

python -m pip install .

Or without cloning

python -m pip install git+https://github.com/hugsy/bochscpu-python.git#egg=bochscpu-python

Note that this approach will require you to have all the building tools necessary installed (as described below)

Build

Requirements

• Python 3.8+ (with development kit)
• cmake
• pip
• a C++20 compatible compiler (tested cl for Windows, clang++ for MacOS and g++ Linux)

Steps

• Build BochsCPU, BochsCPU-FFI, and BochsCPU-Build following the instructions on their respective pages
• ... Alternatively BochsCPU-FFI for Windows & Linux libraries object files can be downloaded from the build Github Actions
• Move the *.lib in bochscpu/lib/<BuildType> (where BuildType can be Debug, Release, RelWithDebInfo, etc.)
• Install the requirements: python -m pip install -r requirements.txt
• Build with cmake This will generate the bochscpu pyd file (and its PDB) which you can import from a Python session with import bochscpu.
• ... Alternatively you can also generate a .whl from the root of the project:

python -m pip wheel .

Usage

Just import the bochscpu module and let the fun begin! Installing the package will also install interface files, allowing modern IDEs (VSCode, PyCharm, etc.) to offer useful completion.

A very crude template can be made as such:

import bochscpu, bochscpu.utils, bochscpu.cpu

sess = bochscpu.Session()
sess.missing_page_handler = bochscpu.utils.callbacks.missing_page_cb
state = bochscpu.State()
bochscpu.cpu.set_real_mode(state)
hook = bochscpu.Hook()
bochscpu.utils.callbacks.install_default_callbacks(hook)
sess.run([hook,])

This will create a bochscpu session, set the CPU state for real mode, and pre-populate hooks with basic callbacks (that only perform a print upon execution). Note that this sample will actually do nothing as we haven't allocated code pages nor correctly set registers to point to it.

A more complete template can be found in the examples/ folder

Some Examples

Emulate a Fibonascii sequence in x64 long mode

long-mode-fibonacci.mp4

Code

Emulate code from a Windows 11 x64 memory dump

Code

Emulate a print("hello world")-like assembly code in 16 bit real mode

real-mode-print-hello.mp4

Code

Emulate Linux Glibc's rand() function on x64

linux-x64-rand-emulation.mp4

Code

Enjoy 🍻