Skip to content

Understanding Tool Permissions

Sidekick uses an AI agent that can take actions on your behalf — reading decompiled code, renaming functions, running Python scripts, issuing debugger commands. Before you hand the agent broad authority, it helps to understand exactly how those actions are controlled and what you can do to keep the agent inside boundaries you are comfortable with.

This tutorial walks you through the current permissions model, from the moment the agent asks to run a tool, through tag-based rules and per-tool overrides, to the scopes where you can save your preferences.

What happens when a tool needs approval

Sidekick is fail-closed by default. A tool call requires approval unless an explicit policy allows it. For user-created chats, those policies can come from the current chat, the current workspace, or the application-wide settings. For actor-owned or other system-owned processes, the runtime provides the process policy directly.

When the agent tries to use a tool that is not already allowed, the chat thread pauses and a tool call card appears in the conversation.

The card shows:

  • The tool name and a summary of its arguments
  • The tags associated with the tool (used for category-based rules, explained below)
  • An Allow button with a dropdown arrow, and a Reject button with a dropdown arrow

Library-backed chat execution appears here as its own tool call. For example, running a Library script from chat shows up as library_python_run, which is categorized under library.run even though it still executes Python inside Binary Ninja.

The five actions

Clicking the main button performs the default action. Opening the dropdown reveals additional choices.

Allow menu:

Action What it does
Allow (default) Approves this single tool call. The next call from the same tool will ask again.
Allow all [tag] tools for this chat Approves the tool now and adds the tool's tag to the allow list for the current user-owned chat process only. Matching tools in that chat run without asking until the chat ends.
Allow 'tool_name' for this chat Approves the tool now and adds this specific tool to the allow list for the current user-owned chat process only.

Reject menu:

Action What it does
Reject (default) Cancels the tool call and returns a rejection message to the agent.
Reject with Reason... Opens a text field so you can explain why you rejected the call. The agent receives your explanation and can adjust its approach.

Tip

"Allow for this chat" options are a good way to build momentum when you trust the current user-owned chat but are not ready to make a workspace-wide or application-wide change.

When approvals are pending only in child threads, the synthetic descendant notice in chat provides bulk actions as well: approve all pending descendant calls once, reject them all, or allow the currently pending tool types for the rest of that chat. That bulk allow action is tag-first: it adds all tags on the currently pending descendant tools to the chat policy, and falls back to tool-name allowance only for pending tools that have no tags.

Edit before approving

Next to the Allow and Reject buttons is an Edit button. Clicking it opens the tool call arguments as editable JSON, so you can modify parameters before the tool runs. Click Save to approve the edited call, or Cancel to go back to the original approval prompt.

Opening the Tool Permissions Settings dialog

To configure standing rules that apply across sessions, open the dialog from the Binary Ninja menu:

Plugins > Sidekick > Configure Tool Permissions...

Note

This menu item is disabled (greyed out) unless a binary is open and a Sidekick session is active.

The dialog has two sections stacked vertically:

  • Tag-Based Permissions — a checkbox tree of tool categories
  • Tool-Specific Overrides — a list of explicit per-tool rules

At the top of the dialog is a Scope selector that controls which level of settings you are editing.

Tag-based permissions

Every tool registered with Sidekick is assigned one or more tags when it is loaded. Tags follow a dot-separated hierarchy. A parent tag can cover an entire family of tools, without you needing to name each tool individually.

The tag hierarchy

The dialog is driven by the tags exposed by the tools currently registered in your environment. The table below shows common examples.

Tag Description Example tools
repo All repository operations —
repo.read Read files read_file, list_files
repo.write Write or create files write_file, delete_file
repo.manage Git operations (commit, checkout) create_repo, commit
ui All Binary Ninja UI operations —
ui.visible Read visible content get_visible_content
ui.selection Read the current selection get_selection
notebook All Notebook operations —
notebook.query Query notebook entries query_notebook
notebook.update Modify notebook entries and analysis context update_notebook, update_notebook_context
briefing All session briefing operations —
briefing.query Read the session briefing get_session_briefing
briefing.update Modify the session briefing update_session_briefing
database All decompilation database operations —
database.query Query the binary database query_database
database.update Modify the binary database update_database
index All index operations —
index.query Query indexes query_indexes
index.update Update indexes update_index
library All Library item tools —
library.run Run Library items in chat library_python_run
codemap All code map operations —
codemap.query Query code maps query_code_maps
codemap.update Update code maps update_code_map
python All Python tools —
python.binja Python interpreter running inside Binary Ninja —
python.binja.run Run Python scripts inside Binary Ninja python_run, library_python_run
python.binja.eval Evaluate Python expressions python_eval
docs Bundled documentation tools search_docs, read_doc_page
debugger All debugger operations —
debugger.control Control execution debug_launch, debug_continue, debug_step
debugger.inspection Inspect state debug_inspect, debug_modules
debugger.mutation Modify registers or memory debug_write_register, debug_write_memory
debugger.backend Direct backend commands debug_backend_command
debugger.breakpoints Manage breakpoints debug_breakpoint
system Internal system tools (used by tools without another category)

How tag state works

Each scope stores an explicit tri-state for tags and tools:

  • Allow: tools matching that rule run without asking
  • Ask: tools matching that rule always require approval
  • Inherit: no explicit rule at this scope; Sidekick falls through to the next lower-precedence scope

Checking database stores an explicit Allow for the database tag. Any tool tagged database.query, database.update, or any other sub-tag under database matches that rule unless a more specific tag or tool override says otherwise.

