interaction module

Class	Description
binaryninja.interaction.AddressField	AddressField prompts the user for an address. By passing the optional view and…
binaryninja.interaction.CheckboxField	CheckboxField prompts the user to choose a yes/no option in a checkbox.
binaryninja.interaction.ChoiceField	ChoiceField prompts the user to choose from the list of strings provided in choices….
binaryninja.interaction.DirectoryNameField	DirectoryNameField prompts the user to specify a directory name to open. Result is stored in…
binaryninja.interaction.FlowGraphReport
binaryninja.interaction.HTMLReport
binaryninja.interaction.IntegerField	IntegerField add prompt for integer. Result is stored in self.result as an int.
binaryninja.interaction.InteractionHandler
binaryninja.interaction.LabelField	LabelField adds a text label to the display.
binaryninja.interaction.MarkdownReport
binaryninja.interaction.MultilineTextField	MultilineTextField add multi-line text string input field. Result is stored in self.result
binaryninja.interaction.OpenFileNameField	OpenFileNameField prompts the user to specify a file name to open. Result is stored in…
binaryninja.interaction.PlainTextReport
binaryninja.interaction.ReportCollection
binaryninja.interaction.SaveFileNameField	SaveFileNameField prompts the user to specify a file name to save. Result is stored in…
binaryninja.interaction.SeparatorField	SeparatorField adds vertical separation to the display.
binaryninja.interaction.TextLineField	TextLineField Adds prompt for text string input. Result is stored in self.result as a string…

class AddressField

Bases: object

AddressField prompts the user for an address. By passing the optional view and current_address parameters offsets can be used instead of just an address. The result is stored as in int in self.result.

Note

This API currently functions differently on the command-line, as the view and current_address are disregarded. Additionally where as in the UI the result defaults to hexadecimal on the command-line 0x must be specified.

__init__(prompt: str, view: BinaryView | None = None, current_address: int = 0, default: int | None = None)

Parameters:

• prompt (str) –

• view (BinaryView | None) –

• current_address (int) –

• default (int | None) –

property current_address

current address to use as a base for relative calculations

property prompt

prompt to be presented to the user

property result

property view

BinaryView for the address

class CheckboxField

Bases: object

CheckboxField prompts the user to choose a yes/no option in a checkbox. Result is stored in self.result as a boolean value.

Parameters:

• prompt (str) – Prompt to be presented to the user

• default (bool) – Default state of the checkbox (False == unchecked, True == checked)

__init__(prompt, default)

property default

property prompt

property result

class ChoiceField

Bases: object

ChoiceField prompts the user to choose from the list of strings provided in choices. Result is stored in self.result as an index in to the choices array.

Parameters:

• prompt (str) – Prompt to be presented to the user

• choices (list(str)) – List of choices to choose from

• default (Optional[int]) – Optional index into choices that will be selected by default

__init__(prompt: str, choices: List[str], default: int | None = None)

Parameters:

• prompt (str) –

• choices (List[str]) –

• default (int | None) –

property choices: List[str]

property default: int | None

property prompt: str

property result: int | None

class DirectoryNameField

Bases: object

DirectoryNameField prompts the user to specify a directory name to open. Result is stored in self.result as a string.

__init__(prompt, default_name='', default=None)

property default_name

property prompt

property result

class FlowGraphReport

Bases: object

__init__(title, graph, view=None)

property graph

property title

property view

class HTMLReport

Bases: object

__init__(title, contents, plaintext='', view=None)

property contents

property plaintext

property title

property view

class IntegerField

Bases: object

IntegerField add prompt for integer. Result is stored in self.result as an int.

__init__(prompt: str, default: int | None = None)

Parameters:

• prompt (str) –

• default (int | None) –

property prompt

property result

class InteractionHandler

Bases: object

__init__()

get_address_input(prompt, title, view, current_address)

get_checkbox_input(prompt, default_choice)

get_choice_input(prompt, title, choices)

get_directory_name_input(prompt, default_name)

get_form_input(fields, title)

get_int_input(prompt, title)

get_large_choice_input(prompt, title, choices)

get_open_filename_input(prompt, ext)

get_save_filename_input(prompt, ext, default_name)

get_text_line_input(prompt, title)

open_url(url)

register()

run_progress_dialog(task: Callable[[Callable[[int, int], bool]], None]) → bool

Parameters:

task (Callable[[Callable[[int, int], bool]], None]) –

