pybinwalk 0.0.3

Python bindings for Binwalk v3

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

Method	Description
Binwalk()	Create an instance with default settings.
Binwalk.configure(...)	Create an instance with custom options.
scan_bytes(data: bytes)	Scan in-memory data. Returns list[SignatureResult].
scan_path(file_path: str)	Scan a file on disk. Returns list[SignatureResult].
extract_bytes(data, file_path, file_map)	Extract from in-memory data using a prior scan result. Returns dict[str, ExtractionResult].
analyze_path(target_file, do_extraction)	Scan and optionally extract a file. Returns AnalysisResults.

Properties: signature_count, base_target_file, base_output_directory.

Binwalk.configure() parameters

Parameter	Type	Default	Description
target_file_name	str or None	None	Path to target file (required for extraction).
output_directory	str or None	None	Directory for extracted files.
include	list[str] or None	None	Only scan for these signature types.
exclude	list[str] or None	None	Skip these signature types.
full_search	bool	False	Search all offsets instead of optimized locations.

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:

Function	Description
bw_scan(data, len)	Scan a buffer. Returns JSON string.
bw_scan_with_options(data, len, options_json)	Scan with filter options. Returns JSON string.
bw_version()	Get version info. Returns JSON string.
bw_list_signatures()	List available signatures. Returns JSON string.
bw_free(ptr)	Free a string returned by any of the above.

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

License

MIT