diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index d751aa36b..bc9c3908c 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -39,11 +39,11 @@ jobs: python_version: 3.8 steps: - name: Checkout capa - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 with: submodules: true - name: Set up Python ${{ matrix.python_version }} - uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0 + uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0 with: python-version: ${{ matrix.python_version }} - if: matrix.os == 'ubuntu-20.04' @@ -66,7 +66,7 @@ jobs: run: | 7z e "tests/data/dynamic/cape/v2.2/d46900384c78863420fb3e297d0a2f743cd2b6b3f7f82bf64059a168e07aceb7.json.gz" dist/capa -d "d46900384c78863420fb3e297d0a2f743cd2b6b3f7f82bf64059a168e07aceb7.json" - - uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce # v3.1.2 + - uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 with: name: ${{ matrix.asset_name }} path: dist/${{ matrix.artifact_name }} @@ -90,7 +90,7 @@ jobs: asset_name: windows steps: - name: Download ${{ matrix.asset_name }} - uses: actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a # v3.0.2 + uses: actions/download-artifact@eaceaf801fd36c7dee90939fad912460b18a1ffe # v4.1.2 with: name: ${{ matrix.asset_name }} - name: Set executable flag @@ -118,7 +118,7 @@ jobs: artifact_name: capa steps: - name: Download ${{ matrix.asset_name }} - uses: actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a # v3.0.2 + uses: actions/download-artifact@eaceaf801fd36c7dee90939fad912460b18a1ffe # v4.1.2 with: name: ${{ matrix.asset_name }} - name: Set executable flag diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 4188cf090..cb2a00f97 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -17,9 +17,9 @@ jobs: permissions: id-token: write steps: - - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 - name: Set up Python - uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0 + uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0 with: python-version: '3.8' - name: Install dependencies @@ -30,7 +30,7 @@ jobs: run: | python -m build - name: upload package artifacts - uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce # v3.1.2 + uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 with: path: dist/* - name: publish package diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 0968fecd6..1844b881c 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -59,7 +59,7 @@ jobs: # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF # format to the repository Actions tab. - name: "Upload artifact" - uses: actions/upload-artifact@3cea5372237819ed00197afe530f5a7ea3e805c8 # v3.1.0 + uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1 with: name: SARIF file path: results.sarif diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml index 752a008e6..ea14817e6 100644 --- a/.github/workflows/tag.yml +++ b/.github/workflows/tag.yml @@ -12,7 +12,7 @@ jobs: runs-on: ubuntu-20.04 steps: - name: Checkout capa-rules - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 with: repository: mandiant/capa-rules token: ${{ secrets.CAPA_TOKEN }} diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index bb8eb6070..05d6414ad 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -17,7 +17,7 @@ jobs: runs-on: ubuntu-20.04 steps: - name: Checkout capa - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 # The sync GH action in capa-rules relies on a single '- *$' in the CHANGELOG file - name: Ensure CHANGELOG has '- *$' run: | @@ -28,10 +28,10 @@ jobs: runs-on: ubuntu-20.04 steps: - name: Checkout capa - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 # use latest available python to take advantage of best performance - name: Set up Python 3.11 - uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0 + uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0 with: python-version: "3.11" - name: Install dependencies @@ -51,11 +51,11 @@ jobs: runs-on: ubuntu-20.04 steps: - name: Checkout capa with submodules - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 with: submodules: recursive - name: Set up Python 3.11 - uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0 + uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0 with: python-version: "3.11" - name: Install capa @@ -83,11 +83,11 @@ jobs: python-version: "3.10" steps: - name: Checkout capa with submodules - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 with: submodules: recursive - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0 + uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0 with: python-version: ${{ matrix.python-version }} - name: Install pyyaml @@ -116,12 +116,12 @@ jobs: - name: Checkout capa with submodules # do only run if BN_SERIAL is available, have to do this in every step, see https://github.com/orgs/community/discussions/26726#discussioncomment-3253118 if: ${{ env.BN_SERIAL != 0 }} - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 with: submodules: recursive - name: Set up Python ${{ matrix.python-version }} if: ${{ env.BN_SERIAL != 0 }} - uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0 + uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0 with: python-version: ${{ matrix.python-version }} - name: Install pyyaml @@ -160,15 +160,15 @@ jobs: ghidrathon-version: ["3.0.0"] steps: - name: Checkout capa with submodules - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3.3.0 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 with: submodules: true - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4.5.0 + uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5.0.0 with: python-version: ${{ matrix.python-version }} - name: Set up Java ${{ matrix.java-version }} - uses: actions/setup-java@5ffc13f4174014e2d4d4572b3d74c3fa61aeb2c2 # v3 + uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 # v4.0.0 with: distribution: 'temurin' java-version: ${{ matrix.java-version }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 57e1a60e6..e469a676b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,18 +8,28 @@ ### Breaking Changes -### New Rules (1) +### New Rules (6) - impact/wipe-disk/delete-drive-layout-via-ioctl william.ballenthin@mandiant.com +- host-interaction/driver/interact-with-driver-via-ioctl moritz.raabe@mandiant.com +- host-interaction/driver/unload-driver moritz.raabe@mandiant.com +- nursery/get-disk-information-via-ioctl william.ballenthin@mandiant.com +- nursery/get-volume-information-via-ioctl william.ballenthin@mandiant.com +- nursery/unmount-volume-via-ioctl william.ballenthin@mandiant.com - ### Bug Fixes +- do some imports closer to where they are used #1810 @williballenthin + ### capa explorer IDA Pro plugin ### Development +- ci: update github workflows to use latest version for depricated actions (checkout, setup-python, upload-artifact, download-artifact) #1967 @sjha2048 +- ci: use rules number badge stored in our bot gist and generated using `schneegans/dynamic-badges-action` #2001 capa-rules#882 @Ana06 + ### Raw diffs - [capa v7.0.1...master](https://github.com/mandiant/capa/compare/v7.0.1...master) - [capa-rules v7.0.1...master](https://github.com/mandiant/capa-rules/compare/v7.0.1...master) diff --git a/README.md b/README.md index f3ccdfc1b..9c387cdcb 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flare-capa)](https://pypi.org/project/flare-capa) [![Last release](https://img.shields.io/github/v/release/mandiant/capa)](https://github.com/mandiant/capa/releases) -[![Number of rules](https://img.shields.io/badge/rules-867-blue.svg)](https://github.com/mandiant/capa-rules) +[![Number of rules](https://gist.githubusercontent.com/capa-bot/6d7960e911f48b3b74916df8988cf0f3/raw/rules_badge.svg)](https://github.com/mandiant/capa-rules) [![CI status](https://github.com/mandiant/capa/workflows/CI/badge.svg)](https://github.com/mandiant/capa/actions?query=workflow%3ACI+event%3Apush+branch%3Amaster) [![Downloads](https://img.shields.io/github/downloads/mandiant/capa/total)](https://github.com/mandiant/capa/releases) [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE.txt) @@ -260,7 +260,9 @@ capa explorer helps you identify interesting areas of a program and build new ca ![capa + IDA Pro integration](https://github.com/mandiant/capa/blob/master/doc/img/explorer_expanded.png) -If you use Ghidra, you can use the Python 3 [Ghidra feature extractor](/capa/ghidra/). This integration enables capa to extract features directly from your Ghidra database, which can help you identify capabilities in programs that you analyze using Ghidra. +If you use Ghidra, then you can use the [capa + Ghidra integration](/capa/ghidra/) to run capa's analysis directly on your Ghidra database and render the results in Ghidra's user interface. + + # further information ## capa diff --git a/capa/features/extractors/elf.py b/capa/features/extractors/elf.py index b969463df..1e50ca2f7 100644 --- a/capa/features/extractors/elf.py +++ b/capa/features/extractors/elf.py @@ -10,10 +10,11 @@ import itertools import collections from enum import Enum -from typing import Set, Dict, List, Tuple, BinaryIO, Iterator, Optional +from typing import TYPE_CHECKING, Set, Dict, List, Tuple, BinaryIO, Iterator, Optional from dataclasses import dataclass -import Elf # from vivisect +if TYPE_CHECKING: + import Elf # from vivisect logger = logging.getLogger(__name__) @@ -724,7 +725,7 @@ def get_symbols(self) -> Iterator[Symbol]: yield from self.symbols @classmethod - def from_viv(cls, elf: Elf.Elf) -> Optional["SymTab"]: + def from_viv(cls, elf: "Elf.Elf") -> Optional["SymTab"]: endian = "<" if elf.getEndian() == 0 else ">" bitness = elf.bits diff --git a/capa/ghidra/README.md b/capa/ghidra/README.md index 3f2f32097..f4b80edce 100644 --- a/capa/ghidra/README.md +++ b/capa/ghidra/README.md @@ -1,184 +1,104 @@
- +
-The Ghidra feature extractor is an application of the FLARE team's open-source project, Ghidrathon, to integrate capa with Ghidra using Python 3. 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. The Ghidra feature extractor can be used to run capa analysis on your Ghidra databases without needing access to the original binary file. As a part of this integration, we've developed two scripts, [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py), to display capa results directly in Ghidra. +# capa + Ghidra -### Using `capa_explorer.py` +[capa](https://github.com/mandiant/capa) is the FLARE team’s open-source tool that detects capabilities in executable files. [Ghidra](https://github.com/NationalSecurityAgency/ghidra) is an open-source software reverse engineering framework created and maintained by the National Security Agency Research Directorate. capa + Ghidra brings capa’s detection capabilities directly to Ghidra’s user interface helping speed up your reverse engineering tasks by identifying what parts of a program suggest interesting behavior, such as setting a registry value. You can execute the included Python 3 scripts [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) or [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) to run capa’s analysis and view the results in Ghidra. You may be asking yourself, “Python 3 scripts in Ghidra?”. You read that correctly. This integration is written entirely in Python 3 and relies on [Ghidrathon]( https://github.com/mandiant/ghidrathon), an open source Ghidra extension that adds Python 3 scripting to Ghidra. -`capa_explorer.py` integrates capa results directly into Ghidra's UI. In the Symbol Tree Window, under the Namespaces section, you can find the matched rules as well as the corresponding functions that contain the matched features: +## UI Integration +[capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) renders capa results in Ghidra's UI to help you quickly navigate them. This includes adding matched functions to Ghidra’s Symbol Tree and Bookmarks windows and adding comments to functions that indicate matched capabilities and features. You can execute this script using Ghidra’s Script Manager window. -![image](https://github.com/mandiant/capa/assets/66766340/eeae33f4-99d4-42dc-a5e8-4c1b8c661492) +### Symbol Tree Window +Matched functions are added to Ghidra's Symbol Tree window under a custom namespace that maps to the capabilities' [capa namespace](https://github.com/mandiant/capa-rules/blob/master/doc/format.md#rule-namespace). +
+ +
-Labeled functions may be clicked in the Symbol Tree Window to navigate Ghidra's Disassembly Listing and Decompilation windows to the function locations. A comment listing each matched capa rule is inserted at the beginning of the function and a comment for each matched capa feature is added at the matched address within the function. These comments can be viewed using Ghidra's Disassembly Listing and Decompilation windows: +### Comments -![image](https://github.com/mandiant/capa/assets/66766340/bb2b4170-7fd4-45fc-8c7b-ff8f2e2f101b) +Comments are added at the beginning of matched functions indicating matched capabilities and inline comments are added to functions indicating matched features. You can view these comments in Ghidra’s Disassembly Listing and Decompile windows. +
+ +
-The script also adds bookmarks for capa matches that are categorized under MITRE ATT&CK and Malware Behavior Catalog. These may be found and navigated using Ghidra's Bookmarks Window: +### Bookmarks -![image](https://github.com/mandiant/capa/assets/66766340/7f9a66a9-7be7-4223-91c6-4b8fc4651336) +Bookmarks are added to functions that matched a capabilitiy that is mapped to a MITRE ATT&CK and/or Malware Behavior Catalog (MBC) technique. You can view these bookmarks in Ghidra's Bookmarks window. +
+ +
-### Using `capa_ghidra.py` +## Text-based Integration -`capa_ghidra.py` displays capa results in Ghidra's Console window and can be executed using Ghidra's Headless Analyzer. The following is an example of running `capa_ghidra.py` using the Ghidra Script Manager: +[capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) outputs text-based capa results that mirror the output of capa’s standalone tool. You can execute this script using Ghidra’s Script Manager and view its output in Ghidra’s Console window. -Selecting capa rules: - +
+ +
-Choosing output format: - +You can also execute [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using Ghidra's Headless Analyzer to view its output in a terminal window. -Viewing results in Ghidra Console Window: - +
+ +
-## Installation +# Getting Started -### Requirements +## Requirements | Tool | Version | Source | |------------|---------|--------| +| capa | `>= 7.0.0` | https://github.com/mandiant/capa/releases | | Ghidrathon | `>= 3.0.0` | https://github.com/mandiant/Ghidrathon/releases | | Ghidra | `>= 10.3.2` | https://github.com/NationalSecurityAgency/ghidra/releases | | Python | `>= 3.8.0` | https://www.python.org/downloads | -You can run capa in Ghidra by completing the following steps using the Python 3 interpreter that you have configured for your Ghidrathon installation: +## Installation + +**Note**: capa + Ghidra relies on [Ghidrathon]( https://github.com/mandiant/ghidrathon) to execute Python 3 code in Ghidra. You must first install and configure Ghidrathon using the [steps outlined in its README]( https://github.com/mandiant/ghidrathon?tab=readme-ov-file#installing-ghidrathon). Then, you must use the Python 3 interpreter that you configured with Ghidrathon to complete the following steps: 1. Install capa and its dependencies from PyPI using the following command: ```bash $ pip install flare-capa ``` -2. Download and extract the [official capa rules](https://github.com/mandiant/capa-rules/releases) that match the capa version you have installed. Use the following command to view the version of capa you have installed: +2. Download and extract the [official capa rules](https://github.com/mandiant/capa-rules/releases) that match the capa version you have installed. You can use the following command to view the version of capa you have installed: ```bash $ pip show flare-capa OR $ capa --version ``` -3. Copy [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) to your `$USER_HOME/ghidra_scripts` directory or manually add the absolute path of each script to the Ghidra Script Manager. +3. Copy [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) to your `ghidra_scripts` directory or manually add the parent directory of each script using Ghidra’s Script Manager. ## Usage -After completing the installation steps you can execute [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using the Ghidra Script Manager. You can also execute [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using Ghidra's Headless Analyzer. - -### Ghidra Script Manager +You can execute [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using Ghidra’s Script Manager. [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) can also be executed using Ghidra's Headless Analyzer. -Use the following steps to execute [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using Ghidra's Script Manager: -1. Open the Ghidra Script Manager by navigating to `Window > Script Manager` -2. Locate [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) by selecting the `Python 3 > capa` category or using the Ghidra Script Manager search functionality -3. Double-click [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) or [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) to execute the script +### Execution using Ghidra’s Script Manager -If you don't see [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) make sure you have copied these scripts to your `$USER_HOME/ghidra_scripts` directory or manually added the absolute path of each script to the Ghidra Script Manager. +You can execute [capa_explorer.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_explorer.py) and [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using Ghidra's Script Manager as follows: +1. Navigate to `Window > Script Manager` +2. Expand the `Python 3 > capa` category +3. Double-click a script to execute it -Both scripts ask you to provide the path of your capa rules directory. [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) also asks you to select `default`, `verbose`, and `vverbose` output formats used when writing output to the Ghidra Console Window. +Both scripts ask you to provide the path of your capa rules directory (see installation step 2). [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) also has you choose one of `default`, `verbose`, and `vverbose` output formats which mirror the output formats of capa’s standalone tool. -### Ghidra Headless Analyzer +### Execution using Ghidra’s Headless Analyzer -To execute [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using the Ghidra Headless Analyzer, you can use the Ghidra `analyzeHeadless` script located in your `/support` directory. You will need to provide the following arguments to the Ghidra `analyzeHeadless` script: +You can execute [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using Ghidra’s Headless Analyzer by invoking the `analyzeHeadless` script included with Ghidra in its `support` directory. The following arguments must be provided: -1. ``: path to Ghidra project -2. ``: name of Ghidra Project -3. `-process `: name of sample `` -4. `-ScriptPath `: OPTIONAL argument specifying the absolute path of [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) -5. `-PostScript capa_ghidra.py`: execute [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) as post-analysis script -6. `""`: single, quoted string containing capa arguments that must specify capa rules directory and output format, e.g. `" --verbose"`. [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) supports `default`, `verbose`, `vverbose` and `json` formats when executed using the Ghidra Headless Analyzer. [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) writes output to the console window used to execute the Ghidra `analyzeHeadless` script. +| Argument | Description | +|----|----| +|``| Path to Ghidra project| +| ``| Name of Ghidra Project| +| `-Process ` OR `-Import `| Name of sample `` already imported into `` OR absolute path of sample `` to import into ``| +| `-ScriptPath `| OPTIONAL parent directory `` of [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py)| +| `-PostScript capa_ghidra.py`| Execute [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) after Ghidra analysis| +| `""`| Quoted string `""` containing script arguments passed to [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) that must specify a capa rules path and optionally the output format (`--verbose`, `--vverbose`, `--json`) – you can specify `”help”` to view the script’s help message | The following is an example of combining these arguments into a single `analyzeHeadless` script command: - -``` -/support/analyzeHeadless -process -PostScript capa_ghidra.py " --verbose" -``` - -You may also want to run capa against a sample that you have not yet imported into your Ghidra project. The following is an example of importing a sample and running [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) using a single `analyzeHeadless` script command: - -``` -/support/analyzeHeadless -Import -PostScript capa_ghidra.py " --verbose" -``` - -You can also provide [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) the single argument `"help"` to view supported arguments when running the script using the Ghidra Headless Analyzer: -``` -/support/analyzeHeadless -process -PostScript capa_ghidra.py "help" -``` - -The following is an example of running [capa_ghidra.py](https://raw.githubusercontent.com/mandiant/capa/master/capa/ghidra/capa_ghidra.py) against a shellcode sample using the Ghidra `analyzeHeadless` script: -``` -$ analyzeHeadless /home/wumbo/Desktop/ghidra_projects/ capa_test -process 499c2a85f6e8142c3f48d4251c9c7cd6.raw32 -processor x86:LE:32:default -PostScript capa_ghidra.py "/home/wumbo/capa/rules -vv" -[...] - -INFO REPORT: Analysis succeeded for file: /499c2a85f6e8142c3f48d4251c9c7cd6.raw32 (HeadlessAnalyzer) -INFO SCRIPT: /home/wumbo/ghidra_scripts/capa_ghidra.py (HeadlessAnalyzer) -md5 499c2a85f6e8142c3f48d4251c9c7cd6 -sha1 -sha256 e8e02191c1b38c808d27a899ac164b3675eb5cadd3a8907b0ffa863714000e72 -path /home/wumbo/capa/tests/data/499c2a85f6e8142c3f48d4251c9c7cd6.raw32 -timestamp 2023-08-29 17:57:00.946588 -capa version 6.1.0 -os unknown os -format Raw Binary -arch x86 -extractor ghidra -base address global -rules /home/wumbo/capa/rules -function count 42 -library function count 0 -total feature count 1970 - -contain loop (24 matches, only showing first match of library rule) -author moritz.raabe@mandiant.com -scope function -function @ 0x0 - or: - characteristic: loop @ 0x0 - characteristic: tight loop @ 0x278 - -contain obfuscated stackstrings -namespace anti-analysis/obfuscation/string/stackstring -author moritz.raabe@mandiant.com -scope basic block -att&ck Defense Evasion::Obfuscated Files or Information::Indicator Removal from Tools [T1027.005] -mbc Anti-Static Analysis::Executable Code Obfuscation::Argument Obfuscation [B0032.020], Anti-Static Analysis::Executable Code Obfuscation::Stack Strings [B0032.017] -basic block @ 0x0 in function 0x0 - characteristic: stack string @ 0x0 - -encode data using XOR -namespace data-manipulation/encoding/xor -author moritz.raabe@mandiant.com -scope basic block -att&ck Defense Evasion::Obfuscated Files or Information [T1027] -mbc Defense Evasion::Obfuscated Files or Information::Encoding-Standard Algorithm [E1027.m02], Data::Encode Data::XOR [C0026.002] -basic block @ 0x8AF in function 0x8A1 - and: - characteristic: tight loop @ 0x8AF - characteristic: nzxor @ 0x8C0 - not: = filter for potential false positives - or: - or: = unsigned bitwise negation operation (~i) - number: 0xFFFFFFFF = bitwise negation for unsigned 32 bits - number: 0xFFFFFFFFFFFFFFFF = bitwise negation for unsigned 64 bits - or: = signed bitwise negation operation (~i) - number: 0xFFFFFFF = bitwise negation for signed 32 bits - number: 0xFFFFFFFFFFFFFFF = bitwise negation for signed 64 bits - or: = Magic constants used in the implementation of strings functions. - number: 0x7EFEFEFF = optimized string constant for 32 bits - number: 0x81010101 = -0x81010101 = 0x7EFEFEFF - number: 0x81010100 = 0x81010100 = ~0x7EFEFEFF - number: 0x7EFEFEFEFEFEFEFF = optimized string constant for 64 bits - number: 0x8101010101010101 = -0x8101010101010101 = 0x7EFEFEFEFEFEFEFF - number: 0x8101010101010100 = 0x8101010101010100 = ~0x7EFEFEFEFEFEFEFF - -get OS information via KUSER_SHARED_DATA -namespace host-interaction/os/version -author @mr-tz -scope function -att&ck Discovery::System Information Discovery [T1082] -references https://www.geoffchappell.com/studies/windows/km/ntoskrnl/inc/api/ntexapi_x/kuser_shared_data/index.htm -function @ 0x1CA6 - or: - number: 0x7FFE026C = NtMajorVersion @ 0x1D18 - - - -Script /home/wumbo/ghidra_scripts/capa_ghidra.py called exit with code 0 - -[...] +```bash +$ analyzeHeadless /home/wumbo/demo demo -Import /home/wumbo/capa/tests/data/Practical\ Malware\ Analysis\ Lab\ 01-01.dll_ -PostScript capa_ghidra.py "/home/wumbo/capa/rules --verbose" ``` diff --git a/capa/ghidra/capa_explorer.py b/capa/ghidra/capa_explorer.py index 4bf14c267..5c2ff9362 100644 --- a/capa/ghidra/capa_explorer.py +++ b/capa/ghidra/capa_explorer.py @@ -1,4 +1,4 @@ -# Integrate capa results with Ghidra UI +# Run capa against loaded Ghidra database and render results in Ghidra UI # @author Colton Gabertan (gabertan.colton@gmail.com) # @category Python 3.capa diff --git a/capa/ghidra/capa_ghidra.py b/capa/ghidra/capa_ghidra.py index b3ec0183b..55ab8046e 100644 --- a/capa/ghidra/capa_ghidra.py +++ b/capa/ghidra/capa_ghidra.py @@ -1,4 +1,4 @@ -# Run capa against loaded Ghidra database +# Run capa against loaded Ghidra database and render results in Ghidra Console window # @author Mike Hunhoff (mehunhoff@google.com) # @category Python 3.capa diff --git a/capa/loader.py b/capa/loader.py index a8ffccf0f..e4f0a5c92 100644 --- a/capa/loader.py +++ b/capa/loader.py @@ -31,9 +31,6 @@ import capa.render.result_document import capa.render.result_document as rdoc import capa.features.extractors.common -import capa.features.extractors.pefile -import capa.features.extractors.elffile -import capa.features.extractors.dotnetfile import capa.features.extractors.base_extractor import capa.features.extractors.cape.extractor from capa.rules import RuleSet @@ -276,17 +273,30 @@ def get_extractor( def get_file_extractors(input_file: Path, input_format: str) -> List[FeatureExtractor]: file_extractors: List[FeatureExtractor] = [] + # we use lazy importing here to avoid eagerly loading dependencies + # that some specialized environments may not have, + # e.g., those that run capa without vivisect. + if input_format == FORMAT_PE: + import capa.features.extractors.pefile + file_extractors.append(capa.features.extractors.pefile.PefileFeatureExtractor(input_file)) elif input_format == FORMAT_DOTNET: + import capa.features.extractors.pefile + import capa.features.extractors.dotnetfile + file_extractors.append(capa.features.extractors.pefile.PefileFeatureExtractor(input_file)) file_extractors.append(capa.features.extractors.dotnetfile.DotnetFileFeatureExtractor(input_file)) elif input_format == FORMAT_ELF: + import capa.features.extractors.elffile + file_extractors.append(capa.features.extractors.elffile.ElfFeatureExtractor(input_file)) elif input_format == FORMAT_CAPE: + import capa.features.extractors.cape.extractor + report = json.loads(input_file.read_text(encoding="utf-8")) file_extractors.append(capa.features.extractors.cape.extractor.CapeExtractor.from_report(report)) diff --git a/capa/main.py b/capa/main.py index 9d0b1af59..16d6d3cba 100644 --- a/capa/main.py +++ b/capa/main.py @@ -40,11 +40,6 @@ import capa.render.result_document import capa.render.result_document as rdoc import capa.features.extractors.common -import capa.features.extractors.pefile -import capa.features.extractors.elffile -import capa.features.extractors.dotnetfile -import capa.features.extractors.base_extractor -import capa.features.extractors.cape.extractor from capa.rules import RuleSet from capa.engine import MatchResults from capa.loader import BACKEND_VIV, BACKEND_CAPE, BACKEND_BINJA, BACKEND_DOTNET, BACKEND_FREEZE, BACKEND_PEFILE diff --git a/capa/rules/__init__.py b/capa/rules/__init__.py index d9e43dfc5..530c8424c 100644 --- a/capa/rules/__init__.py +++ b/capa/rules/__init__.py @@ -31,7 +31,6 @@ import yaml import pydantic -import ruamel.yaml import yaml.parser import capa.perf @@ -1053,8 +1052,12 @@ def _get_yaml_loader(): @staticmethod def _get_ruamel_yaml_parser(): - # use ruamel to enable nice formatting + # we use lazy importing here to avoid eagerly loading dependencies + # that some specialized environments may not have, + # e.g., those that run capa without ruamel. + import ruamel.yaml + # use ruamel to enable nice formatting # we use the ruamel.yaml parser because it supports roundtripping of documents with comments. y = ruamel.yaml.YAML(typ="rt") diff --git a/doc/img/ghidra_headless_analyzer.png b/doc/img/ghidra_headless_analyzer.png new file mode 100644 index 000000000..3f3c68ed0 Binary files /dev/null and b/doc/img/ghidra_headless_analyzer.png differ diff --git a/pyproject.toml b/pyproject.toml index 529e1dcfd..dec60bc41 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -32,7 +32,7 @@ classifiers = [ "Topic :: Security", ] dependencies = [ - "tqdm==4.66.1", + "tqdm==4.66.2", "pyyaml==6.0.1", "tabulate==0.9.0", "colorama==0.4.6", @@ -64,11 +64,11 @@ namespaces = false dev = [ "pre-commit==3.5.0", "pytest==8.0.0", - "pytest-sugar==0.9.7", + "pytest-sugar==1.0.0", "pytest-instafail==0.5.0", "pytest-cov==4.1.0", "flake8==7.0.0", - "flake8-bugbear==24.1.17", + "flake8-bugbear==24.2.6", "flake8-encodings==0.5.1", "flake8-comprehensions==3.14.0", "flake8-logging-format==0.9.0", @@ -78,7 +78,7 @@ dev = [ "flake8-simplify==0.21.0", "flake8-use-pathlib==0.3.0", "flake8-copyright==0.2.4", - "ruff==0.1.14", + "ruff==0.2.1", "black==24.1.1", "isort==5.13.2", "mypy==1.8.0", @@ -97,7 +97,7 @@ dev = [ "types-protobuf==4.23.0.3", ] build = [ - "pyinstaller==6.3.0", + "pyinstaller==6.4.0", "setuptools==69.0.3", "build==1.0.3" ] diff --git a/rules b/rules index 0c32d6570..34e375562 160000 --- a/rules +++ b/rules @@ -1 +1 @@ -Subproject commit 0c32d65705391f4e9f6e3157530fc6bd351f280f +Subproject commit 34e3755624530a6ed0da9942ad3c68ea8afa89d3