Editing Binaries with Suggestions

Sidekick provides a rich set of features to edit binaries by generating suggestions focused on improving the understanding and readability of decompiled code.

The Decompilation Suggestions sidebar is the primary interface for requesting, reviewing and applying suggestions. The types of suggestions include:

• Recover and Define Structure Types
• Rename Structure Types and Fields
• Rename Variables
• Rename Function
• Comment Function
• Rename Function Callees
• Simplify Symbols

As Sidekick generates suggestions, you can review them and then accept or reject them.

The following sections detail the actions that you can take within the Decompilation Suggestions sidebar. To get the most use out of the Suggestions features, read Tips on Using Suggestions

Requesting Suggestions

There are two primary methods for requesting suggestions: general and specific. Suggestions returned by Sidekick are added to the suggestions tree and organized by function within the Decompilation Suggestions sidebar. Suggestions will accumulate within the tree until you apply, reject, or clear them.

General Suggestions

When requesting general suggestions, Sidekick determines what suggestions to make based on the current state of the function. Sidekick makes suggestions in stages according to the following order of categories:

Category	Description	Suggestion Types
Code Transformation	Impacts IL generation	Recover and Define Structure Types
Contextual Identifiers	Adds context to the current function	Rename Function Callees, Simplify Symbols
Structural Identifiers	Impacts structure names	Rename Structure Types and Fields
Local Identifiers	Impacts names of elements local to the current function	Rename Variables, Rename Data Variables, Rename Function
Metadata	Adds information about the current function	Comment Function

As you iteratively request general suggestions, Sidekick generates other suggestion types during its progression through each suggestion stage.

To request general suggestions for the current function, perform any of the following actions: - Click the Make suggestions for: <current_function> button - Select Make suggestions for: <current_function> from the hamburger menu

Specific Suggestions

You can also request Sidekick to generate suggestions of a specific type by selecting from the following items in the hamburger menu:

• Suggest Function Name
• Suggest Function Comment
• Suggest Variable Names
• Suggest Struct/Field Names

These actions are also available from the Plugins->Sidekick menu.

(Note: Structure and field name suggestions will not be generated if Structure Recovery has not been performed first.)

Applying Suggestions

Suggestions returned by Sidekick in the suggestions tree can be applied in the following ways:

• To apply all suggestions in the tree (for all functions), perform any of the following actions:
  • Select Apply All from the hamburger menu in the Sidekick Suggestion sidebar
  • Select Apply All Suggestions from the Plugins->Sidekick menu
• To apply a selection of suggestions, select each suggestion you want to apply (using Cntrl + Click or Shift + Click depending on the desired selection scope) and perform any of the following actions:
  • Click on the Accept selected suggestions button
  • Right-click and select Apply
• To apply all suggestions for the current function, perform any of the following actions:
  • Select Apply and Suggest for: <current_function> from the hamburger menu in the Sidekick Suggestions sidebar. (Note: If auto-suggestions are disabled, then Sidekick will not make suggestions after applying suggestions for the current function.)
  • Select Apply Suggestions for Current Function from the Plugins->Sidekick menu
  • Press F12

Note

Applying a suggestion submits feedback to up-vote the suggestion. See Feedback for Suggestions for more information.

Clearing Suggestions

Suggestions returned by Sidekick in the suggestions tree can be cleared in the following ways:

• To clear all suggestions in the tree (for all functions), perform any of the following actions:
  • Select Clear All from the hamburger menu in the Sidekick Suggestions sidebar
  • Select Clear All Suggestions from the Plugins->Sidekick menu
• To clear a selection of suggestions, select each suggestion you want to clear (using Cntrl + Click or Shift + Click depending on the desired selection scope), right-click, and select Clear
• To clear all suggestions for the current function, select Clear and Suggest for: <current_function> from the hamburger menu. (Note: If auto-suggestions are disabled, then Sidekick will not make suggestions after clearing suggestions for the current function.)

Rejecting Suggestions

Suggestions returned by Sidekick in the suggestions tree can be rejected as follows:

• To reject a selection of suggestions, select each suggestion you want to reject (using Cntrl + Click or Shift + Click depending on the desired selection scope), right-click, and select Reject

