mirror of
https://github.com/mandiant/capa.git
synced 2026-01-03 16:27:58 -08:00
400e28c3f7
* doc: add rules documentation * version: add accessor for capa major version and git checkout command * doc: rules: document version output * doc: rules: show example error due to mismatched rule version * doc: rules: update links * ci: tag major rule version test * ci: tag major rule version * doc: update changelog * ci: force to replace tag if exists * ci: simplify tagging step * Update doc/rules.md * feat: disable tag, show error branch cmd * doc: update major version rules branch * Apply suggestions from code review Co-authored-by: Willi Ballenthin <willi.ballenthin@gmail.com> * Update capa/main.py * black Co-authored-by: Moritz Raabe <moritz.raabe@mandiant.com> Co-authored-by: Moritz <mr-tz@users.noreply.github.com>
73 lines
2.6 KiB
Markdown
73 lines
2.6 KiB
Markdown
### 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, and/or
|
|
- tweak existing rules to reduce false positives, and/or
|
|
- 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 collect the standard set of rules in two ways:
|
|
|
|
- [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.
|
|
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 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`
|
|
|