BNQL Reference¶

Binary Ninja Query Language (BNQL) is a path-oriented query language for navigating and filtering the object graph of one or more analyzed binaries. Every query produces an ordered set of Binary Ninja objects.

For practical usage, see Building and Using Indexes and Using Semantic Indexing.

Query Structure¶

A BNQL query is a sequence of steps separated by /. Each step transforms the current set of objects into a new set by traversing a relationship (an axis) or by calling a function. An optional predicate in [...] filters the set after each step.

/step1/step2[predicate]/step3

A leading / makes the path absolute: it starts from the set of all open binary views. A path without a leading / is relative to the current context object (used inside predicates and function arguments).

Steps¶

Axis step¶

[axis::]node_type[predicate]

Traverse a relationship from the current objects to target objects of the specified type.

axis — the relationship to follow (see Axes). Defaults to contains when omitted.
node_type — the type of target objects, or * to match any type.
predicate — optional filter expression in [...].

Shorthand:

Shorthand	Equivalent
`/function`	`/contains::function`
`/^section`	`/contained-in::section`

Function step¶

A built-in function call used as a step. The function produces the set for the next step.

function_name(arg1, arg2, name=value)

Functions support both positional and named arguments. Positional arguments must precede named arguments.

Predicates¶

A predicate is a boolean expression wrapped in [...] that filters objects after a step. The context item (the current object being tested) is referred to as ..

/function[@name == "main"]
/datavar[entropy(.) > 7.0]
/function[calls::function[@name == "malloc"]]

A predicate that is itself a path expression evaluates to true if that path returns a non-empty set.

An integer literal inside [...] selects by zero-based index:

/function[0]     # first function
/section[2]      # third section

Operators¶

Comparison operators¶

Used in predicate expressions.

Operator	Meaning
`==`	Equal (numeric or string)
`!=`	Not equal
`<`	Less than
`>`	Greater than
`<=`	Less than or equal
`>=`	Greater than or equal
`~=`	Regex match — right-hand side is a regex pattern
`in`	Membership — left value is contained in right set or list

Logical operators¶

Operator	Meaning
`and`	Both conditions true
`or`	Either condition true
`not`	Negation

Set operators¶

Combine two query expressions. Both operands must produce sets.

Operator	Alias	Meaning
`union`	`\\|`	All items from either set
`intersect`	—	Items present in both sets
`except`	—	Items in the left set that are not in the right set

callers("malloc") union callers("free")
callers("malloc") intersect callers("free")
callers("malloc") except callers("free")

Attribute access¶

Inside a predicate, @attribute_name reads a property of the current object.

/function[@name == "main"]
/section[@name ~= r"\.text"]
/view/tag[@scope == "instruction"]
/view/function[@stack_size >= 256]

Special attributes available on all addressable objects:

Attribute	Notes
`@name`	Object name. On `datavar`, defaults to `data_<hex>` if unnamed.
`@address`	Alias for `@start` on objects that have a `start` attribute.
`@start`	Start address.

Symbol-specific attributes:

Attribute	Notes
`@imported`	`true` if the symbol is an imported function, imported data, or import address.
`@exported`	`true` if the symbol has global or weak binding and is a function or data symbol.

String-specific attributes:

Attribute	Notes
`@value`	The text content of the string literal.

Function-specific attributes:

Attribute	Notes
`@is_entry_point`	`true` if the function is one of the binary's entry points.
`@stack_size`	Recovered stack-frame size approximation in bytes, derived from Binary Ninja `stack_layout`. If no stack-layout data is recovered, the attribute is unavailable and numeric predicates do not match.

View-specific attributes:

Attribute	Notes
`@id`	Sidekick BinaryView id for this view.
`@binary_view_id`	Alias for `@id`.

Literals¶

Form	Type	Examples
`"text"` or `'text'`	String	`"main"`, `'malloc'`
`123`, `0x1a2b`, `3.14`	Number (integer or float)	`0x401000`, `7.0`
`true`, `false`	Boolean	`true`
`r"pattern"` or `r'pattern'`	Regex	`r"sub_.*"`, `r"^_Z"`
`[v1, v2, ...]`	List (for `in` operator)	`["malloc", "free"]`

Object types¶

The following type names are used in axis steps (e.g., /function, calls::symbol). Use * to match any type.

Core types¶

