> 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/automated-unpacking.md). # Automated Unpacking Packers hide the inner payload of a malware sample. Until you remove this layer, IDA shows only the packer code, and the code that matters for your investigation stays hidden. IDA detects packed binaries when you load them, so you do not have to scan for packers manually. When you confirm, the unpacker unpacks the sample in place: it overwrites the packed data and shows analyzable code immediately. You do not have to leave your analysis to set up a debugger, dump memory, or repair imports by hand. The unpacker removes the repetitive unpacking work on commodity malware. It is made for the easy and medium cases, which can be difficult or just annoying to deal with. For samples that the unpacker cannot handle, you can step through the unpacking stub with the [isolated system emulator](/add-ons/malware/concepts/isolated-system-emulation.md). The unpacker targets Windows PE files. It has good support for UPX, MPRESS, ASPack, RLPack, NSPack, WinUpack, and Packman, and some support for PECompact, PEtite, and Themida. To ask for support of a different packer, email . Unpacking is different from deobfuscation. The unpacker removes the packing layer and restores the original code. It does not simplify complicated logic, and it does not remove control-flow flattening, opaque predicates, or VM-based protection. For protectors like Themida, which also virtualize code, the unpacker removes only the packing layer. {% hint style="info" %} Hex-Rays is developing a [deobfuscator](/add-ons/malware/concepts/deobfuscation.md) for these protections. {% endhint %} ## Unpacking at database open When you open a new database in the IDA GUI, the unpacker waits for the first auto-analysis. If the file looks packed, it asks you one time for that database if you want to unpack it. Before it unpacks, it takes a database snapshot, so you can go back to the packed state. ![The prompt to unpack a packed sample](https://492083732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFP6ibt8r6WPBHTqekG9u%2Fuploads%2Fgit-blob-50e58530c3a217297188d5c02b0315c9a7bd9e41%2Funpack-prompt.png?alt=media) In idalib, the unpacker does the same check, and unpacks a packed file automatically with no dialogs. It always uses an emulator: the `default_debugger` backend if it is `bochs` or `speakeasy`, otherwise `bochs`. It never uses the local debugger or the remote debugger. The unpack runs in `open_database`, so the call can take up to `default_timeout` seconds (300 by default), and it changes the database. To turn off the check at database open, set `ask_at_startup` to `false`, or set the environment variable `IDA_MALWARE_DISABLE_UNPACKER=1`. You can still unpack manually with **Extensions → Malware Analysis → Unpacking → Unpack now\...**. ## Emulators and real debuggers The unpacker runs the sample to unpack it. Start with an emulator: [`bochs`](/add-ons/malware/concepts/emulators/bochs.md) (the default) or [`speakeasy`](/add-ons/malware/concepts/emulators/speakeasy.md). With an emulator, the sample runs in the emulator, never on your system, as described in [Isolation](/add-ons/malware/concepts/isolated-system-emulation.md#isolation). Use `bochs` first. Bochs emulates a full x86 PC and runs the sample with a minimal Windows kernel. If the sample does not unpack correctly in Bochs, restore the snapshot, set `default_debugger` to `speakeasy`, and unpack again. Speakeasy models many Windows APIs in Python, so a stub that needs these APIs can go further. [Interactive emulation](/add-ons/malware/concepts/isolated-system-emulation.md) always uses Speakeasy. A real debugger runs the malware on a real system. This is the case with `win32`, the local Windows debugger, and with any backend when `default_remote` is `true`. Use a real debugger only on a dedicated analysis machine or a VM that you can restore. It can do better on samples that detect emulators or fail in them. Before the unpacker uses a real debugger, it asks you to confirm. ## Algorithms The unpacker has several heuristics. To select one, select **Malware Analysis → Unpacking → Unpack now\...** or press Shift + P. | Heuristic | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `run-to-exit-point` | Sets breakpoints on the exits of the entry point function and runs the sample. The unpacker suggests this heuristic for UPX-like stubs: one function with one exit that ends in a call or jump. | | `jumps-other-section` | Sets execute breakpoints on the other segments and runs the sample until code in another segment executes. | | `run-until-timeout` | Sets breakpoints on exit functions, such as `ExitProcess`, and runs the sample for a fixed time. | | `vt-unpack` | Applies the CAPE or Zenbox memory dumps of the sample from VirusTotal. Available only if `vt_api_key` is set. | | `vmray-unpack` | Applies the process memory dumps of the sample from VMRay. Available only if `vmray_api_key` is set. | | `already-unpacked` | Does not unpack. Runs only the steps after unpacking, such as the search for the original entry point. | The first heuristic in the list is the suggestion. For UPX-like stubs, this is `run-to-exit-point`. For all other samples, it is `run-until-timeout`, which does not depend on the structure of the stub, but runs for up to `default_min_timeout` seconds. If the result is not correct, restore the snapshot and try `run-to-exit-point` or `jumps-other-section`. These two stop when the stub transfers control to the unpacked code, before the payload runs. If the sample does not run correctly in the emulator, try `vt-unpack` or `vmray-unpack`, which use memory dumps from a full sandbox run. In idalib, the unpacker uses the suggestion, and never selects `vt-unpack` or `vmray-unpack` automatically. ## Rebuilding PE and ELF files Some tools expect a PE or ELF file, such as YARA scanners, code indexers, and sample collections. To give them the unpacked code, select **Malware Analysis → Unpacking → Dump database to binary...** or press Ctrl + Shift + D, and then select the output file. The add-on writes the segments, entry point, imports, and exports of the database to a new PE or ELF file. This works only for PE and ELF databases. The output file does not run. ## Configuration To change the settings, select **Malware Analysis → Unpacking → Configure unpacker...**. | Setting | Default | Description | | ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ask_at_startup` | `true` | If `true`, the unpacker checks if the file looks packed after the first auto-analysis, as described in [Unpacking at database open](#unpacking-at-database-open). A file looks packed when functions use 10% or less of the bytes in its executable segments. | | `default_debugger` | `bochs` | The backend that the heuristics use to run the sample. [`bochs`](/add-ons/malware/concepts/emulators/bochs.md) and [`speakeasy`](/add-ons/malware/concepts/emulators/speakeasy.md) are emulators. With `speakeasy`, the unpacker starts the emulator through the [isolated system emulator](/add-ons/malware/concepts/isolated-system-emulation.md). `win32` is the local Windows debugger, which runs the sample on your system, so the unpacker asks for confirmation first. | | `default_remote` | `false` | If `true`, the unpacker uses the remote debugger at `localhost:23946`, with no password, the path `c:\${FILE}.exe`, and the directory `C:\`. The sample runs on the remote system. | | `allow_unsafe_debugger` | `false` | If `true` and `default_remote` is `true`, the unpacker does not ask for confirmation before it uses the remote debugger. | | `default_stop` | `true` | If `true`, the unpacker stops the process after a successful unpack. | | `brute_force_oep` | `true` | If `true`, the unpacker looks for the original entry point after unpacking. It compares each function with IDA's startup signatures, and names the first match `OriginalEntryPoint`. | | `default_timeout` | `300` | Time limit in seconds for the `run-to-exit-point` and `jumps-other-section` heuristics. | | `default_min_timeout` | `120` | Run time in seconds for the `run-until-timeout` heuristic. This is also the time limit to start or attach the debugger. | | `vt_api_key` | empty | VirusTotal API key. If empty, the `vt-unpack` heuristic is not available. | | `vmray_api_key` | empty | VMRay API key. If empty, the `vmray-unpack` heuristic is not available. | | `vmray_host` | `https://eu.cloud.vmray.com` | URL of the VMRay server, with no trailing slash. | {% hint style="info" %} The [Multi-service Checker](/add-ons/malware/concepts/multi-service-checker.md) has its own `vt_api_key`, `vmray_api_key`, and `vmray_host` settings. To use VirusTotal and VMRay in both features, set the keys in both. {% endhint %} 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/automated-unpacking.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.