Return type:

bool

show_graph_report(view, title, graph)

show_html_report(view, title, contents, plaintext)

show_markdown_report(view, title, contents, plaintext)

show_message_box(title, text, buttons, icon)

show_plain_text_report(view, title, contents)

show_report_collection(title, reports)

class LabelField

Bases: object

LabelField adds a text label to the display.

__init__(text: str)

Parameters:

text (str) –

property text: str

class MarkdownReport

Bases: object

__init__(title, contents, plaintext='', view=None)

property contents

property plaintext

property title

property view

class MultilineTextField

Bases: object

MultilineTextField add multi-line text string input field. Result is stored in self.result as a string. This option is not supported on the command-line.

__init__(prompt: str, default: str | None = None)

Parameters:

• prompt (str) –

• default (str | None) –

property prompt

property result

class OpenFileNameField

Bases: object

OpenFileNameField prompts the user to specify a file name to open. Result is stored in self.result as a string.

__init__(prompt: str, ext: str = '', default: str | None = None)

Parameters:

• prompt (str) –

• ext (str) –

• default (str | None) –

property ext

property prompt

property result

class PlainTextReport

Bases: object

__init__(title, contents, view=None)

property contents

property title

property view

class ReportCollection

Bases: object

__init__(handle=None)

append(report)

update(i, report)

class SaveFileNameField

Bases: object

SaveFileNameField prompts the user to specify a file name to save. Result is stored in self.result as a string.

__init__(prompt, ext='', default_name='', default=None)

property default_name

property ext

property prompt

property result

class SeparatorField

Bases: object

SeparatorField adds vertical separation to the display.

class TextLineField

Bases: object

TextLineField Adds prompt for text string input. Result is stored in self.result as a string on completion.

__init__(prompt: str, default: str | None = None)

Parameters:

• prompt (str) –

• default (str | None) –

property prompt

property result

get_address_input(prompt, title)

get_address_input prompts the user for an address with the given prompt and title

Note

This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used.

Parameters:

• prompt (str) – String to prompt with.

• title (str) – Title of the window when executed in the UI.

Return type:

integer value input by the user.

Example:

>>> get_address_input("PROMPT>", "getinfo")
PROMPT> 10
10L

get_checkbox_input(prompt: str, title: str, default: bool = False)

get_checkbox_input prompts the user for a checkbox input :param prompt: String to prompt with :param title: Title of the window when executed in the UI :param default: Optional default state for the checkbox (false == unchecked, true == checked), False if not set. :rtype: bool indicating the state of the checkbox

Parameters:

• prompt (str) –

• title (str) –

• default (bool) –

get_choice_input(prompt, title, choices)

get_choice_input prompts the user to select the one of the provided choices

Note

This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used. The UI uses a combo box.

Parameters:

• prompt (str) – String to prompt with.

• title (str) – Title of the window when executed in the UI.

• choices (list(str)) – A list of strings for the user to choose from.

Return type:

integer array index of the selected option

Example:

>>> get_choice_input("PROMPT>", "choices", ["Yes", "No", "Maybe"])
choices
1) Yes
2) No
3) Maybe
PROMPT> 1
0L

get_directory_name_input(prompt: str, default_name: str = '')

get_directory_name_input prompts the user for a directory name to save as, optionally providing a default_name

Note

This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used. The UI uses the native window pop-up for file selection.

Parameters:

• prompt (str) – Prompt to display.

• default_name (str) – Optional, default directory name.

Return type:

str

Example:

>>> get_directory_name_input("prompt")
prompt dirname
'dirname'

get_form_input(fields, title)

get_from_input Prompts the user for a set of inputs specified in fields with given title. The fields parameter is a list which can contain the following types:

FieldType	Description
str	an alias for LabelField
None	an alias for SeparatorField
LabelField	Text output
SeparatorField	Vertical spacing
TextLineField	Prompt for a string value
MultilineTextField	Prompt for multi-line string value
IntegerField	Prompt for an integer
AddressField	Prompt for an address
ChoiceField	Prompt for a choice from provided options
OpenFileNameField	Prompt for file to open
SaveFileNameField	Prompt for file to save to
DirectoryNameField	Prompt for directory name
CheckboxFormField	Prompt for a checkbox

This API is flexible and works both in the UI via a pop-up dialog and on the command-line.

Note

