pybinwalk

Python bindings for Binwalk v3, built with PyO3 and maturin.

Provides direct access to binwalk's signature scanning and extraction from Python. Also exposes a C API for use from other languages.

Requirements

• Python >= 3.8
• Rust toolchain (for building from source)

Installation

pip install pybinwalk

To build from source:

pip install maturin
maturin build --release
pip install target/wheels/pybinwalk-*.whl

Wheels

Prebuilt wheels are published via GitHub Actions for:

• macOS: universal2 (arm64 + x86_64)
• Windows: x86_64
• Linux: manylinux (x86_64)

If a wheel isn’t available for your Python/platform, pip will build from source (requires Rust).

Usage

Scan bytes in memory

import pybinwalk

bw = pybinwalk.Binwalk()
data = open("firmware.bin", "rb").read()

for result in bw.scan_bytes(data):
    print(f"0x{result.offset:08X}  {result.name}  {result.description}")

Scan a file from disk

bw = pybinwalk.Binwalk()

for result in bw.scan_path("/path/to/firmware.bin"):
    print(f"0x{result.offset:08X}  {result.name}  {result.description}")

Configure with filters

bw = pybinwalk.Binwalk.configure(
    include=["gzip", "squashfs"],
    exclude=["jpeg"],
    full_search=False,
)

results = bw.scan_path("firmware.bin")

Extract

bw = pybinwalk.Binwalk.configure(
    target_file_name="firmware.bin",
    output_directory="./extracted",
)

analysis = bw.analyze_path(bw.base_target_file, do_extraction=True)

for sig in analysis.file_map:
    print(f"0x{sig.offset:08X}  {sig.name}")

for sig_id, extraction in analysis.extractions.items():
    print(f"{sig_id}: success={extraction.success}, dir={extraction.output_directory}")

Version

print(pybinwalk.version())

API reference

Binwalk

Properties: signature_count, base_target_file, base_output_directory.

Binwalk.configure() parameters

SignatureResult

Properties: offset, id, size, name, confidence, description, always_display, extraction_declined, preferred_extractor.

ExtractionResult

Properties: size, success, extractor, do_not_recurse, output_directory.

AnalysisResults

Properties: file_path, file_map (list of SignatureResult), extractions (dict mapping signature id to ExtractionResult).

C API

When built without the python feature (cargo build --release --no-default-features), the library exposes a C-compatible API:

All C API functions return a *mut c_char pointer to a JSON string. The caller must free it with bw_free().

License

MIT