Analyzing Binaries with Tasks¶

What are Tasks¶

Tasks are a way to break down the analysis of a binary into manageable pieces. They allow you to focus on specific aspects of the binary or a particular objective, such as identifying functions, analyzing data structures, or searching for specific patterns. Tasks can be created, delegated, and managed within the Tasks sidebar, enabling a collaborative approach to binary analysis.

As tasks are created, they are added to the Tasks sidebar and placed in one of three tabs depending on their state:

Pending: Tasks that have been created but not yet started. These tasks are waiting for you to edit, approve, or decline them.
Completed: Tasks that have finished running, but results not applied. These tasks are waiting for you to review the results and either accept or reject them.
Archived: Tasks that have been completed with results applied. These tasks are stored for reference and can be reviewed later.

Instructions¶

For each task, Sidekick generates a plan detailing how to accomplish the given task. This plan is captured in the Instructions tab of the Task, which also includes the other relevant information about the task, such as:

Suggested Tools: A list of tools that Sidekick suggests to use for the task. These tools can be used to perform specific actions or analyses related to the task.
Analysis Scope: The scope of the analysis, which defines the boundaries of the task and what aspects of the binary it will cover. This helps to focus the analysis on specific areas of interest.
User Request: For tasks that you initiate, this section contains the original description of the task you entered.
Justification: A brief explanation of why the task is being performed, which helps to clarify the purpose and importance of the task. This can include details about the binary being analyzed, the specific objectives of the task, and any relevant background information.

Editing Instructions¶

For tasks in the Pending state, you can edit the text of the instruction details. To do this, click the Edit button in the Task, apply your changes, and then click the Save button.

Results¶

Each task that has completed its analysis contains a viewable Results tab that displays the proposed results of the task, which can include sections for findings to record in the Notebook, items to record in Indexes, edits to apply to the binary, or other relevant information.

Log¶

Each task that has completed its analysis contains a viewable Log tab that provides a detailed history of the actions that Sidekick took during the task. This log includes information about the steps performed, the results obtained, and any issues encountered during the analysis, which is useful for reviewing the analysis process and troubleshooting any problems that arise. The Log is displayed as a Chat conversation with an initial prompt or message containing the Task instructions.

You can perform the following actions in the Log:

Search the Log: Enter a search term in the Search Log
View and Manage Tools: Select Tools... from the hamburger menu of the Log tab
View Raw Conversation: Select View Raw Page from the hamburger menu of the Log tab

Approving/Declining Tasks¶

For tasks in the Pending state, you can approve or decline them.

To approve a task, either click the Approve button or right-click the task and select Approve Task. Sidekick will execute the task according to the instructions provided. Its state will change to Executing... while the task is being processed. Once the task is complete, it will move to either the Review tab or the Archive tab, depending on the task mode and whether the results were applied.

To decline a task, either click the Decline button or right-click the task and select Decline Task. This will move the task to the Archive tab, marking it for reconsideration where it can be reviewed later if needed.

Accepting/Rejecting Results¶

For tasks in the Review state, you can accept or reject the results.

To accept the results, either click the Accept button or right-click the task and select Accept Results. This will apply the proposed results to the binary and move the task to the Archive tab, where it will be stored for reference.

To reject the results, either click the Reject button or right-click the task and select Reject Results. This will move the task to the Archive tab, marking it for reconsideration where it can be reviewed later if needed.

Reconsidering Tasks¶

Tasks that have been declined or their results rejected are placed in the Archive tab and marked for reconsideration, which is indicated by the strikethrough text in the Description field of the task. These tasks can be moved back to their prior state by clicking the Reconsider button, which will move a task that was previoulsy declined back to the Pending tab or move a task whose results were previously rejected back to the Review tab. This allows you to revisit tasks that may need further analysis or a different approach.

Retrying Tasks¶

In the event that a task step fails, the task will display an error message in an error in the Task. You can retry the task by clicking the Retry button. This will re-execute the task step that failed, allowing you to continue with the analysis without having to recreate the task.

Deleting Tasks¶