Node type	Binary Ninja class	Description
`view`	`BinaryView`	The analyzed binary view
`function`	`Function`	Disassembled function
`block`	`BasicBlock`	Assembly basic block
`instruction`	`AssemblyInstruction`	Native assembly instruction
`datavar`	`DataVariable`	Global or static data variable
`variable`	`Variable`	Local variable within a function
`ssa_variable`	`SSAVariableWrapper`	SSA-versioned local variable
`string`	`StringWrapper`	String literal found in the binary
`symbol`	`SymbolWrapper`	Named symbol (function, data, import, export)
`type`	`TypeWrapper`	Data type definition (struct, enum, typedef)
`segment`	`SegmentWrapper`	Loadable memory segment
`section`	`SectionWrapper`	Named section (`.text`, `.data`, etc.)
`component`	`Component`	User-defined grouping of functions and data
`tag`	`TagWrapper`	Binary Ninja tag on a function, instruction, or data location
`comment`	`Comment`	User or auto-generated comment at an address
`constant`	`Constant`	Constant value used in code
`argument`	`Argument`	Function call argument value
`platform`	`PlatformWrapper`	Target OS/ABI platform
`architecture`	`ArchitectureWrapper`	CPU architecture

IL types¶

Node type	Description
`llil`	Low-Level IL function representation
`mlil`	Medium-Level IL function representation
`hlil`	High-Level IL function representation (decompiled)
`llil_instruction`	Single LLIL instruction
`mlil_instruction`	Single MLIL instruction
`hlil_instruction`	Single HLIL instruction
`llil_block`	LLIL basic block
`mlil_block`	MLIL basic block
`hlil_block`	HLIL basic block

Type library types¶

Node type	Description
`type_library`	Collection of type definitions for a platform
`library_type`	Named type definition from a type library
`library_object`	Function or variable signature from a type library

Query-internal types¶

These types appear in query results but cannot always be used as step inputs.

Node type	Description
`address`	Specific virtual address (from `address()` or `pattern()`)
`address_range`	Address range (from `address-range()`)
`graph_path`	Path through a relationship graph (from `path()`)

Axes¶

Axes define the relationships traversed by axis steps. Every axis has a direction and an inverse.

Structural axes¶

Axis	Inverse	Description
`contains`	`contained-in`	Children of the current object. Default — can be omitted. Shorthand: `/node_type`.
`contained-in`	`contains`	Parent container of the current object. Shorthand: `^node_type`.

Call graph axes¶

Axis	Inverse	Description
`calls`	`called-by`	Functions or symbols called by the current function or instruction.
`called-by`	`calls`	Functions that call the current function or symbol.

Control flow axes¶

Axis	Inverse	Description
`next`	`prev`	Successor blocks in the control flow graph.
`prev`	`next`	Predecessor blocks in the control flow graph.
`back`	`back-from`	Back-edge targets (loop headers).
`back-from`	`back`	Blocks that have a back edge to the current block.

Dominance axes¶

These axes apply to basic blocks.

Axis	Inverse	Description
`dominates`	`dominated-by`	Blocks dominated by the current block (every path to them passes through the current block).
`dominated-by`	`dominates`	Blocks that dominate the current block.
`immediately-dominates`	`immediate-dominator`	Blocks that the current block immediately dominates.
`immediate-dominator`	`immediately-dominates`	The immediate dominator of the current block.
`post-dominates`	`post-dominated-by`	Blocks post-dominated by the current block (every path from them passes through the current block).
`post-dominated-by`	`post-dominates`	Blocks that post-dominate the current block.
`dominance-frontier`	—	Dominance frontier of the current block.

Data flow axes¶

Axis	Inverse	Description
`reads`	`read-by`	Variables or data locations read by the current function or instruction.
`read-by`	`reads`	Functions or instructions that read the current variable or data.
`writes`	`written-by`	Variables or data locations written by the current function or instruction.
`written-by`	`writes`	Functions or instructions that write to the current variable or data.
`uses`	`used-by`	Union of `reads` and `writes`.
`used-by`	`uses`	Union of `read-by` and `written-by`.

Pointer analysis axes¶

Axis	Inverse	Description
`address-taken-by`	`takes-address-of`	Code or data that takes the address of the current object.
`takes-address-of`	`address-taken-by`	Objects whose address is taken by the current code.

Type system axes¶

Axis	Inverse	Description
`type-references`	`referenced-by`	Types referenced by the current object (struct members, typedef targets, etc.).
`referenced-by`	`type-references`	Functions, blocks, or instructions that reference the current type.
`instance-of`	`instance`	Type of the current variable or function.
`instance`	`instance-of`	Variables or functions of the current type.
`inherits`	—	Base types of the current type.
`implements`	—	Placeholder — transition map is currently empty; reserved for future use.

Symbol axes¶

Axis	Inverse	Description
`has-symbol`	`symbol-of`	Symbol associated with the current function or data variable.
`symbol-of`	`has-symbol`	Object (function or data) that owns the current symbol.

IL representation axes¶

Axis	Inverse	Description
`il`	`il-of`	IL representation of the current function or instruction. Use with a node type to specify the level: `il::hlil`, `il::mlil`, `il::llil`.
`il-of`	`il`	Source function or instruction for the current IL object.

