firmwareninja module

binaryninja.firmwareninja.FirmwareNinja(view)	class FirmwareNinja is a class that aids in analysis of firmware binaries.
binaryninja.firmwareninja.FirmwareNinjaDevice(...)	class FirmwareNinjaDevice is a class that stores information about a hardware device, including the device name, start address, size, and information about the device.
binaryninja.firmwareninja.FirmwareNinjaDeviceAccesses(...)	class FirmwareNinjaDeviceAccesses is a class that stores information on the number of accesses to hardware devices for each board that is compatible with the current architecture.
binaryninja.firmwareninja.FirmwareNinjaFunctionMemoryAccesses(...)	class FirmwareNinjaFunctionMemoryAccesses is a class that stores information on accesses made by a function to memory regions that are not file-backed, such as memory-mapped I/O and RAM.
binaryninja.firmwareninja.FirmwareNinjaMemoryAccess(...)	class FirmwareNinjaMemoryAccess is a class that stores information on instructions that access regions of memory that are not file-backed, such as memory-mapped I/O and RAM.
binaryninja.firmwareninja.FirmwareNinjaReferenceNode([...])	class FirmwareNinjaReferenceNode is a class for building reference trees for functions, data variables, and memory regions.
binaryninja.firmwareninja.FirmwareNinjaRelationship(view)	class FirmwareNinjaRelationship is a class for representing inter-binary and cross-binary relationships.
binaryninja.firmwareninja.FirmwareNinjaSection(...)	class FirmwareNinjaSection is a class that stores information about a section identified with Firmware Ninja analysis, including the section type, start address, size, and entropy.

class FirmwareNinja(view: BinaryView)

Bases: object

class FirmwareNinja is a class that aids in analysis of firmware binaries. This class is only available in the Ultimate Edition of Binary Ninja.

Example:

>>> from binaryninja import *
>>> view = load("path/to/firmware.bin", options={"loader.imageBase": 0x100000})
>>> fwn = FirmwareNinja(view)
>>> fwn.get_function_memory_accesses()[0].accesses[0].mem_address
<const ptr 0x40090028>

Parameters:

view (BinaryView) –

add_relationship(relationship: FirmwareNinjaRelationship) → None

add_relationship adds a relationship to the binary view metadata

Parameters:

relationship (FirmwareNinjaRelationship) – Relationship to add

Return type:

None

get_board_device_accesses(fma: list[FirmwareNinjaFunctionMemoryAccesses]) → list[FirmwareNinjaDeviceAccesses]

get_board_device_accesses counts accesses made to memory-mapped hardware devices for each board that is compatible with the current architecture. This function can be used to help identify a board.

Example:

>>> fwn = FirmwareNinja(bv)
>>> fma = fwn.get_function_memory_accesses()
>>> fwn.get_board_device_accesses(fma)[0]
FirmwareNinjaDeviceAccesses(board_name='stm32mp157c-dhcom-picoitx', total=414, unique=2)

Parameters:

fma (list[FirmwareNinjaFunctionMemoryAccesses]) – List of function memory accesses

Returns:

List of device accesses

Return type:

list[FirmwareNinjaDeviceAccesses]

get_devices_for_board(name: str) → list[FirmwareNinjaDevice]

get_devices_for_board queries the hardware device information for a specific board

Example:

>>> fwn = FirmwareNinja(bv)
>>> fwn.get_devices_for_board(fwn.boards[0])[0]
FirmwareNinjaDevice(name='nand@12f', start=303, size=1024, info='marvell,orion-nand')

Parameters:

name (str) – Name of the board

Returns:

List of Firmware Ninja devices

Return type:

list[FirmwareNinjaDevice]

get_function_memory_accesses(progress_func: Callable | None = None) → list[FirmwareNinjaFunctionMemoryAccesses]

get_function_memory_accesses runs analysis to find accesses to memory regions that are not file-backed, such as memory-mapped I/O and RAM

Parameters:

progress_func (callback) – optional function to be called with the current progress and total count.

Returns:

List of function memory accesses

Return type:

list[FirmwareNinjaFunctionMemoryAccesses]

get_reference_tree(location: Section | FirmwareNinjaDevice | Function | DataVariable | int, fma: list[FirmwareNinjaFunctionMemoryAccesses], value: int | None = None) → FirmwareNinjaReferenceNode

get_reference_tree returns a tree of reference nodes for a memory region, function, or address

Parameters:

• location (Section | FirmwareNinjaDevice | Function | DataVariable | int) – Memory location to build the

• location –

• fma (list[FirmwareNinjaFunctionMemoryAccesses]) –

• value (int | None) –

Return type:

FirmwareNinjaReferenceNode

