transform module

Class	Description
binaryninja.transform.Transform	class Transform allows users to implement custom transformations. New transformations may be…
binaryninja.transform.TransformContext	TransformContext represents a node in the container extraction tree, containing the input…
binaryninja.transform.TransformParameter
binaryninja.transform.TransformSession	TransformSession manages the extraction workflow for container files (ZIP, 7z, IMG4, etc.),…
binaryninja.transform.ZipPython	ZipPython is a transform that handles ZIP archive decoding using Python’s built-in zipfile…

Transform

class Transform

Bases: object

class Transform allows users to implement custom transformations. New transformations may be added at runtime, so an instance of a transform is created like:

>>> list(Transform)
[<transform: Zlib>, <transform: StringEscape>, <transform: RawHex>, <transform: HexDump>, <transform: Base64>, <transform: Reverse>, <transform: CArray08>, <transform: CArrayA16>, <transform: CArrayA32>, <transform: CArrayA64>, <transform: CArrayB16>, <transform: CArrayB32>, <transform: CArrayB64>, <transform: IntList08>, <transform: IntListA16>, <transform: IntListA32>, <transform: IntListA64>, <transform: IntListB16>, <transform: IntListB32>, <transform: IntListB64>, <transform: MD4>, <transform: MD5>, <transform: SHA1>, <transform: SHA224>, <transform: SHA256>, <transform: SHA384>, <transform: SHA512>, <transform: AES-128 ECB>, <transform: AES-128 CBC>, <transform: AES-256 ECB>, <transform: AES-256 CBC>, <transform: DES ECB>, <transform: DES CBC>, <transform: Triple DES ECB>, <transform: Triple DES CBC>, <transform: RC2 ECB>, <transform: RC2 CBC>, <transform: Blowfish ECB>, <transform: Blowfish CBC>, <transform: CAST ECB>, <transform: CAST CBC>, <transform: RC4>, <transform: XOR>]
>>> sha512=Transform['SHA512']
>>> rawhex=Transform['RawHex']
>>> rawhex.encode(sha512.encode("test string"))
'10e6d647af44624442f388c2c14a787ff8b17e6165b83d767ec047768d8cbcb71a1a3226e7cc7816bc79c0427d94a9da688c41a3992c7bf5e4d7cc3e0be5dbac'

Note that some transformations take additional parameters (most notably encryption ones that require a ‘key’ parameter passed via a dict):

>>> xor=Transform['XOR']
>>> rawhex=Transform['RawHex']
>>> xor.encode("Original Data", {'key':'XORKEY'})
>>> rawhex.encode(xor.encode("Original Data", {'key':'XORKEY'}))
b'173d3b2c2c373923720f242d39'

__init__(handle)

can_decode(input)

can_decode checks if this transform can decode the given input.

Parameters:

input – can be a bytes, bytearray, DataBuffer, or BinaryView

Returns:

bool indicating whether the transform can decode the input

Return type:

bool

decode(input_buf, params={})

decode_with_context(context, params={})

decode_with_context performs context-aware transformation for container formats, enabling multi-file extraction

Processing Protocol:

Container transforms typically operate in two phases:

1. Discovery Phase: Transform enumerates available files and populates context.available_files. Returns False to indicate user file selection is required.

2. Extraction Phase: Transform processes context.requested_files and creates child contexts for each file with extraction results. Returns True when extraction is complete.

Return Value Semantics:

• True: Processing complete, no more user interaction needed

• False: Processing incomplete, requires user input or session management (e.g., file selection after discovery)

Error Reporting:

Extraction results and messages are accessible via context properties:

• Context-level (transformation/extraction status): - context.extraction_result: Result of parent producing input - context.extraction_message: Human-readable extraction message - context.transform_result: Result of applying transform to input

Common error scenarios:

• Archive encrypted, password required

• Corrupt archive structure

• Unsupported archive format

• Individual file extraction failures

Usage Examples:

from binaryninja import TransformSession

