> 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/ida-9.5/add-ons/malware/concepts/sandbox-integration.md). # Sandbox Integration ## Purpose 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. All items are in **Malware Analysis > Sandbox > VMRay**. Select **...fetch 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 import an analysis archive that you downloaded from VMRay, select **...import existing archive (.zip)**. This makes no network requests. The add-on connects to VMRay only when you select **...fetch results via API**. This action is available only when you set `vmray_api_key`. ### Speakeasy [Speakeasy](/ida-9.5/add-ons/malware/concepts/speakeasy.md) runs the sample in an emulator on your computer, so you do not need a sandbox service. All items are in **Malware Analysis > Sandbox > Speakeasy (isolated system emulator)**. Select **...run sandbox** to run the sample and show the trace. 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 **...load existing 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 first time, the add-on downloads the latest capa rules from GitHub. After that, it uses the downloaded rules. ### 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. The **Import Memory** 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 **Remote Process IDBs** pane makes a new IDB for each of these processes. The add-on runs `idat` in batch mode and saves the IDB as `sandbox-injected-.i64` next to the current IDB. You can then open the new IDB in a new IDA window. ## Configuration To change the VMRay settings, select **Malware Analysis > Sandbox > VMRay > ...configure**, or use HCLI: ```bash hcli extension config ida-sandbox-vmray set vmray_api_key hcli extension config ida-sandbox-speakeasy set emulation_timeout 120 ``` Restart IDA after you change a setting. | Plugin | Setting | Default | Description | | ----------------------- | ------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ida-sandbox-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. | | `ida-sandbox-vmray` | `vmray_api_key` | empty | Your VMRay API key. When empty, **...fetch results via API** is not available and the menu shows "VMRay (no API key)". Archive import works without a key. | | `ida-sandbox-speakeasy` | `emulation_timeout` | `60` | The maximum run time in seconds. `0` turns off the limit. Speakeasy also stops a run after 10,000 API calls. This setting has no effect when you load an existing report. | {% hint style="info" %} The [multi-service checker](/ida-9.5/add-ons/malware/concepts/multi-service-checker.md) has a separate VMRay key and server setting. {% 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 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` | --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hex-rays.com/ida-9.5/add-ons/malware/concepts/sandbox-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.