Configuring Rules in Exakat

Exakat default installation is tailored for discovery : it is made so as to give a broad view over the engine’s possibilities. As your experience grows, a more refined configuration is needed to adapt the results to the style of the development team. This tutorial helps your configuring rules in Exakat.

An Exakat analysis is called a rule. Rules are the atomic element of an audit. They provide all the necessary elements for tracking a bug, collecting context or documenting a piece of code. As their population is growing by the day, rules are grouped in rulesets.

There are three ways to change the rulesets in use : the ignore_rules directive, the target report, and the custom rulesets. Let’s see how each of them works.

The Reports

Let’s start by the end : the report is the final form of the Exakat audit. It is where the issues that were detected are presented. There are over 30 types of reports, published with Exakat : some reports are for humans, some are for machines.

Reports have two ways of operating : flexible, they work on any set of rules, or planned, when they require specific sets of rules. Flexible means that they accept a last-minute configuration. The planned reports, on the other hand, add their own configurations from the start.

Flexible reports

The Text report is the most flexible report. It displays the issues, one by line. It doesn’t require any ruleset by itself, and accepts any of them as configuration.

# default configuration : Analyze
php exakat.phar report -p my-project --format Text -v 

# One rule : + 0 analysis
php exakat.phar report -p my-project --format Text -P Structures/AddZero -v 

# One Ruleset : Security
php exakat.phar report -p my-project --format Text -T Security -v 

Note : the above-mentioned commands are valid after Installation and a first Audit run.

Other flexible formats include sqlite, XML or YAML.

Planned reports

Diplomat is a good example of a report that requires a specific set of ruleset. Diplomat presents lots of information in a graphical interface : when those issues are missing, because they were not run, it creates empty sections. For example, the inventories may be empty.

To avoid empty sections, Diplomat requests a number of rulesets, as soon as Exakat process the project. That way, the Diplomat report will have all the needed information. By configuring Diplomat, Exakat will automatically add the requested rulesets.

Configuration

To configure, or not, a report, you can use two different files : config/exakat.ini or projects/<my-project>/config.ini.

In there, add the directive project_reports[] =, followed by the name for the report. Repeat as often as needed. You may even use the All report, which will produce all of them. The detailed listis available in the documentation.

Configuring config/exakat.ini configures the default behavior for every project. Each project may be configured independently with projects/<my-project>/config.ini. That last configuration file has precedence over the general configuration.

The ignore_rules Directive

The ignore_rules directive works with planned reports, and the audit phase of Exakat. It is meant to skip a rule, even when the rule is requested by a ruleset or a planned report. The rule is then simply omitted.

Ignoring a rule inside a ruleset, simply reduces the size of the ruleset. As an extreme case, the ruleset may end up empty.

Configuration

To configure the ignore_rules directive, you can use two different files : config/exakat.ini or projects/<my-project>/config.ini.

In there, add the directive ignore_rules[] =, followed by the name for the rule. A rule name uses the format Directory/Name. You can find all of the rules in the documentation, online or in Diplomat’s report.

Doctor Check For Ignored Rules

Once you have added enough rules to the ruleset, you can check its availability with the command php exakat.phar doctor. There is a line ignored rules, in the exakat section of the display. It should bear the name of the rules that were ignored.

The rulesets

For flexible reports, you can add the rules at generation time.

# Two rules : repeat -P option as often as needed
php exakat.phar report -p myself --format Text -P Structures/AddZero -P Structures/MultiplyByOne -v 


# One Ruleset : Security
php exakat.phar report -p my-project --format Text -T Security -v 

The second format is more convenient : for example, the ‘Security’ ruleset includes over 44 rules. Writing them in a row is too long : this is why rulesets were introduced initially.

To create a custom ruleset, add the file config/rulesets.ini. It is a .INI file, with the following structure :

[name_of_the_ruleset]
analyzer[] = "Structures/AddZero"
analyzer[] = "Structures/MultiplyByOne"

Each section bears the name of one new ruleset. You can add as many rulesets as you want. They must each bear a distinct name, to avoid confusion.

Each section includes the name analyzer, with a short rule name as value. The short names are available in the documentation, and reports such as Diplomat and Ambassador.

Doctor Check For Extra Rulesets

Once you have added enough rules to the ruleset, you can check its availability with the command php exakat.phar doctor. There is a line extra rulesets, in the exakat section of the display. It should bear the name of the ruleset you just created.

Ruleset Usage

To get tailor your report with the new ruleset, use its name in the report command :

# One Ruleset : name_of_the_ruleset
php exakat.phar report -p my-project --format Text -T name_of_the_ruleset -v 

Note that rules that are invalid, not run during the audit, or non-existing will be omitted in the final result.

Configuring Exakat As You Need

The three ways to configure Exakat fit the different phases of usage : + Report is an early choice where the rules are chosen by the tool + ignore_rules refines the previous choice + Custom rulesets is for advanced users, cherry-picking each rules as fit with the development style.

Happy Audits!