Using Exakat with Docker
Exakat is available on docker, as community version. It is available at hub.docker.com. Here is how to use it.
docker is needed to run this tutorial.
To install exakat, start docker, then run the following command in the terminal :
git pull exakat/exakat:latest
With a graphical interface, such as Docker Desktop, in the ‘images’ entry, use the ‘remote repositories’ to load a remote image.
This is the latest exakat version,
2.4.0 at the time of writing this tutorial. The fixed version is also available with the
The image uses the last PHP version available, PHP
8.1.8 at the time of writing. A PHP 8.0 version is also available.
Finally, Exakat is also build for AMD (Intel processor) or ARM (Apple M1). It is possible to choose among those version with the following format :
- tag : latest, 2.4.0
- php : 81, 80
- platform : amd64, arm64
git pull exakat/exakat-81-arm64:latestis the latest version for Apple M1 computers. In the rest of the tutorial, we’ll use
exakat/exakat:latest as image, and you may use any downloaded image instead in the commands.
Checking the image
Before running an audit, let’s check if the installation is correct. Run the following command :
docker run -it --rm exakat/exakat:latest
This is the default command, which prints the version of Exakat. The results should look list this :
________ __ _ |_ __ | [ | _ / |_ | |_ \_| _ __ ,--. | | / ] ,--. `| |-' | _| _ [ \ [ ]`'_\ : | '' < `'_\ : | | _| |__/ | > ' < // | |, | |`\ \ // | |,| |, |________|[__]`\_]\'-;__/[__| \_]\'-;__/\__/ Exakat : @ 2014-2022 Damien Seguy - Exakat SAS <contact(at)exakat.io>. Version : 2.4.0 - Build 1312 - Wed, 20 Apr 2022 14:54:25 +0200
You may also run the
doctor command, to review the default installation config :
docker run -it --rm exakat/exakat:latest doctor
Here is a result :
exakat : executable : ./exakat version : 2.4.0 build : 1312 exakat.ini : ./config/exakat.ini graphdb : gsneo4jv3 reports : rulesets : CompatibilityPHP74, CompatibilityPHP80, CompatibilityPHP81, Analyze, Appinfo extra rulesets : ignored rules : tokenslimit : 100 000 000 stubs : PHP : binary : 8.1.8 memory_limit : -1 short_open_tags : Off ext/curl : Yes ext/hash : Yes ext/phar : Yes ext/sqlite3 : Yes ext/tokenizer : Yes ext/mbstring : Yes ext/json : Yes ext/xmlwriter : Yes pcre.jit : On (Must be off on PHP 7.3 and OSX) java : installed : Yes type : OpenJDK Runtime Environment 18.9 (build 11.0.16+8) version : openjdk $JAVA_HOME : /usr/local/openjdk-11 $JAVA_OPTIONS : tinkergraph : installed : Yes (folder : /usr/src/exakat/tinkergraph) host : 127.0.0.1 port : 7474 gremlin version : 3.4.13 tinkergraphv3 : installed : Yes (folder : /usr/src/exakat/tinkergraph) host : 127.0.0.1 port : 7474 gremlin version : 3.4.13 gsneo4j : installed : No (folder : tinkergraph) gsneo4jv3 : installed : Yes (folder : /usr/src/exakat/tinkergraph) host : 127.0.0.1 port : 8182 gremlin version : 3.4.13 neo4j version : 3.2.3 nogremlin : installed : Always project : name : url : phpversion : 7.4 reports : "Diplomat" rulesets : CompatibilityPHP74, CompatibilityPHP80, CompatibilityPHP81, Analyze, Appinfo included dirs : ignored dirs : /assets, /cache, /css, /data, /doc, /docker, /docs, /example, /examples, /images, /js, /lang, /spec, /sql, /test, /tests, /tmp, /version, /var ignored rules : file extensions : php, php3, inc, tpl, phtml, tmpl, phps, ctp, module folders : projects folder : Yes php81 : configured : Yes (/usr/bin/php) actual version : 8.1.8
We can check that PHP 8.1, Java 11 and Exakat 2.4.0 are all installed. So far, so good.
To run a first audit, we need source code. We are going to use the following Git repository, for the purpose of testing :
https://github.com/zordius/lightncandy.git. It is a public package, from Zordius, which makes handlebars.
To run the audit, use the following
project command :
docker run -it --rm exakat/exakat:latest project -p zordius -R https://github.com/zordius/lightncandy.git --format Text
While it runs, here are some explanations :
-pis the project name. It is a compulsory argument for exakat. Here, it is a free string.
-Ris the URI to the repository. It is compulsory with the
initcommand. The format of the value depends on the VCS in use. Here, it is a URL, while it would be a package handle with composer.
-githas been omitted here, as it is the default option. Other VCS are supported, such as
--formatprovides the format of the audit. It is
Texthere, so the audit is exported to the STDOUT, in Text format, one issue per line. There are other format which outputs results to the STDOUT. Other possible format here, are
Once the audit has run, it will provide results similar to this :
/src/Encoder.php:84 Type/OneVariableStrings One Variable String $v /src/Encoder.php:101 Functions/UndefinedFunctions Undefined Functions htmlspecialchars(static::raw($cx, $var), ENT_QUOTES, 'UTF-8') /src/Encoder.php:101 Constants/UndefinedConstants Undefined Constants ENT_QUOTES /src/Encoder.php:101 Constants/ConstantUsage Constants Usage ENT_QUOTES /src/Encoder.php:119 Functions/UndefinedFunctions Undefined Functions str_replace(array('=', '`', '''), array('=', '`', '''), htmlspecialchars(static::raw($cx, $var), ENT_QUOTES, 'UTF-8')) /src/Encoder.php:119 Functions/UndefinedFunctions Undefined Functions htmlspecialchars(static::raw($cx, $var), ENT_QUOTES, 'UTF-8') /src/Encoder.php:119 Constants/UndefinedConstants Undefined Constants ENT_QUOTES /src/Encoder.php:119 Constants/ConstantUsage Constants Usage ENT_QUOTES /src/Encoder.php:70 Functions/UndefinedFunctions Undefined Functions array_diff_key($v, array_keys(array_keys($v))) /src/Encoder.php:70 Functions/UndefinedFunctions Undefined Functions array_keys(array_keys($v)) /// ..... more lines
The first audit provides results to STDOUT, the terminal screen. Exakat offers several other formats, which are saved as files. Since those would be lost at the end of the run of the image, we need to adapt the command to keep the results.
docker run -it --rm -v `pwd`/projects:/usr/src/exakat/projects/ exakat/exakat:latest project -p zordius -R https://github.com/zordius/lightncandy.git
This time, Exakat runs and share a folder called
projects, where the intermediate results are stored. While it runs, here are some details :
-vis a docker option, which maps a host machine folder (here the
projectsfolder, in the current directory), to a folder in the docker container, where the audits and various files will be stored.
--formatwas removed, as the command produces the
Diplomatreport, by default. We’ll see some other format later.
After the run, you should find a local folder called
projects. In it, you’ll find a folder called
zordius, and, yet again, in it, several files and folder. Open the one called
diplomat, and the file
index.htmlwith a web browser. You should get the result of the audit.
Producing more reports
One advantage of saving the results is the possibility to produce more reports, using a different format.
report command produce the same report as the first audit, without running the audit again : it relies on the results that were produced by the previous step. For a repeat, or a specific extraction, this is a lot faster as all is cached.
docker run -it --rm -v `pwd`/projects:/usr/src/exakat/projects/ exakat/exakat:latest report -p zordius --format Text
The following report provides the same results, grouped by file.
docker run -it --rm -v `pwd`/projects:/usr/src/exakat/projects/ exakat/exakat:latest report -p zordius --format Perfile
List of reports and rulesets
All the availables rules, rulesets and reports in the current Exakat version are listed with the
catalog command :
docker run -it --rm -v `pwd`/projects:/usr/src/exakat/projects/ exakat/exakat:latest catalog
The full list, including the extra availables in the Enterprise version of Exakat is online, in the documentation.
Rerun the audit on updated code
With a locally saved report, exakat may update the source, and run the audit again. Use the following commands :
docker run -it --rm -v `pwd`/projects:/usr/src/exakat/projects/ exakat/exakat:latest update -p zordius docker run -it --rm -v `pwd`/projects:/usr/src/exakat/projects/ exakat/exakat:latest update -p zordius
update command only works with a saved report : with a direct
projectcommand, the code is cloned again, so there is no need for
The resulting audit will be replaced with a new one. Save it before starting the new audit if you want to compare them later.
Run another saved audit
To run an audit on another code, use the commands from the
Second auditsection, with a different URL and project name. They will all be stored in the
Extract only some results
By default, the Text report exports a preset list of rules. If you want focus on one specific ruleset, you can use the
-T option. Here is the command with the
docker run -it --rm -v `pwd`/projects:/usr/src/exakat/projects/ exakat/exakat:latest report -p zordius --format Text -T Security
Here is the command with one specific rule :
Structures/NoParenthesisForLanguageConstruct. This rule checks if parenthesis are used with language constructs, such as include_once : they are useless.
docker run -it --rm -v `pwd`/projects:/usr/src/exakat/projects/ exakat/exakat:latest report -p zordius --format Text -P Php\BetterRand
The names of Rulesets and Rules are available in the documentation of the Diplomat report, or online.
Docker installation is convenient as it hides the complexity of the installation. The audit results are quick to obtain, and it is now time to review what was found.