## File: README.md --- capa detects capabilities in executable files. You run it against a PE, ELF, .NET module, shellcode file, or a sandbox report and it tells you what it thinks the program can do. For example, it might suggest that the file is a backdoor, is capable of installing services, or relies on HTTP to communicate. To interactively inspect capa results in your browser use the [capa Explorer Web](https://mandiant.github.io/capa/explorer/). If you want to inspect or write capa rules, head on over to the [capa-rules repository](https://github.com/mandiant/capa-rules). Otherwise, keep reading. Below you find a list of [our capa blog posts with more details.](#blog-posts) # example capa output ``` /* Detailed source-code truncated for AI context efficiency. */ ``` # download and usage Download stable releases of the standalone capa binaries [here](https://github.com/mandiant/capa/releases). You can run the standalone binaries without installation. capa is a command line tool that should be run from the terminal. To use capa as a library or integrate with another tool, see [doc/installation.md](https://github.com/mandiant/capa/blob/master/doc/installation.md) for further setup instructions. **Documentation:** [Usage and tips](doc/usage.md) · [Installation](doc/installation.md) · [Limitations](doc/limitations.md) · [FAQ](doc/faq.md) # capa Explorer Web The [capa Explorer Web](https://mandiant.github.io/capa/explorer/) enables you to interactively explore capa results in your web browser. Besides the online version you can download a standalone HTML file for local offline usage. More details on the web UI is available in the [capa Explorer Web README](https://github.com/mandiant/capa/blob/master/web/explorer/README.md). # example In the above sample output, we run capa against an unknown binary (`suspicious.exe`), and the tool reports that the program can send HTTP requests, decode data via XOR and Base64, install services, and spawn new processes. Taken together, this makes us think that `suspicious.exe` could be a persistent backdoor. Therefore, our next analysis step might be to run `suspicious.exe` in a sandbox and try to recover the command and control server. ## detailed results By passing the `-vv` flag (for very verbose), capa reports exactly where it found evidence of these capabilities. This is useful for at least two reasons: - it helps explain why we should trust the results, and enables us to verify the conclusions, and - it shows where within the binary an experienced analyst might study with IDA Pro ``` $ capa.exe suspicious.exe -vv ... execute shell command and capture output namespace c2/shell author matthew.williams@mandiant.com scope function att&ck Execution::Command and Scripting Interpreter::Windows Command Shell [T1059.003] references https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-startupinfoa function @ 0x4011C0 and: match: create a process with modified I/O handles and window @ 0x4011C0 and: number: 257 = STARTF_USESTDHANDLES | STARTF_USESHOWWINDOW @ 0x4012B8 or: number: 68 = StartupInfo.cb (size) @ 0x401282 or: = API functions that accept a pointer to a STARTUPINFO structure api: kernel32.CreateProcess @ 0x401343 match: create pipe @ 0x4011C0 or: api: kernel32.CreatePipe @ 0x40126F, 0x401280 optional: match: create thread @ 0x40136A, 0x4013BA or: and: os: windows or: api: kernel32.CreateThread @ 0x4013D7 or: and: os: windows or: api: kernel32.CreateThread @ 0x401395 or: string: "cmd.exe" @ 0x4012FD ... ``` # dynamic capa capa also supports dynamic capabilities detection for multiple sandboxes including: * [CAPE](https://github.com/kevoreilly/CAPEv2) (supported report formats: `.json`, `.json_`, `.json.gz`) * [DRAKVUF](https://github.com/CERT-Polska/drakvuf-sandbox/) (supported report formats: `.log`, `.log.gz`) * [VMRay](https://www.vmray.com/) (supported report formats: analysis archive `.zip`) To use this feature, submit your file to a supported sandbox and then download and run capa against the generated report file. This feature enables capa to match capabilities against dynamic and static features that the sandbox captured during execution. Here's an example of running capa against a packed file, and then running capa against the CAPE report generated for the same packed file: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` # capa rules capa uses a collection of rules to identify capabilities within a program. These rules are easy to write, even for those new to reverse engineering. By authoring rules, you can extend the capabilities that capa recognizes. In some regards, capa rules are a mixture of the OpenIOC, Yara, and YAML formats. Here's an example rule used by capa: ```yaml rule: meta: name: create TCP socket namespace: communication/socket/tcp authors: - william.ballenthin@mandiant.com - joakim@intezer.com - anushka.virgaonkar@mandiant.com scopes: static: basic block dynamic: call mbc: - Communication::Socket Communication::Create TCP Socket [C0001.011] examples: - Practical Malware Analysis Lab 01-01.dll_:0x10001010 features: - or: - and: - number: 6 = IPPROTO_TCP - number: 1 = SOCK_STREAM - number: 2 = AF_INET - or: - api: ws2_32.socket - api: ws2_32.WSASocket - api: socket - property/read: System.Net.Sockets.TcpClient::Client ``` The [github.com/mandiant/capa-rules](https://github.com/mandiant/capa-rules) repository contains hundreds of standard rules that are distributed with capa. Please learn to write rules and contribute new entries as you find interesting techniques in malware. # IDA Pro plugin: capa explorer If you use IDA Pro, then you can use the [capa explorer](https://github.com/mandiant/capa/tree/master/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. It also uses your local changes to the .idb to extract better features, such as when you rename a global variable that contains a dynamically resolved API address. # Ghidra integration capa supports using Ghidra (via [PyGhidra](https://github.com/NationalSecurityAgency/ghidra/tree/master/Ghidra/Features/PyGhidra)) as a feature extraction backend. This allows you to run capa against binaries using Ghidra's analysis engine. You can run and view capa results in the Ghidra UI using [capa explorer for Ghidra](https://github.com/mandiant/capa/tree/master/capa/ghidra/plugin). You can also run capa from the command line using the [Ghidra backend](https://github.com/mandiant/capa/tree/master/capa/ghidra). # blog posts - [Riding Dragons: capa Harnesses Ghidra](https://www.mandiant.com/resources/blog/capa-harnesses-ghidra) - [Dynamic capa: Exploring Executable Run-Time Behavior with the CAPE Sandbox](https://www.mandiant.com/resources/blog/dynamic-capa-executable-behavior-cape-sandbox) - [capa v4: casting a wider .NET](https://www.mandiant.com/resources/blog/capa-v4-casting-wider-net) (.NET support) - [ELFant in the Room – capa v3](https://www.mandiant.com/resources/elfant-in-the-room-capa-v3) (ELF support) - [capa 2.0: Better, Stronger, Faster](https://www.mandiant.com/resources/capa-2-better-stronger-faster) - [capa: Automatically Identify Malware Capabilities](https://www.mandiant.com/resources/capa-automatically-identify-malware-capabilities) # further information ## capa - [Installation](https://github.com/mandiant/capa/blob/master/doc/installation.md) - [Usage](https://github.com/mandiant/capa/blob/master/doc/usage.md) - [Limitations](https://github.com/mandiant/capa/blob/master/doc/limitations.md) - [Contributing Guide](https://github.com/mandiant/capa/blob/master/.github/CONTRIBUTING.md) ## capa rules - [capa-rules repository](https://github.com/mandiant/capa-rules) - [capa-rules rule format](https://github.com/mandiant/capa-rules/blob/master/doc/format.md) ## capa testfiles The [capa-testfiles repository](https://github.com/mandiant/capa-testfiles) contains the data we use to test capa's code and rules ## mailing list Subscribe to the FLARE mailing list for community announcements! Email "subscribe" to [flare-external@google.com](mailto:flare-external@google.com?subject=subscribe). --- ## File: capa/ghidra/README.md # capa analysis using Ghidra capa supports using Ghidra (via [PyGhidra](https://github.com/NationalSecurityAgency/ghidra/tree/master/Ghidra/Features/PyGhidra)) as a feature extraction backend. This enables you to run capa against binaries using Ghidra's analysis engine. ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## getting started ### requirements - [Ghidra](https://github.com/NationalSecurityAgency/ghidra) >= 12.0 must be installed and available via the `GHIDRA_INSTALL_DIR` environment variable. #### standalone binary (recommended) The capa [standalone binary](https://github.com/mandiant/capa/releases) is the preferred way to run capa with the Ghidra backend. Although the binary does not bundle the Java environment or Ghidra itself, it will dynamically load them at runtime. #### python package You can also use the Ghidra backend with the capa Python package by installing `flare-capa` with the `ghidra` extra. ```bash $ pip install "flare-capa[ghidra]" ``` ### usage To use the Ghidra backend, specify it with the `-b` or `--backend` flag: ```bash $ capa -b ghidra /path/to/sample ``` capa will: 1. Initialize a headless Ghidra instance. 2. Create a temporary project. 3. Import and analyze the sample. 4. Extract features and match rules. 5. Clean up the temporary project. **Note:** The first time you run this, it may take a few moments to initialize the Ghidra environment. --- ## File: capa/ida/plugin/README.md 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, ELF 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. capa explorer runs capa analysis on your IDA Pro database (IDB) without needing 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 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. 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`: 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`. 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`. capa explorer also helps you build and test 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 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`. For more information on the FLARE team's open-source framework, capa, check out the overview in our first [blog](https://www.mandiant.com/resources/capa-automatically-identify-malware-capabilities). ## Getting Started ### Installation You can install capa explorer using the following steps: 1. Install capa and its dependencies from PyPI using the Python interpreter configured for your IDA installation: ``` $ pip install flare-capa ``` 2. Download and extract the [official capa rules](https://github.com/mandiant/capa-rules/releases) that match the version of capa you have installed 1. Use the following command to view the version of capa you have installed: ```commandline $ pip show flare-capa OR $ capa --version ``` 3. Copy [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ida/plugin/capa_explorer.py) to your IDA plugins directory - find your plugin directories via `idaapi.get_ida_subdirs("plugins")` or see this [Hex-Rays blog](https://hex-rays.com/blog/igors-tip-of-the-week-103-sharing-plugins-between-ida-installs/) - common paths are `%APPDATA%\Hex-Rays\IDA Pro\plugins` (Windows) or `$HOME/.idapro/plugins` on Linux/Mac ### Supported File Types capa explorer is limited to the file types supported by capa, which include: * Windows x86 (32- and 64-bit) PE files * Windows x86 (32- and 64-bit) shellcode * ELF files on various operating systems ### Usage 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` You can also use `ida_loader.load_and_run_plugin("capa_explorer", arg)`. `arg` is a bitflag for which setting the LSB enables automatic analysis. See `capa.ida.plugin.form.Options` for more details. 3. Select the `Program Analysis` tab 4. Click the `Analyze` button The first time you run capa explorer you will be asked to specify a local directory containing capa rules to use for analysis. We recommend downloading and extracting the [official capa rules](https://github.com/mandiant/capa-rules/releases) that match the version of capa you have installed (see installation instructions above for more details). capa explorer remembers your selection for future analysis which you can update using the `Settings` button. #### Tips for Program Analysis * Start analysis by clicking the `Analyze` button * capa explorer caches results to the database and reuses them across IDA sessions * Reset the plugin user interface and remove highlighting from your Disassembly view by clicking the `Reset` button * Change your local capa rules directory, auto analysis settings, and other default settings by clicking the `Settings` button * Hover your cursor over a rule match to view the source content of the rule * 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 your Disassembly view * Reanalyze if you renamed global variables that store dynamically resolved APIs. capa will use these to improve its analysis. #### Tips for Rule Generator * 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` ### Requirements capa explorer supports Python versions >= 3.10 and IDA Pro versions >= 7.4. The following IDA Pro versions have been tested: * IDA 7.4 * IDA 7.5 * IDA 7.6 Service Pack 1 * IDA 7.7 * IDA 8.0 * IDA 8.1 * IDA 8.2 * IDA 9.0 capa explorer is however limited to the Python versions supported by your IDA installation (which may not include all Python versions >= 3.10). If you encounter issues with your specific setup, please open a new [Issue](https://github.com/mandiant/capa/issues). ## Development 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/mandiant/capa/blob/master/doc/installation.md#method-3-inspecting-the-capa-source-code). Once installed, copy [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ida/plugin/capa_explorer.py) to your plugins directory to install capa explorer in IDA. ### Components capa explorer consists of two main components: * An [feature extractor](https://github.com/mandiant/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/mandiant/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/mandiant/capa/tree/master/capa/ida/plugin) for displaying and exploring capa rule matches * 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 --- ## File: doc/faq.md # Frequently Asked Questions ## Why does capa trigger my Antivirus? Is the tool safe to use? The purpose of `capa` is to analyse the capabilities of a potentially malicious application or file. To achieve this, it needs to include portions of the data it is designed to detect as a basis for comparison. The release version of capa comes with embedded rules designed to detect common malware functionality. These rules possess similar features to malware and may trigger alerts. Additionally, Antivirus and Endpoint Detection and Response (EDR) products may alert on the way capa is packaged using PyInstaller. ## How can I ensure that capa is a benign program? We recommend downloading releases only from this repository's Release page. Alternatively, you can build capa yourself or use other Python installation methods. This project is open-source, ensuring transparency for everyone involved. For additional peace of mind, you can utilize VirusTotal to analyze unknown files against numerous antivirus products, sandboxes, and other analysis tools. It's worth noting that capa itself operates within VirusTotal. ### Understanding VirusTotal output VirusTotal tests files against a large number of Antivirus engines and sandboxes. There's often little insight into Antivirus detections, but you can further inspect dynamic analysis results produced by sandboxes. These details can be used to double-check alerts and understand detections. --- ## File: doc/installation.md # Installation You can install capa in a few different ways. First, if you simply want to use capa, just download the [standalone binary](https://github.com/mandiant/capa/releases). If you want to use capa as a Python library, you can install the package directly from GitHub using `pip`. If you'd like to contribute patches or features to capa, you can work with a local copy of the source code. ## Method 1: Standalone installation If you simply want to use capa, use the standalone binaries we host on GitHub: https://github.com/mandiant/capa/releases. These binary executable files contain all the source code, Python interpreter, and associated resources needed to make capa run. This means you can run it without any installation! Just invoke the file using your terminal shell to see the help documentation. We use PyInstaller to create these packages. ### Linux Standalone installation The Linux Standalone binary has been built using GLIB 2.26. Consequently, it works when using GLIB >= 2.26. This requirement is satisfied by default in newer distribution such as Ubuntu >= 18, Debian >= 10, openSUSE >= 15.1 and CentOS >= 8. But the binary may not work in older distributions. ### MacOS Standalone installation By default, on MacOS Catalina or greater, Gatekeeper will block execution of the standalone binary. To resolve this, simply try to execute it once on the command-line and then go to `System Preferences` / `Security & Privacy` / `General` and approve the application: ## Method 2: Using capa as a Python library To install capa as a Python library use `pip` to fetch the `flare-capa` module. ### 1. Install capa module Use `pip` to install the capa module to your local Python environment. This fetches the library code to your computer but does not keep editable source files around for you to hack on. If you'd like to edit the source files, see below. `$ pip install flare-capa` #### *Note on capa rules and library identification signatures* This method is appropriate for integrating capa in an existing project. This technique doesn't pull the default rule set. You can obtain rule releases from [capa-rules](https://github.com/mandiant/capa-rules/releases) and pass the directory to the entrypoint using `-r`. In the IDA Pro plugin you need to configure the rules directory path once. ```console $ wget https://github.com/mandiant/capa-rules/archive/refs/tags/v9.4.0.zip $ unzip v9.4.0.zip $ capa -r capa-rules-v9.4.0/ suspicious.exe ``` This technique also doesn't set up the default library identification [signatures](https://github.com/mandiant/capa/tree/master/sigs). You can pass the signature directory using the `-s` argument. For example, to run capa with both a rule path and a signature path: ```console $ capa -s /path/to/capa-sigs suspicious.exe ``` Alternatively, see Method 3 below. ### 2. Use capa You can now import the `capa` module from a Python script or use the IDA Pro plugins from the `capa/ida` directory. For more information please see the [usage](usage.md) documentation. ## Method 3: Inspecting the capa source code If you'd like to review and modify the capa source code, you'll need to check it out from GitHub and install it locally. By following these instructions, you'll maintain a local directory of source code that you can modify and run easily. ### 1. Check out source code Clone the capa git repository. We use submodules to separate [code](https://github.com/mandiant/capa), [rules](https://github.com/mandiant/capa-rules), and [test data](https://github.com/mandiant/capa-testfiles). To clone everything use the `--recurse-submodules` option: - CAUTION: The capa testfiles repository contains many malware samples. If you pull down everything using this method, you may want to install to a directory that is ignored by your anti-virus software. - `$ git clone --recurse-submodules https://github.com/mandiant/capa.git /local/path/to/src` (HTTPS) - `$ git clone --recurse-submodules git@github.com:mandiant/capa.git /local/path/to/src` (SSH) To only get the source code and our provided rules (a more common use-case), follow these steps: - clone repository - `$ git clone https://github.com/mandiant/capa.git /local/path/to/src` (HTTPS) - `$ git clone git@github.com:mandiant/capa.git /local/path/to/src` (SSH) - `$ cd /local/path/to/src` - initialize the rules submodule and pull rules - `$ git submodule update --init rules` ### 2. Install the local source code Use `pip` to install the source code in "editable" mode. This means that Python will load the capa module from the local directory rather than copying it to `site-packages` or `dist-packages`. This is good because it is easy to modify files and see the effects reflected immediately. But, be careful not to remove this directory unless uninstalling capa. `$ pip install -e /local/path/to/src` You'll find that the `capa.exe` (Windows) or `capa` (Linux/MacOS) executables in your path now invoke the capa binary from this directory. #### Development ##### venv [optional] For development, we recommend to use [venv](https://docs.python.org/3/tutorial/venv.html). It allows you to create a virtual environment: a self-contained directory tree that contains a Python installation for a particular version of Python, plus a number of additional packages. This approach avoids conflicts between the requirements of different applications on your computer. It also ensures that you don't overlook to add a new requirement to `setup.up` using a library already installed on your system. To create an environment (in the parent directory, to avoid committing it by accident or messing with the linters), run: `$ python3 -m venv ../capa-env` To activate `capa-env` in Linux or MacOS, run: `$ source ../capa-env/bin/activate` To activate `capa-env` in Windows, run: `$ ..\capa-env\Scripts\activate.bat` For more details about creating and using virtual environments, check out the [venv documentation](https://docs.python.org/3/tutorial/venv.html). ##### Install development dependencies When developing capa, please use the pinned dependencies found in `requirements.txt`. This ensures that everyone has the exact same, reproducible environment. Please install these dependencies before install capa (from source or from PyPI): `$ pip install -r requirements.txt` We use the following tools to ensure consistent code style and formatting: - [ruff](https://docs.astral.sh/ruff/) code linter and formatter - [mypy](https://mypy-lang.org/) type checking - [capafmt](https://github.com/mandiant/capa/blob/master/scripts/capafmt.py) rule formatter To install these development dependencies, run: - `$ pip install -e /local/path/to/src[dev]` or - `$ pip install -e /local/path/to/src[dev,scripts]` to also install all script dependencies We use [pre-commit](https://pre-commit.com/) so that its trivial to run the same linters & configuration locally as in CI. Run all linters like: ❯ pre-commit run --hook-stage=manual --all-files ruff-format..............................................................Passed ruff.....................................................................Passed mypy.....................................................................Passed pytest (fast)............................................................Passed Or run a single linter like: ❯ pre-commit run --all-files --hook-stage=manual ruff ruff.....................................................................Passed Importantly, you can configure pre-commit to run automatically before every commit by running: ❯ pre-commit install --hook-type=pre-commit pre-commit installed at .git/hooks/pre-commit ❯ pre-commit install --hook-type=pre-push pre-commit installed at .git/hooks/pre-push This way you can ensure that you don't commit code style or formatting offenses. You can always temporarily skip the checks by using the `-n`/`--no-verify` git option. ### 3. Compile binary using PyInstaller We compile capa standalone binaries using PyInstaller. To reproduce the build process check out the source code as described above and follow the following steps. #### Install PyInstaller: `$ pip install pyinstaller` Or install capa with build dependencies: `$ pip install -e /local/path/to/src[build]` #### Generate rule cache Generate cache for all rules in the `rules` folder and save the output in the `cache` folder. `$ python scripts/cache-ruleset.py rules/ cache/` #### Run Pyinstaller `$ pyinstaller .github/pyinstaller/pyinstaller.spec` You can find the compiled binary in the created directory `dist/`. --- ## File: doc/limitations.md # Packers Packed programs have often been obfuscated to hide their logic. Since capa cannot handle obfuscation well, results may be misleading or incomplete. If possible, users should unpack input files before analyzing them with capa. If capa detects that a program may be packed using its rules it warns the user. # Installers, run-time programs, etc. capa cannot handle installers, run-time programs, or other packaged applications like AutoIt well. This means that the results may be misleading or incomplete. If capa detects an installer, run-time program, etc. it warns the user. # Wrapper functions and matches in child functions Currently capa does not handle wrapper functions or other matches in child functions. Consider this example call tree where `f1` calls a wrapper function `f2` and the `CreateProcess` API. `f2` writes to a file. ``` f1 f2 (WriteFile wrapper) CreateFile WriteFile CreateProcess ``` Here capa does not match a rule that hits on file creation and execution on function `f1`. Software often contains such nested calls because programmers wrap API calls in helper functions or because specific compilers or languages, such as Go, layer calls. While a feature to capture nested functionality is desirable it introduces various issues and complications. These include: - how to assign matches from child to parent functions? - a potential significant increase in analysis requirements and rule matching complexity Moreover, we require more real-world samples to see how prevalent this really is and how much it would improve capa's results. # Loop scope Encryption, encoding, or processing functions often contain loops and it could be beneficial to capture functionality within loops. However, tracking all basic blocks part of a loop especially with nested loop constructs is not trivial. As a compromise, capa provides the `characteristic(loop)` feature to filter on functions that contain a loop. We need more practical use cases and test samples to justify the additional workload to implement a full loop scope feature. # ATT&CK, MAEC, MBC, and other capability tagging capa uses namespaces to group capabilities (see https://github.com/mandiant/capa-rules/tree/master#namespace-organization). The `rule.meta` field also supports `att&ck`, `mbc`, and `maec` fields to associate rules with the respective taxonomy (see https://github.com/mandiant/capa-rules/blob/master/doc/format.md#meta-block). --- ## File: doc/release.md # Release checklist - [ ] Ensure all [milestoned issues/PRs](https://github.com/mandiant/capa/milestones) are addressed, or reassign to a new milestone. - [ ] Add the `don't merge` label to all PRs that are close to be ready to merge (or merge them if they are ready) in [capa](https://github.com/mandiant/capa/pulls) and [capa-rules](https://github.com/mandiant/capa-rules/pulls). - [ ] Ensure the [CI workflow succeeds in master](https://github.com/mandiant/capa/actions/workflows/tests.yml?query=branch%3Amaster). - [ ] Ensure that `python scripts/lint.py rules/ --thorough` succeeds (only `missing examples` offenses are allowed in the nursery). You can [manually trigger a thorough lint](https://github.com/mandiant/capa-rules/actions/workflows/tests.yml) in CI via the "Run workflow" option. - [ ] Review changes - capa https://github.com/mandiant/capa/compare/\...master - capa-rules https://github.com/mandiant/capa-rules/compare/\\...master - [ ] Run `$ bump-my-version bump {patch/minor/major} [--allow-dirty]` to update [capa/version.py](https://github.com/mandiant/capa/blob/master/capa/version.py) and other version files - [ ] Update [CHANGELOG.md](https://github.com/mandiant/capa/blob/master/CHANGELOG.md) - Do not forget to add a nice introduction thanking contributors - Remember that we need a major release if we introduce breaking changes - Sections: see template below - Update `Raw diffs` links - Create placeholder for `master (unreleased)` section ``` ## master (unreleased) ### New Features ### Breaking Changes ### New Rules (0) - ### Bug Fixes ### capa Explorer Web ### capa Explorer IDA Pro plugin ### Development ### Raw diffs - [capa ...master](https://github.com/mandiant/capa/compare/...master) - [capa-rules ...master](https://github.com/mandiant/capa-rules/compare/...master) ``` - [ ] Create a PR with the updated [CHANGELOG.md](https://github.com/mandiant/capa/blob/master/CHANGELOG.md) and [capa/version.py](https://github.com/mandiant/capa/blob/master/capa/version.py). Copy this checklist in the PR description. - [ ] Update the [homepage](https://github.com/mandiant/capa/blob/master/web/public/index.html) (i.e. What's New section) - [ ] After PR review, merge the PR and [create the release in GH](https://github.com/mandiant/capa/releases/new) using text from the [CHANGELOG.md](https://github.com/mandiant/capa/blob/master/CHANGELOG.md). - Verify GH actions - [ ] [upload artifacts](https://github.com/mandiant/capa/releases) - [ ] [publish to PyPI](https://pypi.org/project/flare-capa) - [ ] [create tag in capa rules](https://github.com/mandiant/capa-rules/tags) - [ ] [create release in capa rules](https://github.com/mandiant/capa-rules/releases) - [ ] [Spread the word](https://twitter.com) - [ ] Update internal service --- ## File: doc/rules.md ### rules capa uses a collection of rules to identify capabilities within a program. The [github.com/mandiant/capa-rules](https://github.com/mandiant/capa-rules) repository contains hundreds of standard library rules that are distributed with capa. When you download a standalone version of capa, this standard library is embedded within the executable and capa will use these rules by default: ```console $ capa suspicious.exe ``` However, you may want to modify the rules for a variety of reasons: - develop new rules to find behaviors, - tweak existing rules to reduce false positives, - collect a private selection of rules not shared publicly. Or, you may want to use capa as a Python library within another application. In these scenarios, you must provide the rule set to capa as a directory on your file system. Do this using the `-r`/`--rules` parameter: ```console $ capa --rules /local/path/to/rules suspicious.exe ``` You can download the standard set of rules as ZIP or TGZ archives from the [capa-rules release page](https://github.com/mandiant/capa-rules/releases). Note that you must use match the rules major version with the capa major version, i.e., use `v1` rules with `v1` of capa. This is so that new versions of capa can update rule syntax, such as by adding new fields and logic. Otherwise, using rules with a mismatched version of capa may lead to errors like: ``` $ capa --rules /path/to/mismatched/rules suspicious.exe ERROR:lint:invalid rule: injection.yml: invalid rule: unexpected statement: instruction ``` You can check the version of capa you're currently using like this: ```console $ capa --version capa 9.4.0 ``` --- ## File: doc/usage.md # capa usage See `capa -h` for all supported arguments and usage examples. ## Ways to consume capa output | Method | Output / interface | Typical use | |--------|--------------------|-------------| | **CLI** | Text (default, `-v`, `-vv`), JSON (`-j`), or other formats | Scripting, CI, one-off analysis | | [**IDA Pro**](https://github.com/mandiant/capa/tree/master/capa/ida/plugin) | capa Explorer plugin inside IDA | Interactive analysis with jump-to-address | | [**Ghidra**](https://github.com/mandiant/capa/tree/master/capa/ghidra/plugin) | capa Explorer plugin inside Ghidra | Interactive analysis with Ghidra integration | | [**Binary Ninja**](https://github.com/mandiant/capa/tree/master/capa/features/extractors/binja) | capa run using Binary Ninja as the analysis backend | Interactive analysis with Binary Ninja integration | | [**Dynamic (Sandbox)**](https://www.mandiant.com/resources/blog/dynamic-capa-executable-behavior-cape-sandbox) | capa run on dynamic sandbox report (CAPE, VMRay, etc.) | Dynamic analysis of sandbox output | | [**Web (capa Explorer)**](https://mandiant.github.io/capa/explorer/) | Web UI (upload JSON or load from URL) | Sharing results, viewing from VirusTotal or similar | ## Default vs verbose output By default, capa shows only *top-level* rule matches: capabilities that are not already implied by another displayed rule. For example, if a rule "persist via Run registry key" matches and it *contains* a match for "set registry value", the default output lists only "persist via Run registry key". This keeps the default output short while still reflecting all detected capabilities at the top level. Use **`-v`** to see all rule matches, including nested ones. Use **`-vv`** for an even more detailed view that shows how each rule matched. ## tips and tricks ### only run selected rules 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`. ### only analyze selected functions Use the `--restrict-to-functions` option to extract capabilities from only a selected set of functions. This is useful for analyzing large functions and figuring out their capabilities and their address of occurrence; for example: PEB access, RC4 encryption, etc. To use this, you can copy the virtual addresses from your favorite disassembler and pass them to capa as follows: `capa sample.exe --restrict-to-functions 0x4019C0,0x401CD0`. If you add the `-v` option then capa will extract the interesting parts of a function for you. ### only analyze selected processes Use the `--restrict-to-processes` option to extract capabilities from only a selected set of processes. This is useful for filtering the noise generated from analyzing non-malicious processes that can be reported by some sandboxes, as well as reduce the execution time by not analyzing such processes in the first place. To use this, you can pick the PIDs of the processes you are interested in from the sandbox-generated process tree (or from the sandbox-reported malware PID) and pass that to capa as follows: `capa report.log --restrict-to-processes 3888,3214,4299`. If you add the `-v` option then capa will tell you which threads perform what actions (encrypt/decrypt data, initiate a connection, etc.). ### IDA Pro plugin: capa explorer Please check out the [capa explorer documentation](/capa/ida/plugin/README.md). ### save time by reusing .viv files Set the environment variable `CAPA_SAVE_WORKSPACE` to instruct the underlying analysis engine to cache its intermediate results to the file system. For example, vivisect will create `.viv` files. Subsequently, capa may run faster when reprocessing the same input file. This is particularly useful during rule development as you repeatedly test a rule against a known sample. --- ## File: sigs/README.md # capa/sigs This directory contains FLIRT signatures that capa uses to identify library functions. Typically, capa will ignore library functions, which reduces false positives and improves runtime. These FLIRT signatures were generated by Mandiant using the Hex-Rays FLAIR tools such as `pcf` and `sigmake`. Mandiant generated the signatures from source data that they collected; these signatures are not derived from the FLIRT signatures distributed with IDA Pro. The signatures in this directory have the same license as capa: Apache 2.0.