> 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/isolated-system-emulation.md). # Isolated System Emulation When you find a code sequence that you do not understand, you can step through it to learn what it does. But debugging malware is risky, and to do it safely you usually must leave your analysis to set up a VM or a remote debugger. The isolated system emulator removes this risk. Start an interactive "debug" session with one click on the dedicated toolbar button (the "magic wand") on the Analysis toolbar. The sample runs in the [Speakeasy](/add-ons/malware/concepts/emulators/speakeasy.md) emulator, never on your system, so you cannot run malicious code by accident. The add-on sets up the debugger configuration for you. Step, set breakpoints, and stop with IDA's debugger controls. A session is fast to start, so you can run a sequence again until you understand it. When you rename an item during emulation, IDA keeps the new name in the disassembly and pseudocode views. ## Isolation The sample runs in the emulator, never on your system. It cannot change your files, run code on your host, or connect to your network. This applies to: * isolated system emulation with Speakeasy * the [Speakeasy sandbox run](/add-ons/malware/concepts/sandbox-integration.md) * [automated unpacking](/add-ons/malware/concepts/automated-unpacking.md) with the `bochs` or `speakeasy` backend During interactive emulation, the sample sees only the emulated file system of Speakeasy, which contains decoy files. It does not see the files on your system. In the guest, the sample is at `C:\Windows\system32\`. Files that the sample writes stay in the memory of the emulator. Each session starts a new Speakeasy process, so changes that the sample makes do not go into the next session. The Speakeasy sandbox run gives the sample a copy of its own folder, so that the sample finds the DLLs and other files that it loads from there. The add-on copies the sample and the files next to it, up to 512 MiB, to a temporary directory, and deletes the copy after the run. The sample cannot get access to other folders on your system. {% hint style="warning" %} Some settings let the sample go outside the emulator. When you use them, the isolation does not apply: automated unpacking with `default_debugger` set to `win32`, or with `default_remote` set to `true`. The sample then runs on a real system. {% endhint %} ## Speakeasy [Speakeasy](/add-ons/malware/concepts/emulators/speakeasy.md) models the Windows API in Python. It runs 32-bit and 64-bit Windows PE files. When the sample calls an API that Speakeasy does not model, the call returns 1 and the session continues. Interactive emulation runs PE files only. For other file types, the toolbar button and the menu item are disabled. For a DLL, Speakeasy runs the TLS callbacks and `DllMain` first. Then it runs up to 10 exports from the start of the export table, one after the other, with placeholder arguments. You cannot select an export. To stop in an export, set a breakpoint on it before you start the session. Interactive emulation always uses Speakeasy. The unpacker can also use Bochs. For when to use each emulator to unpack, see [Emulators and real debuggers](/add-ons/malware/concepts/automated-unpacking.md#emulators-and-real-debuggers). ## Configuration To change the settings, select **Extensions → Malware Analysis → Emulation → Configure emulator...**. | Setting | Default | Description | | ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `backend` | `speakeasy` | The emulator to use. `speakeasy` is the only choice. | | `speakeasy_timeout` | `0` | The time in seconds of emulated execution, after which Speakeasy ends the session. The time when the debugger is paused does not count. `0` turns off the limit. | | `load_export_names` | `true` | If `true`, when a module loads, the add-on reads its export table from the emulator memory and names each export, for example `kernel32_HeapFree`, as IDA's Windows debuggers do. | To start a session, select **Malware Analysis → Emulation → Start interactive emulation → with Speakeasy**, or click the toolbar button. To stop a session, select **Debugger → Terminate process**. If the database has no breakpoints, the add-on adds a breakpoint at the entry point. To restart a session, stop it, and then click the toolbar button or select the menu item again. Do not use IDA's **Debugger** menu to start the process again: when a session ends, the add-on restores your debugger settings, so IDA does not start the emulator. During a session, the add-on selects IDA's remote GDB debugger on `127.0.0.1` and a random free port. When the session ends, the add-on restores your debugger settings. The IDC function `start_emulator()` starts a session with the configured backend. `start_emulator_with_backend("speakeasy")` starts a session with Speakeasy. If you have a question, an idea, or a problem, email . 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/isolated-system-emulation.md?ask=&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.