To delete a task, right-click the task in the Tasks sidebar and select Delete. This will remove the task from the Tasks sidebar and delete all associated data, including instructions, results, and logs. Deleting a task is irreversible, so be sure you want to remove it before proceeding.

Marking Tasks as Read/Unread¶

You can mark tasks as read or unread to help manage your workflow.

Tasks that are unread contain bold text in the Tasks tables. This indicates that you have not yet reviewed the task or its contents. To mark these tasks as read, click on the task, or right-click the task in the Tasks sidebar and select Mark as Read. This will change the text to normal weight, indicating that you have reviewed the task.

Tasks that are read contain normal text in the Tasks tables. This indicates that you have already reviewed the task and its contents. To mark these tasks as unread, right-click the task in the Tasks sidebar and select Mark as Unread. This will change the text to bold, indicating that you need to revisit the task later.

Delegating Tasks¶

You can delegate tasks to Sidekick, which performs the analysis on your behalf while you focus on other aspects of the binary.

To delegate a task, select New Task... from the hamburger menu in the Tasks sidebar or Plugins->Sidekick->New Task... from Binary Ninja's top-level menu. This opens a dialog where you can describe a task for Sidekick to work on and click Submit.

Letting Sidekick Create Tasks¶

Sidekick can automatically create tasks on its own that complement your analysis. To do this, Sidekick monitors your activity within the binary and uses that information to infer your intent and recommend tasks that align with your analysis goals. This allows Sidekick to assist you in a more proactive manner, helping you to stay focused on your analysis without having to manually create tasks for every step. Tasks generated by Sidekick are automatically added to the Tasks sidebar, where you can review and manage them.

To enable this feature, do the following:

Enable Intent Tracking: Check the sidekick.intents.enabled setting in the Binary Ninja settings. This enables Sidekick to record your activity in the activity trace and use it to infer your intent.
Set the Collaboration Mode: Set the Collaboration Mode setting sidekick.tasks.collaboration_mode to guided in the Binary Ninja settings. The default is guided. When set to guided, Sidekick will create tasks based on your activity and intent, but requires your approval before executing them.

Setting the Collaboration Level¶

You can control how much Sidekick automates your workflow by choosing a Collaboration Mode and adjusting task handling settings.

Setting the Collaboration Mode¶

To set the overall mode, select Set Collaboration Mode... from the hamburger menu of the Tasks sidebar menu and select one of the following available modes:

Manual Mode: You specify all tasks and review every result.
Guided Mode: Your tasks run automatically, you review results. Sidekick suggests tasks for your approval. (Default)
Streamlined Mode: Your tasks run and apply automatically, results are applied without review. Sidekick tasks run automatically, you review the results.
Autonomous Mode: All tasks run automatically, results are applied without review.

These modes can also bet set in the Binary Ninja settings under sidekick.tasks.collaboration_mode. The default is guided.

Setting Task Modes¶

Tasks can be initiated by you, the Sidekick Assistant, or a tool. You can control how tasks are handled based on their source by setting the task mode for each type of task using the following settings in Binary Ninja:

sidekick.tasks.user_task_mode: Controls handling of user-initiated tasks. Default is auto.
sidekick.tasks.assistant_task_mode: Controls handling of assistant-suggested tasks. Default is manual.
sidekick.tasks.tool_task_mode: Controls handling of tool-generated tasks. Default is auto.

For each of these settings, you can choose one of the following task modes:

manual: Tasks require manual approval and application
auto-plan: Tasks are automatically generated but require manual approval before execution (assistant-suggested tasks only)
auto-execute: Tasks are automatically executed, but results require manual approval
auto: Tasks are automatically executed and applied

Viewing the Activity Trace¶

Sidekick maintains a record of your activity within the binary in order to infer your intent and support its task recommendations.

To view the activity trace, select Plugins->Sidekick->View Activity Trace... from Binary Ninja's top-level menu. This opens the Activity Trace Viewer dialog that displays the recorded activity. The activity trace is formatted as a JSON file and stored in the file sidekick/user_signals.json in your Binary Ninja User Folder.

By default, activity tracing is enabled. To disable it, you can uncheck the sidekick.intents.enabled setting in the Binary Ninja settings.