More complicated APIs should consider using the included pyside2 functionality in the binaryninjaui module. Returns true or false depending on whether the user submitted responses or cancelled the dialog.

Parameters:

• fields (list(str) or list(None) or list(LabelField) or list(SeparatorField) or list(TextLineField) or list(MultilineTextField) or list(IntegerField) or list(AddressField) or list(ChoiceField) or list(OpenFileNameField) or list(SaveFileNameField) or list(DirectoryNameField)) – A list containing these classes, strings or None

• title (str) – The title of the pop-up dialog

Return type:

bool

Example:

>>> int_f = IntegerField("Specify Integer")
>>> tex_f = TextLineField("Specify name")
>>> choice_f = ChoiceField("Options", ["Yes", "No", "Maybe"])
>>> get_form_input(["Get Data", None, int_f, tex_f, choice_f], "The options")
Get Data
<empty>
Specify Integer 1337
Specify name Peter
The options
1) Yes
2) No
3) Maybe
Options 1
>>> True
>>> print(tex_f.result, int_f.result, choice_f.result)
Peter 1337 0

get_int_input(prompt, title)

get_int_input prompts the user to input a integer with the given prompt and title

Note

This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used.

Parameters:

• prompt (str) – String to prompt with

• title (str) – Title of the window when executed in the UI

Return type:

integer value input by the user

Example:

>>> get_int_input("PROMPT>", "getinfo")
PROMPT> 10
10

get_large_choice_input(prompt, title, choices)

get_large_choice_input prompts the user to select the one of the provided choices from a large pool

Note

This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a text prompt is used. The UI uses a filterable list of entries

Parameters:

• prompt (str) – Text for the button when executed in the UI. Prompt shown for selection headless.

• title (str) – Title of the window when executed in the UI.

• choices (list(str)) – A list of strings for the user to choose from.

Return type:

integer array index of the selected option

Example:

>>> get_large_choice_input("Select Function", "Select a Function", [f.symbol.short_name for f in bv.functions])

get_open_filename_input(prompt: str, ext: str = '') → str | None

get_open_filename_input prompts the user for a file name to open

Note

This API functions differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used. The UI uses the native window pop-up for file selection.

Multiple file selection groups can be included if separated by two semicolons. Multiple file wildcards may be specified by using a space within the parenthesis.

Also, a simple selector of *.extension by itself may also be used instead of specifying the description.

Parameters:

• prompt (str) – Prompt to display.

• ext (str) – Optional, file extension

Example:

>>> get_open_filename_input("filename:", "*.py")
'test.py'
>>> get_open_filename_input("filename:", "All Files (*)")
'test.py'
>>> get_open_filename_input("filename:", "Executables (*.exe)")
'foo.exe'
>>> get_open_filename_input("filename:", "Executables (*.exe *.com)")
'foo.exe'
>>> get_open_filename_input("filename:", "Executables (*.exe *.com);;Python Files (*.py);;All Files (*)")
'foo.exe'

Return type:

str | None

get_save_filename_input(prompt: str, ext: str = '', default_name: str = '') → str | None

get_save_filename_input prompts the user for a file name to save as, optionally providing a file extension and default_name

Note

This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used. The UI uses the native window pop-up for file selection.

Parameters:

• prompt (str) – Prompt to display.

• ext (str) – Optional, file extension

• default_name (str) – Optional, default file name.

Example:

>>> get_save_filename_input("filename:", "*.py", "test.py")
filename: test.py
'test.py'
>>> get_save_filename_input("filename:", "All Files (*)", "test.py")
filename: test.py
'test.py'
>>> get_save_filename_input("filename:", "Executables (*.exe)", "foo.exe")
filename: foo.exe
'foo.exe'
>>> get_save_filename_input("filename:", "Executables (*.exe *.com)", "foo.exe")
filename: foo.exe
'foo.exe'
>>> get_save_filename_input("filename:", "Executables (*.exe *.com);;Python Files (*.py);;All Files (*)", "foo.exe")
filename: foo.exe
'foo.exe'

Return type:

str | None

get_text_line_input(prompt, title)

get_text_line_input prompts the user to input a string with the given prompt and title

Note

This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used.

Parameters:

• prompt (str) – String to prompt with

• title (str) – Title of the window when executed in the UI

Return type:

str containing the input without trailing newline character

Example:

>>> get_text_line_input("PROMPT>", "getinfo")
PROMPT> Input!
'Input!'

markdown_to_html(contents)

