Basic configuration

Once the YARA-CI application is installed in the repository that contains your YARA rules you don’t need to do anything special. Just by installing the application your YARA files are going to be analyzed by YARA-CI every time a change occurs in the repository. However, you can control the way in which YARA-CI behaves by adding a .yara-ci.yml file to the repository’s root directory.

As the name indicates .yara-ci.yml is a YAML file. A minimal .yara-ci.yml with the default configuration for YARA-CI is shown below. This is the configuration file used when you don’t add one to your repository.

branches:
  accept:
  - "**"
files:
  accept:
  - "**.yar"
  - "**.yara"

The branches section allows you to specify the patterns that decide in which branches to run the YARA-CI analyses. It can include both an accept and an ignore lists with glob patterns. When you make a commit to a branch whose name matches one of the patterns in the accept list, YARA-CI will launch the analyses in this branch as long as it doesn’t also match a pattern in the ignore list. Lets see some examples.

Analyze only the master branch:

branches:
  accept:
  - "master"

Analyze any branch except those whose name begins with dirty-test:

branches:
  ignore:
  - "dirty-test**"

Note that no accept pattern was given in the example above. When no accept pattern is given the ** pattern is included by default.

As with branches, the accept list is where you specify the patterns that decide which files are analyzed by YARA-CI. By default this is all files with .yar and .yara extensions in all directories. Patterns are written in glob format, where single asterisks (*) stand for any number of arbitrary characters not including the path separator (/) and double asterisks (**) stand for any number of characters, including the path separator.

For example, **.yar matches foo.yar, foo/bar.yar and foo/bar/baz.yar, but *.yar matches foo.yar and bar.yar, but it doesn’t match foo/bar.yar.

Patterns are always matched against the file’s absolute path within the repository, and they are analyzed by YARA-CI if the path matches at least one of the patterns in the accept list.

In addition to the accept list you can use specify an ignore list. For example, with the configuration file shown below YARA-CI analyzes files with extensions yar and yara, but excludes those that are located in the ignored_files directory or any of its subdirectories, even if its extension is .yar or .yara.

files:
  accept:
  - "**.yar"
  - "**.yara"
  ignore:
  - "ignored_files/**"

Of course, the ignore list can have multiple patterns, and you can even use it without an accept list:

files:
  ignore:
  - "ignored_files/**"
  - "more_ignored_files/*"

When the accept list is not explicitly included in the configuration file, the patterns accepted by default are **.yar and **.yara. The patterns in the accept list are applied first to determine which files should be analyzed, those passing the filter are matched against the patterns listed in ignore, excluding those that matches any of the patterns.