reference tree for :param list[FirmwareNinjaFunctionMemoryAccesses] fma: List of function memory accesses or None to use cross references. None should only be supplied if location is a Function, DataVariable, or address. :param Optional[int] value: Only include the node in the tree if this value is written to the location :return: Root reference node containing the reference tree :rtype: FirmwareNinjaReferenceNode

get_relationship_by_guid(guid: str) → FirmwareNinjaRelationship

get_relationship_by_guid queries a relationship from the binary view metadata by GUID

Parameters:

guid (str) – GUID of the relationship

Returns:

Relationship

Return type:

FirmwareNinjaRelationship

get_sections_from_entropy(high_code_entropy_threshold: float = 0.91, low_code_entropy_threshold: float = 0.5, block_size: int = 4096, mode: FirmwareNinjaSectionAnalysisMode = FirmwareNinjaSectionAnalysisMode.DetectStringsSectionAnalysisMode) → list[FirmwareNinjaSection]

get_sections_from_entropy uses entropy analysis and heuristics to identify code, data, padding, and compressed sections in the file-backed regions of the binary view

Example:

>>> fwn = FirmwareNinja(bv)
>>> fwn.get_sections_from_entropy(block_size=2048)[0].entropy
0.48716872930526733
>>> fwn.get_sections_from_entropy(block_size=2048)[0].type
<FirmwareNinjaSectionType.DataSectionType: 1>

Parameters:

• high_code_entropy_threshold (float) – High code entropy threshold

• low_code_entropy_threshold (float) – Low code entropy threshold

• block_size (int) – Block size

• mode (FirmwareNinjaSectionAnalysisMode) – Analysis mode

Returns:

List of sections

Return type:

list[FirmwareNinjaSection]

query_function_memory_accesses() → list[FirmwareNinjaFunctionMemoryAccesses]

query_function_memory_accesses queries information on function memory accesses from binary view metadata

Returns:

List of function memory accesses

Return type:

list[FirmwareNinjaFunctionMemoryAccesses]

remove_custom_device(name: str) → bool

remove_custom_device removes a user-defined Firmware Ninja device from the binary view metadata by device name

Parameters:

name (str) – Name of the device

Returns:

True on success, False on failure

Return type:

bool

remove_relationship_by_guid(guid: str) → None

remove_relationship_by_guid removes a relationship from the binary view metadata by GUID

Parameters:

guid (str) – GUID of the relationship

Return type:

None

store_custom_device(name: str, start: int, size: int, info: str) → bool

store_custom_device stores a user-defined Firmware Ninja device in the binary view metadata

Parameters:

• name (str) – Name of the device

• start (int) – Start address of the device

• size (int) – Size of the device memory region

• info (str) – Information about the device

Returns:

True on success, False on failure

Return type:

bool

store_function_memory_accesses(fma: list[FirmwareNinjaFunctionMemoryAccesses]) → None

store_function_memory_accesses saves information on function memory accesses to binary view metadata

Example:

>>> fwn = FirmwareNinja(bv)
>>> fma = fwn.get_function_memory_accesses()
>>> fwn.store_function_memory_accesses(fma)

Parameters:

fma (list[FirmwareNinjaFunctionMemoryAccesses]) – List of function memory accesses

Return type:

None

property boards: list[str]

boards queries the name of all boards that are compatible with the current architecture

Returns:

List of board names

Return type:

list[str]

property relationships: list[FirmwareNinjaRelationship]

relationships queries all Firmware Ninja relationships from the binary view metadata

Returns:

List of relationships

Return type:

list[FirmwareNinjaRelationship]

property user_devices: list[FirmwareNinjaDevice]

user_devices queries user-defined Firmware Ninja devices from the binary view metadata

Returns:

List of Firmware Ninja devices

Return type:

list[FirmwareNinjaDevice]

class FirmwareNinjaDevice(name: str, start: int, size: int, info: str)

Bases: object

class FirmwareNinjaDevice is a class that stores information about a hardware device, including the device name, start address, size, and information about the device. This class is only available in the Ultimate Edition of Binary Ninja.

Parameters:

• name (str) –

• start (int) –

• size (int) –

• info (str) –

info: str

name: str

size: int

start: int

class FirmwareNinjaDeviceAccesses(board_name: str, total: int, unique: int)

Bases: object

class FirmwareNinjaDeviceAccesses is a class that stores information on the number of accesses to hardware devices for each board that is compatible with the current architecture. This information can be used to identify a board based on the number of accesses to hardware devices. This class is only available in the Ultimate Edition of Binary Ninja.

Parameters:

• board_name (str) –

• total (int) –

• unique (int) –

board_name: str

total: int

unique: int

