Bases: object

class FileMetadata represents the file being analyzed by Binary Ninja. It is responsible for opening, closing, creating the database (.bndb) files, and is used to keep track of undoable actions.

Parameters:

• filename (str) – The string path to the file to be opened. Defaults to None.

• handle – A handle to the underlying C FileMetadata object. Defaults to None. (Internal use only.)

__init__(filename: str | None = None, handle: LP_BNFileMetadata | None = None)[source]¶

Parameters:

• filename (str | None)

• handle (LP_BNFileMetadata | None)

begin_undo_actions(anonymous_allowed: bool = True) → str[source]¶

begin_undo_actions starts recording actions taken so they can be undone at some point.

Parameters:

anonymous_allowed (bool) – Legacy interop: prevent empty calls to commit_undo_actions from affecting this undo state. Specifically for undoable_transaction

Returns:

Id of undo state, for passing to commit_undo_actions or revert_undo_actions.

Return type:

str

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions(state)
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>>

close() → None[source]¶

Closes the underlying file handle. It is recommended that this is done in a finally clause to avoid handle leaks.

Return type:

None

commit_undo_actions(id: str | None = None) → None[source]¶

commit_undo_actions commits the actions taken since a call to begin_undo_actions Pass as id the value returned by begin_undo_actions. Empty values of id will commit all changes since the last call to begin_undo_actions.

Parameters:

id (Optional[str]) – id of undo state, from begin_undo_actions

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.commit_undo_actions(state)
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>>

create_database(filename: str, progress_func: Callable[[int, int], bool] | None = None, settings: SaveSettings | None = None) → bool[source]¶

create_database writes the current database (.bndb) out to the specified file.

Parameters:

• filename (str) – path and filename to write the bndb to, this string should have “.bndb” appended to it.

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

• settings (SaveSettings) – optional argument for special save options.

Returns:

true on success, false on failure

Return type:

bool

Note

The progress_func callback must return True to continue the save operation, False will abort the save operation.

Warning

The calling thread must not hold a lock on the BinaryView instance as this action is run on the main thread which requires the lock.

Example:

>>> settings = SaveSettings()
>>> bv.file.create_database(f"{bv.file.filename}.bndb", None, settings)
True

Parameters:

• filename (str)

• progress_func (Callable[[int, int], bool] | None)

• settings (SaveSettings | None)

Return type:

bool

forget_undo_actions(id: str | None = None) → None[source]¶

forget_undo_actions removes the actions taken since a call to begin_undo_actions Pass as id the value returned by begin_undo_actions. Empty values of id will remove all changes since the last call to begin_undo_actions.

Parameters:

id (Optional[str]) – id of undo state, from begin_undo_actions

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.forget_undo_actions(state)
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>>

get_view_of_type(name: str) → BinaryView | None[source]¶

Parameters:

name (str)

Return type:

BinaryView | None

navigate(view: str, offset: int) → bool[source]¶

navigate navigates the UI to the specified virtual address

Note

Despite the confusing name, view in this context is not a BinaryView but rather a string describing the different UI Views. Check view while in different views to see examples such as Linear:ELF, Graph:PE.

Parameters:

• view (str) – view name

• offset (int) – address to navigate to

Returns:

whether or not navigation succeeded

Return type:

bool

Example:

>>> import random
>>> bv.navigate(bv.view, random.choice(list(bv.functions)).start)
True

redo() → None[source]¶

redo redo the last committed transaction in the undo database.

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> with bv.undoable_transaction():
>>>     bv.convert_to_nop(0x100012f1)
True
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.redo()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>>

reopen_moved_database(filename: str) → bool[source]¶

reopen_moved_database reopens the database backing this file metadata from a new path.

Parameters:

filename (str) – path and filename to the moved bndb.

Returns:

true on success, false on failure

Return type:

bool

revert_undo_actions(id: str | None = None) → None[source]¶

revert_undo_actions reverts the actions taken since a call to begin_undo_actions Pass as id the value returned by begin_undo_actions. Empty values of id will revert all changes since the last call to begin_undo_actions.

Parameters:

id (Optional[str]) – id of undo state, from begin_undo_actions

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> state = bv.begin_undo_actions()
>>> bv.convert_to_nop(0x100012f1)
True
>>> bv.revert_undo_actions(state)
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>>

save_auto_snapshot(progress_func: Callable[[int, int], bool] | None = None, settings: SaveSettings | None = None) → bool[source]¶

Parameters:

• progress_func (Callable[[int, int], bool] | None)

• settings (SaveSettings | None)

Return type:

bool

static set_default_session_data(name: str, value: Any) → None[source]¶

Parameters:

• name (str)

• value (Any)

Return type:

None

undo() → None[source]¶

undo undo the last committed transaction in the undo database.

Return type:

None

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> with bv.undoable_transaction():
>>>     bv.convert_to_nop(0x100012f1)
True
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> bv.redo()
>>> bv.get_disassembly(0x100012f1)
'nop'
>>>

undoable_transaction() → Generator[source]¶

undoable_transaction gives you a context in which you can make changes to analysis, and creates an Undo state containing those actions. If an exception is thrown, any changes made to the analysis inside the transaction are reverted.

Returns:

Transaction context manager, which will commit/revert actions depending on if an exception is thrown when it goes out of scope.

Return type:

Generator

Example:

>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> # Actions inside the transaction will be committed to the undo state upon exit
>>> with bv.undoable_transaction():
>>>     bv.convert_to_nop(0x100012f1)
True
>>> bv.get_disassembly(0x100012f1)
'nop'
>>> bv.undo()
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'
>>> # A thrown exception inside the transaction will undo all changes made inside it
>>> with bv.undoable_transaction():
>>>     bv.convert_to_nop(0x100012f1)  # Reverted on thrown exception
>>>     raise RuntimeError("oh no")
RuntimeError: oh no
>>> bv.get_disassembly(0x100012f1)
'xor     eax, eax'

property analysis_changed: bool¶

Boolean result of whether the auto-analysis results have changed (read-only)

property database: Database | None¶

Gets the backing Database of the file

property display_name: str¶

display_name is a leaf-shaped human-readable name for UI presentation. It never contains a directory path. Resolution order:

• An explicitly set display name (project-assigned, transform-synthesized for container entries, or set by a plugin or user).

• Otherwise the leaf of filename.

Use this for tab titles, save-dialog default leaf names, logs, and any UI surface where you’d refer to the file by name. Use filename for the physical path that can be reopened.

property existing_views: List[str]¶

property filename: str¶

The name of the open bndb or binary filename (read/write)

property has_database: bool¶

Whether the FileMetadata is backed by a database, or if specified, a specific BinaryViewType (read-only)

property is_container_entry: bool¶

True if this file was produced by the container transform system (e.g. an entry extracted from a Zip archive). False for plain files, databases, and FileMetadata that has not yet been processed by the transform system.

property modified: bool¶

Boolean result of whether the file is modified (Inverse of ‘saved’ property) (read/write)

property nav: NavigationHandler | None¶

Navigation handler for this FileMetadata (read/write)

property navigation: NavigationHandler | None¶

Alias for nav

property offset: int¶

The current offset into the file (read/write)

property original_filename: str¶

The original name of the binary opened if a bndb, otherwise reads or sets the current filename (read/write)

Note

With projects, bv.file.original_filename queries the path of the binary as staged in the project directory. Use bv.project_file.name to query the original name of the opened binary.

property project: Project | None¶

property project_file: ProjectFile | None¶

property raw: BinaryView | None¶

Gets the “Raw” BinaryView of the file

property redo_entries: List[UndoEntry]¶

property saved: bool¶

Boolean result of whether the file has been saved (Inverse of ‘modified’ property) (read/write)

property session_data: Any¶

Dictionary object where plugins can store arbitrary data associated with the file

property session_id: int¶

property snapshot_data_applied_without_error: bool¶

property undo_entries: List[UndoEntry]¶

property view: str¶

property virtual_path: str¶

virtual_path is a logical (non-filesystem) path describing how this file was derived from the container transform system in the current session. There are three meaningful states:

• Empty - not yet processed by the transform system.

• Equal to filename - processed, no transform chain applied (plain file, database, or container system disabled via files.container.mode).

• Non-empty and different from filename - derived container entry.

Session-scoped: save-as does not persist the chain. Reopening the saved artifact yields whatever chain that session’s access path produces.

Use this for cache keys or identity-sensitive operations. Use filename for the physical path and display_name for UI display.

Bases: object

get_current_offset() → int[source]¶

Return type:

int

get_current_view() → str[source]¶

Return type:

str

navigate(view: str, offset: int) → bool[source]¶

Parameters:

• view (str)

• offset (int)

Return type:

bool

Bases: object

class SaveSettings is used to specify actions and options that apply to saving a database (.bndb).

__init__(handle=None)[source]¶

is_option_set(option: SaveOption) → bool[source]¶

Parameters:

option (SaveOption)

Return type:

bool

set_option(option: SaveOption, state: bool = True)[source]¶

Set a SaveOption in this instance.

Parameters:

• option (SaveOption) – Option to set.

• state (bool) – State to assign. Defaults to True.

Example:

>>> settings = SaveSettings()
>>> settings.set_option(SaveOption.TrimSnapshots)