> 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/malware/concepts/sandbox-integration.md).

# Sandbox Integration

Sandboxes find key indicators quickly and show what a program did at run time. IDA shows the program logic, but a large code listing is difficult to read without runtime context. Sandbox integration joins the two: import a sandbox run and cross-reference its behavior directly with the code.

The sandbox results highlight the interesting regions of code, resolve complicated indirect calls, and recover injected payloads. Because you do this in IDA, you do not have to move information between two technical interfaces. This makes IDA easier to use and the sandbox results easier to act on.

## Backends

You can import runs from VMRay or Speakeasy.

### VMRay

VMRay runs the sample on a full Windows system. Select **Extensions → Malware Analysis → Sandbox → Fetch VMRay results via API...** to download the analyses of the sample from your VMRay server. The add-on searches by the SHA-256 hash of the input file. Then select the analyses to import in the **Select VMRay Analyses** dialog. If there is only one analysis, the add-on imports it without the dialog.

To fetch results, you need a VMRay account and an API key, on the VMRay cloud (the default server is `eu.cloud.vmray.com`) or on your own VMRay server. The add-on uses the VMRay REST API. It downloads the analysis archive of each analysis that you select, and reads the function log (`logs/flog.xml`) and the summary (`logs/summary.json`) from the archive.

To import an analysis archive that you downloaded from VMRay, select **Malware Analysis → Sandbox → Import VMRay archive (.zip)...**. This makes no network requests and needs no API key.

The add-on connects to VMRay only when you select **Fetch VMRay results via API...**. If the server or the API key is not set, the add-on shows "VMRay server or API key is not set. Set them with Malware Analysis > Sandbox > Configure VMRay...".

### Speakeasy

[Speakeasy](/add-ons/malware/concepts/emulators/speakeasy.md) runs the sample in an emulator on your computer, so you do not need a sandbox service. Select **Malware Analysis → Sandbox → Run Speakeasy sandbox** to run the sample and show the trace. The same item is also in **Malware Analysis → Emulation**. If the input file is not at its original path, the add-on asks you to find it. To show a Speakeasy report that you made before, select **Malware Analysis → Sandbox → Load Speakeasy report (.json)...**.

## User interface

### Trace view

The trace view shows the API calls from the run and their arguments. From a call in the trace view, you can go directly to the code that made it. Double-click an event to go to its address. If the address is not in the database, the add-on asks to import the memory region.

Type at least 3 characters in the search box to filter the events. The context box sets how many events show before and after each match, from 0 to 10. Use the scope dialog to show only some analyses, processes, or threads. To open the trace view again after you close it, select **Malware Analysis → Sandbox → Re-open trace viewer**.