Expression tree axes (IL instructions only)¶

Axis	Inverse	Description
`child`	`parent`	Immediate sub-expressions of the current IL instruction.
`parent`	`child`	Parent expression of the current IL instruction.
`descendant`	`ancestor`	All sub-expressions recursively.
`ancestor`	`descendant`	All ancestor expressions recursively.

Built-in functions¶

All functions receive the current evaluation context and the current context item. Arguments listed below are those you provide in the query.

Functions that resolve a target by name or address accept strings, integers, Binary Ninja objects, or sets of any of these.

Lookup functions¶

These functions return sets of objects by name, address, or identifier.

Function	Signature	Returns	Description
`function`	`function(val)`	`set[function]`	Functions by name (string) or address (int or addressable object). Alias: `f`.
`f`	`f(val)`	`set[function]`	Alias for `function`.
`symbol`	`symbol(val)`	`set[symbol]`	Symbols by name or address. Alias: `s`.
`s`	`s(val)`	`set[symbol]`	Alias for `symbol`.
`datavar`	`datavar(val)`	`set[datavar]`	Data variables by name or address. Alias: `g` (mnemonic: global).
`g`	`g(val)`	`set[datavar]`	Alias for `datavar`.
`type`	`type(val)`	`set[type]`	Types by name. Alias: `t`.
`t`	`t(val)`	`set[type]`	Alias for `type`.
`tag`	`tag(name)`	`set[tag]`	All tags whose type name exactly matches the given string.
`address`	`address(val)`	`set[address]`	Address node from an int, hex string, or addressable object.
`address-range`	`address-range(start, size=256)`	`set[address_range]`	Address range starting at `start` of `size` bytes.
`section`	`section(val)`	`set[section]`	Sections that contain the given address. `val` must be an addressable object.
`bv`	`bv(filename)`	`set[view]`	Binary views whose file basename matches the given string.

function("main")               # function named "main"
f(0x401000)                    # function at address
datavar("g_config")            # global named g_config
tag("Reviewed")                # all Reviewed tags
address(0x1000)/^function      # function containing address 0x1000
address-range(0x500000, 512)   # 512-byte region starting at 0x500000
bv("libc.so.6")/function       # functions in a specific binary

Search functions¶

Function	Signature	Returns	Description
`pattern`	`pattern(bytes)`	`set[address]`	Addresses where the byte pattern occurs. `bytes` is a hex string with optional spaces (e.g., `"48 89 5c 24"`). Returns `address` nodes — use `/^function` to find containing functions.
`xref`	`xref(val)`	`set[address]`	Code and data cross-references to the given address. Returns `address` nodes.
`syscall`	`syscall(number)`	`set[hlil_instruction]`	HLIL syscall instructions (`HighLevelILSyscall`) where at least one integer parameter in `insn.params` matches `number`. Searches all open binary views.
`concept`	`concept(text, similarity=0.45, limit=20)`	`set[concept_node]`	Semantic search using the embedding index. Returns a concept node you traverse with `/node_type` to get matching objects. When the semantic index is disabled, silently returns an empty set (logs a warning; does not raise an error).

pattern("48 89 5c 24")/^function   # functions containing byte pattern
xref(0x401000)/^function           # functions that reference address
syscall(1)/^function               # functions making syscall 1 (write on Linux)
concept("string decryption")/function  # functions semantically related to string decryption

Note

concept() requires the semantic index to be enabled and built. When the semantic index is disabled, concept() returns an empty set and logs a warning rather than raising an error. See Using Semantic Indexing.

Call graph functions¶

Function	Signature	Returns	Description
`callers`	`callers(target)`	`set[function]`	Functions that call the target function or symbol. `target` can be a name, address, function, or symbol.
`callees`	`callees(target)`	`set[function \\| symbol]`	Functions and symbols called by the target function.
`callsites`	`callsites(target)`	`set[hlil_instruction \\| mlil_instruction]`	Call instructions that call the target. IL level is inferred from the target type; defaults to HLIL.
`reachable-from`	`reachable-from(roots, depth=None)`	`set[function]`	All functions reachable from `roots` in the call graph. Limited to 1000 functions.
`reaching-to`	`reaching-to(targets, depth=None)`	`set[function]`	All functions that can reach `targets` in the call graph. Limited to 1000 functions.
`path`	`path(sources, sinks, avoid=None, via="calls", depth=None)`	`set[graph_path]`	Shortest path from any source to any sink using BFS. `via` names the axis to traverse. Returns a `graph_path` object; traverse with `/contains::*` to enumerate nodes.
`path-exists`	`path-exists(sources, sinks, depth=None)`	`bool`	`true` if any path exists from a source to a sink.
`is-leaf`	`is-leaf(val=.)`	`bool`	`true` if the function has no callees (no direct calls and no indirect calls via MLIL). When called with no argument inside a predicate, tests the context item.

