BNMF Reference¶

Binary Ninja Modification Format (BNMF) is the declarative JSON protocol Sidekick uses to write changes back to the Binary Ninja database. Instead of issuing imperative commands, you describe the desired state of an object. The processor reads the current state, computes the delta, and applies the minimum changes needed.

BNMF is used internally by Sidekick's AI agents whenever they rename functions, define types, annotate code, or perform any other database modification. BNMF is submitted through the update_database tool.

For a conceptual overview of how modifications fit into the analysis workflow, see Editing Binaries with Suggestions.

Request Structure¶

A BNMF request is a JSON object with a human-readable description and a list of per-view change sets.

{
  "description": "Human-readable summary of the change set",
  "binary_view_changes": [
    {
      "modifications": [
        {"uri": "bv:function/0x401000", "state": {"name": "process_input"}}
      ]
    }
  ]
}

Request fields¶

Field	Type	Default	Description
`description`	String	Required	Human-readable summary of the change set; recorded as the transaction's description in the Sidekick Transaction Log
`binary_view_changes`	Array[Object]	Required	Per-view change sets (see below)
`options.return_sample`	Integer (0–100)	`10`	Number of sample modifications to include in the result

Change set fields¶

Field	Type	Default	Description
`binary_view_id`	String	None	Binary view to modify. Optional when the target has a single binary view (a missing or unknown ID is then replaced by that view). When several views are open (project or multi-binary targets), name the view explicitly: a change set without `binary_view_id` is skipped with a warning, and if no change set remains the request is rejected with a list of the available view IDs
`modifications`	Array[Modification]	Required	Modifications to apply

Modifications from all change sets that target the same binary view are applied together as one batch. Malformed change sets or modifications are skipped and reported in the result warnings. If you omit a modification id, one is assigned automatically (mod_0, mod_1, ...).

Modification fields¶

Field	Type	Default	Description
`uri`	String	Required	Target object identifier
`state`	Object \| null	Required	Desired state; `null` deletes the object
`id`	String	None	Client-assigned ID for dependency references
`depends_on`	Array[String]	None	IDs of modifications that must succeed first
`expect`	Object	None	Preconditions to validate before applying

Processing Modes¶

Atomic (default)¶

All modifications for a given binary view succeed or none of that view's changes are applied. If any modification fails, that view's batch is rolled back using Binary Ninja's undo system and the update fails with Failed to apply N modification(s): <uri>: <error>. When one update targets several binary views, the views are applied one after another. Views processed before the failing one keep their changes in the database, even though the transaction is reported as failed; the failing view and any later views are not applied.

update_database always applies a batch atomically. The processor also has an internal best-effort mode that continues past individual failures, but it is not exposed through update_database.

Dependency Ordering¶

Use id and depends_on to enforce ordering when one modification must precede another — for example, defining a type before using it.

{
  "modifications": [
    {
      "id": "def_type",
      "uri": "bv:type/Buffer",
      "state": {"definition": "struct Buffer { char* data; size_t len; }"}
    },
    {
      "uri": "bv:function/0x401000/variable/arg1",
      "state": {"type": "struct Buffer*"},
      "depends_on": ["def_type"]
    }
  ]
}

Rules: - Modifications are sorted topologically by depends_on before execution. - If a modification fails, all modifications that depend on it (directly or transitively) are skipped. - Duplicate id values, unknown dependency IDs, and circular dependencies all raise an error and fail the entire batch.

Preconditions (`expect`)¶

The expect field validates the current state before applying a modification. If validation fails, the modification fails with an ExpectationError, reported as Expectation failed: <uri>.<property>: expected 'X', got 'Y' for a property mismatch, or Expectation failed: Expected <uri> to exist / Expected <uri> to NOT exist for $exists checks.

`$exists` operator¶

{"expect": {"$exists": true}}   // Entity must already exist
{"expect": {"$exists": false}}  // Entity must NOT exist

An empty expect object ({}) requires the entity to exist without constraining any property values.

Property matching¶

{"expect": {"name": "sub_401000"}}  // name property must equal "sub_401000"

Multiple properties can be checked simultaneously. All must match.

Collection Operators¶

For array-valued properties, use $add and $remove to make targeted changes without replacing the entire list.

{
  "uri": "bv:component/NetworkSubsystem",
  "state": {
    "functions": {
      "$add": ["0x401500"],
      "$remove": ["0x401100"]
    }
  }
}

Collection operators are supported on functions and datavars (Component), indirect_branches and code_refs (Function Instruction), and parameters (Function). Function parameters are updated by position only — see the Function notes.

Processing order: $remove is applied first, then $add. $add deduplicates — adding an item that already exists is a no-op.

