Configuring analysis in Exakat

With the 15 mins install, you can get Exakat running in short time, and audit any PHP code without configuration. This is great to start with, and explore the features of the static analysis engine.

Later, when you get to know the report and the important analysis for you, you want to refine this initial configuration and tailor it to your needs. This helps focusing on the important issues, rather than sorting out unused results. It also saves some time while processing the code.

There are several ways to configure Exakat:

• Configure the analysis
• Select just one report
• Select analysis themes
• Build your own theme

Configuring analysis

Some analysis may be configured independently. For example, the ‘Too Many Parameters’ rules has a default threshold of 8. According to extensive stats, this is a decent amount, and probably well beyond the red flag limit of 4. Yet, with applications accepting up to 20 arguments, it may quickly report too many false positive.

To configure the analysis, open the project/*/config.ini file. At the end, you can add the following:

[Functions/TooManyParameters]
parametersCount = 8;

The INI section name is ‘Functions/TooManyParameters’. It is the id name for the analysis. You can find that name in Exakat documentation Too Many Parameters, or in the Ambassador documentation.

Simply add as many sections as you need. Any extra parameter are ignored.

All the parametrized analysis are listed in the Specific analyzer configurations section.

Configuring one report

Exakat runs audits until it can build a report. That report is the final goal, and where you’ll have access to the results.

There are two type of reports. Some, like ‘Ambassador’ or ‘Drillinstructor’, have a list of pre-requisite to be built. Others, like ‘Json’ or ‘Text’ have no pre-requisite, and may be built with any list of analysis that are available. We’ll cover those in the next section.

Configuring in config.ini

The straightforward configuration is to set one or more reports for Exakat to produces. Use the project_reports directive. Set it in the projects/*/config.ini file, with the rest of the directives, such as project_name, ignore_dirs, etc. Avoid putting it after a section, as introduced in the previous presentation.

project_reports[] = 'Ambassador'
project_reports[] = 'Drillinstructor'

[Functions/TooManyParameters]
parametersCount = 8;

You can find the list of available reports in the documentation;

Configuring in exakat.ini

When you have a long list of projects to audit, it is easier to configure project_reports in config/exakat.ini file. This way, the configuration is available by default for all the projects, and new projects.

Edit config/exakat.ini file. There should already be a line in the document with project_reports configured with ‘Ambassador’. Add more lines if you need multiple reports to be build automatically.

Once this has beed configure, check that it is understood by Exakat with

php exakat.phar doctor

The name of the reports are at the top of the list. If they are missing, check the configuration file and the name of the reports.

Configuring Analysis Themes

Some reports require specific configurations, while others have a general purpose and can report about anything. They are usually less human-friendly, and more machine friendly.

For example, the Text report list all the results, one by line. It’s easy to store, or transmit to another processing script. The JSON report does the same, in JSON format.

To use them, add the -format option to ‘report‘ command, and mention -P with an analysis, or -T for a Theme. Like this:

# list all the results for Functions/TooManyParameters
php exakat.phar report -format Text -P Functions/TooManyParameters

# list all the results for Security
php exakat.phar report -format Text -T Security

When using Text or Json, the report format doesn’t have any pre-requisite. It checks that the theme has been audited, and it reports an error when it is not available. So, the theme has to be audited first.

This is done by adding the project_themes array, to the config/exakat.ini (for global configuration) or the projects/*/config.ini file for per-project configuration. Just like projects_reports, put the variable in the main section, and not in an analysis section.

project_reports[] = 'Ambassador'
project_themes[] = 'Security'

[Functions/TooManyParameters]
parametersCount = 8;

Exakat collects all the configured and required themes, and run them once. No need to check if a theme is configured multiple times: it is only processed once.

That means that ‘Ambassador’, which requires among others ‘Security’ and ‘Performances’, allows the production of the following report, even if it it not explicitly configured.

# list all the results for Security
php exakat.phar report -format Text -T Performances

Configuring You Own Themes

Finally, it is possible to build a custom list of analysis to run, and then export it with a generic report.

As for that, create a config/themes.ini files in exakat config folder. Each themes you want to build is an INI section, and the analyzer are stored in the ‘analyzer’ array, with their short name. Here is a short example:

['mine']
analyzer[] = 'Structures/AddZero';
analyzer[] = 'Performances/ArrayMergeInLoops';

You may configure as many custom themes are you want. Use lowercase only names, so as to differentiate them with the built-in themes: the behavior is undefined if two themes use the same name.

You can check that the themes are available when running the doctor command. Configured and valid themes are also mentioned when running the project command, in verbose mode.

This feature is available with Exakat 1.2.8, from May 21rst 2018.

Happy code reviews

Exakat works quickly, out of the box, and without configuration. This important for exploring the capabilities of the engine, and explore what are the useful analysis for a source code.

As you capitalize experience with your code, it is time to switch from exploration to enforcement: keeping a narrow number of aspects under scrutiny, to make sure they never come back. This calls for a targeted analysis, based on the previous explorations. Reports, Themes and Analysis are all described in the documentation.

Exakat has split the audit phase and the report phase : the engine collects a wide range of analysis, and allows you to access them later, depending on your usage, or other systems requirement.