Unlike older versions of the dialog, Sidekick does not expand a parent rule into explicit sibling rules behind the scenes. The UI shows inherited and effective state directly instead.

Note

Tags use prefix matching under the hood. A rule that allows database automatically covers any tool tagged database.query, database.update, or any other sub-tag under database.

Tool-specific overrides

The Tool-Specific Overrides section lets you pin a single tool to Allow (never ask) or Ask (always ask, even if its tag would otherwise allow it), regardless of what the tag tree says.

Adding an override

  1. In the tool selector dropdown at the bottom of the Tool-Specific Overrides section, type or choose a tool name. The field supports autocomplete.
  2. In the state dropdown next to it, choose Allow or Ask.
  3. Click Set.

The tool appears in the override list with its current state and its tags shown for reference.

Removing an override

Select the tool in the override list and click Clear. The tool reverts to whatever the tag rules say.

When overrides and tags conflict

An explicit tool Ask override always beats a tag allow. If database is allowed but you have added update_database as Ask, the agent will still ask before modifying your binary.

An explicit tool Allow override beats a tag set to Ask. If python.binja is set to Ask but you add python_eval as Allow, python_eval runs without asking while python_run and library_python_run still do.

The resolution order within any scope is:

  1. Explicit tool state
  2. The most specific matching tag state
  3. No rule at this scope — inherit to the next scope

If no scope allows the tool, the final result is Ask.

Permission scoping

The Scope selector at the top of the dialog determines which layer you are reading and writing. Changes in one scope do not affect the others.

Scope Label in UI What it covers When to use
This Chat "Applies only to this chat." The current user-owned chat process Temporary grants for the active chat; changes are lost when the chat ends
This Workspace "Applies only to this workspace." The current Binary Ninja workspace Per-binary or per-project rules for user-owned chats
All Workspaces "Applies across all workspaces." The live application-wide policy for user-owned chats Global preferences that should apply everywhere immediately

Note

For user-owned chats, scopes are consulted in order from most specific to least: This Chat, then This Workspace, then All Workspaces. If a tool is set to Ask in "This Chat" but Allow in "This Workspace", the chat-level Ask wins for that session.

Settings saved to This Workspace and All Workspaces are persisted between sessions. Settings for This Chat are always in-memory only.

Note

Actor-owned and other system-owned processes do not inherit your workspace or application settings. In the permissions dialog they appear as read-only, process-owned policies.

By default, Sidekick ships with no tags or tools in the allow list. Every tool call requires your explicit approval until you add standing rules. The configurations below are suggested starting points, not presets — you configure them manually in the dialog.

There is no single correct configuration — it depends on what you are doing and how much you trust the current task. Three starting points are described below.

Conservative: approve everything

Leave all tags set to Ask or Inherit and add no allow overrides. Every action the agent takes will require your explicit approval unless another scope already allows it.

This is appropriate when: - You are working with a sensitive or production binary - You are exploring what the agent does on a new binary for the first time - You want a complete audit trail of every agent action

The tradeoff is friction: multi-step analysis tasks will pause frequently waiting for your input.

Moderate: allow the reads you trust

Check the following tags in This Workspace scope so they apply to user-owned chats on this binary:

  • database.query — lets the agent read decompiled code, functions, and types without modifying them
  • ui.visible and ui.selection — let the agent see what is on screen and read the current selection
  • notebook.query — lets the agent read your notes
  • docs — lets the agent look up Binary Ninja API documentation
  • index.query and codemap.query — lets the agent inspect indexes and code maps you have built

Leave write and mutation tags unchecked. The agent can read freely but must ask before making any change.

This configuration suits most day-to-day reverse engineering sessions. The agent can investigate the binary, reason about it, and propose actions, while you review each proposed change.

Liberal: allow most tools

Check all read tags as above, and additionally check:

  • database.update — lets the agent rename functions, add types, write comments
  • notebook.update — lets the agent modify notebook entries, including outcomes and structured analysis context
  • index.update and codemap.update — lets the agent update indexes and code maps
  • library.run — lets chat launch Library items without pausing for approval
  • repo.read — lets the agent read files if you have a file repository configured

Leave the following always requiring approval: - python.binja.run and python.binja.eval — direct Python execution can do anything the BN API allows - debugger — all debugger controls carry significant risk - repo.write and repo.manage — file and repository mutations are hard to reverse

This configuration suits experienced users working on CTF challenges or personal research where convenience outweighs the risk of unreviewed database edits.

Warning

Enabling database.update at the All Workspaces scope means user-owned chats can rename functions and add annotations in every binary you open without asking. Consider using This Workspace scope for write permissions so you opt in per binary.

Putting it together: a practical example

Suppose you are analyzing a malware sample and want the agent to survey the binary, create a Notebook summary, and propose a list of interesting functions — but you do not want it modifying anything yet.

  1. Open Plugins > Sidekick > Configure Tool Permissions...
  2. Set scope to This Workspace.
  3. Check: database.query, ui.visible, ui.selection, notebook.query, docs.
  4. Leave everything else unchecked.
  5. Click Close.

Now start a chat and ask Sidekick to survey the binary. The agent can read freely. When it eventually wants to write a Notebook entry summarizing its findings, it will pause and ask you — giving you a chance to review before anything is recorded.

After reviewing its summary and approving the notebook write, you can re-open the dialog and check notebook.update to let future writes go through automatically.

Next steps