Getting Started

Welcome to Binary Ninja Sidekick. This document will get you up and running and show you the main features of the Sidekick plugin. For more detailed information, check out the User's Guide.

Purchase a Sidekick Plan

Most features of the Sidekick plugin are powered by the Sidekick service, which requires an active plan to access. Click here to purchase a plan that best fits your needs.

Note

When purchasing a plan, you will need to sign in to your Sidekick account. If you do not have a Sidekick account, you will be prompted to create one, or you can create one here.

Sidekick Plugin Installation

The installation process is straightforward and takes only a few minutes. You can install the Sidekick plugin using the Plugin Manager.

Note

The plugin has been well tested using the version of Python packaged with Binary Ninja, which is currently Python 3.10. By default, Binary Ninja will install the plugin using this version of Python, except for Linux users, which defaults to the latest version available on the system. For Linux users, we recommend configuring Binary Ninja to use Python 3.10. If you decide to configure Binary Ninja to use a separate Python virtual environment, see Setting Up a Virtual Environment.

Installing the Plugin

Installing the Sidekick plugin is easy. Launch the Plugin Manager by selecting Plugins->Manage Plugins from the main menu. From the Plugin Manager search for "Sidekick" and locate the Sidekick plugin. Then click the Install button.

Note

The Sidekick plugin has several package dependencies that may take a few minutes to install. Restart Binary Ninja after installation of the plugin is complete.

Updating the Plugin

Binary Ninja 4.2.5814 and Later

If an update for the installed Sidekick plugin is available, then choose one of the following methods for updating the Sidekick plugin:

• Plugin Manager: Launch the Plugin Manager by selecting Plugins->Manage Plugins from the main menu. From the Plugin Manager search for "Sidekick" and locate the Sidekick plugin. If an update is available, then click the Update button.

• Automatic Notification (Sidekick 2.x or later): On plugin startup, Sidekick automatically checks for updates. If one is available, then Sidekick asks you if you want to install it. Click Yes. Once the update is complete, then you will need to restart Binary Ninja.

Before Binary Ninja 4.2.5814

If an update is available, then complete the following steps to update the plugin:

• Launch the Plugin Manager
• Locate the Sidekick plugin
• Click Uninstall
• Restart Binary Ninja
• Launch the Plugin Manager
• Locate the Sidekick plugin
• Click Install

Configuring the Plugin

Set the API Key

To set your Sidekick API Key:

• Open the Settings tab within Binary Ninja from the Binary Ninja->Preferences->Settings menu
• Search for sidekick.api_key
• Copy one of your API keys from your Sidekick account to the Sidekick API Key setting

Note

You can find the API keys in your Sidekick account here

Alternatively, the first time you launch the Sidekick plugin, you will be prompted to enter your Sidekick API key. If you provide an API key at this point, then it will get saved to your Settings.

Quick Start

Connecting to the Sidekick Service

The plugin will connect to the Sidekick service using the API key value in the sidekick.api_key setting. If an API key is not provided, then you will not be able to access the Sidekick service.

Note

All Sidekick features that do not rely on access to the Sidekick service are available to use for free. Refer here for more information on which features require access to the Sidekick service.

Sidekick Service Connection

You can configure the Sidekick plugin to connect to/disconnect from the Sidekick service. To switch the Sidekick plugin between the connected (online) and disconnected (offline) status, click the Sidekick status in the status bar at the bottom of the Binary Ninja window and select Connect/Disconnect.

Basic Usage

Sidekick Analysis Workbench Sidebar (Sidekick Version 2.x)

Starting in Sidekick version 2.0, the Sidekick Analysis Workbench Sidebar provides an interface for creating, modifying, and running scripts that blend both the capabilities of Python code and large language models to perform a wide variety of program analysis tasks.

Try running the existing example script named "High-Level Functions" and click Run. This particular script outputs results to an Index named "High-Level Functions", which can be viewed in the Sidekick Indexes Sidebar.

Try describing a new analysis task and pressing Enter, which will open a new script editor. Sidekick will generate an initial version of the script based on your analysis task description.

