firmwareninja module

Class

Description

binaryninja.firmwareninja.FirmwareNinja

class FirmwareNinja is a class that aids in analysis of firmware binaries. This class is…

binaryninja.firmwareninja.FirmwareNinjaDevice

class FirmwareNinjaDevice is a class that stores information about a hardware device,…

binaryninja.firmwareninja.FirmwareNinjaDeviceAccesses

class FirmwareNinjaDeviceAccesses is a class that stores information on the number of…

binaryninja.firmwareninja.FirmwareNinjaFunctionMemoryAccesses

class FirmwareNinjaFunctionMemoryAccesses is a class that stores information on accesses…

binaryninja.firmwareninja.FirmwareNinjaMemoryAccess

class FirmwareNinjaMemoryAccess is a class that stores information on instructions that…

binaryninja.firmwareninja.FirmwareNinjaReferenceNode

class FirmwareNinjaReferenceNode is a class for building reference trees for functions, data…

binaryninja.firmwareninja.FirmwareNinjaRelationship

class FirmwareNinjaRelationship is a class for representing inter-binary and cross-binary…

binaryninja.firmwareninja.FirmwareNinjaSection

class FirmwareNinjaSection is a class that stores information about a section identified…

class FirmwareNinja[source]

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>
__init__(view: BinaryView) None[source]
Parameters:

view (BinaryView) –

Return type:

None

add_relationship(relationship: FirmwareNinjaRelationship) None[source]

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][source]

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][source]

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][source]

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[source]

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

Parameters:
Returns:

Root reference node containing the reference tree

Return type:

FirmwareNinjaReferenceNode

get_relationship_by_guid(guid: str) FirmwareNinjaRelationship[source]

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][source]

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][source]

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[source]

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[source]

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[source]

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[source]

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[source]

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.

__init__(name: str, start: int, size: int, info: str) None
Parameters:
  • name (str) –

  • start (int) –

  • size (int) –

  • info (str) –

Return type:

None

info: str
name: str
size: int
start: int
class FirmwareNinjaDeviceAccesses[source]

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.

__init__(board_name: str, total: int, unique: int) None
Parameters:
  • board_name (str) –

  • total (int) –

  • unique (int) –

Return type:

None

board_name: str
total: int
unique: int
class FirmwareNinjaFunctionMemoryAccesses[source]

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.

__init__(function: Function, accesses: list[FirmwareNinjaMemoryAccess]) None
Parameters:
Return type:

None

classmethod from_BNFirmwareNinjaFunctionMemoryAccesses(info: BNFirmwareNinjaFunctionMemoryAccesses, view: BinaryView) FirmwareNinjaFunctionMemoryAccesses[source]
Parameters:
  • info (BNFirmwareNinjaFunctionMemoryAccesses) –

  • view (BinaryView) –

Return type:

FirmwareNinjaFunctionMemoryAccesses

accesses: list[FirmwareNinjaMemoryAccess]
function: Function
class FirmwareNinjaMemoryAccess[source]

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.

__init__(instr_address: int, mem_address: RegisterValue, heuristic: FirmwareNinjaMemoryHeuristic, type: FirmwareNinjaMemoryAccessType, value: RegisterValue) None
Parameters:
Return type:

None

classmethod from_BNFirmwareNinjaMemoryAccess(access: BNFirmwareNinjaMemoryAccess) FirmwareNinjaMemoryAccess[source]
Parameters:

access (BNFirmwareNinjaMemoryAccess) –

Return type:

FirmwareNinjaMemoryAccess

classmethod to_BNFirmwareNinjaMemoryAccess(access: FirmwareNinjaMemoryAccess) BNFirmwareNinjaMemoryAccess[source]
Parameters:

access (FirmwareNinjaMemoryAccess) –

Return type:

BNFirmwareNinjaMemoryAccess

heuristic: FirmwareNinjaMemoryHeuristic
instr_address: int
mem_address: RegisterValue
type: FirmwareNinjaMemoryAccessType
value: RegisterValue
class FirmwareNinjaReferenceNode[source]

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.