URI Reference¶

All URIs use the bv: scheme. Addresses are always in hexadecimal with a 0x prefix.

Summary table¶

URI Pattern	Description
`bv:comment/{address}`	Address-level comment
`bv:type/{name}`	Named type definition
`bv:type/{type_name}/member/{member_id}`	Struct or union member, or enum member (enum members are addressed by name)
`bv:datavar/{address}`	Data variable
`bv:function/{address}`	Function
`bv:function/{address}/instruction/{instr_addr}`	Instruction within a function
`bv:function/{address}/instruction/{instr_addr}/integer/{value}/{operand}`	Integer operand display type
`bv:function/{address}/variable/{var_name}`	Local variable within a function
`bv:function/{address}/block/{block_addr}`	Basic block highlight
`bv:function/{address}/uservalue/{def_site}/{var_name}`	User-informed value for a variable before or after an instruction
`bv:function/{address}/uservalues`	All user-informed variable values in a function
`bv:dataref/{from_addr}/{to_addr}`	User-defined data cross-reference
`bv:pointer`	Global pointer value
`bv:memory/{address}`	Raw bytes at an address
`bv:symbol/{address}/{symbol_type}`	Named symbol
`bv:section/{name}`	Memory section
`bv:segment/{address}`	Memory segment
`bv:region/{name}`	Named memory-map overlay region
`bv:tag/{address}/{type_name}`	Tag at an address
`bv:tagtype/{name}`	Tag type definition
`bv:library/{name}`	External library
`bv:external/{library}/{source_address}`	External symbol location
`bv:import/{address}`	Imported function signature (IAT slot / GOT entry)
`bv:component/{component_id}`	Component (function/data grouping)
`bv:stack/{function_address}/variable/{offset}`	Stack variable
`bv:stack/{function_address}/call_adjustment/{instruction_address}`	Per-call stack adjustment
`bv:stack/{function_address}/return_adjustment`	Function return stack adjustment

Handler Reference¶

Comment — `bv:comment/{address}`¶

Property	Type	Read	Write	Notes
`text`	String	Yes	Yes	Empty string is the default (no comment)

Comments always "exist" — there is no absent state, only an empty string.
state: null clears the comment (equivalent to {"text": ""}).

{"uri": "bv:comment/0x401200", "state": {"text": "AES key schedule loop"}}

Type — `bv:type/{name}`¶

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Rename by setting `name` to a new value
`definition`	String	Yes	Yes	Full C-syntax type definition

state: null undefines the type (undefine_user_type).
Namespace qualifiers (::) in type strings are automatically wrapped in backticks if needed.
The URI takes the bare type name (no struct/union/enum keyword). bv:type/struct table is accepted as table when the definition declares the same type.
A struct, union, class, or enum definition must be a direct named definition whose name matches the URI (bv:type/Foo with struct Foo { ... }). Anonymous aggregates and typedef wrappers such as typedef struct Foo {...} Bar; are rejected.
Derived types can use __base(BaseName, offset) attributes. Each base type must already be defined (define it first and use id/depends_on), or the change fails with Base type '...' is not defined in the binary view. Define it before the derived type.
After applying, Sidekick compares the resulting type with the requested definition and fails the modification if the layout, base types, or members differ.

{"uri": "bv:type/Config", "state": {"definition": "struct Config { int version; char name[32]; }"}}

Type Member — `bv:type/{type_name}/member/{member_id}`¶

Works on struct, union, and enum types. Enum members are described in Enum members below.

For struct and union types, member_id formats are: - Hex offset: 0x8, 0x10 - Decimal offset: 8, 16 - Member name: fieldName

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Member name
`type`	String	Yes	Yes	Member type string
`offset`	Integer	Yes	Yes	Byte offset in the structure

Adding a new member requires type and an offset, taken from a numeric member_id or from offset.
Changing offset removes the member and re-inserts it at the new position.
state: null removes the member from the structure.
Union limitation: For unions all members share offset 0, so address-based lookup returns the first match. Use member name as the member_id to target a specific union member.

{"uri": "bv:type/Header/member/field_name", "state": {"name": "magic", "type": "uint32_t"}}

Enum members¶

The parent enum must already exist (define it first with bv:type/{name}, using id/depends_on for ordering). Enum members are addressed by name only; numeric member_id values are rejected.

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Rename the member; renaming to an existing member name is rejected
`value`	Integer or String	Yes	Yes	Integer, or a decimal/hex integer string such as `"-0x1"`. Required when adding a member; must fit the enum's width and signedness

state: null deletes the member. Deleting a missing member is a no-op.
Other members keep their effective values: implicitly numbered members that follow an edited or removed member become explicit.
Different member names may share the same value.