markdown_to_html converts the provided markdown to HTML

Parameters:

contents (str) – Markdown contents to convert to HTML

Return type:

str

Example:

>>> markdown_to_html("##Yay")
'<h2>Yay</h2>'

open_url(url)

open_url Opens a given url in the user’s web browser, if available.

Parameters:

url (str) – Url to open

Returns:

True if successful

Return type:

bool

run_progress_dialog(title: str, can_cancel: bool, task: Callable[[Callable[[int, int], bool]], None]) → bool

run_progress_dialog runs a given task in a background thread, showing an updating progress bar which the user can cancel.

Parameters:

• title (str) – Dialog title

• can_cancel (bool) – If the task can be cancelled

• task (Callable[[Callable[[int, int], bool]], None]) – Function to perform the task, taking as a parameter a function which should be called to report progress updates and check for cancellation. If the progress function returns false, the user has requested to cancel, and the task should handle this appropriately.

Returns:

True if not cancelled

Return type:

bool

show_graph_report(title, graph)

show_graph_report displays a flow graph in UI applications and nothing in command-line applications. This API doesn’t support clickable references into an existing BinaryView. Use the BinaryView.show_html_report API if hyperlinking is needed.

Note

This API function will have no effect outside the UI.

Parameters:

• title (str) – Title to display in the tab

• graph (FlowGraph) – Flow graph to display

Return type:

None

show_html_report(title, contents, plaintext='')

show_html_report displays the HTML contents in UI applications and plaintext in command-line applications. This API doesn’t support hyperlinking into the BinaryView, use the BinaryView.show_html_report API if hyperlinking is needed.

Parameters:

• title (str) – Title to display in the tab

• contents (str) – HTML contents to display

• plaintext (str) – Plain text version to display (used on the command-line)

Return type:

None

Example:

>>> show_html_report("title", "<h1>Contents</h1>", "Plain text contents")
Plain text contents

show_markdown_report(title, contents, plaintext='')

show_markdown_report displays the markdown contents in UI applications and plaintext in command-line applications. This API doesn’t support hyperlinking into the BinaryView, use the BinaryView.show_markdown_report API if hyperlinking is needed.

Note

This API function differently on the command-line vs the UI. In the UI a pop-up is used. On the command-line a simple text prompt is used.

Parameters:

• title (str) – title to display in the tab

• contents (str) – markdown contents to display

• plaintext (str) – Plain text version to display (used on the command-line)

Return type:

None

Example:

>>> show_markdown_report("title", "##Contents", "Plain text contents")
Plain text contents

show_message_box(title, text, buttons=MessageBoxButtonSet.OKButtonSet, icon=MessageBoxIcon.InformationIcon)

show_message_box Displays a configurable message box in the UI, or prompts on the console as appropriate

Parameters:

• title (str) – Text title for the message box.

• text (str) – Text for the main body of the message box.

• buttons (MessageBoxButtonSet) – One of MessageBoxButtonSet

• icon (MessageBoxIcon) – One of MessageBoxIcon

Returns:

Which button was selected

Return type:

MessageBoxButtonResult

show_plain_text_report(title, contents)

show_plain_text_report displays contents to the user in the UI or on the command-line

Note

This API functions differently on the command-line vs the UI. In the UI, a pop-up is used. On the command-line, a simple text prompt is used.

Parameters:

• title (str) – Title to display in the tab

• contents (str) – Plaintext contents to display

Return type:

None

Example:

>>> show_plain_text_report("title", "contents")
contents

show_report_collection(title, reports)

show_report_collection displays multiple reports in UI applications

Note

This API function will have no effect outside the UI.

Parameters:

reports (ReportCollection) – Reports to display

Return type:

None

AddressField

class AddressField

Bases: object

AddressField prompts the user for an address. By passing the optional view and current_address parameters offsets can be used instead of just an address. The result is stored as in int in self.result.

Note

This API currently functions differently on the command-line, as the view and current_address are disregarded. Additionally where as in the UI the result defaults to hexadecimal on the command-line 0x must be specified.

__init__(prompt: str, view: BinaryView | None = None, current_address: int = 0, default: int | None = None)

Parameters:

• prompt (str) –

• view (BinaryView | None) –

• current_address (int) –

• default (int | None) –

property current_address

current address to use as a base for relative calculations

property prompt

prompt to be presented to the user

property result

property view

BinaryView for the address

CheckboxField

