diff --git a/README.md b/README.md index f2942921..13f0d3b4 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ Alternatively, you can fetch a nightly build of a standalone binary from one of To use capa as a library or integrate with another tool, see [doc/installation.md](doc/installation.md) for further setup instructions. -For more information about how to use capa, including running it as an IDA script/plugin see [doc/usage.md](doc/usage.md). +For more information about how to use capa, see [doc/usage.md](doc/usage.md). # example @@ -146,12 +146,11 @@ rule: The [github.com/fireeye/capa-rules](https://github.com/fireeye/capa-rules) repository contains hundreds of standard library rules that are distributed with capa. Please learn to write rules and contribute new entries as you find interesting techniques in malware. -If you use IDA Pro, then you use can use the [IDA Pro plugin for capa](capa/ida/plugin/). -This script adds new user interface elements to IDA, including an interactive tree view of rule matches and their locations within the current database. -As you select the checkboxes, the plugin will highlight the addresses associated with the features. -We use this plugin all the time to quickly jump to interesting parts of a program. +If you use IDA Pro, then you use can use the [capa explorer IDA plugin](capa/ida/plugin/). +capa explorer lets you quickly identify and navigate to interesting areas of a program and dissect capa rule matches at +the assembly level. -![capa + IDA Pro integration](.github/capa-ida.jpg) +![capa + IDA Pro integration](doc/img/ida_plugin_intro.gif) # further information ## capa diff --git a/capa/ida/plugin/README.md b/capa/ida/plugin/README.md new file mode 100644 index 00000000..3cd10574 --- /dev/null +++ b/capa/ida/plugin/README.md @@ -0,0 +1,111 @@ +# capa explorer + +capa explorer is an IDA Pro plugin that integrates the FLARE team's open-source framework, capa, with IDA. capa is a framework that uses a well-defined collection of rules to +identify capabilities in a program. You can run capa against a PE file or shellcode and it tells you what it thinks the program can do. For example, it might suggest that +the program is a backdoor, can install services, or relies on HTTP to communicate. + +The capa explorer IDA plugin brings capa's detection capabilities to IDA. You can use capa explorer to run capa directly on an IDA database without needing access +to the source binary. Once a database has been analyzed, capa explorer can be used to quickly identify and navigate to interesting areas of a program +and dissect capa rule matches at the assembly level. + +To illustrate, we use capa explorer to analyze Lab 14-02 from [Practical Malware Analysis](https://nostarch.com/malware) (PMA) available [here](https://practicalmalwareanalysis.com/labs/). Our +goal is to understand the program's functionality. + +After loading Lab 14-02 into IDA and analyzing the database with capa explorer, we see that capa detected a rule match for `self delete via COMSPEC environment variable`: + +![](../../../doc/img/ida_plugin_example_1.png) + +We can use capa explorer to navigate the IDA Disassembly view directly to the suspect function and get an assembly-level breakdown of why capa matched `self delete via COMSPEC environment variable` +for this particular function. + +![](../../../doc/img/ida_plugin_example_2.png) + +Using the `Rule Information` and `Details` columns capa explorer shows us that the suspect function matched `self delete via COMSPEC environment variable` because it contains capa rule matches for `create process`, `get COMSPEC environment variable`, +and `query environment variable`, references to the strings `COMSPEC`, ` > nul`, and `/c del`, and a call to the Windows API function `GetEnvironmentVariableA`. + +For more information on the FLARE team's open-source framework, capa, check out the overview in our first [blog](https://www.fireeye.com/blog/threat-research/2020/07/capa-automatically-identify-malware-capabilities.html). + +## Features + +![](../../../doc/img/ida_plugin_intro.gif) + +* Display capa results in an interactive tree view of rule matches and their locations in the current database +* Search for keywords or phrases found in the `Rule Information`, `Address`, or `Details` columns +* Display rule source content when a user hovers their cursor over a rule match +* Double-click `Address` column to view associated feature in the IDA Disassembly view +* Limit tree view results to the function currently displayed in the IDA Disassembly view; update results as a user navigates to different functions +* Export results as formatted JSON by navigating to `File > Export results...` +* Remember a user's capa rules directory for future runs; change capa rules directory by navigating to `Rules > Change rules directory...` +* Automatically re-analyze database when user performs a program rebase +* Automatically update results when IDA is used to rename a function +* Select one or more checkboxes to highlight the associated addresses in the IDA Disassembly view +* Right-click a function match to rename it; the new function name is propagated to the current IDA database +* Right-click to copy a result by column or by row +* Sort results by column +* Reset tree view and IDA Disassembly view highlighting by clicking `Reset` + +## Getting Started + +### Requirements + +capa explorer supports the following IDA setups: + +* IDA Pro 7.4+ with Python 2.7 or Python 3. + +If you encounter issues with your specific setup, please open a new [Issue](https://github.com/fireeye/capa/issues). + +### Supported File Types + +capa explorer is limited to the file types supported by capa, which includes: + +* Windows 32-bit and 64-bit PE files +* Windows 32-bit and 64-bit shellcode + +### Installation + +You can install capa explorer using the following steps: + +1. Install capa for the Python interpreter used by your IDA installation: + ``` + $ pip install flare-capa + ``` +3. Download the [standard collection of capa rules](https://github.com/fireeye/capa-rules) (capa explorer needs capa rules to analyze a database) +4. Copy [capa_explorer.py](https://raw.githubusercontent.com/fireeye/capa/master/capa/ida/plugin/capa_explorer.py) to your IDA plugins directory + +### Usage + +1. Run IDA and analyze a supported file type (select `Manual Load` and `Load Resources` for best results) +2. Open capa explorer in IDA by navigating to `Edit > Plugins > FLARE capa explorer` or using the keyboard shortcut `Alt+F5` +3. Click `Analyze` + +When running capa explorer for the first time you are prompted to select a file directory containing capa rules. The plugin conveniently +remembers your selection for future runs; you can change this selection by navigating to `Rules > Change rules directory...`. We recommend +downloading and using the [standard collection of capa rules](https://github.com/fireeye/capa-rules) when getting started with the plugin. + +#### Tips + +* Start analysis by clicking `Analyze` +* Reset the plugin user interface and remove highlighting from IDA disassembly view by clicking `Reset` +* Change your capa rules directory by navigating to `Rules > Change rules directory...` +* Hover your cursor over a rule match to view the source content of the rule +* Double-click the `Address` column to navigate the IDA Disassembly view to the associated feature +* Double-click a result in the `Rule Information` column to expand its children +* Select a checkbox in the `Rule Information` column to highlight the address of the associated feature in the IDA Dissasembly view + +## Development + +Because capa explorer is packaged with capa you will need to install capa locally for development. + +You can install capa locally by following the steps outlined in `Method 3: Inspecting the capa source code` of the [capa +installation guide](https://github.com/fireeye/capa/blob/ida_plugin_documentation/doc/installation.md#method-3-inspecting-the-capa-source-code). Once installed, copy [capa_explorer.py](https://raw.githubusercontent.com/fireeye/capa/master/capa/ida/plugin/capa_explorer.py) +to your IDA plugins directory to run the plugin in IDA. + +### Components + +capa explorer consists of two main components: + +* An IDA [feature extractor](https://github.com/fireeye/capa/tree/master/capa/features/extractors/ida) built on top of IDA's binary analysis engine + * This component uses IDAPython to extract [capa features](https://github.com/fireeye/capa-rules/blob/master/doc/format.md#extracted-features) from the IDA database such as strings, +disassembly, and control flow; these extracted features are used by capa to find feature combinations that result in a rule match +* An [interactive plugin](https://github.com/fireeye/capa/tree/master/capa/ida/plugin) for displaying and exploring capa rule matches + * This component integrates the IDA feature extractor and capa, providing an interactive user interface to dissect rule matches found by capa using features extracted by the IDA feature extractor diff --git a/doc/img/capa_explorer.png b/doc/img/capa_explorer.png deleted file mode 100644 index f997c935..00000000 Binary files a/doc/img/capa_explorer.png and /dev/null differ diff --git a/doc/img/ida_plugin_example_1.png b/doc/img/ida_plugin_example_1.png new file mode 100644 index 00000000..d9f727e5 Binary files /dev/null and b/doc/img/ida_plugin_example_1.png differ diff --git a/doc/img/ida_plugin_example_2.png b/doc/img/ida_plugin_example_2.png new file mode 100644 index 00000000..0d85d515 Binary files /dev/null and b/doc/img/ida_plugin_example_2.png differ diff --git a/doc/img/ida_plugin_intro.gif b/doc/img/ida_plugin_intro.gif new file mode 100644 index 00000000..b44d6381 Binary files /dev/null and b/doc/img/ida_plugin_intro.gif differ diff --git a/doc/usage.md b/doc/usage.md index 422aa965..ea9547cb 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -12,27 +12,3 @@ See `capa -h` for all supported arguments and usage examples. Use the `-t` option to run rules with the given metadata value (see the rule fields `rule.meta.*`). For example, `capa -t william.ballenthin@mandiant.com` runs rules that reference Willi's email address (probably as the author), or `capa -t communication` runs rules with the namespace `communication`. - -### IDA Pro integrations -You can run capa from within IDA Pro. Run `capa/main.py` via `File - Script file...` (or ALT + F7). -When running in IDA, capa uses IDA's disassembly and file analysis as its backend. -These results may vary from the standalone version that uses vivisect. -IDA's analysis is generally a bit faster and more thorough than vivisect's, so you might prefer this mode. - -When run under IDA, capa supports both Python 2 and Python 3 interpreters. -If you encounter issues with your specific setup, please open a new [Issue](https://github.com/fireeye/capa/issues). - -Additionally, capa comes with an IDA Pro plugin located in the `capa/ida/plugin` directory: the explorer. - -#### capa explorer -The capa explorer allows you to interactively display and browse capabilities capa identified in a binary. -As you select rules or logic, capa will highlight the addresses that support its analysis conclusions. -We like to use capa to help find the most interesting parts of a program, such as where the C2 mechanism might be. - -![capa explorer](img/capa_explorer.png) - -The plugin currently supports IDA Pro 7.1 through 7.5 with either Python 2 or Python 3. To use the plugin, install capa -by following method 2 or 3 from the [installation guide](installation.md) and copy [capa_plugin_ida.py](../capa/ida/plugin/capa_explorer.py) -to the plugins directory of your IDA Pro installation. Following these steps you can run capa explorer in IDA Pro by navigating -to `Edit > Plugins > capa explorer`. The plugin will prompt you to select a rules directory to use for analysis. You can -use the [default rule set](https://github.com/fireeye/capa-rules/) or point the plugin to your own directory of rules.