{"uri": "bv:type/Status/member/STATUS_TIMEOUT", "expect": {"$exists": false}, "state": {"value": 3}}

Data Variable — `bv:datavar/{address}`¶

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Symbol name; empty string means unnamed
`type`	String	Yes	Yes	Type string; required when creating
`confidence`	Integer	Yes	Yes	Binary Ninja type confidence (0–255) attached to `type`; omit on write for the default (maximum)
`comment`	String	Yes	Yes	Comment at this address

state: null undefines the variable, removing both any user definition and any underlying analysis-generated definition. Removed analysis-generated definitions are blocked from being recreated by analysis. Deleting a missing variable is a no-op.
Supply type when creating a data variable. If only name is given for an address with no data variable, a placeholder void-typed variable is created with that name. comment is stored at the address even when no data variable is defined.
confidence must be sent together with type in the same modification; sending confidence alone is rejected with Unknown attributes for <uri>: confidence. It is attached to the parsed type via Type.with_confidence(...) before assignment. Use a lower value (e.g. 128) to mark an AI-suggested type as "soft" so subsequent analysis can still refine it; omit the field (or use 255) to pin a user-confident type that analysis will not override.

{"uri": "bv:datavar/0x804a020", "state": {"name": "g_config", "type": "struct Config*"}}

{
  "uri": "bv:datavar/0x804a020",
  "state": {"type": "struct Config*", "confidence": 128}
}

Function — `bv:function/{address}`¶

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Function name
`type`	String	Yes	Yes	Full function type signature
`comment`	String	Yes	Yes	Function-level comment
`return_type`	String	Yes	Yes	Return type only
`calling_convention`	String	Yes	Yes	e.g. `"cdecl"`, `"stdcall"` (case-insensitive)
`inline`	Boolean	Yes	Yes	Mark function as inline during analysis
`analysis_skipped`	Boolean	Yes	Yes	Skip analysis for this function
`can_return`	Boolean	Yes	Yes	Whether the function can return
`clobbered_regs`	Array[String]	Yes	Yes	Register names clobbered by the function; `null` reverts to auto-detected
`parameters`	Array[Object]	Yes	Yes	`[{"name": "buf", "type": "char*"}, ...]`. Renames or retypes the existing parameters by position; it cannot add or remove parameters, and entries past the current parameter count are ignored. To change the parameter count, set `type` with the full signature

state: null removes the user-defined function (remove_user_function).
state: {} creates a function at the address (create_user_function).
Invalid register names in clobbered_regs raise an error with examples of valid names.
The function signature itself has no confidence field: Binary Ninja's BNSetFunctionUserType stores user function types at maximum confidence and provides no confidence parameter, so any confidence on the parsed type would be silently dropped. If you need a soft type, apply it to individual arguments via bv:function/{address}/variable/{var_name} with confidence, or set the data variable at a global's address via bv:datavar/{address}.

{"uri": "bv:function/0x406ec0", "state": {"name": "command_interpreter", "return_type": "void"}}

Function Instruction — `bv:function/{address}/instruction/{instr_addr}`¶

Property	Type	Read	Write	Notes
`comment`	String	Yes	Yes	Instruction-level comment
`highlight`	String	Yes	Yes	Color name: `blue`, `red`, `green`, `cyan`, `magenta`, `yellow`, `orange`, `white`, `black`; `null` clears the highlight
`goto_label`	String	No	Yes	Label name for jump target (requires HLIL)
`call_type`	String	No	Yes	Call type override; must be a function type such as `int64_t(void, int16_t)`, not a pointer-to-function type
`stack_adjustment`	Integer	No	Yes	Stack adjustment value at this call site
`reg_stack_adjustment`	Integer	No	Yes	Register stack adjustment value
`indirect_branches`	Array	Yes	Yes	Target addresses for indirect branches (integers or hex strings; reads return hex strings). Each target must be a function start or lie in an executable segment; `null` clears user-defined branches
`code_refs`	Array	No	Yes	Addresses to add as user code cross-references

state: null clears the comment and highlight.
indirect_branches takes raw addresses: ["0x100000e58", "0x100000eb8"]. Do not use symbol names or (arch, address) tuples.

{
  "uri": "bv:function/0x401200/instruction/0x401210",
  "state": {"highlight": "yellow", "comment": "Round key XOR"}
}

Function Instruction Integer — `bv:function/{address}/instruction/{instr_addr}/integer/{value}/{operand}`¶

