> 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/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 unpack manually with the [isolated system emulator](/ida-9.5/add-ons/malware/concepts/isolated-system-emulation.md), as shown in [Manually unpack UPX with the isolated system emulator](/ida-9.5/add-ons/malware/how-tos/manually-unpack-upx.md). The Automated Unpacker Framework generally has good support for packers like: UPX, MPRESS, ASPack, RLPack, NSPack, WinUpack, and Packman. It has some support for other packers like PECompact, PEtite, and Themida. As always, based on your needs and feedback, we can prioritize further support, so please reach out. ## Algorithms The unpacker has several heuristics. To select one, use **Malware Analysis > Unpacker > 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. | ## Rebuilding PE and ELF files In order to integrate with other systems that expect code in a PE or ELF format, you can use the "Binary Dumper" to rebuild executable files from the unpacked view in IDA. This will create a fairly good representation of the unpacked code, entry point, and IAT; however, do not expect that this file will be runnable. Fortunately, this is often enough to pass into Yara scanners, code indexers, or sample curation systems. ## Configuration To change the settings, select **Malware Analysis > Unpacker > Configure...**, or use HCLI: ```bash hcli extension config ida-unpacker-framework set default_debugger sogen ``` Restart IDA after you change a setting. | Setting | Default | Description | | --------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ask_at_startup` | `true` | If `true`, the unpacker checks if the binary looks packed after the first auto-analysis, and asks you to unpack it. It does this one time for each database, for PE and ELF files on x86, x64, and ARM. A binary 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`](/ida-9.5/add-ons/malware/concepts/bochs.md), [`speakeasy`](/ida-9.5/add-ons/malware/concepts/speakeasy.md), and [`sogen`](/ida-9.5/add-ons/malware/concepts/sogen.md) are emulators. With `speakeasy` or `sogen`, the unpacker starts the emulator through the [isolated system emulator](/ida-9.5/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. `IDC:start_emulator()` uses the backend that you select for [isolated system emulation](/ida-9.5/add-ons/malware/concepts/isolated-system-emulation.md). | | `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:\`. | | `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](/ida-9.5/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 components, set the keys in both. {% endhint %} --- # 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/automated-unpacking.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.