Skip to content

Commit 328ad3b

Browse files
authored
Add file and database loading examples to Python cookbook (#7508)
1 parent d33bfa3 commit 328ad3b

File tree

1 file changed

+59
-0
lines changed

1 file changed

+59
-0
lines changed

docs/dev/cookbook.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,65 @@ One of the best ways to learn a complicated API is to simply find the right exam
1111

1212
# Recipes
1313

14+
## Loading Files & Databases
15+
16+
When scripting from the Binary Ninja UI, the `bv` magic variable is already defined and available in the Python console or scripts loaded via `File -> Run Script...`. You can directly use `bv` to access the currently open binary.
17+
18+
If you have Binary Ninja Commercial and above (Commercial, Ultimate, and Enterprise), you can also use Binary Ninja headlessly as a library. This allows you to write standalone scripts that load and analyze files without the UI.
19+
20+
!!! note "Headless Usage Requirement"
21+
Using Binary Ninja as a library (headlessly) is only available in Binary Ninja Commercial and above. This feature is not available in the Personal edition.
22+
23+
### Basic file loading
24+
25+
```python
26+
from binaryninja import load
27+
28+
# Using context manager (recommended)
29+
with load('/bin/ls') as bv:
30+
if bv is not None:
31+
print(f"{bv.arch.name}: {hex(bv.entry_point)}")
32+
33+
# Without context manager - must close manually
34+
bv = load('/bin/ls')
35+
if bv is not None:
36+
print(f"Loaded {bv.file.filename}")
37+
bv.file.close() # Important: prevents memory leaks
38+
```
39+
40+
### Loading with options
41+
42+
```python
43+
from binaryninja import load
44+
45+
bv = load('/bin/ls', options={
46+
'loader.imageBase': 0xfffffff0000,
47+
'loader.macho.processFunctionStarts': False,
48+
'analysis.mode': 'basic'
49+
})
50+
```
51+
52+
### Loading a database
53+
54+
```python
55+
from binaryninja import load
56+
57+
# .bndb files use the same API
58+
bv = load('/path/to/analysis.bndb')
59+
```
60+
61+
### Controlling analysis
62+
63+
```python
64+
from binaryninja import load
65+
66+
# Load without running analysis
67+
bv = load('/bin/ls', update_analysis=False)
68+
if bv is not None:
69+
bv.update_analysis_and_wait() # Run analysis manually
70+
bv.file.close()
71+
```
72+
1473
## Navigation / Search
1574

1675
### Getting all functions in a binary

0 commit comments

Comments
 (0)