(Note: In this example, the script uses the LLMOperator class to request a large language model to perform a given task based on an initial prompt and an input Binary Ninja object (e.g. Function).)

The script editor also comes with the Sidekick Coding Assistant to provide you a chat-like interface to incrementally revise the script to do what you want.

Once you are satisfied with the script, try running it by clicking Run. Since this script outputs results to an index named "CSV Processing Functions", open the "CSV Processing Functions" index within the Sidekick Indexes Sidebar to view them.

Provide us with feedback on how things went by selecting Submit Feedback... from the hamburger menu.

Note

Feedback is only collected for non-commercial plans or commercial-plan users that have opted-in for data collection.

Sidekick Indexes Sidebar

Sidekick Version 2.x

The Sidekick Indexes Sidebar manages a set of indexes for the current binary. Each index contains a table of items in the binary (e.g., functions, instructions, strings, etc.) that are added by scripts from the Analysis Workbench. By default, when opening a binary for the first time, the Indexes Sidebar does not contain any indexes.

Try adding an index by running one of the example scripts from the Analysis Workbench (e.g. High-Level Functions). To do this, open the Analysis Workbench Sidebar, enter "High" in the search box, select the "High-Level Functions" script, and click Run. Once the script completes, open the Sidekick Indexes Sidebar, select "High-Level Functions" from the indexes drop-down combobox, and view the entries in the table.

Note

Sidekick legacy indexer scripts (from Sidekick 1.x) can been converted to scripts in the Analysis Workbench. Any legacy indexer scripts stored in a user's Binary Ninja Database (BNDB) or User Directory can be converted by selecting the appropriate Import Indexer Scripts action from the Sidekick Plugin main menu.

Sidekick Version 1.x

The Sidekick Indexes Sidebar manages a set of indexes for the current binary. Each index contains a table of items in the binary (e.g., functions, instructions, strings, etc.) that are generated by running an indexer script related to a specific topic. Some indexer scripts for common items are included with Sidekick, or you can create your own.

By default, the built-in index of High-Level Functions is loaded in the set the indexes for the current binary. This index generates a list of functions with a high out-degree.

Try adding other indexes to the set of indexes for the current binary by clicking on the New Index button

Search from existing indexes by describing the topic you are interested in

Accept the selected index in order to add it to the index

View and navigate to index entries

If an index you are interested in does not exist, then create your own by providing a description of what you are looking for and allow Sidekick to generate the indexer script for you

Sidekick Suggestions Sidebar

Once you have selected a function to investigate, use the Sidekick Suggestions sidebar to get suggestions for improving the clarity of the current function.

Request Sidekick to make suggestions for you, or choose specific suggestions types yourself

Review suggestions and accept the ones you want to apply

Sit back and watch Sidekick apply them

Code Insight Map View

The Code Insight Map View is a call-graph oriented view centered on a selected function and includes items only from the index topics. This view allows you to quickly visualize the calling relationships between functions and their index topics to aid program comprehension.

Select the Code Insight Map view from the View drop-down menu

Enable/disable displayed topics

Adjust Call Depth sliders to expand/collapse the call graph context of the given function

Sidekick Assistant Sidebar

The Sidekick Assistant Sidebar provides a chat interface to interact with the Sidekick Assistant for a given scope of functions. These conversations are stored for easy reference.

Ask a question about the current function

Navigate to another function and ask a question about that function

Add a private note to the page that does not get sent to the Sidekick Assistant

Sidekick Investigations Sidebar

The Sidekick Investigations Sidebar provides an interface for launching topic-specific investigations and documenting those findings for a given function. Currently, Sidekick offers a set of pre-defined investigations such as manpage-like information, instances of use-after-free, SQL injections, NULL pointer dereferences, and more.

Launch an investigation

Edit findings

For a complete description of Sidekick's features, see the User's Guide.

Documentation View

Note

This feature will be deprecated in a future release.

The Documentation View provides a description of the current function very much in the style of a traditional man page. Sidekick will automatically generate documentation based on the function code; however, you are able to edit and/or extend this content as you wish.

Select the Documentation View from the View drop-down menu

Generate documentation