Note

Rejecting a suggestion submits feedback to down-vote the suggestion. See Feedback for Suggestions for more information.

Auto-Suggestions

Sidekick supports the ability to generate suggestions automatically when as you dwell at a given location for a period of time (configurable in Settings). When enabled, simply click on a location in a function, stay there for the configured time, and then Sidekick starts to generate suggestions for that function. After you apply all of the suggestions for the current function, then Sidekick generates another set of suggestions based on the updated function. This iterative process repeats until no more suggestions can be made.

The sidekick.suggestions.auto_suggest_dwell_time setting controls the dwell time (in seonds) for auto-suggestions. Set to 0 to disable auto-suggestions.

Saving Suggestions

When saving a BNDB, all suggestions currently in the suggestions tree are stored in the BNDB. When re-opening a saved BNDB, suggestions stored in the BNDB are reloaded in the suggetions tree.

Feedback for Suggestions

For the purpose of product improvement, Sidekick implements a simple up-/down-vote mechanism for collecting feedback on the quality of its suggestions. The following feedback is submitted for each suggestion action:

Suggestion Action	Feedback Submitted
Apply	Up-Vote
Reject	Down-Vote
Clear	None

Note

Feedback is only collected for non-commercial plans or for commercial plans that you have opted in to allow collection. You can log in to your Sidekick account and update your commercial plan to allow/disallow collection at any time.

Tips on Using Suggestions

The following lists several ways to use Suggestions more easily and effectively:

1. Tired of all the clicking to just accept what Sidekick has suggested for the current function? Then simply press F12.
2. Speaking of F12, when combined with the auto-suggestion feature, the sequence of visiting a function, automatically receiving suggestions, and quickly applying them via F12 is an effective workflow to quickly reverse engineer a function.
3. Sidekick tends to suggest better names for things in the function after all of the callees in the function have been named. Sometimes Sidekick will make this suggestion for you, but if not, then just select Name Callee Functions from the Plugins->Sidekick menu. (Note: This operation can take a while to complete based on the number of unnamed callee functions.)
4. Not getting a specific type of suggestion from Sidekick? Manually request the specific suggestion type from the hamburger menu in the Suggestions sidebar.
5. If you clear a suggestion, then Sidekick will no longer make a suggestion of that type automatically (using any of the Make Suggestions for: <current_function> actions). This is one reason why you may not be getting a specific type of suggestion from Sidekick. You must manually request it for that function after that point.
6. Not getting suggestions for structure and field names? Make sure that you've run structure recovery first by selecting Recover Structures from the Plugins->Sidekick menu.

Recovering Structures

One type of suggestion that Sidekick makes is to recover and define structure types. This improves decompilation by replacing pointer offset dereferences with their recovered structure types.

How it works

Sidekick first creates a component for the current function if one does not already exist, which is a necessary pre-requisite for structure recovery. Next, Sidekick performs an interprocedural points-to analysis within the component to identify the data structures that are used by the functions in the component. It then uses the data structures to create structure definitions for the functions in the component.

Sidekick tries to infer more refined types for the fields. For example, if a field takes on a small number of integer values (e.g., 0, 1, 2, 3), it will be inferred as an enum. Or, if the only values are 0 and 1, it will be inferred as a boolean.

By default, the structs and fields are named using a simple prefix scheme (i.e., struct_ and field_). You can choose to prefix the structs and fields with the component name to make them more meaningful. Even better, you can ask Sidekick to suggest more meaningful names using the Structure and Field Naming feature.

How to use it

Sidekick automatically suggests recovering structures during the first stage of suggestions when you make a general request for suggestions in the Decompilation Suggestions sidebar. To apply the suggestion when present, choose any of the applying suggestion methods described in the Applying Suggestions section.

Additionally, you can manuaally request Sidekick to recover structures for the current function by selecting Recover Structures from the Plugins->Sidekick menu.

The structure recovery operation is generally fast, but can take a few moments to complete, depending on the size of the component.

When it's done, Binary Ninja's IL is updated with new structs and fields, and the new recovered structure types can be viewed in the Types sidebar.

Common questions

What about structures that are used by multiple components?