**Run capa** finds the capabilities of the sample in the trace with [capa](https://github.com/mandiant/capa). The add-on installs capa 9.0 or later as a Python package. The first time, the add-on downloads the latest release of the [capa rules](https://github.com/mandiant/capa-rules) from GitHub. After that, it uses the downloaded rules and does not connect to GitHub. When the analysis completes, the trace view status bar shows the rules version and the number of capabilities that matched. If capabilities matched, the capability pane opens on the left. It shows each capability with its namespace and the number of events that matched. Select one or more capabilities to show only their events.

### Code coverage

IDA highlights the instructions that executed during the run, so you can see which code ran and which code did not.

### Line prefix

In the disassembly, an `S` before an instruction shows that the trace has events at that address. Move the mouse over the prefix to see the number of events. Click the prefix to filter the trace view to these events.

### Context menu actions

Right-click in the disassembly or pseudocode view and open the **Sandbox** submenu.

#### Select events at address or function

**Select events at this address** and **Select events in this function** filter the trace view to the events from the current address or function.

#### Set type for call

**Apply API name/type at this address** uses the trace to find the API that an indirect call goes to. It sets the function type at the call, renames the target, adds a comment, and renames the decompiler variable that holds the target. **Apply all API names/types in function** does this for all calls in the function. The add-on does not change names that you set.

In the trace view, right-click an event to import its memory region, or to apply the API name and type at its address.

### Importing memory regions

You can import memory regions from the run into the IDB, such as shellcode and injected payloads. To open the **Import Memory Regions** dialog, click **Import Memory...** in the trace view status bar. The dialog lists the memory regions from the run. By default, it shows only the interesting regions: memory from `VirtualAlloc` and similar calls, and memory that is writable and executable.

### Rebuilding IDBs from child processes

When the sample writes code into other processes, the **Import Memory Regions** dialog also has a **Remote Process IDBs** group, with one row for each of these processes. Click **Generate** to make a new IDB for the process. The add-on runs `idat` in batch mode and saves the IDB as `sandbox-injected-<pid>.i64` next to the current IDB, or as `sandbox-injected-<pid>.idb` when the current database is 32-bit. Then it asks if it should open the new IDB in a new IDA window. If the IDB already exists, the row has **Regenerate** and **Open** buttons.

The add-on looks for `idat` in the directory of the IDA that runs. If it does not find `idat`, or if `idat` fails, the add-on shows the error in the **IDB Generation Failed** message and does not make the IDB.

## Configuration

To change the VMRay settings, select **Malware Analysis → Sandbox → Configure VMRay...**. To change the Speakeasy settings, select **Malware Analysis → Sandbox → Configure Speakeasy sandbox...**.

| Backend   | Setting                      | Default              | Description                                                                                                                             |
| --------- | ---------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| VMRay     | `vmray_server`               | `eu.cloud.vmray.com` | The VMRay server. Use a host name or a URL. Without a scheme, the add-on uses `https://`. The add-on always checks the TLS certificate. |
| VMRay     | `vmray_api_key`              | empty                | Your VMRay API key. Fetch needs the key. Archive import works without a key.                                                            |
| Speakeasy | `emulation_timeout`          | `60`                 | The maximum run time in seconds for each entry point. `0` turns off the limit.                                                          |
| Speakeasy | `emulation_max_total_time`   | `0`                  | The maximum run time in seconds for all entry points together. `0` turns off the limit.                                                 |
| Speakeasy | `emulation_max_api_count`    | `10000`              | The maximum number of API calls for each entry point.                                                                                   |
| Speakeasy | `emulation_max_instructions` | `0`                  | The maximum number of instructions for each entry point. `0` turns off the limit.                                                       |

The Speakeasy settings have no effect when you load an existing report.

{% hint style="info" %}
The [Multi-service Checker](/add-ons/malware/concepts/multi-service-checker.md) and the [unpacker](/add-ons/malware/concepts/automated-unpacking.md) have their own `vmray_api_key` and `vmray_host` settings.
{% endhint %}

The add-on keeps traces and downloaded archives in a cache directory, and does not store them in the IDB. A Speakeasy trace from **Run Speakeasy sandbox** is temporary, and the add-on deletes it when you close the IDB.

| Platform | Cache directory                                                                                             |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| macOS    | `~/Library/Caches/hex-rays/ida/sandbox`                                                                     |
| Linux    | `$XDG_CACHE_HOME/hex-rays/ida/sandbox`, or `~/.cache/hex-rays/ida/sandbox` when `XDG_CACHE_HOME` is not set |
| Windows  | `%LOCALAPPDATA%\hex-rays\ida\cache\sandbox`                                                                 |

The cache has no size limit, and the add-on does not delete old files from it. One VMRay analysis archive can be about 200 MB. To clear the cache, close IDA and delete the cache directory. The add-on makes it again when it needs it. To get the latest release of the capa rules, delete only the `capa` directory in the cache. The next **Run capa** then downloads the rules again.

If you have a question, an idea, or a problem, email <support@hex-rays.com>. The Malware Analysis team reads every message and replies quickly.


---

# 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/malware/concepts/sandbox-integration.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.