# Full mode - automatically extracts all files
session = TransformSession("archive.zip")
if session.process(): # All extraction complete, no interaction needed
        # Select the intended context(s) for loading
        session.set_selected_contexts(session.current_context)
        # Load the resulting BinaryView(s)
        loaded_view = load(session.current_view)
else:
        # Extraction incomplete - user input required
        print("Extraction requires user input")

# Interactive mode - requires manual processing for each step
session = TransformSession("nested.zip")
while not session.process():
        # Process returned False - user input needed
        ctx = session.current_context

        # Check if parent has available files for selection
        if ctx.parent and ctx.parent.has_available_files:
                # Show files to user and let them select
                available = ctx.parent.available_files
                print(f"Available files: {available}")

                # Select files to extract (or all)
                ctx.parent.set_requested_files(available)

                # Continue processing from parent
                session.process_from(ctx.parent)

# Extraction complete - select and load the final context
session.set_selected_contexts(session.current_context)
final_view = session.current_view

Parameters:

• context (TransformContext) – Transform context containing input data and state

• params (dict) – Optional transform parameters (e.g., passwords, settings)

Returns:

True if processing complete, False if user input required

Return type:

bool

encode(input_buf, params={})

abstract perform_decode(data, params)

perform_decode_with_context(context, params)

abstract perform_encode(data, params)

classmethod register()

capabilities = 0

group = None

long_name = None

name = None

parameters = []

supports_detection = False

transform_type = None

TransformContext

class TransformContext

Bases: object

TransformContext represents a node in the container extraction tree, containing the input data, transformation state, and relationships to parent/child contexts.

Each context can have: - Input data (BinaryView) - Transform information (name, parameters, results) - File selection state (available_files, requested_files) - Parent/child relationships for nested containers - Extraction status and error messages

Contexts are typically accessed through a TransformSession rather than created directly.

Example:

session = TransformSession("archive.zip")
session.process()

# Access context properties
ctx = session.current_context
print(f"Filename: {ctx.filename}")
print(f"Transform: {ctx.transform_name}")
print(f"Size: {ctx.input.length}")

# Navigate the tree
if ctx.parent:
        print(f"Parent files: {ctx.parent.available_files}")

# Check extraction status
if ctx.extraction_result != 0:
        print(f"Error: {ctx.extraction_message}")

__init__(handle)

clear_transform_parameter(name: str)

Clear a transform parameter

Parameters:

name (str) –

create_child(data: DataBuffer, filename: str = '', result: TransformResult = TransformResult.TransformSuccess, message: str = '') → TransformContext

Create a new child context with the given data, filename, result status, and message

Parameters:

• data (DataBuffer) – The data for the child context

• filename (str) – The filename for the child context (default: “”)

• result (TransformResult) – Transform result for the child (default: TransformResult.TransformSuccess)

• message (str) – Extraction message for the child (default: “”)

Return type:

TransformContext

get_child(filename: str) → TransformContext | None

Get a child context by filename

Parameters:

filename (str) –

Return type:

TransformContext | None

has_transform_parameter(name: str) → bool

Check if a transform parameter exists

Parameters:

name (str) –

Return type:

bool

set_available_files(files: List[str])

Set the list of available files for selection

Parameters:

files (List[str]) –

set_requested_files(files: List[str])

Set the list of requested files

Parameters:

files (List[str]) –

set_transform_name(transform_name: str)

Set the transform name for this context

Parameters:

transform_name (str) –

set_transform_parameter(name: str, data: DataBuffer)

Set a transform parameter

Parameters:

• name (str) –

• data (DataBuffer) –

property available_files: List[str]

Get the list of available files for selection

property available_transforms: List[str]

Get the list of transforms that can decode this context’s input

property child_count: int

Get the number of child contexts

property children: List[TransformContext]

Get all child contexts

property extraction_message: str

Get the extraction message

property extraction_result: TransformResult

Get the extraction result

property filename: str

Get the filename for this context

property has_available_files: bool

