Code auditing

Installing Exakat to monitor several projects

Posted on by dams

Installing Exakat to monitor several projects

Exakat is the smart Static analysis tool for PHP. It reviews the source for PHP compatibility (8.0, 8.1, 8.2 already, Security, and much more. When running it for several projects, it is convenient to use the ‘projects’ style of installation, more than the ‘in-code’ configuration.

The ‘projects’ installation is organized around the ‘projects’ folder, where each code source will have its own folder. That way, you may have several source code ready, with their own local caches and distinct audits. It is most convenient when you run the audits locally, and then, dispatch the audits to various targets, human or machines.

Agenda

  • Installation of exakat
  • Running an Exakat audit
  • Extra configuration

Installation of Exakat

To do the installation, you can use the following script :

Note : the first step creates a folder that will contain all the installation and data. Just locate it where you want, in the file system.

mkdir exakat 
cd exakat
curl -o exakat.phar 'https://www.exakat.io/versions/index.php?file=latest'
curl -o apache-tinkerpop-gremlin-server-3.4.12-bin.zip 'https://www.exakat.io/versions/apache-tinkerpop-gremlin-server-3.4.12-bin.zip'
unzip apache-tinkerpop-gremlin-server-3.4.12-bin.zip
mv apache-tinkerpop-gremlin-server-3.4.12 tinkergraph
rm -rf apache-tinkerpop-gremlin-server-3.4.12-bin.zip

# install neo4j engine for gremlin. This is optional and recommended
cd tinkergraph
./bin/gremlin-server.sh install org.apache.tinkerpop neo4j-gremlin 3.4.12
cd ..

php exakat.phar doctor

At the end of this step, you may see the following

exakat : 
    executable           : exakat.phar
    version              : 2.3.0
    build                : 1266
    exakat.ini           : ./config/exakat.ini
    graphdb              : gsneo4jv3
    reports              : 
    rulesets             : Analyze,
                           Appinfo,
                           "Dead code",
                           Security
    extra rulesets       : 
    ignored rules        : 
    tokenslimit          : 1 000 000 000
    stubs                : 
    
/// More lines after that

Troubleshooting

  • Make sure that you have PHP ready on the command line. PHP 8.0+ is recommended, though PHP 7.3 and 7.4 are supported.
  • PHP requires mbstring, sqlite3, phar, curl, json and hash.
  • The call to ./bin/gremlin-server.sh sometimes fails, due to network timeout. In that case, remove the tinkergraph/ext/neo4j-gremlin/ and try again.

Running an Exakat audit

At that point, you are ready to run an audit. Let’s assume that the code is available online, at the following address https://github.com/sculpin/sculpin. This is probably not your code of interest, though it is worth checking the installation with it.

From the root of the installation, run the following commands, then keep on reading :

php exakat init -p sculpin -R https://github.com/sculpin/sculpin -v
php exakat project -p sculpin

Now, the second command is probably running. So, you have a few minuts to keep on reading this tutorial.

The first command initialize the project, in the projects folder : there is now a folder, named sculpin, with different files in it :

  • code : the actual source code
  • config.ini : the configuration file
  • datastore.sqlite : a sqlite database with audit related data
  • dump.sqlite : the raw results from the audit
  • other files, as new reports will be created there

The second command, ‘project’ run an audit on the provided code. To keep this short, exakat collect the files, load them in a graph database, then runs the rules in the code, looking for patterns. Then, it dumps the results in the dump.sqlite file, and finally, build the report.

By default, exakat build the ‘Diplomat’ report, which is a general purpose report, with code review, dead code detection, PHP 7.4,8.0 and 8.1 compatibility. It will be available in a folder called ‘diplomat’ in the ‘projects/sculpin/’ folder.

As this is an HTML report, you can use your browser to open the projects/sculpin/diplomat/index.html file.

Running another audit

While the first audit is still running, you may prepare your target code by running again the first command, and download the source locally. Here are some extra interesting options.

Exakat uses by default git to clone source code. It also supports several other VCS, such as SVN, hg. Here is an example with mercurial

php exakat init -p frontaccounting -R http://hg.code.sf.net/p/frontaccounting/mercurial -v -hg

There is also the -symlink option, which works with a local folder, and create a link to that directory.

php exakat init -p localcode -R /home/my/src/ -symlink -v

In case of an error, you may drop an existing project with the following command.

php exakat remove -p localcode

Extra configuration

There are two different configuration files for Exakat with this installation : the config/exakat.ini and the projects/***/config.ini.

The first one holds common directives, for the whole installation, while the second holds project specific configuration.

PHP versions

You have already been using a PHP binary to run exakat, which is actually written in PHP itself. Yet, you may target a different PHP version for your review : indeed, some of the exakat rules have a version range of validity, and may or may not be available, depending on the PHP target.

Exakat has no less than three PHP versions to configure :

  • The PHP to run exakat itself. This is the ‘php’ at the beginning of the command line above.
  • The phpversion directive, which is available both in config/exakat.ini and projects/***/config.ini : this version is the target version. It is configured by default to the PHP version used at creation time, so this usually means that the default value is available on your system. You may replace this directive with any middle version of PHP from PHP 5.2 to PHP 8.2, as show here : phpversion = 81
  • the php** directives in the config/exakat.ini : those have to point to a local PHP binary, with the corresponding version. For example : php74 = /usr/local/sbin/php74 Exakat will use those binary to check for compilation for each of those version during the audit. It will also use those binaries to run the audit, when a specific version is configured. The PHP binaries are only configured in the config/exakat.ini file.

After changing the values, you can check them with the doctor command. By appending the -p <project> option, the doctor will display the configuration, including the directives specified in the projects/***/config.ini files.

php exakat.phar doctor -p sculpin

If you have changed those directive, you should then run again an new ‘project’ command, to update the audits.

php exakat.phar project -p sculpin

A running Exakat installation

After this tutorial, you now have a running exakat installation! Congratulations. You may repeat the section Running an Exakat audit for each and every project that you need to audit. While auditing one project, the audits are always available in their distinct project folder, for you to consume locally or ship remotely.

Happy PHP Auditing with Exakat!