DOCSEARCHbyAlgolia
Submit Docs

capa

repository·master·Indexed 27 days ago

https://github.com/mandiant/capa

An open-source tool by the FLARE team that detects capabilities in executable files (PE, ELF, .NET, shellcode) and sandbox reports, mapping them to ATT&CK tactics and techniques. It includes plugins for IDA Pro and Ghidra, a web-based explorer, and support for dynamic analysis via CAPE, DRAKVUF, and VMRay reports. Users can author custom rules using a YAML-based format to identify specific program behaviors.

Tokens
8.3K
Snippets
19
Records
67
Agent score
82%

What's inside capa

  1. Overview of capa capabilities

    master
    capa is a tool that detects capabilities in executable files. It analyzes PE, ELF, .NET modules, shellcode files, or sandbox reports to identify program behaviors. It maps these behaviors to ATT&CK Tactics and Techniques and provides specific capability namespaces (e.g., c2/shell, communication/http/client).

  2. Understand limitations with wrapper functions and nested calls

    master
    capa does not currently support matching wrapper functions or identifying matches within child functions. If a rule requires a sequence of actions (e.g., file creation followed by execution) but those actions are separated by a wrapper function in the call tree, the rule may not trigger on the parent function.

  3. Ways to consume capa output

    master

    capa output can be consumed through several interfaces depending on your workflow:

    • CLI: Standard text output (default, -v, -vv), JSON (-j), or other formats. Best for scripting, CI/CD, or one-off analysis.
    • IDA Pro: Use the capa Explorer plugin for interactive analysis with jump-to-address capabilities.
    • Ghidra: Use the capa Explorer plugin for interactive analysis integrated with Ghidra.
    • Binary Ninja: Run capa using Binary Ninja as the analysis backend.
    • Dynamic (Sandbox): Run capa on dynamic sandbox reports (e.g., CAPE, VMRay) to analyze executable behavior.
    • Web (capa Explorer): Use the capa Explorer Web UI to upload JSON results or load them from a URL for sharing and viewing.

  4. Understand the purpose of capa/sigs FLIRT signatures

    master
    The capa/sigs directory contains FLIRT signatures used by capa to identify library functions. By identifying these functions, capa can ignore them during analysis, which helps reduce false positives and improves overall runtime performance.

  7. Install capa as a Python library

    master

    To integrate capa into an existing Python project, install the flare-capa module using pip.

    Note on Rules and Signatures: Installing via pip does not include the default rule set or library identification signatures. You must provide them manually using the -r (rules) and -s (signatures) flags.

    Manual Rule and Signature Configuration

    1. Download rules from capa-rules.
    2. Use the -r flag to point to the rules directory.
    3. Use the -s flag to point to the signatures directory.
    # Install the module
$ pip install flare-capa

# Example: Running with downloaded rules
$ 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

# Example: Running with rules and signatures
$ capa -s /path/to/capa-sigs suspicious.exe

  8. Set up capa for development

    master

    To modify the capa source code, clone the repository and install it in 'editable' mode. This allows changes to the source to be reflected immediately without re-installing.

    1. Clone the repository

    Use --recurse-submodules to include code, rules, and test files. CAUTION: The testfiles submodule contains malware samples; ensure you use a directory ignored by your antivirus.

    2. Install in editable mode

    Use pip install -e to link the local directory to your Python environment.

    3. Development Environment (Recommended)

    Use venv to avoid dependency conflicts and ensure all requirements are captured in setup.py.

    4. Install Dependencies

    Install pinned dependencies from requirements.txt first, then install the local package with development extras ([dev] or [dev,scripts]).

    # Clone with all submodules
$ git clone --recurse-submodules https://github.com/mandiant/capa.git /local/path/to/src

# OR: Clone only code and rules
$ git clone https://github.com/mandiant/capa.git /local/path/to/src
$ cd /local/path/to/src
$ git submodule update --init rules

# Create and activate virtual environment
$ python3 -m venv ../capa-env
$ source ../capa-env/bin/activate

# Install dependencies and package in editable mode
$ pip install -r requirements.txt
$ pip install -e /local/path/to/src[dev]

  9. Run Ghidra with PyGhidra

    master

    To ensure the Python environment is correctly loaded for the plugin, you must start Ghidra using the pyghidraRun script located in your Ghidra installation's support directory. You should execute pyghidraRun from within the same Python environment where you installed flare-capa.

    <ghidra_install>/support/pyghidraRun

  12. Use dynamic capability detection with sandboxes

    master

    capa supports dynamic capability detection by analyzing reports generated from supported sandboxes. This allows capa to match capabilities against both static features and dynamic features captured during execution.

    To use this feature:

    1. Submit your file to a supported sandbox.
    2. Download the generated report file.
    3. Run capa against the report file instead of the original binary.

    Supported Sandboxes and Formats:

    • CAPE: .json, .json_, .json.gz
    • DRAKVUF: .log, .log.gz
    • VMRay: analysis archive .zip