Property	Type	Read	Write	Notes
`display_type`	String	No	Yes	Integer display type name without the `DisplayType` suffix: `Binary`, `SignedOctal`, `UnsignedOctal`, `SignedDecimal`, `UnsignedDecimal`, `SignedHexadecimal`, `UnsignedHexadecimal`, `CharacterConstant`, `Pointer`, `Float`, `Double`, `Enumeration`. Newer Binary Ninja builds also provide `InvertedCharacterConstant`, `UnsignedComplementDecimal`, and `UnsignedComplementHexadecimal`. `null` (or `state: null`) resets to the default display

operand is a zero-based index that disambiguates when the same integer value appears multiple times in an instruction.

{
  "uri": "bv:function/0x401000/instruction/0x401005/integer/0x100/0",
  "state": {"display_type": "UnsignedDecimal"}
}

Function Variable — `bv:function/{address}/variable/{var_name}`¶

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Variable name
`type`	String	Yes	Yes	Variable type
`confidence`	Integer	Yes	Yes	Binary Ninja type confidence (0–255) attached to `type`; omit on write for the default (maximum)
`dead_store_elimination`	Boolean	Yes	Yes	Enable or disable dead store elimination
`merge_from`	Array[String]	No	Yes	Variable names to merge into this one

Variables cannot be deleted in Binary Ninja — delete operations are no-ops.
The variable must already exist.
To inform a variable's value at an instruction, use bv:function/{address}/uservalue/{def_site}/{var_name} (see User Value below).
confidence must be sent together with type in the same modification; sending confidence alone is rejected with Unknown attributes for <uri>: confidence. It is attached to the parsed type via Type.with_confidence(...) before the underlying create_user_var call. Use a lower value to mark an AI-suggested type as "soft" so subsequent analysis can still refine it; omit the field (or use 255) to pin a user-confident type.
merge_from combines the listed source variables into the target using func.merge_vars. Source names that do not exist are silently skipped.

{"uri": "bv:function/0x406ec0/variable/var_8", "state": {"name": "buffer", "type": "char*"}}

{
  "uri": "bv:function/0x406ec0/variable/arg1",
  "state": {"type": "struct Connection*", "confidence": 128}
}

Function Block — `bv:function/{address}/block/{block_addr}`¶

Property	Type	Read	Write	Notes
`color`	String	Yes	Yes	Block highlight color name: `blue`, `green`, `cyan`, `red`, `magenta`, `yellow`, `orange`, `white`, `black` (write); `null` or `state: null` clears it. Reads report the enum name in lowercase (e.g. `bluehighlightcolor`)

Block lookup is scoped to the specific function, so the same address in multiple functions is unambiguous.

User Value — `bv:function/{address}/uservalue/{def_site}/{var_name}`¶

Informs analysis of a variable's value at an instruction, influencing constant propagation, branch resolution, and type inference. def_site is the hex address of an instruction inside the function. By default the value applies after that instruction; append :before (0x401010:before) to inform the value before it instead. 0x401010:after is also accepted. The before and after values at one instruction are independent resources. The variable is looked up by name.

Property	Type	Read	Write	Notes
`value`	Integer or Object	Yes	Yes	An integer constant, or one of the value sets below; `null` clears the user value
`size`	Integer	Yes	No	Variable width in bytes

Value sets are objects with a kind. Integers anywhere in them may be decimal or hex strings.

`kind`	Fields	Meaning
`constant`	`value`	Same as a plain integer
`constant_ptr`	`value`	A constant pointer
`stack_frame_offset`	`offset`	An address at this offset in the function's stack frame
`signed_range` / `unsigned_range`	`ranges`: list of `{start, end, step}`	Values within the ranges; `step` defaults to 1
`in_set`	`values`	One of the listed values
`not_in_set`	`values`	Any value except those listed
`undetermined`	—	Explicitly unknown

The resource exists only while a user value is set at that site, so expect: {"$exists": false} keeps a write from replacing an existing value.
state: null clears the user value at that site, including values at instructions that are not definitions of the variable.
Reads report the canonical form: a constant as a plain integer, sets sorted, and every range step explicit. expect comparisons accept any equivalent spelling.

{"uri": "bv:function/0x401000/uservalue/0x401010/arg1", "state": {"value": 0}}

{
  "uri": "bv:function/0x401000/uservalue/0x401050:before/var_14",
  "expect": {"$exists": false},
  "state": {"value": {"kind": "in_set", "values": [3, 7]}}
}

User Values — `bv:function/{address}/uservalues`¶

Every user-informed variable value in the function. The resource is absent when the function has none.

Property	Type	Read	Write	Notes
`entries`	Array	Yes	Yes	`{def_site, var, value}` objects; `def_site` and `var` are the segments of the matching User Value URI. Writing replaces all of the function's user values
`count`	Integer	Yes	No	Number of entries