__init__(handle=None, view=None)[source]
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[source]

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.

__init__(view: BinaryView, handle=None) None[source]
Parameters:

view (BinaryView) –

Return type:

None

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[source]

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.

__init__(type: FirmwareNinjaSectionType, start: int, size: int, entropy: float) None
Parameters:
Return type:

None

entropy: float
size: int
start: int
type: FirmwareNinjaSectionType

FirmwareNinja

class FirmwareNinja[source]

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>
__init__(view: BinaryView) None[source]
Parameters:

view (BinaryView) –

Return type:

None

add_relationship(relationship: FirmwareNinjaRelationship) None[source]

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][source]

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][source]

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][source]

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[source]

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

Parameters:
Returns:

Root reference node containing the reference tree

Return type:

FirmwareNinjaReferenceNode

get_relationship_by_guid(guid: str) FirmwareNinjaRelationship[source]

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][source]

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][source]

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[source]

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[source]

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[source]

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[source]

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]

FirmwareNinjaDevice

class FirmwareNinjaDevice[source]

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.

__init__(name: str, start: int, size: int, info: str) None
Parameters:
  • name (str) –

  • start (int) –

  • size (int) –

  • info (str) –

Return type:

None

info: str
name: str
size: int
start: int

FirmwareNinjaDeviceAccesses

class FirmwareNinjaDeviceAccesses[source]

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.

__init__(board_name: str, total: int, unique: int) None
Parameters:
  • board_name (str) –

  • total (int) –

  • unique (int) –

Return type:

None

board_name: str
total: int
unique: int

FirmwareNinjaFunctionMemoryAccesses

class FirmwareNinjaFunctionMemoryAccesses[source]

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.

__init__(function: Function, accesses: list[FirmwareNinjaMemoryAccess]) None
Parameters:
Return type:

None

classmethod from_BNFirmwareNinjaFunctionMemoryAccesses(info: BNFirmwareNinjaFunctionMemoryAccesses, view: BinaryView) FirmwareNinjaFunctionMemoryAccesses[source]
Parameters:
  • info (BNFirmwareNinjaFunctionMemoryAccesses) –

  • view (BinaryView) –

Return type:

FirmwareNinjaFunctionMemoryAccesses

accesses: list[FirmwareNinjaMemoryAccess]
function: Function

FirmwareNinjaMemoryAccess

class FirmwareNinjaMemoryAccess[source]

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.

__init__(instr_address: int, mem_address: RegisterValue, heuristic: FirmwareNinjaMemoryHeuristic, type: FirmwareNinjaMemoryAccessType, value: RegisterValue) None
Parameters:
Return type:

None

classmethod from_BNFirmwareNinjaMemoryAccess(access: BNFirmwareNinjaMemoryAccess) FirmwareNinjaMemoryAccess[source]
Parameters:

access (BNFirmwareNinjaMemoryAccess) –

Return type:

FirmwareNinjaMemoryAccess

classmethod to_BNFirmwareNinjaMemoryAccess(access: FirmwareNinjaMemoryAccess) BNFirmwareNinjaMemoryAccess[source]
Parameters:

access (FirmwareNinjaMemoryAccess) –

Return type:

BNFirmwareNinjaMemoryAccess

heuristic: FirmwareNinjaMemoryHeuristic
instr_address: int
mem_address: RegisterValue
type: FirmwareNinjaMemoryAccessType
value: RegisterValue

FirmwareNinjaReferenceNode

class FirmwareNinjaReferenceNode[source]

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.

__init__(handle=None, view=None)[source]
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]

FirmwareNinjaRelationship

class FirmwareNinjaRelationship[source]

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.

__init__(view: BinaryView, handle=None) None[source]
Parameters:

view (BinaryView) –

Return type:

None

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]]

FirmwareNinjaSection

class FirmwareNinjaSection[source]

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.

__init__(type: FirmwareNinjaSectionType, start: int, size: int, entropy: float) None
Parameters:
Return type:

None

entropy: float
size: int
start: int
type: FirmwareNinjaSectionType