diff --git a/README.md b/README.md index e11b3580..71b5a5e4 100644 --- a/README.md +++ b/README.md @@ -149,8 +149,8 @@ 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 can use the [capa explorer plugin](capa/ida/plugin/). -capa explorer lets you quickly identify and navigate to interesting areas of a program and help you build new capa rules out of the features extracted directly from your IDB. +If you use IDA Pro, then you can use the [capa explorer](capa/ida/plugin/) plugin. +capa explorer helps you identify interesting areas of a program and build new capa rules using features extracted directly from your IDA Pro database. ![capa + IDA Pro integration](doc/img/explorer_expanded.png) diff --git a/capa/ida/plugin/README.md b/capa/ida/plugin/README.md index 54306b89..aea42c58 100644 --- a/capa/ida/plugin/README.md +++ b/capa/ida/plugin/README.md @@ -1,13 +1,12 @@ ![capa explorer](../../../.github/capa-explorer-logo.png) -capa explorer is an IDA Pro plugin written in Python 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 +capa explorer is an IDAPython plugin that integrates the FLARE team's open-source framework, capa, with IDA Pro. 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. You can use capa explorer to run capa directly on an IDA database without requiring access -to or execution of 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 manually build new capa rules out -of the features extracted directly from your IDB. +the program is a backdoor, can install services, or relies on HTTP to communicate. capa explorer runs capa directly against your IDA Pro database (IDB) without requiring access +to the original binary file. Once a database has been analyzed, capa explorer helps you identify interesting areas of a program and build new capa rules using features extracted from your IDB. We love using capa explorer during malware analysis because it teaches us what parts of a program suggest a behavior. As we click on rows, capa explorer jumps directly -to important addresses in the IDA Pro database and highlights key features in the Disassembly view so they stand out visually. To illustrate, we use capa explorer to +to important addresses in the IDB and highlights key features in the Disassembly view so they stand out visually. 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. @@ -15,16 +14,15 @@ After loading Lab 14-02 into IDA and analyzing the database with capa explorer, ![](../../../doc/img/explorer_condensed.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. +We can use capa explorer to navigate our Disassembly view directly to the suspect function and get an assembly-level breakdown of why capa matched `self delete via COMSPEC environment variable`. ![](../../../doc/img/explorer_expanded.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 calls to the Windows API functions `GetEnvironmentVariableA` and `ShellExecuteEx`. +and `query environment variable`, references to the strings `COMSPEC`, ` > nul`, and `/c del `, and calls to the Windows API functions `GetEnvironmentVariableA` and `ShellExecuteEx`. -capa explorer also helps you build new capa rules. To start select the `Rule Generator` tab, navigate to a function in the IDA `Disassembly` view, -and click `Analyze`. capa explorer will extract features from this function and display them in the `Function Features` pane. You can add features listed in this pane to the `Editor` pane +capa explorer also helps you build new capa rules. To start select the `Rule Generator` tab, navigate to a function in your Disassembly view, +and click `Analyze`. capa explorer will extract features from the function and display them in the `Features` pane. You can add features listed in this pane to the `Editor` pane by either double-clicking a feature or using multi-select + right-click to add multiple features at once. The `Preview` and `Editor` panes help edit your rule. Use the `Preview` pane to modify the rule text directly and the `Editor` pane to construct and rearrange your hierarchy of statements and features. When you finish a rule you can save it directly to a file by clicking `Save`. @@ -44,7 +42,7 @@ If you encounter issues with your specific setup, please open a new [Issue](http ### Supported File Types -capa explorer is limited to the file types supported by capa, which includes: +capa explorer is limited to the file types supported by capa, which include: * Windows 32-bit and 64-bit PE files * Windows 32-bit and 64-bit shellcode @@ -62,50 +60,48 @@ You can install capa explorer using the following steps: ### Usage -1. Run IDA and analyze a supported file type (select the `Manual Load` and `Load Resources` options in IDA for best results) +1. Open IDA and analyze a supported file type (select the `Manual Load` and `Load Resources` options in IDA 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. Select the `Program Analysis` tab 4. Click the `Analyze` button 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 `Settings > Change default rules directory...`. We recommend +remembers your selection for future runs; you can change this selection and other default settings by clicking `Settings`. We recommend downloading and using the [standard collection of capa rules](https://github.com/fireeye/capa-rules) when getting started with the plugin. #### Tips for Program Analysis * Start analysis by clicking the `Analyze` button -* Reset the plugin user interface and remove highlighting from IDA disassembly view by clicking the `Reset` button -* Change your capa rules directory by navigating to `Settings > Change default rules directory...` from the plugin menu +* Reset the plugin user interface and remove highlighting from your Disassembly view by clicking the `Reset` button +* Change your capa rules directory and other default settings by clicking `Settings` * 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 the `Address` column to navigate your Disassembly view to the address of 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 +* Select a checkbox in the `Rule Information` column to highlight the address of the associated feature in your Dissasembly view #### Tips for Rule Generator -* Navigate to a function in the `Disassembly` view and click`Analyze` to get started -* Double-click or multi-select + right-click in the `Function Features` pane to add features to the `Editor` pane -* Right-click features in the `Editor` pane to make modifications -* Drag-and-drop (single click + multi-select support) features in the `Editor` pane to quickly build a hierarchy of statements and features -* Right-click anywhere in the `Editor` pane not on a feature to quickly remove all features -* Add descriptions/comments by placing editing the appropriate column in the `Editor` pane -* Directly edit rule text, including rule metadata fields using the `Preview` pane -* Change the default rule author and default scope displayed in the `Preview` pane by navigating to `Settings` +* Navigate to a function in your Disassembly view and click`Analyze` to get started +* Double-click or use multi-select + right-click to add features from the `Features` pane to the `Editor` pane +* Right-click features in the `Editor` pane to make context-specific modifications +* Drag-and-drop (single click + multi-select support) features in the `Editor` pane to construct your hierarchy of statements and features +* Right-click anywhere in the `Editor` pane not on a feature to remove all features +* Add descriptions or comments to a feature by editing the corresponding column in the `Editor` pane +* Directly edit rule text and metadata fields using the `Preview` pane +* Change the default rule author and default rule scope displayed in the `Preview` pane by clicking `Settings` ## 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 +capa explorer is packaged with capa so 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/master/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. +to your plugins directory to install capa explorer 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, +* An [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 your IDBs 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 user interface](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 + * This component integrates the feature extractor and capa, providing an interactive user interface to dissect rule matches found by capa using features extracted directly from your IDBs diff --git a/doc/img/explorer_condensed.png b/doc/img/explorer_condensed.png index bd3cdcb4..8372cdd0 100644 Binary files a/doc/img/explorer_condensed.png and b/doc/img/explorer_condensed.png differ diff --git a/doc/img/explorer_expanded.png b/doc/img/explorer_expanded.png index a2f82e45..26cbbad7 100644 Binary files a/doc/img/explorer_expanded.png and b/doc/img/explorer_expanded.png differ diff --git a/doc/img/rulegen_expanded.png b/doc/img/rulegen_expanded.png index c3c4d0ee..5b3e5816 100644 Binary files a/doc/img/rulegen_expanded.png and b/doc/img/rulegen_expanded.png differ