state: null clears every user value in the function.

{
  "uri": "bv:function/0x401000/uservalues",
  "state": {"entries": [
    {"def_site": "0x401010", "var": "arg1", "value": 0},
    {"def_site": "0x401050:before", "var": "var_14", "value": {"kind": "in_set", "values": [3, 7]}}
  ]}
}

Data Reference — `bv:dataref/{from_addr}/{to_addr}`¶

No properties — this is an existence-only resource.

state: {} creates the reference (add_user_data_ref).
state: null removes the reference (remove_user_data_ref).

{"uri": "bv:dataref/0x401050/0x804a000", "state": {}}

Pointer — `bv:pointer`¶

Property	Type	Read	Write	Notes
`value`	Integer	Yes	Yes	Global pointer address (binary-wide)
`user_set`	Boolean	Yes	No	Whether the user has set the value (read-only)

state: null clears the user-set global pointer value.
state: {"value": null} forces the pointer to Undetermined.

Memory — `bv:memory/{address}`¶

Property	Type	Read	Write	Notes
`bytes`	Hex String	No	Yes	Raw bytes to write, e.g. `"90909090"`
`expect`	Hex String	No	Yes	Expected current bytes (compare-and-swap)

state: null raises an error — memory cannot be deleted.
When expect is provided, the write only proceeds if the current bytes at the address match. Use this to avoid overwriting bytes that have already changed.
If expect and bytes have different lengths, the original bytes are removed and the new bytes inserted (growing or shrinking the data, which shifts the following bytes). With no expect, the bytes are overwritten in place.
A top-level "expect": {"bytes": "7401"} precondition works as an equivalent guard.

{"uri": "bv:memory/0x401000", "state": {"bytes": "9090", "expect": "7401"}}

Symbol — `bv:symbol/{address}/{symbol_type}`¶

symbol_type is any Binary Ninja SymbolType name: FunctionSymbol, ImportAddressSymbol, ImportedFunctionSymbol, DataSymbol, ImportedDataSymbol, ExternalSymbol, LibraryFunctionSymbol, SymbolicFunctionSymbol, LocalLabelSymbol. An unknown name fails the modification.

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Short name (required for create or update)
`full_name`	String	Yes	Yes	Full name including namespace (defaults to `name`)
`raw_name`	String	Yes	Yes	Raw or mangled name (defaults to `full_name`)
`binding`	String	Yes	Yes	`NoBinding`, `LocalBinding`, `GlobalBinding`, `WeakBinding`
`namespace`	String	Yes	Yes	Symbol namespace
`ordinal`	Integer	Yes	Yes	Symbol ordinal (default 0)

Multiple symbols of different types can exist at the same address.
When updating, the existing symbol of the matching type is undefined before the new one is created.
Only user-defined symbols can be deleted. Loader-generated symbols (e.g. ImportedFunctionSymbol from the file format) cannot be removed and will raise an error.

{"uri": "bv:symbol/0x401000/FunctionSymbol", "state": {"name": "main", "binding": "GlobalBinding"}}

Section — `bv:section/{name}`¶

Property	Type	Read	Write	Notes
`start`	Integer or hex String	Yes	Yes	Start address; reads return a hex string such as `0x401000`
`length`	Integer	Yes	Yes	Size in bytes
`semantics`	String	Yes	Yes	See semantics values below
`type`	String	Yes	Yes	Section type string
`align`	Integer	Yes	Yes	Alignment (default 1)
`entry_size`	Integer	Yes	Yes	Entry size (default 1)
`linked_section`	String	Yes	Yes	Linked section name
`info_section`	String	Yes	Yes	Info section name
`info_data`	Integer	Yes	Yes	Info data value
`auto_defined`	Boolean	Yes	No	Whether the section is loader-defined (read-only)

Semantics values: DefaultSectionSemantics, ReadOnlyCodeSectionSemantics, ReadOnlyDataSectionSemantics, ReadWriteDataSectionSemantics, ExternalSectionSemantics

Creating a section requires start and length.
state: null calls remove_user_section — only user-created sections can be deleted.
Modifying a user section is implemented as delete-and-recreate with merged properties. Only the properties you specify change; the rest retain their existing values.
Loader-defined sections (auto_defined: true, such as .text or .rodata) cannot be modified and will raise an error.

Segment — `bv:segment/{address}`¶

Property	Type	Read	Write	Notes
`length`	Integer	Yes	Yes	Total size
`data_offset`	Integer	Yes	Yes	File offset
`data_length`	Integer	Yes	Yes	File size
`readable`	Boolean	Yes	Yes	Read permission
`writable`	Boolean	Yes	Yes	Write permission
`executable`	Boolean	Yes	Yes	Execute permission
`contains_data`	Boolean	No	Yes	Contains data flag
`contains_code`	Boolean	No	Yes	Contains code flag