Sidekick creates structures for each component independently. If a structure is used by multiple components, it may be created multiple times under a different name. This is a limitation of the current implementation, which we plan to address it in the future. However, if you use the Structure Recovery feature one component at a time, Binary Ninja's type propagation should prevent the creation of duplicate structures most of the time.

Creating Components

Sidekick creates components by identifying groups of related functions (think compilation units) and arranges them hierarchically, making it easier to understand the binary program's structure.

How it works

Sidekick uses features derived from Binary Ninja's static analysis and consolidates them into a single graph that captures the relationships between functions. The graph is uploaded to the Sidekick service where it is partitioned into components, arranged hierarchically to form a tree. The tree is then displayed in the Symbols sidebar.

Sidekick attempts to name the components based on function names and other symbols it finds. If these features are not present in the binary, the components will be named based on their location in the binary.

How to use it

Sidekick automatically creates components for the current function when you request suggestions or recover structures. However, you can also manually request Sidekick to create a component by selecting Create Component for Current Function from the Plugins->Sidekick menu. When the operation is complete, any created components are displayed in the Symbols sidebar as Folders.

If you want to manually create components for a set of functions, you can do so using Binary Ninja's Folders features from within the Symbols sidebar. Alternatively, you can create components for a set of functions displayed within a Code Insight Map by following the instructions in the Code Insight Map documentation.

How to customize it

The component creation algorithm has several parameters that you can adjust to customize its behavior. To adjust these parameters, go to the Settings tab and locate the Sidekick.components section. The following options are available:

Option	Description
Minimum Component Size	The minimum number of functions that a component must contain. The default is 2.
Maximum Component Size	The maximum number of functions that a component must contain. The default is 50.
Component Depth	The maximum depth of the component tree. The default is 3.
Maximum Tier Width	The maximum number of components in a tier. The default is 7.
Maximum Adjacent Distance	The maximum distance between adjacent functions in a leaf component. The default is 1.

Note

The default values for the component clustering options are based on our experience with the most common types of binaries. You can experiment with other values, but the results may vary depending on your binary.

You can customize the naming convention used for components using the Binary Ninja settings sidekick.components.naming_convention. The following naming convention options are available:

Value	Description
any	Use whatever names are generated by the model.
snake	Formats the variable name as snake_case.
camel	Formats the variable name as camelCase.
pascal	Formats the variable name as PascalCase.

How to interpret it

The component creation process depends on the features that are available in the binary. Some binaries will have more indicators than others. In general, the components will correspond to logical units of the program and roughly correspond to its compilation units, libraries, or subsystems.

Renaming Structures and Fields

When Sidekick encounters code that accesses structures and their fields, it may suggest renaming them to improve the clarity of the decompiled code. This is particularly useful when the original names are generic or not descriptive enough.

How to Use It

Sidekick automatically suggests renaming structures and fields during the third stage of suggestions when you make a general request for suggestions in the Decompilation Suggestions sidebar. This only occurs when structures and fields with default names (e.g., struct_0, field_0) are present in the current function. To manually request suggestions for renaming structures and fields, select Suggest Struct/Field Names from the hamburger menu in the Decompilation Suggestions sidebar or select Suggest->Structure and Fields Names from the Plugins->Sidekick menu.

To apply the suggestion when present, choose any of the applying suggestion methods described in the Applying Suggestions section.

How to Customize It

You can customize the naming convention used for structures and fields using the Binary Ninja settings sidekick.suggestions.struct_naming_convention and sidekick.suggestions.field_naming_convention, respectively. The following naming convention options are available:

Value	Description
any	Use whatever names are generated by the model.
snake	Formats the variable name as snake_case.
camel	Formats the variable name as camelCase.
pascal	Formats the variable name as PascalCase.

Renaming Variables

Sidekick suggests variable names for parameters and local variables in functions making it easier to understand the purpose of the variables in the function.

How it works

The variable naming feature works on a per-function basis. It submits a representation of the function to the Sidekick service, which uses a language model to suggest names for the variables.

How to use it

Sidekick automatically suggests renaming variables during the fourth stage of suggestions when you make a general request for suggestions in the Decompilation Suggestions sidebar. To manually request suggestions for renaming variables, select Suggest Variable Names from the hamburger menu in the Decompilation Suggestions sidebar or select Suggest->Variable Names from the Plugins->Sidekick menu.

