settings module

binaryninja.settings.Settings([instance_id, ...])

Settings provides a way to define and access settings in a hierarchical fashion.

class Settings(instance_id: str = 'default', handle=None)[source]

Bases: object

Settings provides a way to define and access settings in a hierarchical fashion. The value of a setting can be defined for each hierarchical level, where each level overrides the preceding level. The backing-store for setting values at each level is also configurable. This allows for ephemeral or platform-independent persistent settings storage for components within Binary Ninja or consumers of the Binary Ninja API.

Each Settings instance has an instance_id which identifies a schema. The schema defines the settings contents and the way in which settings are retrieved and manipulated. A new Settings instance defaults to using a value of ‘default’ for the instance_id. The ‘default’ settings schema defines all of the settings available for the active Binary Ninja components which include at a minimum, the settings defined by the Binary Ninja core. The ‘default’ schema may additionally define settings for the UI and/or installed plugins. Extending existing schemas, or defining new ones is accomplished by calling register_group and register_setting methods, or by deserializing an existing schema with deserialize_schema.

Note

All settings in the ‘default’ settings schema are rendered with UI elements in the Settings View of Binary Ninja UI.

Allowing setting overrides is an important feature and Binary Ninja accomplishes this by allowing one to override a setting at various levels. The levels and their associated storage are shown in the following table. Default setting values are optional, and if specified, saved in the schema itself.

Setting Level

Settings Scope

Preference

Storage

Default

SettingsDefaultScope

Lowest

Settings Schema

User

SettingsUserScope

<User Directory>/settings.json

Project

SettingsProjectScope

<Project Directory>/settings.json

Resource

SettingsResourceScope

Highest

Raw BinaryView (Storage in BNDB)

Settings are identified by a key, which is a string in the form of ‘<group>.<name>’ or ‘<group>.<subGroup>.<name>’. Groups provide a simple way to categorize settings. Sub-groups are optional and multiple sub-groups are allowed. When defining a settings group, the register_group method allows for specifying a UI friendly title for use in the Binary Ninja UI. Defining a new setting requires a unique setting key and a JSON string of property, value pairs. The following table describes the available properties and values.

Property

JSON Data Type

Prerequisite

Optional

{Allowed Values} and Notes

“title”

string

None

No

Concise Setting Title

“type”

string

None

No

{“array”, “boolean”, “number”, “string”}

“elementType”

string

“type” is “array”

No

{“string”}

“enum”

array : {string}

“type” is “string”

Yes

Enumeration definitions

“enumDescriptions”

array : {string}

“type” is “string”

Yes

Enumeration descriptions that match “enum” array

“minValue”

number

“type” is “number”

Yes

Specify 0 to infer unsigned (default is signed)

“maxValue”

number

“type” is “number”

Yes

Values less than or equal to INT_MAX result in a QSpinBox UI element

“precision”

number

“type” is “number”

Yes

Specify precision for a QDoubleSpinBox

“default”

{array, boolean, number, string, null}

None

Yes

Specify optimal default value

“aliases”

array : {string}

None

Yes

Array of deprecated setting key(s)

“description”

string

None

No

Detailed setting description

“ignore”

array : {string}

None

Yes

{“SettingsUserScope”, “SettingsProjectScope”, “SettingsResourceScope”}

“message”

string

None

Yes

An optional message with additional emphasis

“readOnly”

boolean

None

Yes

Only enforced by UI elements

“optional”

boolean

None

Yes

Indicates setting can be null

“hidden”

bool

“type” is “string”

Yes

Indicates the UI should conceal the content

“requiresRestart

boolean

None

Yes

Enable restart notification in the UI upon change

Note

In order to facilitate deterministic analysis results, settings from the ‘default’ schema that impact analysis are serialized from Default, User, and Project scope into Resource scope during initial BinaryView analysis. This allows an analysis database to be opened at a later time with the same settings, regardless if Default, User, or Project settings have been modified.

Note

Settings that do not impact analysis (e.g. many UI settings) should use the “ignore” property to exclude “SettingsProjectScope” and “SettingsResourceScope” from the applicable scopes for the setting.

Example analysis plugin setting:

>>> my_settings = Settings()
>>> title = "My Pre-Analysis Plugin"
>>> description = "Enable extra analysis before core analysis."
>>> properties = f'{{"title" : "{title}", "description" : "{description}", "type" : "boolean", "default" : false}}'
>>> my_settings.register_group("myPlugin", "My Plugin")
True
>>> my_settings.register_setting("myPlugin.enablePreAnalysis", properties)
True
>>> my_bv = load("/bin/ls", options={'myPlugin.enablePreAnalysis' : True})
>>> Settings().get_bool("myPlugin.enablePreAnalysis")
False
>>> Settings().get_bool("myPlugin.enablePreAnalysis", my_bv)
True

