> 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/getting-started.md). # Getting Started ## Installation ### Requirements * IDA Pro 9.5 or later, with a license that includes the Malware Analysis add-on. You buy the add-on in the [Hex-Rays portal](https://my.hex-rays.com). IDA Free and IDA Home are not supported. * Python 3.10 to 3.14, in a dedicated virtual environment as described in [IDAPython environment](/getting-started/idapython-environment.md) * [HCLI](https://hcli.docs.hex-rays.com) 0.27.0 or later * Windows x64, Linux x64, Linux arm64, or macOS on Apple silicon. macOS on Intel and Windows on ARM64 are not supported. Without the add-on in your license, HCLI does not find it. If you install it anyway, the menu items do not work, and the Output window shows "your IDA license does not include the Malware Analysis add-on". {% hint style="info" %} CyberChef is a separate, optional plugin. HCLI installs it together with the add-on when Node.js and npm are available. If they are not, HCLI skips CyberChef, and the CyberChef menu item does not show. CyberChef is not in the offline bundle, and it turns itself off on Python 3.13.0 to 3.13.12 and 3.14.0. See [CyberChef](/add-ons/malware/concepts/cyberchef.md). {% endhint %} ### Install with HCLI Most users install with HCLI. It downloads the add-on from the Hex-Rays portal, together with everything the add-on needs. For an offline machine or a floating license, see the next sections. ```bash hcli login hcli extension install hexrays/malware-analysis ``` Then restart IDA if it is open. If HCLI cannot find `hexrays/malware-analysis`, run `hcli login` with the account that holds the license, make sure that the license includes the add-on, and update HCLI to 0.27.0 or later. If the install stops with a Python error, run `hcli ida python doctor` to check your IDA Python environment. ### Install offline Use this method on a machine with no internet access, for example in an air-gapped network. 1. On a machine with internet access, download the offline bundle from the portal, in **Download center → Installers → Release → Extensions → Malware Analysis**, in the folder of the version that you want. The file name has the version of the add-on, for example `malware-analysis-bundle-v1.0.zip`. One bundle covers all supported platforms and Python versions. ![The Malware Analysis folder in the Download center of the Hex-Rays portal](https://492083732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFP6ibt8r6WPBHTqekG9u%2Fuploads%2Fgit-blob-9e228692c6a5f4baf99e3fd5ee0d3e0344495840%2Fportal-download-center.png?alt=media) 2. Copy the bundle and HCLI to the offline machine. This machine needs the same [requirements](#requirements) as above. 3. Install from the bundle: ```bash hcli extension --repo /path/to/malware-analysis-bundle-v1.0.zip --offline install malware-analysis ``` `--offline` tells HCLI to install Python packages only from the bundle, so it does not try to reach the internet. ### Install with a floating license The add-on works with a floating license that includes Malware Analysis. Install it from the offline bundle, with the steps in [Install offline](#install-offline). You may need extra steps to download the bundle, for example when your portal account cannot see it. In that case, ask your license administrator, or email . ### Update and uninstall To see the installed version and whether an update is available: ```bash hcli extension status malware-analysis ``` To update, run this command, then restart IDA: ```bash hcli extension upgrade hexrays/malware-analysis ``` To update from a new offline bundle: ```bash hcli extension --repo /path/to/malware-analysis-bundle-v.zip --offline upgrade malware-analysis ``` To uninstall: ```bash hcli extension uninstall malware-analysis ``` HCLI then asks if it should also remove the dependencies that came with the add-on. The uninstall keeps your settings and API keys (in `ida-config.json` in your IDA user directory), the Python packages, and the data that the add-on saved in your databases. If you install the add-on again, it uses the same settings. ## First use The add-on adds the **Extensions → Malware Analysis** menu to IDA. The menu has one group for each step of an analysis: Triage, Unpacking, Data Transformation (only when CyberChef is installed), Emulation, and Sandbox. ![Malware Analysis menu with the Sandbox group open](https://492083732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFP6ibt8r6WPBHTqekG9u%2Fuploads%2Fgit-blob-9741bd9c3b968abc63265331ea02febeb921e4c6%2Fmenu.png?alt=media) The menu items show after you open a database. If the items are greyed out, IDA did not find the add-on. Run `hcli extension status malware-analysis` to see if HCLI installed it, install it if necessary, and then restart IDA. If the items do not show at all, look in the Output window. The message "your IDA license does not include the Malware Analysis add-on" means that you must get the add-on for your license in the [Hex-Rays portal](https://my.hex-rays.com). A message with "cannot import" and "not loading" means that the install is broken: run `hcli ida python doctor`, and then uninstall and install the add-on again. The add-on also adds a toolbar button with a magic-wand icon to the Analysis toolbar. Click it to step through the sample in the [isolated system emulator](/add-ons/malware/concepts/isolated-system-emulation.md). The button is disabled when the database is not a PE file. When you open a packed PE file, the add-on asks if it should unpack the sample. It asks one time for each database. ![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) Click **Yes** to unpack. Before it unpacks, the add-on takes a database snapshot, so you can go back to the packed sample with IDA's database snapshot manager. If you click **No**, you can unpack later with **Malware Analysis → Unpacking → Unpack now\...** (Shift + P). For a full example, see [Unpack a Malware Sample](/add-ons/malware/how-tos/unpack-a-malware-sample.md). To look up the sample on VirusTotal, VMRay, and MalwareBazaar, use **Malware Analysis → Triage → Services Checker** (Shift + U). Each service needs an API key, which you set in **Malware Analysis → Triage → Configure Services Checker...**. The checker sends no requests to a service that has no API key. ### Default behavior and configuration To change the settings of all features, use **Malware Analysis → Settings...**. Most groups also have a **Configure** item for the settings of their feature, such as **Malware Analysis → Unpacking → Configure unpacker...**. Each feature has its own API keys. The add-on reads the settings when an action starts, so a change applies immediately. You do not have to restart IDA or open the database again. With no API keys, you can: * unpack with the Bochs or Speakeasy emulators. The unpacker uses Bochs by default, so the sample does not run on your system. * start interactive emulation with Speakeasy. * run the Speakeasy sandbox and show its trace on the code. * decode data with CyberChef, if it is installed. In idalib, the add-on unpacks a packed PE file automatically when you open it, with no prompt. It never uses a debugger that runs the sample on your system. 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 this check, set `ask_at_startup` to false in the unpacker settings, or set the environment variable `IDA_MALWARE_DISABLE_UNPACKER=1`. ## Next steps The concept pages explain how each feature works and how to configure it: * [Multi-service Checker](/add-ons/malware/concepts/multi-service-checker.md) looks up the sample on public and commercial malware services. * [Automated Unpacking](/add-ons/malware/concepts/automated-unpacking.md) detects packed samples on load and unpacks them in place. * [Isolated System Emulation](/add-ons/malware/concepts/isolated-system-emulation.md) lets you step through code safely with IDA's debugger controls. * [Sandbox Integration](/add-ons/malware/concepts/sandbox-integration.md) shows VMRay and Speakeasy runs on the code. * [CyberChef](/add-ons/malware/concepts/cyberchef.md) decodes and transforms data with CyberChef recipes in IDA. To find out which features connect to the network and what they send, see [Network and Data Sharing](/add-ons/malware/network-and-data.md). 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/getting-started.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.