To apply the suggestion when present, choose any of the applying suggestion methods described in the Applying Suggestions section.

Alternatively, you can click on a variable name suggestion to navigate to the variable definition. You can then rename that variable directly using the Binary Ninja UI. At that point, the suggestion items that refer to that variable will be removed from the list. The remaining suggestions can be reviewed, accepted, or rejected.

How to Customize It

You can customize the naming convention used for variables using the Binary Ninja settings sidekick.suggestions.variable_naming_convention. The following naming convention options are available:

Value	Description
any	Use whatever names are generated by the model.
snake	Formats the variable name as snake_case.
camel	Formats the variable name as camelCase.
pascal	Formats the variable name as PascalCase.

Renaming Functions

Sidekick suggests names for functions to help you quickly understand the purpose of the function.

How it works

Sidekick submits a representation of the function to the Sidekick service, which uses a language model to suggest a name for the function.

How to use it

Sidekick automatically suggests function names during the fourth stage of suggestions when you make a general request for suggestions in the Decompilation Suggestions sidebar. To manually request suggestions for renaming the function, select Suggest Function Name from the hamburger menu in the Decompilation Suggestions sidebar or select Suggest->Function Name from the Plugins->Sidekick menu.

To apply the suggestion when present, choose any of the applying suggestion methods described in the Applying Suggestions section.

Alternatively, you can click on the function name suggestion to navigate to the function definition. You can then rename the function directly using the Binary Ninja UI. At that point, the suggestion that refers to that function name will be removed from the list.

How to Customize It

You can customize the naming convention used for functions using the Binary Ninja settings sidekick.suggestions.function_naming_convention. The following naming convention options are available:

Value	Description
any	Use whatever names are generated by the model.
snake	Formats the variable name as snake_case.
camel	Formats the variable name as camelCase.
pascal	Formats the variable name as PascalCase.

Commenting Functions

Sidekick suggests function comments that summarize the behavior of the entire function.

How it works

Sidekick submits a representation of the function to the Sidekick service, which uses a language model to generate a summary of the function.

How to use it

Sidekick automatically suggests function comments during the fifth stage of suggestions when you make a general request for suggestions in the Decompilation Suggestions sidebar. To manually request suggestions for commenting the function, select Suggest Function Comment from the hamburger menu in the Decompilation Suggestions sidebar or select Suggest->Function Comment from the Plugins->Sidekick menu.

To apply the suggestion when present, choose any of the applying suggestion methods described in the Applying Suggestions section.

Alternatively, you can request Sidekick to automatically generate and insert a function comment by selecting Add Function Comment from the Plugins -> Sidekick main menu.

Commenting Code Selections

Sidekick can generate and insert comments that summarize or explain a highlighted selection of code. (Currently only High Level IL and Pseudo C are supported.)

To use this feature, highlight a section of code and select Add Comment for Selected Lines from the Plugins -> Sidekick menu (or alternatively press Shift + C).

Comments are applied inline above the code selection.

Renaming Function Callees

Sidekick suggests renaming function callees to improve the quality of other names it generates for the current function. Names for callees are applied recursively in order to maximize the quality of this type of information.

How it works

Sidekick generates names for all unnamed function callees recursively. All unnamed callees at the deepest layer of the call tree for the current function are named first before moving on to those at the next layer up in the call tree. The naming process continues until the all unnamed callees are named (or until the limit is reached for a single operation).

How to use it

Sidekick automatically suggests renaming function callees during the fifth stage of suggestions when you make a general request for suggestions in the Decompilation Suggestions sidebar. To apply the suggestion when present, choose any of the applying suggestion methods described in the Applying Suggestions section.

Alternatively, you can manually request Sidekick to rename function callees for the current function by selecting Name Callee Functions from the Plugins->Sidekick menu. This operation may take a while depending on the number of unnamed callees in the call tree of the current function. While the operation is in progress, status is displayed in the status bar on the lower left corner. The operation can be canceled by clicking on the X on the status bar. Any function names applied prior to canceling are kept. This also allows you to apply names in batches if you want.