Adding YARA Rules

YARA is a powerful pattern-matching tool designed for identifying and classifying malware. BinaryAlert includes a number of custom YARA rules and makes it easy to add more of your own. Rules are automatically compiled and bundled with every deploy.

Included Rules

BinaryAlert includes a number of custom YARA rules written by Airbnb’s analysts which detect a variety of hacktools, malware, and ransomware. All included rules have been tested against a corpus of more than 2 million binaries to ensure the highest fidelity.

Clone Rules From Other Projects

BinaryAlert makes it easy to clone YARA rules from other open-source projects:

$ ./manage.py clone_rules

This will copy a subset of YARA rules from several open-source collections. You can add more rule sources in rules/clone_rules.py

Note

We are working on a more expressive configuration for cloning subsets of rule repositories.

Write Your Own Rules

You can add your own .yar or .yara files anywhere in the rules/ directory tree. Refer to the writing YARA rules documentation for guidance and examples. Note that when BinaryAlert finds a file which matches a YARA rule, the rule name, metadata, tags, and matched string names will be included in the alert for your convenience.

External Variables

In order to support the rule repositories listed above, BinaryAlert provides the following external variables:

  • extension - File extension (“.docx”, “.exe”, “.pdf”, etc)
  • filename - File basename (“file.exe”)
  • filepath - Full file path (“/path/to/file.exe”)
  • filetype - Uppercase extension without leading period (“DOCX”, “EXE”, “PDF”), etc

You can use these variables in your own rules to match or exclude certain filepaths. (Note that the variables will default to empty strings if they are not available.) For example, this is a YARA rule which matches only files containing the string “evil” in the /home/ directory:

rule evil_at_home
{
    strings:
        $evil = "evil" nocase wide ascii

    condition:
        $evil and filepath matches /\/home\/*/
}

Supported Modules

BinaryAlert supports all of the default YARA modules, including ELF, Math, Hash, and PE.

Disabling Rules

There may be times you want to disable certain YARA rules, but not delete them (e.g. rules with high false-positive rates). Since only .yar and .yara files in the rules/ directory tree are bundled in a BinaryAlert deploy, you can simply rename rules.yar to any other extension, e.g. rules.yar.DISABLED, to skip it during rules compilation.

If you want to disable an individual rule (not the entire file), you can either comment it out or prefix the rule with the private modifier to elide it from reported YARA match results. Unfortunately, there is no easy way to automatically remove individual rules from a file.

Testing Your Rules

The easiest way to test individual YARA rules is to install YARA locally. Note that you will need the -d flag to define external variables. For example, to test the evil_at_home rule above:

$ brew install yara  # MacOS
$ yara evil_at_home.yar file_to_test.exe -d filepath="/home/user/file_to_test.exe"
# evil_at_home file_to_text.exe

To test all of your YARA rules, you first need to compile them into a single binary file:

$ ./manage.py compile_rules  # Saves "compiled_yara_rules.bin"

This compiled rules file is what gets bundled with the BinaryAlert analyzers. Now, from a Python interpreter:

import yara
rules = yara.load('compiled_yara_rules.bin')
matches = rules.match('file_to_text.exe')
print(matches)

See the yara-python docs for more information about using YARA from Python.