Check if this context has available files for selection

property has_requested_files: bool

Check if this context has requested files

property input: BinaryView | None

Get the input BinaryView for this context

property is_database: bool

Check if this context represents a database file

property is_leaf: bool

Check if this context is a leaf (has no children)

property is_root: bool

Check if this context is the root (has no parent)

property metadata_obj: Metadata | None

Get the metadata for this context

property parent: TransformContext | None

Get the parent context

property requested_files: List[str]

Get the list of requested files

property transform_name: str

Get the name of the transform that created this context

property transform_result: TransformResult

Get the transform result

TransformParameter

class TransformParameter

Bases: object

__init__(name, long_name=None, fixed_length=0)

property fixed_length

(read-only)

property long_name

(read-only)

property name

(read-only)

TransformSession

class TransformSession

Bases: object

TransformSession manages the extraction workflow for container files (ZIP, 7z, IMG4, etc.), handling multi-stage extraction, file selection, and transform application.

Sessions automatically detect and apply appropriate transforms to navigate through nested containers, maintaining a tree of TransformContext objects representing each extraction stage.

Modes:

• Full Mode (default): Automatically extracts all files through nested containers

• Interactive Mode: Requires user file selection at each stage

Basic Usage:

from binaryninja import TransformSession

# Full automatic extraction
session = TransformSession("archive.zip")
if session.process():
        final_data = session.current_view
        load(final_data)

Interactive Extraction:

session = TransformSession("nested_archive.zip")
while not session.process():
        # User input needed
        ctx = session.current_context
        if ctx.parent and ctx.parent.has_available_files:
                # Show file choices to user
                print(f"Available: {ctx.parent.available_files}")

                # User selects files
                ctx.parent.set_requested_files(["important_file.bin"])

                # Continue extraction
                session.process_from(ctx.parent)

# Access final extracted data
session.set_selected_contexts(session.current_context)
final_view = session.current_view

Key Methods:

• process(): Process the next extraction stage

• process_from(context): Resume processing from a specific context

• set_selected_contexts(contexts): Mark contexts for final access

Key Properties:

• current_context: The current point in the extraction tree

• current_view: The current BinaryView (after processing)

• root_context: The root of the extraction tree

__init__(filename_or_view: str | BinaryView, mode=None, handle=None)

Parameters:

filename_or_view (str | BinaryView) –

process() → bool

Process the transform session

Return type:

bool

process_from(context: TransformContext) → bool

Process the transform session starting from a specific context

Parameters:

context (TransformContext) –

Return type:

bool

set_selected_contexts(contexts: List[TransformContext] | TransformContext)

Set the selected contexts

Parameters:

contexts (List[TransformContext] | TransformContext) –

property current_context: TransformContext | None

Get the current transform context

property current_view: BinaryView | None

Get the current BinaryView for this session

property has_any_stages: bool

Check if this session has any processing stages

property has_single_path: bool

Check if this session has a single processing path

property root_context: TransformContext | None

Get the root transform context

property selected_contexts: List[TransformContext]

Get the currently selected contexts

ZipPython

class ZipPython

Bases: Transform

ZipPython is a transform that handles ZIP archive decoding using Python’s built-in zipfile module. It supports password-protected archives and context-aware extraction of multiple files. It is provided as a reference implementation and may not be as performant as native implementations. By default, this Transform is not registered; to use it, call ZipPython.register().

can_decode(input) → bool

can_decode checks if this transform can decode the given input.

Parameters:

input – can be a bytes, bytearray, DataBuffer, or BinaryView

Returns:

bool indicating whether the transform can decode the input

Return type:

bool

perform_decode(data: bytes, params: dict) → bytes | None

Parameters:

• data (bytes) –

• params (dict) –

Return type:

bytes | None

perform_decode_with_context(context, params) → bool

Return type:

bool

perform_encode(data, params)

capabilities = 3

group = 'Container'

long_name = 'Zip (Python)'

name = 'ZipPython'

transform_type = 3