Creating a segment requires length, data_offset, and data_length.
state: null calls remove_user_segment.

Memory Region — `bv:region/{name}`¶

Named overlay regions in the binary view's memory map.

Property	Type	Read	Write	Notes
`start`	Integer or hex String	Yes	Create only	Start address; required to create, immutable afterwards
`length`	Integer or hex String	Yes	Create only	Size in bytes; required to create, immutable afterwards
`source`	Object	No	Create only	Backing bytes: `{"raw_offset": N}` copies bytes from the Raw file, `{"bytes": "90c3"}` supplies exact-length hex bytes; omit for an unbacked fill
`flags`	Integer or hex String	Yes	Yes	Binary Ninja `SegmentFlag` bitmask (0 to 2^32-1)
`enabled`	Boolean	Yes	Yes	Whether the region is active
`rebaseable`	Boolean	Yes	Yes	Whether the region is rebaseable
`fill`	Integer or hex String	Yes	Yes	Fill byte (0–255)
`display_name`	String	Yes	Yes	Display name
`end`, `has_target`, `absolute_address_mode`, `local`	—	Yes	No	Read-only

Creating a region requires start and length.
Extent and backing cannot change. To change them, add a region with a new, unique name.
state: null removes the region.
Region deletion is reverted with Binary Ninja Undo, not the Sidekick Transaction Log revert. Property edits and creation can be reverted from the log; enabled: false is the revertible alternative to deletion.

{"uri": "bv:region/patch1", "state": {"start": "0x1000", "length": 4, "source": {"bytes": "90909090"}}}

Tag — `bv:tag/{address}/{type_name}`¶

Property	Type	Read	Write	Notes
`data`	String	Yes	Yes	Tag content
`icon`	String	No	Yes	Icon; accepted only when the tag type does not exist yet and is being auto-created. Supplying `icon` for an existing tag type fails with an unknown-attributes error (use `bv:tagtype/{name}` to change a type icon)

If the tag type does not exist, it is created automatically.
An existing tag of the same type at the address is removed before the new one is added.

{"uri": "bv:tag/0x401000/Reviewed", "state": {"data": "confirmed benign"}}

Tag Type — `bv:tagtype/{name}`¶

Property	Type	Read	Write	Notes
`icon`	String	Yes	Yes	Icon character

state: null calls remove_tag_type.
Changing the icon on an existing tag type requires a delete-and-recreate, which may orphan existing tags of that type.

External Library — `bv:library/{name}`¶

Property	Type	Read	Write	Notes
`backing_file`	String	Yes	Yes	Name or on-disk path of an existing file in the same Binary Ninja project. Setting it on a view that is not in a project, or naming a file that is not in the project, fails

state: null calls remove_external_library.

External Location — `bv:external/{library}/{source_address}`¶

source_address is the address of the import reference in the binary (the source symbol address), which uniquely identifies the location even when multiple symbols share a name.

Property	Type	Read	Write	Notes
`source_symbol`	String	Yes	No	Name of the source symbol (read-only)
`target_symbol`	String	Yes	Yes	Symbol name in the target library
`target_address`	Integer or hex String	Yes	Yes	Address in the target library; reads return a hex string (`null` if none)

The external library must exist before creating an external location.

Imported Function — `bv:import/{address}`¶

Apply a recovered signature to an imported symbol and have it propagate to every caller automatically. This is the right URI for the import-type-recovery workflow — it hides the platform-specific plumbing behind a single address and a function type.

address is the IAT slot (PE) or GOT entry (ELF) — the address Binary Ninja flags with ImportAddressSymbol, same value the enumerator returns as iat_or_got.

Property	Type	Read	Write	Notes
`symbol`	String	Yes	No	Short name of the imported symbol (read-only)
`type`	String	Yes	Yes	Function type — e.g. `"int32_t(const char* fmt, ...)"`, not pointer-to-function
`confidence`	Integer	Yes	Yes	0–255. Attached to the IAT data variable's pointer type when the signature is written to the IAT slot (PE). Advisory when the type is set on an ELF PLT stub, where Binary Ninja drops per-function-type confidence (see Function notes)
`library`	String	Yes	No	Attributed library when the format states one (PE); `null` on ELF
`plt_address`	String	Yes	Yes	ELF PLT stub address. Read-side: the resolved stub. Write-side: optional hint that short-circuits code-ref lookup

