gitea-mirror/capa
1
0
Fork 0
mirror of https://github.com/mandiant/capa.git synced 2025-12-05 20:40:05 -08:00
Code Issues Packages Projects Releases Wiki Activity

simplified rule release guidance

Browse Source
This commit is contained in:
mr-tz
2022-12-21 16:03:05 +01:00
parent d466345e4e
commit 3b95ed0b5a
3 changed files with 41 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
doc/installation.md
View File

@@ -6,13 +6,11 @@ If you simply want to use capa, use the standalone binaries we host on GitHub: h
We use PyInstaller to create these packages.
The capa [README](../README.md#download) also links to nightly builds of standalone binaries from the latest development branch.
### 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 most newer distribution such as Ubuntu >= 18, Debian >= 10, openSUSE >= 15.1 and CentOS >= 8.
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
@@ -24,24 +22,27 @@ By default, on MacOS Catalina or greater, Gatekeeper will block execution of the
## Method 2: Using capa as a Python library
To install capa as a Python library use `pip` to fetch the `flare-capa` module.
#### *Note*:
### 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, so you should check it out separately from [capa-rules](https://github.com/mandiant/capa-rules/) and pass the directory to the entrypoint using `-r` or set the rules path in the IDA Pro plugin:
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
$ git clone https://github.com/mandiant/capa-rules.git -b v3 /local/path/to/rules
$ capa -r /local/path/to/rules suspicious.exe
$ wget https://github.com/mandiant/capa-rules/archive/refs/tags/v4.0.0.zip
$ unzip v4.0.0.zip
$ capa -r /path/to/capa-rules 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
```
capa -r /path/to/capa-rules -s /path/to/capa-sigs suspicious.exe
Alternatively, see Method 3 below.
### 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`
### 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.
@@ -49,18 +50,20 @@ You can now import the `capa` module from a Python script or use the IDA Pro plu
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
Next, clone the capa git repository.
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 won't trigger your anti-virus software.
- 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 (common), follow these steps:
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
@@ -76,8 +79,7 @@ You'll find that the `capa.exe` (Windows) or `capa` (Linux/MacOS) executables in
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 commiting it by accident or messing with the linters), run:
`$ python3 -m venv ../capa-env`
To create an environment (in the parent directory, to avoid commiting 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`
@@ -90,8 +92,8 @@ For more details about creating and using virtual environments, check out the [v
##### Install development dependencies
We use the following tools to ensure consistent code style and formatting:
- [black](https://github.com/psf/black) code formatter, with `-l 120`
- [isort 5](https://pypi.org/project/isort/) code formatter, with `--profile black --length-sort --line-width 120`
- [black](https://github.com/psf/black) code formatter
- [isort 5](https://pypi.org/project/isort/) code formatter
- [dos2unix](https://linux.die.net/man/1/dos2unix) for UNIX-style LF newlines
- [capafmt](https://github.com/mandiant/capa/blob/master/scripts/capafmt.py) rule formatter
@@ -104,7 +106,7 @@ You can run it with the argument `no_tests` to skip the tests and only run the c
##### Setup hooks [optional]
If you plan to contribute to capa, you may want to setup the hooks.
If you plan to contribute to capa, you may want to setup the provided hooks.
Run `scripts/setup-hooks.sh` to set the following hooks up:
- The `pre-commit` hook runs checks before every `git commit`.
It runs `scripts/ci.sh no_tests` aborting the commit if there are code style or rule linter offenses you need to fix.
@@ -112,13 +114,17 @@ Run `scripts/setup-hooks.sh` to set the following hooks up:
It runs `scripts/ci.sh` aborting the push if there are code style or rule linter offenses or if the tests fail.
This way you can ensure everything is alright before sending a pull request.
You can skip the checks by using the `--no-verify` git option.
You can 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 these steps.
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` (Python 3)
`$ pip install pyinstaller`
Or install capa with build dependencies:
`$ pip install -e /local/path/to/src[build]`
#### Run Pyinstaller
`$ pyinstaller .github/pyinstaller/pyinstaller.spec`

13
doc/release.md
View File

@@ -37,13 +37,10 @@
- [ ] Update [capa/version.py](https://github.com/mandiant/capa/blob/master/capa/version.py)
- [ ] 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.
- [ ] 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) and [create a tag in capa rules](https://github.com/mandiant/capa-rules/tags) upon completion.
- [ ] Manually update capa rules major version rule branch
```commandline
[capa/rules] $ git pull master
[capa/rules] $ git checkout v3 # create if new major version: git checkout -b vX
[capa/rules] $ git merge master
[capa/rules] $ git push origin v3
```
- 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

37
doc/rules.md
View File

@@ -1,6 +1,5 @@
### 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.
@@ -12,8 +11,8 @@ $ capa suspicious.exe
However, you may want to modify the rules for a variety of reasons:
- develop new rules to find behaviors, and/or
- tweak existing rules to reduce false positives, and/or
- 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.
@@ -24,13 +23,9 @@ In these scenarios, you must provide the rule set to capa as a directory on your
$ capa --rules /local/path/to/rules suspicious.exe
```
You can collect the standard set of rules in two ways:
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).
- [download from the Github releases page](#download-release-archive), or
- [clone from Github](#clone-with-git).
Note that you must use match the rules major version with the capa major version,
i.e., use `v1` rules with `v1` of capa.
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:
@@ -46,27 +41,3 @@ You can check the version of capa you're currently using like this:
$ capa --version
capa 3.0.3
```
#### download release archive
The releases page is [here](https://github.com/mandiant/capa-rules/tags/).
Find the most recent release corresponding to your major version of capa and download the ZIP archive.
Here are some quick links:
- v1: [v1](https://github.com/mandiant/capa-rules/releases/tag/v1)
- v2: [v2](https://github.com/mandiant/capa-rules/releases/tag/v2)
- v3: [v3](https://github.com/mandiant/capa-rules/releases/tag/v3)
#### clone with git
To fetch with git, clone the appropriate branch like this:
```console
$ git clone https://github.com/mandiant/capa-rules.git -b v3 /local/path/to/rules
```
Note that the branch name (`v3` in the example above) must match the major version of capa you're using.
- [v1](https://github.com/mandiant/capa-rules/tree/v1): `v1`
- [v2](https://github.com/mandiant/capa-rules/tree/v2): `v2`
- [v3](https://github.com/mandiant/capa-rules/tree/v3): `v3`