> 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

This page walks you through the installation of the add-on and your first steps with Malware Analysis in IDA.

## Installation

After you add Malware Analysis to your IDA license in the Hex-Rays portal, the install is usually one HCLI command.

### Requirements

* IDA Pro 9.5 or later, with a license that includes the Malware Analysis add-on. Upgrade your license now 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.

### Install with HCLI

Most users install with HCLI, the Hex-Rays command-line tool. HCLI 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 following 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, and update HCLI to 0.27.0 or later. To make sure that the license includes the add-on, run `hcli license list` and look for `MALWARE` in the Addons column. 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, for example `malware-analysis-bundle-v1.0.0.zip`. The bundle contains all that you need to install the add-on on all supported platforms and Python versions, and it is approximately 900 MB. Download it with HCLI:

   ```bash
   hcli login
   hcli download release/extensions/malware-analysis/1.0.0/offline/malware-analysis-bundle-v1.0.0.zip
   ```

   For a different version, change `1.0.0` in the two places. To select the file from a list, run `hcli download` with no argument, and go to `release/extensions/malware-analysis/<version>/offline`.

   You can also download the bundle from the portal. Go to **Download center → Installers → Release → Extensions → Malware Analysis →&#x20;*****version*****&#x20;→ Offline**. The bundle has the name "Malware Analysis offline bundle" and the version. Do not use the file in the *version* folder. HCLI downloads that file for an online install, and it does not contain the Python packages.

   ![The offline bundle in the Offline folder of the Download center in the Hex-Rays portal](https://492083732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFP6ibt8r6WPBHTqekG9u%2Fuploads%2Fgit-blob-5dccd09f56316aa6772b98873b413267ab1c53f9%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.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

HCLI does not know about your floating license, so install the add-on from the offline bundle, with the steps in [Install offline](#install-offline). Then, when you check out a floating license that includes Malware Analysis, the add-on works in IDA.

The portal and HCLI show the bundle only to an account with a license that includes Malware Analysis. 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 <support@hex-rays.com>.

### Verify the installation

Restart IDA and open a database. The **Extensions → Malware Analysis** menu shows:

![The Malware Analysis menu with the Unpacking group open](https://492083732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFP6ibt8r6WPBHTqekG9u%2Fuploads%2Fgit-blob-cc08a7b924d8d65188283c7ad0aada9733e3e194%2Fverify-menu.jpeg?alt=media)

`hcli extension status malware-analysis` also shows the installed version.

If the menu items are greyed out, IDA did not find the add-on. Install it if necessary, and then restart IDA. If the menu does not show at all, look in the Output window. When your IDA license does not include Malware Analysis, the add-on is installed but does not load, and the Output window shows:

```
malware analysis: your IDA license does not include the Malware Analysis add-on
```

To see the add-ons in your license, open **Help → License manager...** and look for `MALWARE` in the Add-ons column. If it is not there, upgrade your license in the [Hex-Rays portal](https://my.hex-rays.com).

![The License manager with MALWARE in the Add-ons column](https://492083732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFP6ibt8r6WPBHTqekG9u%2Fuploads%2Fgit-blob-063f4bc20c97215561ad820f8c1ea31b8e6fde06%2Flicense-manager-malware.png?alt=media)

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. If you turned on INFO logging for IDAPython, the Output window also shows the add-on version when the add-on loads.

### 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<version>.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, such as Triage, Unpacking, Data Transformation, 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 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\...** (<kbd>Shift</kbd> + <kbd>P</kbd>). 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** (<kbd>Shift</kbd> + <kbd>U</kbd>). 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 uses its own API keys, so you may have to set your VirusTotal key more than one time, in the checker and in the unpacker. 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.

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 behavior, 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) runs the sample in an emulator, where you step through its code with IDA's debugger controls.
* [Sandbox Integration](/add-ons/malware/concepts/sandbox-integration.md) shows the results of VMRay and Speakeasy runs in the disassembly, next to the code that caused them.
* [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 <support@hex-rays.com>. 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=<question>&goal=<user_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.
