diff --git a/README.md b/README.md index f2942921..6c1f96b2 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 @@ -151,7 +151,7 @@ This script adds new user interface elements to IDA, including an interactive tr 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. -![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..d0ac5581 --- /dev/null +++ b/capa/ida/plugin/README.md @@ -0,0 +1,62 @@ +FLARE capa plugin brings the program capabilities detection of [capa](https://github.com/fireeye/capa) to IDA. This plugin adds +new user interface elements including an interactive tree view of rule matches and their locations +within the current database. You can use FLARE capa plugin to dissect capa rules at the assembly level or quickly jump to interesting parts of a program, +such as where the C2 mechanism might be. + +FLARE capa plugin consists of two components: + +* A [feature extractor](https://github.com/fireeye/capa/tree/master/capa/features/extractors/ida) built on top of IDA's powerful binary analysis engine +* An [interactive plugin](https://github.com/fireeye/capa/tree/master/capa/ida/plugin) for displaying and exploring capa rules matched against an IDA database + +![](../../../doc/img/ida_plugin_intro.gif) + +# requirements + +* IDA Pro 7.4+ with Python 2.7 or Python 3.x + +# supported file types + +* Windows `32-bit` and `64-bit` PE files +* Windows `32-bit` and `64-bit` shellcode + +# installation + +## quick install +1. Install capa for the Python interpreter used by your IDA installation: + + ``` + $ pip install flare-capa + ``` + +3. Copy [capa_plugin_ida.py](https://raw.githubusercontent.com/fireeye/capa/master/capa/ida/plugin/capa_plugin_ida.py) to your IDA plugins directory + +## development +1. Install capa for the Python interpreter used by your IDA installation using method 3 of the instructions found [here](https://github.com/fireeye/capa/blob/master/doc/installation.md#method-3-inspecting-the-capa-source-code) +2. Copy [capa_plugin_ida.py](https://raw.githubusercontent.com/fireeye/capa/master/capa/ida/plugin/capa_plugin_ida.py) to your IDA plugins directory + +If you encounter issues with your specific setup, please open a new [Issue](https://github.com/fireeye/capa/issues). + +# usage +1. Run IDA and analyze a supported file type (select `Manual Load` and `Load Resources` for best results) +2. Open FLARE capa plugin in IDA by navigating to `Edit > Plugins > FLARE capa plugin` or using the keyboard shortcut `Alt+F5` +3. Click `Analyze` + +When running the plugin for the first time you are prompted to select a file directory containing capa rules. The plugin conviently +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 first getting familiar with the plugin but any +file directory containing [valid capa rules](https://github.com/fireeye/capa-rules/blob/master/doc/format.md) can be used. + +# features +* Display capa results in an interactive tree view of rule matches and their locations in the current database +* 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...` +* 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 +* Reset tree view and IDA Disassembly view highlighting by clicking `Reset` +* 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 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 750721f1..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_plugin_ida.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.