settings module

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

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

binaryninja.settings.pyNativeStr(arg)

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

Bases: object

class 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 is also configurable and can be different for each level. 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 a unique instance_id and a settings schema that define the contents for the settings repository. By default, a new Settings instance contains an empty schema. A schema can be built up by using the register_group and func:register_setting methods, or by deserializing an existing schema with deserialize_schema. Binary Ninja provides a default Settings instance identified as ‘default’. The ‘default’ settings repository defines all of the settings available for the active Binary Ninja components.

Note

The Binary Ninja Application provides many settings that are only applicable to the UI, and thus would not be defined in the ‘default’ settings schema for Binary Ninja headless.

Except for default setting values, setting values are optional for other levels and stored separately from the schema in a backing store. The backing store can be different for each level. When querying setting values, the values returned or modified are in order of preference (i.e. SettingsAutoScope). It is possible to override the scope by specifying the desired SettingsScope.

Setting Level

Settings Scope

Preference

Storage

Default

SettingsDefaultScope

Lowest

Settings Schema

User

SettingsUserScope

<User Directory>/settings.json

Project

SettingsProjectScope

<Project Directory>/.binaryninja/settings.json

Resource

SettingsResourceScope

Highest

BinaryView (Storage in BNDB)

Individual settings are identified by a key, which is a string in the form of ‘<group>.<name>’. Groups provide a simple way to categorize settings. Additionally, sub-categories can be expressed directly in the name part of the key with a similar dot notation.

Here’s a simple example using a Resource Scope to cause settings to be saved inside of a BNDB when saved:

>>> bv2 = open_view("/tmp/ls")
>>> plugin_settings = Settings()
>>> description = "Tells Zhu Li to do the thing."
>>> title = "Do the thing"
>>> schema = f'{{"description" : "{description}", "title" : "{title}", "default" : true, "type" : "boolean"}}'
>>> plugin_settings.register_setting("ui.dothething", schema)
True
>>> plugin_settings.set_bool("ui.dothething", False, bv, SettingsScope.SettingsResourceScope)
True
>>> # Resource scope will save the setting in the BNDB itself
>>> bv2.create_database("/tmp/ls.bndb")
True
>>> bv = open_view("/tmp/ls")
>>> # If in a plugin we would need to make sure we re-regsitered the setting before querying
>>> plugin_settings.get_bool("ui.dothething", bv)
True
>>> bv = binaryninja.open_view("/tmp/ls.bndb")
>>> plugin_settings.get_bool("ui.dothething", bv)
False
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: 1>, merge=True)[source]
deserialize_settings(contents, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
get_bool(key, view=None)[source]
get_bool_with_scope(key, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
get_double(key, view=None)[source]
get_double_with_scope(key, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
get_integer(key, view=None)[source]
get_integer_with_scope(key, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
get_json(key, view=None)[source]
get_json_with_scope(key, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[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: 1>)[source]
get_string_with_scope(key, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[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)

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: 1>)[source]
reset_all(view=None, scope=<SettingsScope.SettingsAutoScope: 1>, schema_only=True)[source]
serialize_schema()[source]
serialize_settings(view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
set_bool(key, value, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
set_double(key, value, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
set_integer(key, value, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
set_json(key, value, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[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: 1>)[source]
set_string_list(key, value, view=None, scope=<SettingsScope.SettingsAutoScope: 1>)[source]
update_property(key, setting_property)[source]
handle = <binaryninja._binaryninjacore.LP_BNSettings object>
instance_id

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