callers("malloc")                              # all callers of malloc
callees("parse_header")                        # what parse_header calls
callsites("memcpy")                            # HLIL call instructions to memcpy
callsites(function("malloc")/il::mlil)         # MLIL call instructions to malloc
reachable-from(f("main"), depth=5)             # call graph within 5 hops of main
reaching-to(f("dangerous_func"))               # anything that can reach dangerous_func
path(f("recv"), f("system"))                   # call path from recv to system
path(f("open"), f("exec"), avoid=f("check"))   # path avoiding the check function
/function[is-leaf(.)]                          # all leaf functions

Note

reachable-from and reaching-to cap results at 1000 functions. path uses BFS and returns the shortest path.

IL representation functions¶

Function	Signature	Returns	Description
`hlil`	`hlil(val)`	`set[hlil \\| hlil_instruction]`	High-Level IL representation. Accepts a function name, address, `Function`, `AssemblyInstruction`, or other IL instruction. BasicBlock — HLIL block mapping is not supported.
`mlil`	`mlil(val)`	`set[mlil \\| mlil_instruction \\| mlil_block]`	Medium-Level IL representation. Accepts functions, instructions, and basic blocks.
`llil`	`llil(val)`	`set[llil \\| llil_instruction \\| llil_block]`	Low-Level IL representation. Accepts functions, instructions, and basic blocks.

hlil("main")                        # HLIL function for main
mlil(/view/function)                # MLIL for all functions
/view/string/used-by::instruction/hlil(.)   # HLIL instructions using strings

Utility functions¶

Function	Signature	Returns	Description
`count`	`count(set)`	`int`	Number of items in `set`.
`first`	`first(set)`	`set`	Single-element set containing only the first item of `set`.
`entropy`	`entropy(val)`	`float`	Shannon entropy (bits) of the bytes in the object's address range. Range 0.0—8.0.
`contains-address`	`contains-address(addr)`	`bool`	`true` if the context object's address range includes `addr`.

/function[count(calls::*) > 10]         # functions with more than 10 calls
/function[0]                             # equivalent to first(/function)
/datavar[entropy(.) > 7.0]              # high-entropy globals (potential keys)
/section[contains-address(0x401234)]    # section that contains an address

Evaluation semantics¶

Absolute vs. relative paths. A query beginning with / starts from the set of all open binary views. A query without a leading / starts from the current context object (the dynamic context item). Inside predicates, . always refers to the item being tested.

Set semantics. Every step produces an ordered set. Duplicate objects are automatically deduplicated. Order is insertion order — generally the order Binary Ninja enumerates objects.

Short-circuit evaluation. and evaluates right-to-left and stops on the first false. or evaluates right-to-left and stops on the first true.

Timeout. Long-running queries time out automatically. If a timeout occurs on the final step, partial results are returned. If it occurs on an intermediate step, an empty set is returned for that step.

Multi-binary queries. When multiple binaries are open in a project, absolute queries search all open views unless narrowed with bv().

Examples¶

All functions in the binary:

/function

Function by name:

/function[@name == "main"]
# or equivalently:
function("main")

Function by address:

/function[@address == 0x401000]
# or equivalently:
f(0x401000)

Functions whose name matches a pattern:

/function[@name ~= r"parse.*"]

Functions that call malloc:

callers("malloc")
# or equivalently:
/function[calls::function[@name == "malloc"]]

Call instructions to memcpy (the instructions themselves):

callsites("memcpy")

All tags of a specific type:

tag("Reviewed")

Tags filtered by scope:

/view/tag[@scope == "function"]

High-entropy data variables (potential keys or encrypted data):

/datavar[entropy(.) > 7.0]

Leaf functions (no outgoing calls):

/function[is-leaf(.)]

Functions reachable from main within 3 hops:

reachable-from(f("main"), depth=3)

Call path from network input to a sensitive sink:

path(f("recv"), f("system"))

Enumerate nodes in a path:

path(f("recv"), f("system"))/contains::*

Functions that call malloc but not free:

callers("malloc") except callers("free")

Functions that call both malloc and free:

callers("malloc") intersect callers("free")

Functions that use a specific string:

/view/string[@value == "password"]/used-by::function

Functions by semantic concept (requires semantic index):

concept("file encryption")/function
# or to filter within a predicate:
/function[concept("encryption loop") in .]

Find byte pattern and get containing functions:

pattern("48 89 5c 24 08")/^function

Functions in a specific binary (multi-binary project):

bv("target.exe")/function

HLIL instructions that make syscall number 59 (execve on Linux):

syscall(59)/^function

Data variables in the .data section:

/view/section[@name == ".data"]/contains::datavar