{"componentChunkName":"component---src-templates-post-template-js","path":"/binja-python-api-en","result":{"data":{"markdownRemark":{"id":"8267348e-e548-5761-a193-1fd74821151f","html":"
\n

This page has been machine-translated from the original page.

\n
\n

In my previous article on self-restoring binary deobfuscation with Unicorn and Capstone, I wondered whether the same operations could be performed with static analysis alone — without emulating execution with Unicorn and Capstone.

\n

For this kind of implementation I had previously used Ghidra Script, but since I wasn’t making much use of the paid (Personal) version of Binary Ninja I own, I decided to use this as a learning opportunity and try implementing it with the Binary Ninja Python API.

\n\n

Table of Contents

\n\n

Getting Started with the Binary Ninja Python API

\n

Installation

\n

When installing Binary Ninja for the first time, run binaryninja/scripts/linux-setup.sh in the installation directory.

\n

This creates a desktop shortcut for Binary Ninja and registers its PATH.

\n

\n \n \n \n \n \n \n \n \n

\n

Using the Python API from the Binary Ninja GUI

\n

The Binary Ninja Python API requires no complex setup and can be used immediately.

\n

However, the Personal license I use does not currently support “headless processing,” so whenever I use the Python API I must do so through the Binary Ninja GUI.

\n
\n

The “headless processing” in the Commercial and Ultimate editions refers to the ability to run plugins without the GUI (for example “import binaryninja” from within a console or stand-alone python plugin), but both versions support the same full API. The Non-Commercial edition supports accessing the API only through plugins load

\n
\n

Reference: Binary Ninja - Purchase

\n

You can run scripts in Binary Ninja’s Python interpreter within the GUI to see results.

\n

\n \n \n \n \n \n \n \n \n

\n

You are not limited to just the interpreter — you can also write a Python script file and run it from the GUI to automate analysis.

\n

Various Operations with the Binary Ninja API

\n

Sample 1

\n

I created the following sample script.

\n
def main():\n\n    # Load current view\n    bv = current_view\n\n    # Get functions\n    for func in bv.functions:\n        if func.name == \"main\":\n            main_func_startaddr = func.start\n        print(f\"FUNC_NAME: {func.name},\\t OFFSET: {hex(func.start)}\")\n\n\n    # Get disassemble code\n    func_addr = 0x43e0\n    instruction = bv.get_disassembly(func_addr)\n    print(f\"ADDRESS: {hex(func_addr)},\\t CODE: {instruction}\")\n\n\n    # Get disassemble function code(until return)\n    start_addr = main_func_startaddr\n    end_addr = start_addr + 0x4000\n    current_addr = start_addr\n    instruction = \"\"\n\n    while (current_addr < end_addr) and (instruction != \"retn\"):\n        instruction = bv.get_disassembly(current_addr)\n        instruction_length = bv.get_instruction_length(current_addr)\n        current_addr += bv.get_instruction_length(current_addr)\n        if instruction_length > 0:\n            print(f\"0x{current_addr:x}: {instruction}\")   \n        else:\n            break\n\n\n    # Convert to NOP\n\n    ## Stat undo actions\n    undo_actions_state = bv.begin_undo_actions()\n\n    target_address = 0x43e0\n    if bv.convert_to_nop(target_address):\n        print(f\"Converted 0x{target_address:x} to NOP.\")\n    else:\n        print(f\"Failed converted 0x{target_address:x} to NOP.\")\n\n    ## Commit actions\n    bv.commit_undo_actions(undo_actions_state)\n\n\n    # Save file\n    bv.file.save()\n\n\n    return\n\nif __name__ == \"__main__\":\n    import os\n    import sys\n    sys.stdout = open(f\"{os.path.dirname(os.path.realpath(__file__))}/stdout.log\", \"w\")\n    main()\n    sys.stdout = sys.__stdout__
\n

Running the above script lets you access information such as functions and disassembly results as shown below.

\n

\n \n \n \n \n \n \n \n \n

\n

Loading BinaryView and Listing Functions

\n

In Binary Ninja, the BinaryView class serves as the interface for querying binary data.

\n

Therefore, operations such as reading, writing, or modifying data after analyzing a file are generally performed through this BinaryView.

\n

The items that can be retrieved and manipulated through BinaryView are documented here:

\n

Reference: binaryview module — Binary Ninja API Documentation v4.2

\n

When using the Python API from the GUI, you can access the currently viewed BinaryView using the magic variable current_view.

\n

Reference: User Guide - Binary Ninja User Documentation

\n

The following code iterates over functions from the retrieved BinaryView to enumerate all functions in the binary.

\n
# Load current view\nbv = current_view\n\n# Get functions\nfor func in bv.functions:\n    if func.name == \"main\":\n        main_func_startaddr = func.start\n    print(f\"FUNC_NAME: {func.name},\\t OFFSET: {hex(func.start)}\")
\n

Accessing Disassembly Results

\n

The following code retrieves the disassembly result for a specific address.

\n

In this example, only one instruction starting from 0x43e0 is retrieved.

\n
# Get disassemble code\nfunc_addr = 0x43e0\ninstruction = bv.get_disassembly(func_addr)\nprint(f\"ADDRESS: {hex(func_addr)},\\t CODE: {instruction}\")
\n

To retrieve the disassembly of an entire function starting at 0x43e0, you can use a script like the following:

\n
# Get disassemble function code(until return)\nstart_addr = main_func_startaddr\nend_addr = start_addr + 0x4000\ncurrent_addr = start_addr\ninstruction = \"\"\n\nwhile (current_addr < end_addr) and (instruction != \"retn\"):\n    instruction = bv.get_disassembly(current_addr)\n    instruction_length = bv.get_instruction_length(current_addr)\n    current_addr += bv.get_instruction_length(current_addr)\n    if instruction_length > 0:\n        print(f\"0x{current_addr:x}: {instruction}\")   \n    else:\n        break
\n

Replacing All Instances of a Specific Instruction with NOP

\n

The following code performs Convert To NOP (also available from the GUI) via the Python API.

\n

When modifying data through the API, first call begin_undo_actions to declare the start of an undoable operation on the target BinaryView.

\n

Next, use bv.convert_to_nop(addr) to replace all instructions at the specified address with NOPs, then commit the operation with bv.commit_undo_actions(undo_actions_state).

\n

bv.file.save() saves the modified BinaryView as a file.

\n
# Convert to NOP\n\n## Stat undo actions\nundo_actions_state = bv.begin_undo_actions()\n\ntarget_address = 0x43e0\nif bv.convert_to_nop(target_address):\n    print(f\"Converted 0x{target_address:x} to NOP.\")\nelse:\n    print(f\"Failed converted 0x{target_address:x} to NOP.\")\n\n## Commit actions\nbv.commit_undo_actions(undo_actions_state)\n\n# Save file\nbv.file.save()
\n

Replacing Specific Instructions

\n

Converting to NOP is straightforward, but replacing instructions with an arbitrary byte value is also relatively easy.

\n

For example, the following code reads the byte value at a specific address and replaces it with a different value using write.

\n
# Replace the bytes at a specific execution address with an XOR'd version\ndata = bv.read(target_addr, size)\nbv.write(\n    target_addr,\n    (int.from_bytes(data, byteorder=\"little\") ^ key_value).to_bytes(size, byteorder=\"little\")\n)
\n

Deobfuscating a Self-Restoring Binary with Binary Ninja

\n

Using the Binary Ninja Python API, I attempted to deobfuscate the self-restoring binary covered in Self-Restoring Binary Deobfuscation with Unicorn and Capstone.

\n

The binary’s implementation and the deobfuscation strategy are described in that article, so I omit them here.

\n

The final script I created is as follows.

\n

Loading this script in the Binary Ninja GUI was able to deobfuscate the execution code.

\n
# Load current view\nbv = current_view\n\ncall_addrs = [0x43e0]\ndeobfuscated_addrs = []\npushfq_flag = False\ncurrent_call_addr = 0\nprevious_call_addr = 0\n\n\ndef deobfuscate(current_call_addr):\n    global bv\n    global call_addrs\n    global pushfq_flag\n    global deobfuscated_addrs\n    hex_pattern = r\"0x[0-9a-fA-F]+\"\n    word_pattern = r\".word|byte\"\n\n    undo_actions_state = bv.begin_undo_actions()\n\n    # Get disassemble function code(until return)\n    start_addr = current_call_addr\n    end_addr = start_addr + 0x4000\n    current_addr = start_addr\n    instruction = \"\"\n\n    while (current_addr < end_addr):\n        instruction = bv.get_disassembly(current_addr)\n        instruction_length = bv.get_instruction_length(current_addr)\n\n        if (\"xor\" in instruction) and (pushfq_flag == True):\n            # \"xor     dword [rel 0x43ec], 0xaeee8e1\"\n            hex_numbers = re.findall(hex_pattern, instruction)\n            word_type = re.findall(word_pattern, instruction)[0].replace(\" \", \"\")\n            target_addr = int(hex_numbers[0], 16)\n            key_value = int(hex_numbers[1], 16)\n\n            if target_addr > current_addr:     \n                size = 0\n                if word_type == \"byte\":\n                    size = 1\n                elif word_type == \"word\":\n                    size = 2\n                elif word_type == \"dword\":\n                    size = 4      \n                elif word_type == \"qword\":\n                    size = 8\n                \n                bv.convert_to_nop(current_addr)\n                data = bv.read(target_addr, size)\n                bv.write(\n                    target_addr,\n                    (int.from_bytes(data, byteorder=\"little\") ^ key_value).to_bytes(size, byteorder=\"little\")\n                )\n\n            else:\n                bv.convert_to_nop(current_addr)\n\n            \n        elif \"pushfq\" in instruction:\n            bv.convert_to_nop(current_addr)\n            pushfq_flag = True\n\n        elif \"popfq\" in instruction:\n            bv.convert_to_nop(current_addr)\n            pushfq_flag = False\n\n        elif \"retn\" in instruction:\n            bv.commit_undo_actions(undo_actions_state)\n            break\n        \n        else:\n            if pushfq_flag:\n                bv.convert_to_nop(current_addr)\n            else:\n                if \"call\" in instruction:\n                    call_addr = int(re.findall(hex_pattern, instruction)[0], 16)\n                    if call_addr >= 0x1260:\n                        call_addrs.append(call_addr)\n        \n        bv.commit_undo_actions(undo_actions_state)\n        current_addr += bv.get_instruction_length(current_addr)\n    \n    return\n\n\ndef main():\n    global bv\n    global call_addrs\n    global deobfuscated_addrs\n\n    while len(call_addrs) > 0:\n        current_call_addr = call_addrs.pop()\n        if current_call_addr not in deobfuscated_addrs:\n            deobfuscate(current_call_addr)\n            deobfuscated_addrs.append(current_call_addr)\n\n    current_func = bv.get_function_at(current_call_addr)\n    current_func.reanalyze()\n    bv.update_analysis_and_wait()\n\n    return\n\n\nif __name__ == \"__main__\":\n    import os\n    import sys\n    sys.stdout = open(f\"{os.path.dirname(os.path.realpath(__file__))}/stdout.log\", \"w\")\n    main()\n    sys.stdout = sys.__stdout__
\n

The code restored with this script correctly restored the execution code needed to obtain the flag, as shown below.

\n

The program’s behavior at runtime was also equivalent to the pre-deobfuscation version.

\n

\n \n \n \n \n \n \n \n \n

\n

Below I summarize a few key points from writing this script.

\n

How to Retrieve Disassembly Results

\n

When creating this script, I used bv.get_disassembly(current_addr), which returns the disassembly result as a string.

\n

Therefore, regular expressions were used to extract instructions and addresses.

\n

Other methods are also available when retrieving disassembly results with the Binary Ninja API, such as disassembly_text, which returns a Generator containing the disassembly result.

\n

Reference: binaryview module — Binary Ninja API Documentation v4.2

\n

Considering the Timing of reanalyze and updateanalysisand_wait

\n

current_func.reanalyze() triggers re-analysis of a specific function.

\n

bv.update_analysis_and_wait() waits until the analysis results are fully reflected.

\n
current_func = bv.get_function_at(current_call_addr)\ncurrent_func.reanalyze()\nbv.update_analysis_and_wait()
\n

Initially I was triggering bv.update_analysis_and_wait() each time a specific instruction was changed, but that caused the script to run indefinitely. I moved it to a location that is called only a few times across the whole operation.

\n

In contrast, bv.commit_undo_actions(undo_actions_state) is called quite frequently, but that does not seem to have a significant impact on execution time.

\n

Summary

\n

I finally got to use the Binary Ninja Python API that I had been meaning to try for a while.

\n

It feels somewhat easier to use than Ghidra Script did when I first tried it. (This may be payment bias, though…)

","fields":{"slug":"/binja-python-api-en","tagSlugs":["/tag/reversing-en/","/tag/binary-ninja-en/","/tag/english/"]},"frontmatter":{"date":"2025-03-31","description":"Automating binary analysis and manipulation with the Binary Ninja Python API.","tags":["Reversing (en)","Binary Ninja (en)","English"],"title":"Automating Binary Analysis and Manipulation with the Binary Ninja Python API","socialImage":{"publicURL":"/static/94e664185535306f599972be80137494/binja-python-api.png"}}}},"pageContext":{"slug":"/binja-python-api-en"}},"staticQueryHashes":["251939775","401334301","825871152"]}