Example UI plugin setting:

>>> my_settings = Settings()
>>> title = "My UI Plugin"
>>> description = "Enable My UI Plugin table display."
>>> properties = f'{{"title" : "{title}", "description" : "{description}", "type" : "boolean", "default" : true, "ignore" : ["SettingsProjectScope", "SettingsResourceScope"]}}'
>>> my_settings.register_group("myPlugin", "My Plugin")
True
>>> my_settings.register_setting("myPlugin.enableTableView", properties)
True
>>> my_bv = load("/bin/ls", options={'myPlugin.enableTableView' : True})
>>> Settings().get_bool("myPlugin.enableTableView")
True
Parameters:

instance_id (str) –

contains(key)[source]

contains determine if a setting identifier exists in the active settings schema

Parameters:

key (str) – the setting identifier

Returns:

True if the identifier exists in this active settings schema, False otherwise

Return type:

bool

deserialize_schema(schema, scope=SettingsScope.SettingsAutoScope, merge=True)[source]
deserialize_settings(contents, view=None, scope=SettingsScope.SettingsAutoScope)[source]
get_bool(key, view=None)[source]
get_bool_with_scope(key, view=None, scope=SettingsScope.SettingsAutoScope)[source]
get_double(key, view=None)[source]
get_double_with_scope(key, view=None, scope=SettingsScope.SettingsAutoScope)[source]
get_integer(key, view=None)[source]
get_integer_with_scope(key, view=None, scope=SettingsScope.SettingsAutoScope)[source]
get_json(key, view=None)[source]
get_json_with_scope(key, view=None, scope=SettingsScope.SettingsAutoScope)[source]
get_string(key, view=None)[source]
get_string_list(key, view=None)[source]
get_string_list_with_scope(key, view=None, scope=SettingsScope.SettingsAutoScope)[source]
get_string_with_scope(key, view=None, scope=SettingsScope.SettingsAutoScope)[source]
is_empty()[source]

is_empty determine if the active settings schema is empty

Returns:

True if the active settings schema is empty, False otherwise

Return type:

bool

keys()[source]

keys retrieve the list of setting identifiers in the active settings schema

Returns:

list of setting identifiers

Return type:

list(str)

load_settings_file(filename=None, scope=SettingsScope.SettingsAutoScope, view=None)[source]
query_property_string_list(key, property_name)[source]
register_group(group, title)[source]

register_group registers a group in the schema for this Settings instance

Parameters:
  • group (str) – a unique identifier

  • title (str) – a user friendly name appropriate for UI presentation

Returns:

True on success, False on failure.

Return type:

bool

Example:
>>> Settings().register_group("solver", "Solver")
True
>>>
register_setting(key, properties)[source]

register_setting registers a new setting with this Settings instance

Parameters:
  • key (str) – a unique setting identifier in the form ‘<group>.<name>’

  • properties (str) – a JSON string describes the setting schema

Returns:

True on success, False on failure.

Return type:

bool

Example:
>>> Settings().register_group("solver", "Solver")
True
>>> Settings().register_setting("solver.basicBlockSlicing", '{"description" : "Enable the basic block slicing in the solver.", "title" : "Basic Block Slicing", "default" : true, "type" : "boolean"}')
True
reset(key, view=None, scope=SettingsScope.SettingsAutoScope)[source]
reset_all(view=None, scope=SettingsScope.SettingsAutoScope, schema_only=True)[source]
serialize_schema()[source]
serialize_settings(view=None, scope=SettingsScope.SettingsAutoScope)[source]
set_bool(key, value, view=None, scope=SettingsScope.SettingsAutoScope)[source]
set_double(key, value, view=None, scope=SettingsScope.SettingsAutoScope)[source]
set_integer(key, value, view=None, scope=SettingsScope.SettingsAutoScope)[source]
set_json(key, value, view=None, scope=SettingsScope.SettingsAutoScope)[source]
set_resource_id(resource_id=None)[source]

set_resource_id Sets the resource identifier for this class:Settings instance. When accessing setting values at the SettingsResourceScope level, the resource identifier is passed along through the backing store interface.

Note

Currently the only available backing store for SettingsResourceScope is a BinaryView object. In the context of a BinaryView the resource identifier is the BinaryViewType name. All settings for this type of backing store are saved in the ‘Raw’ BinaryViewType. This enables the configuration of setting values such that they are available during BinaryView creation and initialization.

Parameters:

resource_id (str) – a unique identifier

Return type:

None

set_string(key, value, view=None, scope=SettingsScope.SettingsAutoScope)[source]
set_string_list(key, value, view=None, scope=SettingsScope.SettingsAutoScope)[source]
update_property(key, setting_property)[source]
default_handle = <binaryninja._binaryninjacore.LP_BNSettings object>
property instance_id

Returns the instance_id for this Settings repository (read-only)