> For the complete documentation index, see [llms.txt](https://docs.hex-rays.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hex-rays.com/add-ons/assist/concepts/permissions-and-privacy.md).

# Permissions & Privacy

Assist can read your database, run code in an isolated emulator, and — when allowed — modify the [IDB](/add-ons/assist/reference/glossary.md#idb), invoke IDAPython, run shell commands, or write files.

Assist separates permissions into two distinct controls under **Settings → Permissions** (`/permissions`):

1. **Tool capability permissions (`Assist` tab)** — which tool groups are **On**, **Ask when needed** (prompting with a capability card in the transcript), or **Off**.
2. **External MCP client access (`MCP clients` tab)** — which external [MCP](/add-ons/assist/reference/glossary.md#mcp) programs are admitted to call tools that are already **On**.

### Where settings live

| Area                                  | Menu path                                                    | Slash command          |
| ------------------------------------- | ------------------------------------------------------------ | ---------------------- |
| Tool capabilities & MCP client access | **Settings → Permissions** (`Assist` and `MCP clients` tabs) | `/permissions`         |
| Confidentiality rules                 | **Settings → Preferences… → Behavior → Privacy & context**   | `/privacy`             |
| Assist Mesh & network endpoint        | **Settings → Preferences… → Sharing & network**              | `/sharing`, `/network` |
| Persistent memory settings            | **Settings → Preferences… → Advanced → Persistent memory**   | —                      |
| Updates                               | **Settings → Preferences… → Updates**                        | `/update`              |

For the complete reference of all **Settings** items, **Preferences…** tabs, and slash commands, see [Settings & Commands](/add-ons/assist/reference/settings-and-commands.md).

## Tool capability permissions (`Assist` tab)

Each capability group on the **Assist** tab can be set to:

* **On** — the built-in agent and admitted external MCP clients may call the group's tools without a capability prompt.
* **Ask when needed** — the built-in agent pauses and displays a [**capability prompt card**](/add-ons/assist/reference/glossary.md#capability-prompt-card) in the transcript before the tool runs. Because external MCP clients and inbound mesh fanout calls cannot answer interactive cards in the panel, **Ask when needed** behaves as **Off** (refused) for them.
* **Off** — the group's tools are removed from the advertised tool list and blocked for direct local and external MCP calls (note: if you explicitly approve a routed built-in tool call on a capability prompt card in an origin Assist panel, the destination's built-in tool gate honors that forwarded per-call authorization before consulting its ordinary capability state; see [Assist Mesh and external MCP clients](#assist-mesh-and-external-mcp-clients)).

![The Assist tab of the Assist permissions window](https://492083732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFP6ibt8r6WPBHTqekG9u%2Fuploads%2Fgit-blob-28d7875ebcd96a288601d4cf33e898b4b434e0ef%2Fassist-permissions.png?alt=media)

### Capabilities and defaults

The table below shows the recommended **Ask before changes** setup preset and how each default behaves for the panel agent versus external MCP clients:

| Section                                    | Capability                         | Recommended default  | Effective for external MCP clients at default | What it controls                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------ | ---------------------------------- | -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **This machine**                           | **Read files**                     | **On**               | Allowed                                       | Read and search files in the database's folder and Assist's profile (`read_file`, `list_dir`, `find_files`, `search_files`)                                                                                                                                                                                                                                                                                        |
| **This machine**                           | **Read files outside the project** | **Ask when needed**  | Refused                                       | Read or search any other path your OS account can access                                                                                                                                                                                                                                                                                                                                                           |
| **This machine**                           | **Write files**                    | **Ask when needed**  | Refused                                       | Create, edit, move, or delete files and directories (`write_file`, `edit_file`, `create_directory`, `delete_path`, `move_path`), or save the database to disk (`database_state` `save`)                                                                                                                                                                                                                            |
| **This machine**                           | **Run Python**                     | **Ask when needed**  | Refused                                       | Run IDAPython inside IDA (`idascript`), standalone Python (`python`), or mesh script fanout (`mesh_script_fanout`). Automatically enabled while **Run shell commands** is **On**.                                                                                                                                                                                                                                  |
| **This machine**                           | **Run shell commands**             | **Ask when needed**  | Refused                                       | Run arbitrary commands with your OS account's access (`execute_command`), including Python                                                                                                                                                                                                                                                                                                                         |
| **This IDA database**                      | **Modify this IDA database**       | **Ask when needed**¹ | Refused¹                                      | Run built-in tools that change names, types, comments, functions, signatures, or bytes in the database, or undo/redo database actions (`database_state` `undo`/`redo`)                                                                                                                                                                                                                                             |
| **Sending to your other linked databases** | **Share confirmed findings**       | **Ask when needed**  | Refused                                       | Save, revise, or delete persistent memories via agent tools and send confirmed findings to linked databases (`remember`, `revise_memory`, `forget_memory`, `propagate_memory`; local `/fulltriage` and **Create review notes** writes are not gated here and depend on **Allow memory writes**). Even when set to **On**, memory writes from external MCP clients are queued as pending proposals for your review. |

*¹ If the first-run setup wizard is skipped, **Modify this IDA database** defaults to **On** (which also allows admitted external MCP clients to call those tools).*

Read-only database inspection, emulation, constraint solving, and visual rendering (subject to [confidentiality rules](#confidentiality-rules)) are not gated by a capability on the **Assist** tab; admitted callers can always use them. Read-only memory retrieval (`recall`) is controlled separately by **Allow memory recall** *(on by default)* under [Memory → Persistent memory settings](/add-ons/assist/concepts/memory.md#persistent-memory-settings).

{% hint style="info" %}

* **Local and cross-database memory writes.** Despite the **Sending to your other linked databases** section heading, **Share confirmed findings** also gates local agent memory writes (`remember`, `revise_memory`, `forget_memory`) and stays at **Ask when needed** under all three setup presets (see [Memory](/add-ons/assist/concepts/memory.md#how-memories-are-created-and-managed)).
* **IDAPython scripts and database edits.** **Run Python** permits IDAPython scripts (`idascript`) with your OS account's access. Because scripts inside IDA are unrestricted and can change the database or start programs directly, disabling **Modify this IDA database** does not restrict an otherwise permitted script.
  {% endhint %}

### Capability prompt cards

When the built-in agent requests a capability set to **Ask when needed**, Assist renders a **capability prompt card** in the transcript showing the exact target that will run (file path, command, script, or database edit, with an expandable view for the full JSON arguments) and three choices:

* **Deny** — reject this tool call.
* **Allow once** — run this single call only.
* **Allow for this session** — set the capability group to **On** for the remainder of the current session.

{% hint style="warning" %}

* **Session-wide grant:** Choosing **Allow for this session** enables that capability group for subsequent calls in the session, not just the single call in front of you.
* **No automatic timeout:** Capability prompt cards wait indefinitely for your decision. An unattended turn that triggers **Ask when needed** remains paused until you respond.
  {% endhint %}

## Confidentiality rules

If you use a cloud model, you may want to keep specific identifiers — a customer name, a project codename, internal paths, or the binary's filename — off the wire. Under **Settings → Preferences… → Behavior → Privacy & context** (`/privacy`), you can configure **Confidentiality rules** in the `User defaults` or `This binary` rule set (see [Settings & Commands → Confidentiality rule editor](/add-ons/assist/reference/settings-and-commands.md#confidentiality-rule-editor-privacy)):

* **Match types & replacement modes:** **Literal** or **Regex** (RE2 syntax; regex replacements support `$1`–`$9` and `$$`), replacing either the **Matched text** or the **Whole value** (with optional **Ignore case**).
* **Scopes (`Apply to`):** **All text**, **Function names**, **Binary name**, **Variable names** (globals, statics, data labels, and local variables), or **String literals**.
* **Precedence & bidirectional translation:** Rules evaluate in deterministic order (binary overrides first, then category specificity, then longest match, then table row order). Outbound prompts, view context, pseudocode, disassembly, memory context, and tool outputs have matching text replaced before leaving your machine, while inbound model responses and tool-call arguments are reversed back to real IDA identifiers locally *(if two different originals map to the same replacement string, inbound reversal leaves the shared token unchanged)*.
* **Local preview text:** Use the local preview input in the editor to test how your active rules transform text and check for shadowing or validation errors before sending a message.

{% hint style="warning" %}

* **Confidentiality rules start empty.** A fresh install redacts nothing until you add rules. Configure your rules before sending your first prompt on a sensitive target.
* **Enabling any rule withholds screenshots from the model.** Because text rules cannot redact pixels inside an image, calling `screenshot` while any confidentiality rule is active still renders the image in your local transcript, but **withholds the PNG from the model provider** (the model receives a notice that image input is disabled while confidentiality rules are active). Separately, the managed **Claude Code** and **Antigravity CLI** backends do not support image attachments.
  {% endhint %}

### Limitations of confidentiality rules

* **Formatted text vs. raw bytes and local files.** Rules operate on formatted text and symbol/string inventories transmitted through Assist. They do not scan raw byte dumps (`get_bytes`) unless the formatted output matches a rule pattern, and they do not sanitize every local file on disk (such as local session transcripts or diagnostic logs).
* **Fail-closed withholding on inventory or truncation errors.** If the database changes while its symbol/string inventory is being collected, or if command/script output is truncated for size while rules are active, Assist withholds the output to prevent a partial leak.
* **Managed CLI backends vs. independent external tools.** Assist's managed **Claude Code** and **Antigravity CLI** backends expose Assist's host tools and disable those CLIs' built-in file, command, and web tools. By contrast, **OpenCode** or independently configured external MCP clients can invoke their own built-in tools outside Assist's control and can obtain or send content independently.
* **Past turns.** Adding or editing a rule re-masks replayed conversation history on future turns (and discards the provider's cached context), but cannot recall data already sent to a provider in an earlier turn.

## What leaves your machine

Assist has **no telemetry, analytics, or crash reporting**. Assist-managed provider and update connections are:

| Purpose                                      | Destination hosts                                                                                           | When contacted                                                                                              |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **ChatGPT account**                          | `auth.openai.com`, `chatgpt.com` (or your account's workspace backend)                                      | During OAuth sign-in and active chat turns                                                                  |
| **Grok**                                     | `auth.x.ai`, `accounts.x.ai`, `cli-chat-proxy.grok.com`                                                     | During OAuth sign-in and active chat turns                                                                  |
| **API key or OpenAI-compatible endpoint**    | Your configured endpoint URL (e.g., `api.openai.com`, `api.anthropic.com`, `openrouter.ai`, or `localhost`) | When listing models or running chat turns                                                                   |
| **Claude Code / Antigravity CLI / OpenCode** | Managed by the respective CLI (`claude`, `agy`, `opencode`)                                                 | When that CLI subprocess is active                                                                          |
| **Update check**                             | `hexrays.plugins.hex-rays.com`                                                                              | Shortly after IDA startup and once an hour while open (when **Check for updates automatically** is enabled) |

*(**Settings → Guide…** and `/guide` open the in-product Assist guide window locally; clicking the documentation link inside that guide window or clicking **Help** in the **Preferences** or **Assist permissions** dialogs opens `docs.hex-rays.com` in your system web browser, and Assist makes no background requests to it. Permitted scripts or shell commands and independently configured external clients have their own network behavior outside this table.)*

{% hint style="info" %}
**Browser sign-in uses loopback.** Signing in with a **ChatGPT account** or **Grok** binds a temporary local `127.0.0.1` listener purely to receive the OAuth redirect; see [Requirements & Support → Agent backend requirements](/add-ons/assist/reference/requirements.md#agent-backend-requirements).
{% endhint %}

## Assist Mesh and external MCP clients

Open IDA instances belonging to the same OS user account on a machine link automatically over private, owner-only local sockets (macOS and Linux) or named pipes (Windows) using [AMTP](/add-ons/assist/reference/glossary.md#amtp) mutual authentication and encryption. No network port is opened unless you explicitly enable the temporary network endpoint below.

Configure mesh and MCP behavior under **Settings → Preferences… → Sharing & network** (`/sharing`) and **Settings → Permissions → MCP clients** (`/permissions`):

* **Available while the panel is closed.** **Keep linked when chat is closed** is **On** by default, so peer IDA instances and external MCP clients (`plugins/assist/bin/assist --mcp`) can reach the open database even when the Assist panel is closed.
* **Multi-database discovery and routing (`list_databases`, `use_database`, `target`).** Callers can inspect reachable open databases with `list_databases` (returning `binary`, 12-character `hash`, `role`, `instance_id`, `database_id`, `selected`, `binary_version`, and optional `file_extension`), select the active database for subsequent calls on that connection with `use_database` (`{"database": "<hash-or-unambiguous-name>"}`; ambiguous names are refused, and callers should not assume automatic selection when multiple databases are open), or override the target for a single call by passing `target` (`{"target": "<database-handle>", ...}`; `target_binary_hash` is a deprecated alias). If two copies of the same binary are open at once, disambiguate them using the instance or database handle from `list_databases`, and re-run `list_databases` after opening or closing databases.
* **Cross-database reading and fan-out (`scope: "mesh"`, `mesh_fanout_fetch`).** Linked databases on the same machine can read each other's analysis without a prompt because they run under your OS user account on the same host. Passing `scope: "mesh"` (which cannot be combined with `target`) on a fan-out-eligible read tool with portable arguments (for example, `search_strings`, `detect_libraries`, or `recover_interface_layout` with `pattern`) fans the query out across all linked databases and returns per-member outcomes (`Hit`, `NoMatch`, `Refused`, `Timeout`, or `Error`). Detailed per-member results are cached for **15 minutes** (up to **512** entries) and can be expanded on demand with `mesh_fanout_fetch` using the returned `handle` (or `fanout_id` plus member handle).
* **Cross-database tool permissions:**
  * Each open IDA instance has its own capability settings in **Settings → Permissions → Assist**. Database edits routed to a linked database where **Modify this IDA database** is **On** execute there immediately without a prompt.
  * Explicit per-call approvals (**Allow once** or **Allow for this session**) granted on a capability prompt card in your local Assist chat panel can accompany routed built-in tool calls without changing the destination's saved permissions. Because the destination's built-in tool gate honors a forwarded per-call authorization before consulting its ordinary capability state, do not rely on setting a capability to **Off** at the destination alone to override an explicitly approved origin panel call.
  * A mesh fan-out call (or expanding its cached results locally with `mesh_fanout_fetch`) needs no capability permission in the originating session. Each destination database evaluates the incoming call against its own saved permissions: read-only database tools succeed without a prompt, while capability-group tools are refused unless that capability is **On** there. Approved external MCP clients follow the same destination rule.
  * **Cross-database script fan-out (`mesh_script_fanout`).** Running IDAPython across linked databases (`mesh_script_fanout`, gated by **Run Python**) queues a separate fleet-scoped approval capturing the frozen destination roster and a fingerprint of the script code. After approval, `idascript` runs on each destination and returns per-destination results; execution is not atomic across peers (if one destination fails, completed peer edits are not rolled back automatically).
* **Send memories (`propagate_memory`).** Under **Settings → Preferences… → Sharing & network → Mesh → Send memories**, choose **Confirm each send, and let the model suggest them** *(default)*, **Confirm each send**, or **Send automatically for this binary**. Memories arriving from linked databases are always held in quarantine for review before use.
* **Opt-in temporary Network endpoint:**
  * **What it is for:** Lets an external MCP agent running in a VM or on another computer connect to your open IDA session.
  * **How to enable it:** Tick **Open a network endpoint** under **Settings → Preferences… → Sharing & network → Network endpoint** (`/network`). Toggling the checkbox changes live gateway state immediately (clicking **Cancel** in Preferences does not undo a toggle). The setting is off by default and never persisted across restarts — the port closes and its code expires when you untick it or when no IDA instance on the machine remains linked.
  * **What changes when enabled:** The gateway binds a temporary TCP port (`20000`–`32767`) on your chosen interface address (or `127.0.0.1` for an SSH tunnel; IPv6 endpoints format as `[address]:port`) and generates a temporary connection code that remains valid for that active endpoint generation (it is not single-use, and rotates when the endpoint is turned off and re-enabled).
  * **How a client connects:** Copy the generated agent configuration from the settings page, which runs `assist --mcp --connect <ip:port>` with `ASSIST_MCP_CONNECTION_CODE`.
* **External MCP client access policy (`Settings → Permissions → MCP clients`):**
  * **Unapproved clients:** Can browse the advertised tool list, but cannot invoke any tool until admitted.
  * **Admission modes (`New connections`):** Choose **Ask for approval** *(default)*, **Review here (no prompt)**, **Approve all**, or **Deny all**.
  * **`On`-only capability rule:** Admitting a client only allows it to call tool groups set to **On** on the **Assist** tab (see [Tool capability permissions](#tool-capability-permissions-assist-tab)).
  * **Shared per-client decisions:** Admission decisions are remembered per client and shared across open databases on the same machine.
  * **Remote clients:** Clients connecting from another machine through the temporary network endpoint always prompt for admission unless **New connections** is set to **Deny all**.

## Local storage and diagnostics

Assist stores API keys in your **OS credential store** (macOS Keychain, Windows Credential Manager, or Linux Secret Service) and keeps OAuth accounts, settings, knowledge bases, transcripts, and diagnostic logs in owner-only directories under `<user-ida-dir>/assist/`. For exact file paths, OS permission and socket details, `--diagnose`, Developer mode logging channels, and uninstall/reset instructions, see [Diagnostics & Data Storage](/add-ons/assist/reference/diagnostics.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hex-rays.com/add-ons/assist/concepts/permissions-and-privacy.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.