ELF: the handler locates the small PLT stub that jumps through the GOT entry (the first code-ref whose function has ≤3 basic blocks, matching the standard x86-64 / ARM64 / MIPS PLT shape) and calls Function.set_user_type on it. Analysis propagates the stub's signature to every caller's HLIL automatically. If you already know the PLT stub's address, pass plt_address in the state to skip the lookup.
PE: there is no PLT stub — the handler wraps the function type in a pointer and assigns it to the IAT data variable. Callers see the type through the normal indirect-call pointer propagation path.
The type attribute must be a function type. Pointer-to-function forms are rejected with a clear error — pointer wrapping on PE is handled internally so callers use one form on both platforms.
state: null is a no-op: Binary Ninja has no "un-apply" API for imported types, and we don't want to strip types we didn't author.
Why not bv:datavar/{got_addr}? On ELF, typing the GOT data variable does not propagate to callers. The GOT slot is not what analysis consults when resolving calls through the PLT — the stub's own function signature is. bv:import targets the stub, which is the only thing post-load analysis honors.

{
  "uri": "bv:import/0x5cac0",
  "state": {"type": "int32_t(const char* ident, int32_t option, int32_t facility)"}
}

{
  "uri": "bv:import/0x5cac0",
  "state": {
    "type": "int32_t(const char* ident, int32_t option, int32_t facility)",
    "plt_address": "0xc060"
  }
}

Component — `bv:component/{component_id}`¶

component_id can be a GUID or a component name. The lookup searches recursively through all nested components.

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Component display name
`functions`	Array[String]	Yes	Yes	Function addresses (hex strings); setting this replaces the entire list
`datavars`	Array[String]	Yes	Yes	Data variable addresses (hex strings); setting this replaces the entire list

state: null calls remove_component.
Use $add/$remove collection operators to add or remove individual entries without replacing the full list.

Stack Variable — `bv:stack/{function_address}/variable/{offset}`¶

offset formats: -0x10, 0x10, -16, 16

Property	Type	Read	Write	Notes
`name`	String	Yes	Yes	Variable name; defaults to `var_<hex offset>` if omitted
`type`	String	Yes	Yes	Variable type; defaults to `int` if omitted
`offset`	Integer	Yes	No	Stack offset (from URI; read-only in state)

state: null calls delete_user_stack_var(offset).
Creating or updating uses create_user_stack_var(offset, type, name). The variable is recreated on every write, so supply both name and type when updating an existing stack variable; an omitted property is reset to its default.

{"uri": "bv:stack/0x401000/variable/-0x28", "state": {"name": "local_buf", "type": "char[40]"}}

Stack Call Adjustment — `bv:stack/{function_address}/call_adjustment/{instruction_address}`¶

Property	Type	Read	Write	Notes
`value`	Integer	Yes	Yes	Stack adjustment value at this call site

state: null resets the adjustment to 0.

Stack Return Adjustment — `bv:stack/{function_address}/return_adjustment`¶

Property	Type	Read	Write	Notes
`value`	Integer	Yes	Yes	Return stack adjustment for the function

state: null resets the adjustment to OffsetWithConfidence(0).

Result Structure¶

These structures describe the processor's internal result. Through update_database you see a success message with the transaction ID and an effects report. If any modification fails, the whole transaction fails with Failed to apply N modification(s): <uri>: <error> and nothing is committed for the failing binary view. In atomic mode, modifications after the first failure are reported as skipped with the reason batch aborted due to earlier failure; a modification skipped because of a failed dependency has the reason dependency failed: <ids>.

BatchResult¶

Field	Type	Description
`results`	Array[ModificationResult]	Individual result for each modification
`succeeded_ids`	Array[String]	IDs of modifications that succeeded
`failed_ids`	Array[String]	IDs of modifications that failed
`skipped_ids`	Array[String]	IDs of skipped modifications, either because a dependency failed (`dependency failed: <ids>`) or because an earlier failure aborted the atomic batch (`batch aborted due to earlier failure`)
`undo_id`	String	Binary Ninja undo action ID
`committed`	Boolean	`true` if changes were committed; `false` if rolled back
`all_succeeded`	Boolean	`true` if there were no failures

ModificationResult¶

Field	Type	Description
`uri`	String	The modification's target URI
`id`	String \| null	The modification ID, if one was provided
`status`	`"success"` \| `"failed"` \| `"skipped"`	Outcome
`error`	String \| null	Error message when `status` is `"failed"`
`reason`	String \| null	Skip reason when `status` is `"skipped"`

Error Reference¶