class CheckboxField

Bases: object

CheckboxField prompts the user to choose a yes/no option in a checkbox. Result is stored in self.result as a boolean value.

Parameters:

• prompt (str) – Prompt to be presented to the user

• default (bool) – Default state of the checkbox (False == unchecked, True == checked)

__init__(prompt, default)

property default

property prompt

property result

ChoiceField

class ChoiceField

Bases: object

ChoiceField prompts the user to choose from the list of strings provided in choices. Result is stored in self.result as an index in to the choices array.

Parameters:

• prompt (str) – Prompt to be presented to the user

• choices (list(str)) – List of choices to choose from

• default (Optional[int]) – Optional index into choices that will be selected by default

__init__(prompt: str, choices: List[str], default: int | None = None)

Parameters:

• prompt (str) –

• choices (List[str]) –

• default (int | None) –

property choices: List[str]

property default: int | None

property prompt: str

property result: int | None

DirectoryNameField

class DirectoryNameField

Bases: object

DirectoryNameField prompts the user to specify a directory name to open. Result is stored in self.result as a string.

__init__(prompt, default_name='', default=None)

property default_name

property prompt

property result

FlowGraphReport

class FlowGraphReport

Bases: object

__init__(title, graph, view=None)

property graph

property title

property view

HTMLReport

class HTMLReport

Bases: object

__init__(title, contents, plaintext='', view=None)

property contents

property plaintext

property title

property view

IntegerField

class IntegerField

Bases: object

IntegerField add prompt for integer. Result is stored in self.result as an int.

__init__(prompt: str, default: int | None = None)

Parameters:

• prompt (str) –

• default (int | None) –

property prompt

property result

InteractionHandler

class InteractionHandler

Bases: object

__init__()

get_address_input(prompt, title, view, current_address)

get_checkbox_input(prompt, default_choice)

get_choice_input(prompt, title, choices)

get_directory_name_input(prompt, default_name)

get_form_input(fields, title)

get_int_input(prompt, title)

get_large_choice_input(prompt, title, choices)

get_open_filename_input(prompt, ext)

get_save_filename_input(prompt, ext, default_name)

get_text_line_input(prompt, title)

open_url(url)

register()

run_progress_dialog(task: Callable[[Callable[[int, int], bool]], None]) → bool

Parameters:

task (Callable[[Callable[[int, int], bool]], None]) –

Return type:

bool

show_graph_report(view, title, graph)

show_html_report(view, title, contents, plaintext)

show_markdown_report(view, title, contents, plaintext)

show_message_box(title, text, buttons, icon)

show_plain_text_report(view, title, contents)

show_report_collection(title, reports)

LabelField

class LabelField

Bases: object

LabelField adds a text label to the display.

__init__(text: str)

Parameters:

text (str) –

property text: str

MarkdownReport

class MarkdownReport

Bases: object

__init__(title, contents, plaintext='', view=None)

property contents

property plaintext

property title

property view

MultilineTextField

class MultilineTextField

Bases: object

MultilineTextField add multi-line text string input field. Result is stored in self.result as a string. This option is not supported on the command-line.

__init__(prompt: str, default: str | None = None)

Parameters:

• prompt (str) –

• default (str | None) –

property prompt

property result

OpenFileNameField

class OpenFileNameField

Bases: object

OpenFileNameField prompts the user to specify a file name to open. Result is stored in self.result as a string.

__init__(prompt: str, ext: str = '', default: str | None = None)

Parameters:

• prompt (str) –

• ext (str) –

• default (str | None) –

property ext

property prompt

property result

PlainTextReport

class PlainTextReport

Bases: object

__init__(title, contents, view=None)

property contents

property title

property view

ReportCollection

class ReportCollection

Bases: object

__init__(handle=None)

append(report)

update(i, report)

SaveFileNameField

class SaveFileNameField

Bases: object

SaveFileNameField prompts the user to specify a file name to save. Result is stored in self.result as a string.

__init__(prompt, ext='', default_name='', default=None)

property default_name

property ext

property prompt

property result

SeparatorField

class SeparatorField

Bases: object

SeparatorField adds vertical separation to the display.

TextLineField

class TextLineField

Bases: object

TextLineField Adds prompt for text string input. Result is stored in self.result as a string on completion.

__init__(prompt: str, default: str | None = None)

Parameters:

• prompt (str) –

• default (str | None) –

property prompt

property result