class FirmwareNinjaFunctionMemoryAccesses(function: Function, accesses: list[FirmwareNinjaMemoryAccess])

Bases: object

class FirmwareNinjaFunctionMemoryAccesses is a class that stores information on accesses made by a function to memory regions that are not file-backed, such as memory-mapped I/O and RAM. This class is only available in the Ultimate Edition of Binary Ninja.

Parameters:

• function (Function) –

• accesses (list[FirmwareNinjaMemoryAccess]) –

classmethod from_BNFirmwareNinjaFunctionMemoryAccesses(info: BNFirmwareNinjaFunctionMemoryAccesses, view: BinaryView) → FirmwareNinjaFunctionMemoryAccesses

Parameters:

• info (BNFirmwareNinjaFunctionMemoryAccesses) –

• view (BinaryView) –

Return type:

FirmwareNinjaFunctionMemoryAccesses

accesses: list[FirmwareNinjaMemoryAccess]

function: Function

class FirmwareNinjaMemoryAccess(instr_address: int, mem_address: RegisterValue, heuristic: FirmwareNinjaMemoryHeuristic, type: FirmwareNinjaMemoryAccessType, value: RegisterValue)

Bases: object

class FirmwareNinjaMemoryAccess is a class that stores information on instructions that access regions of memory that are not file-backed, such as memory-mapped I/O and RAM. This class is only available in the Ultimate Edition of Binary Ninja.

Parameters:

• instr_address (int) –

• mem_address (RegisterValue) –

• heuristic (FirmwareNinjaMemoryHeuristic) –

• type (FirmwareNinjaMemoryAccessType) –

• value (RegisterValue) –

classmethod from_BNFirmwareNinjaMemoryAccess(access: BNFirmwareNinjaMemoryAccess) → FirmwareNinjaMemoryAccess

Parameters:

access (BNFirmwareNinjaMemoryAccess) –

Return type:

FirmwareNinjaMemoryAccess

classmethod to_BNFirmwareNinjaMemoryAccess(access: FirmwareNinjaMemoryAccess) → BNFirmwareNinjaMemoryAccess

Parameters:

access (FirmwareNinjaMemoryAccess) –

Return type:

BNFirmwareNinjaMemoryAccess

heuristic: FirmwareNinjaMemoryHeuristic

instr_address: int

mem_address: RegisterValue

type: FirmwareNinjaMemoryAccessType

value: RegisterValue

class FirmwareNinjaReferenceNode(handle=None, view=None)

Bases: object

class FirmwareNinjaReferenceNode is a class for building reference trees for functions, data variables, and memory regions. This class is only available in the Ultimate Edition of Binary Ninja.

property children: list[FirmwareNinjaReferenceNode]

children returns the child nodes contained in the reference tree node

Returns:

Child nodes contained in the reference tree node

Return type:

list[FirmwareNinjaReferenceNode]

property object: Function | DataVariable

object returns the function or data variable contained in the reference tree node, or None if the object is a root node and only contains children

Returns:

Object contained in the reference tree node

Return type:

Union[Function, DataVariable]

class FirmwareNinjaRelationship(view: BinaryView, handle=None)

Bases: object

class FirmwareNinjaRelationship is a class for representing inter-binary and cross-binary relationships. This class is only available in the Ultimate Edition of Binary Ninja.

Parameters:

view (BinaryView) –

property description: str

description returns the description of the relationship

Returns:

Description of the relationship

Return type:

str

property guid: str

guid returns the GUID of the relationship

Returns:

GUID of the relationship

Return type:

str

property primary: DataVariable | Function | int

primary returns the primary function, data variable, or address of the relationship

Returns:

Primary object of the relationship

Return type:

Union[DataVariable, Function, int]

property provenance: str

provenance returns the provenance of the relationship

Returns:

Provenance of the relationship

Return type:

str

property secondary: DataVariable | Function | int | tuple[int, ProjectFile] | tuple[str, ProjectFile]

secondary returns the secondary function, data variable, address, external address, or external symbol of the relationship

Returns:

Secondary object of the relationship

Return type:

Union[DataVariable, Function, int, tuple[int, ProjectFile], tuple[str, ProjectFile]]

class FirmwareNinjaSection(type: FirmwareNinjaSectionType, start: int, size: int, entropy: float)

Bases: object

class FirmwareNinjaSection is a class that stores information about a section identified with Firmware Ninja analysis, including the section type, start address, size, and entropy. This class is only available in the Ultimate Edition of Binary Ninja.

Parameters:

• type (FirmwareNinjaSectionType) –

• start (int) –

• size (int) –

• entropy (float) –

entropy: float

size: int

start: int

type: FirmwareNinjaSectionType