Error type	When it occurs
`ExpectationError`	`expect` precondition check failed
`ValueError`	Duplicate modification `id`; circular dependency; unknown dependency `id`; `Invalid target format: <uri>` (the object type is known but the path matches none of its patterns); missing required properties; invalid register name in `clobbered_regs`; attempt to delete a non-user-defined object
`ValueError` (unknown property)	`Unknown attributes for <uri>: <names>`: the state contains a property the handler does not accept (misspelled, or read-only such as `offset` on a stack variable). The whole batch fails
`NotImplementedError`	`No handler registered for <uri>`: the object type (e.g. `bv:foo`) is unknown

Examples¶

Rename a function and its variables¶

{
  "description": "Recover session handling function",
  "binary_view_changes": [{
    "modifications": [
      {"uri": "bv:function/0x406ec0", "state": {"name": "command_interpreter"}},
      {"uri": "bv:function/0x406ec0/variable/arg1", "state": {"name": "db", "type": "int64_t*"}},
      {"uri": "bv:function/0x406ec0/variable/arg2", "state": {"name": "input", "type": "FILE*"}},
      {"uri": "bv:function/0x406ec0/variable/var_28", "state": {"name": "current_user"}},
      {"uri": "bv:function/0x406ec0/variable/var_30_1", "state": {"name": "input_buffer"}}
    ]
  }]
}

Define a struct and apply it to a variable¶

{
  "description": "Define connection struct",
  "binary_view_changes": [{
    "modifications": [
      {
        "id": "def_conn",
        "uri": "bv:type/Connection",
        "state": {"definition": "struct Connection { int fd; char* hostname; uint16_t port; }"}
      },
      {
        "uri": "bv:function/0x401000/variable/arg1",
        "state": {"type": "struct Connection*"},
        "depends_on": ["def_conn"]
      }
    ]
  }]
}

Annotate a crypto loop¶

{
  "description": "Mark AES key schedule",
  "binary_view_changes": [{
    "modifications": [
      {"uri": "bv:comment/0x401200", "state": {"text": "AES key schedule loop"}},
      {"uri": "bv:function/0x401200/instruction/0x401210", "state": {"highlight": "yellow", "comment": "Round key XOR"}},
      {"uri": "bv:function/0x401200/instruction/0x401230", "state": {"highlight": "yellow", "comment": "S-box substitution"}}
    ]
  }]
}

Guard a rename with a precondition¶

{
  "description": "Rename only if still auto-named",
  "binary_view_changes": [{
    "modifications": [
      {
        "uri": "bv:function/0x401000",
        "expect": {"name": "sub_401000"},
        "state": {"name": "init_config"}
      }
    ]
  }]
}

Add and remove component members without full replacement¶

{
  "description": "Update network component membership",
  "binary_view_changes": [{
    "modifications": [
      {
        "uri": "bv:component/NetworkSubsystem",
        "state": {
          "functions": {
            "$add": ["0x401500", "0x401600"],
            "$remove": ["0x401100"]
          }
        }
      }
    ]
  }]
}

BNMF Reference¶

Request Structure¶

Request fields¶

Change set fields¶

Modification fields¶

Processing Modes¶

Atomic (default)¶

Dependency Ordering¶

Preconditions (expect)¶

$exists operator¶

Property matching¶

Collection Operators¶

URI Reference¶

Summary table¶

Handler Reference¶

Comment — bv:comment/{address}¶

Type — bv:type/{name}¶

Type Member — bv:type/{type_name}/member/{member_id}¶

Enum members¶

Data Variable — bv:datavar/{address}¶

Function — bv:function/{address}¶

Function Instruction — bv:function/{address}/instruction/{instr_addr}¶

Function Instruction Integer — bv:function/{address}/instruction/{instr_addr}/integer/{value}/{operand}¶

Function Variable — bv:function/{address}/variable/{var_name}¶

Function Block — bv:function/{address}/block/{block_addr}¶

User Value — bv:function/{address}/uservalue/{def_site}/{var_name}¶

User Values — bv:function/{address}/uservalues¶

Data Reference — bv:dataref/{from_addr}/{to_addr}¶

Pointer — bv:pointer¶

Memory — bv:memory/{address}¶

Symbol — bv:symbol/{address}/{symbol_type}¶

Section — bv:section/{name}¶

Segment — bv:segment/{address}¶

Memory Region — bv:region/{name}¶

Tag — bv:tag/{address}/{type_name}¶

Tag Type — bv:tagtype/{name}¶

External Library — bv:library/{name}¶

External Location — bv:external/{library}/{source_address}¶

Imported Function — bv:import/{address}¶

Component — bv:component/{component_id}¶

Stack Variable — bv:stack/{function_address}/variable/{offset}¶

Stack Call Adjustment — bv:stack/{function_address}/call_adjustment/{instruction_address}¶

Stack Return Adjustment — bv:stack/{function_address}/return_adjustment¶