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>
2.6 KiB
rules
capa uses a collection of rules to identify capabilities within a program. The 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:
$ 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:
$ capa --rules /local/path/to/rules suspicious.exe
You can collect the standard set of rules in two ways:
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:
$ capa --version
capa 3.0.3
download release archive
The releases page is here. Find the most recent release corresponding to your major version of capa and download the ZIP archive. Here are some quick links:
clone with git
To fetch with git, clone the appropriate branch like this:
$ 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.