Installation

Requirements

Exakat relies on external components : mandatroy or optional.

Basic requirements :

  • exakat.phar, the main code.
  • Gremlin server : exakat uses this graph database and the Gremlin 3 traversal language. Currently, only Gremlin Server is supported, with the tinkergraph and neo4j storage engine. Version 3.4.x is the recommended version, while version 3.3.x are still supported. Gremlin version 3.2.# and 3.5.# are unsupported.
  • Java 8.x. Java 9.x/10.x will be supported later. Java 7.x was used, but is not actively supported.
  • PHP 8.0 to run. PHP 8.0 is recommended, PHP 7.2 or later are possible. This version requires the PHP extensions curl, hash, phar, sqlite3, tokenizer, mbstring and json.

Optional requirements :

  • PHP 5.2 to 8.1-dev for analysis purposes. Those versions only require the ext/tokenizer extension.
  • VCS (Version Control Software), such as Git, SVN, bazaar, Mercurial. They all are optional, though git is recommended.
  • Archives, such as zip, tgz, tbz2 may also be opened with optional helpers (See Installation guide for optional tools).

OS requirements :

  • Exakat has beed tested on OSX, Debian and Ubuntu (up to 20.04).
  • Exakat should work on Linux distributions, may be with little work.
  • Exakat hasn’t been tested on Windows at all.

For installation, curl or wget, and zip are needed.

Download exakat.phar

You can download exakat directly from https://www.exakat.io/.

This server also provides older versions of Exakat. It is recommended to always download the last version, which is available with https://www.exakat.io/versions/index.php?file=latest.

For each version, MD5 and SHA256 signatures are available. The downloaded MD5 must match the one in the related .md5 file. The .md5 also has the version number, for extra check.

curl -o exakat.phar 'https://www.exakat.io/versions/index.php?file=latest'

curl -o exakat.phar.md5 'https://www.exakat.io/versions/index.php?file=latest.md5'
//19485adb7d43b43f7c01b7153ae82881  exakat-2.0.0.phar
md5sum exakat.phar.md5
// Example :
//19485adb7d43b43f7c01b7153ae82881  exakat.phar

curl -o exakat.phar.sha256 'https://www.exakat.io/versions/index.php?file=latest.sha256'
//d838c9ec9291e15873137693da2a0038a67c2f15c2282b89f09f27f23d24d27f  exakat-2.0.0.phar
sha256sum exakat.phar.md5
// Example :
//d838c9ec9291e15873137693da2a0038a67c2f15c2282b89f09f27f23d24d27f  exakat.phar

// Check with GPG signature
curl -o exakat.sig 'https://www.exakat.io/versions/index.php?file=latest.sig'
// Optional step : Download the Key
gpg --recv-keys 5EDF7EA4
// Check with GPG signature
gpg --verify exakat.sig exakat.phar
// Good result :
//gpg: Signature made Tue Nov  5 07:48:34 2019 CET using RSA key ID 5EDF7EA4
//gpg: Good signature from "Seguy Damien <damien.seguy@gmail.com>" [ultimate]

Installation with exakat.phar

Exakat.phar includes its own installation script, as long as PHP is available. Exakat will then check different pre-requisites, and proceed to install some of the last elements.

Exakat checks for Java and Zip installations. Then, it downloads tinkergraph and the Neo4j plugin from exakat.io and runs the doctor command.

The script is based on the one displayed on the next section.

You can use the install command this way :

mkdir exakat
cd exakat
curl -o exakat.phar 'https://www.exakat.io/versions/index.php?file=latest'
php exakat.phar install

Installation on OSX

Paste the following commands in a terminal prompt. It downloads Exakat, and installs tinkerpop version 3.4.11. PHP 7.4 or more recent, curl, homebrew are required.

OSX installation with tinkergraph 3.4.11

This is the installation script for Exakat and tinkergraph 3.4.11.

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.11-bin.zip 'https://www.exakat.io/versions/apache-tinkerpop-gremlin-server-3.4.11-bin.zip'
unzip apache-tinkerpop-gremlin-server-3.4.11-bin.zip
mv apache-tinkerpop-gremlin-server-3.4.11 tinkergraph
rm -rf apache-tinkerpop-gremlin-server-3.4.11-bin.zip

# Optional : install neo4j engine.
cd tinkergraph
./bin/gremlin-server.sh install org.apache.tinkerpop neo4j-gremlin 3.4.11
cd ..

php exakat.phar doctor

OSX installation troubleshooting

It has be reported that installation fails on OSX 10.11 and 10.12, with error similar to ‘Error grabbing Grapes’. To fix this, use the following in command line :

rm -r ~/.groovy/grapes/
rm -r ~/.m2/

They remove some files for grapes, that it will rebuild later. Then, try again the optional install instructions.

Installation on Debian/Ubuntu

Debian/Ubuntu installation with Tinkergraph 3.4.11

Paste the following commands in a terminal prompt. It installs Exakat most recent version with Tinkergraph 3.4.11. PHP 7.3 (7.0 or more recent), wget and unzip are expected.

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

# Optional : install neo4j engine.
cd tinkergraph
./bin/gremlin-server.sh install org.apache.tinkerpop neo4j-gremlin 3.4.11
cd ..

php exakat.phar doctor

Prerequisites : Full installation with Debian/Ubuntu

The following commands are an optional pre-requisite to the installation guide, that just follows. If something is missing in the next section, check with this section that all has beed installed correctly.

//// Installing PHP from sury.org
apt update
apt install apt-transport-https lsb-release ca-certificates

wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
sh -c 'echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
apt update

apt-get install php7.2 php7.2-common php7.2-cli php7.2-curl php7.2-json php7.2-mbstring php7.2-sqlite3

//// Installing Java JDK
echo "deb http://ppa.launchpad.net/webupd8team/java/ubuntu trusty main" | tee /etc/apt/sources.list.d/webupd8team-java.list
echo "deb-src http://ppa.launchpad.net/webupd8team/java/ubuntu trusty main" | tee -a /etc/apt/sources.list.d/webupd8team-java.list
apt-get update

echo debconf shared/accepted-oracle-license-v1-1 select true | debconf-set-selections
echo debconf shared/accepted-oracle-license-v1-1 seen true | debconf-set-selections
DEBIAN_FRONTEND=noninteractive  apt-get install -y --force-yes oracle-java8-installer oracle-java8-set-default

//// Installing other tools
apt-get update && apt-get install -y --no-install-recommends git subversion mercurial lsof unzip

Installation guide with Composer

Composer installation first run

To install Exakat with composer, you can use the following commands:

mkdir exakat
cd exakat
composer require exakat/exakat
php vendor/bin/exakat install -v

The final command checks for the presence of Java and unZip utility. Then, it installs a local copy of a Gremlin server. This is needed to run Exakat.

To run your first audit, use the following commands:

php vendor/bin/exakat init -p sculpin -R 'https://github.com/sculpin/sculpin.git'
php vendor/bin/exakat project -p sculpin

The final audit is now in the projects/sculpin/report directory.

Installation guide with Docker

There are multiple ways to use exakat with docker. There is an image with a full exakat installation, which run with a traditional installation, or inside the audited code. Or, You may use Docker with a standard installation, to run useful part, such as a specific PHP version or the central database.

image:: images/exakat-and-docker.png

Docker image for Exakat with projects folder

Installation with Docker is easy, and convenient. It hides the dependency of the graph database, and keeps all files in the ‘projects’ folder, created in the working directory.

Currently, Docker installation only ships with one PHP version (7.3), and with support for bazaar, composer, git, mercurial, svn, and zip.

docker pull exakat/exakat

# Check-run exakat :

docker run -it -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat version
docker run -it -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat doctor

# Init a project :

docker run -it -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat init -p <project name> -R <vcs_url>

If you need SSH credentials to clone a project, you may import your SSH keys in the repository by assigning them to the exakat user. With the commmand below, the local set of keys of user ‘my-user’ are assigned to exakat in the container. Note that those keys will request the passphrase, which will prevent their usage.

docker run -it -v /home/my-user/.ssh:/home/exakat/ssh -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat init -p <project name> -R <vcs_url>

# Run exakat :

docker run -it -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat project -p <project name>

# Run exakat directly in the code base. For that, the code needs to have the .exakat.yml or .exakat.ini file available at the root. Then, you may call exakat with the ‘project’ command, without other options.

docker run -it -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat project

For large code bases, it may be necessary to increase the allocated memory for the graph database. Do this by using the JAVA_OPTIONS environment variable when you start the docker command : this example gives 2Gb of RAM to the graphdb. That should cover medium size applications.

docker run -it -e JAVA_OPTIONS="-Xms32m -Xmx2g" -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat

You may run any exakat command by prefixing it with the following command :

docker run -it -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat

You may also create a handy shortcut, by creating an exakat.sh script and put it in your PATH :

cat 'docker run -it -v $(pwd)/projects:/usr/src/exakat/projects --rm --name my-exakat exakat/exakat exakat $1' > /etc/local/sbin/exakat.sh
chmod u+x  /etc/local/sbin/exakat.sh
./exakat.sh version

Docker image for Exakat with projects folder

To run exakat inside the audited code, you must configure the .exakat.ini or .exakat.yaml file. See Add Exakat To Your CI Pipeline.

Then, you can run the following command, with docker :

docker run -it --rm -v `$pwd`:/src exakat/exakat:latest exakat project -v

Docker PHP image with Exakat

Exakat recognizes docker images configured as PHP binaries. Instead of configuring exakat with local binaries, such as /usr/bin/php, you may configure a specific PHP version with a docker image.

Open the config/exakat.ini file, at the root of the exakat installation, and use the following value :

// configuration with the 'tetraweb/php:5.5' image.
;php55 = tetraweb/php:5.5
php56 = tetraweb/php:5.6
# classic configuration with local binary
php73 = /usr/bin/php

The image may be any docker image that provides a PHP binary. We suggest using tetraweb/php, which supports PHP 5.5 to 7.1. There are other images available, and you may also roll out your own.

Docker Gremlin image with Exakat

Exakat is able to use only the central database, Gremlin, as a docker image. This is convenient, as the database is only a temporary database, and those data are not necessary for producing the final reports.

This image is under construction, and will be soon available.

Installation guide as Github Action

Github Action

Github Action is a way to “Automate, customize, and execute your software development workflows right in your repository”. Exakat runs on Github platform.

Set up Github Action for Exakat

To add Exakat to your repository on Github, create a file .github/workflows/exakat.yml, at the root of your repository (.github/workflows might already exists, otherwise create it).

In the file, use the following YAML code. It creates an automatic action, on push and pull_request actions, that runs Exakat and display the issues found in the workflow panel. It is also possible to run manually this action, with the workflow_dispatch : after installing the exakat.yaml file, go to the ‘Actions’ tab and locate the ‘Run workflow’ button.

on: [push, pull_request, workflow_dispatch]
name: Test
jobs:
  exakat:
    name: Exakat
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Exakat
      uses: docker://exakat/exakat-ga

Note : it is recommended to edit this file directly on github.com, as it cannot be pushed from a remote repository.

Then, you can use the Action button, next to ‘Pull requests’, or push a new commit to trigger this. This will run Exakat on the repository, with the ‘CI-checks’ ruleset, and in the ‘Perfile’ format.

Create status badge

Github action creates automatically status badge, that can be displayed on the repository or other websites, and keep you updated of the last exakat run.

In the ‘Actions’ tag, select the workflow, and find the ‘…’ on the right. Click on it, and the first item will be ‘Create status badge’. Then, follow the instructions to get a Markdown badge.

Github Action Configuration directives

Exakat for Github action provide support for custom directives, by using the ‘with’ keyword in the configuration. Here is an example :

on: [push, pull_request, workflow_dispatch]
name: Test
jobs:
  exakat:
    name: Exakat
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Exakat
      uses: docker://exakat/exakat-ga
    - with:
      ignore_rules: 'Classes/StaticMethodsCalledFromObject,Php/ShouldUseCoalesce,Functions/UsesDefaultArguments'
      ignore_dirs: '/path/to/repos#1,/path/to/repos#2,/path/to/repos#3'
      project_reports: Sarif,Diplomat,Perfile

The supported directives are the following:

  • exit_on_issues : default to true. Use empty string for false. The github action returns with exit code 1 if any issue is found during the review. Set this to empty string, to have the action return 0. You may also configure the step with continue-on-error.
  • ignore_rules : default to empty. A comma-separated list of Exakat rule short names, that will be excluded from the review. For example : ignore_rules: Structures/AddOne,Structures/PlusEgalOne.
  • ignore_dirs : default to empty. A comma-separated list folders that will be omitted. They are relative to the root of the repository.
  • include_dirs : default to empty. A comma-separated list folders that must be added. They are relative to the root of the repository, and will be added after the ignore_dirs directive.
  • file_extensions : default to exakat’s default value. A comma-separated list of file extensions to filter the processed files. Default list is php,php3,inc,tpl,phtml,tmpl,phps,ctp,module. This configuration replaces the default one.
  • project_reports : default to Perfile. A comma-separated list of Exakat reports to be processed. For example : Perfile,Sarif,Diplomat. Reports such as ‘Diplomat’ must be uploaded elsewhere (with upload artifact), as the produced file will be written in the Github Action, which is later removed.

Other exakat directives may be provided by using the In-code Configuration, aka .exakat.yaml or .exakat.ini.

Upload reports as artefact

When producing a report with Github action, the result is either send to STDOUT, aka the log in the Github interface : this is the case for the Perfile report. Or, it is written in the Github action’s container. Then, the report must be uploaded out of the container to be preserved.

Github upload, aka actions/upload-artifact@v2, is a solution to upload the results. Add the following configuration in the action file :

- name: Exakat
  uses: docker://exakat/exakat-ga
- with:
  ///... possible other directives
  project_reports: Diplomat
  /// project_reports may include other reports, like Sarif and Perfile
- uses: actions/upload-artifact@v2
  with:
    name: my-exakat-report
    path: /github/workspace/diplomat

The report files are stored in the /github/workspace folder, with different names depending on the requested exakat report. For example, the Sarif report is exported to the file ‘exakat.sarif’, while the Diplomat report is stored in the folder called ‘diplomat’. Thus, the configuration shall be :

- uses: actions/upload-artifact@v2
  with:
    name: my-exakat-diplomat-report
    path: /github/workspace/diplomat
- uses: actions/upload-artifact@v2
  with:
    name: my-exakat-sharif-report
    path: /github/workspace/exakat.sharif

Exakat Docker image for Github Action

A Docker image is released with Exakat’s version automatically, to be used with Github Action. It is available at https://hub.docker.com/r/exakat/exakat-ga.

You can run it in any given directory like this:

cd /path/to/code
docker pull exakat/exakat-ga
docker run --rm -it -v ${PWD}:/app exakat/exakat-ga:latest

Using multiple PHP versions

You need at least one version of PHP to run exakat. This version needs the curl, hash, tokenizer, hash and sqlite3 extensions. They all are part of the core.

Extra PHP-CLI versions allow more linting of the code. They only need to have the tokenizer extension available.

Exakat recommends PHP 8.0.x (or newer version) to run Exakat. We also recommend the installation of PHP versions 5.6, 7.1, 7.2, 7.3, 7.4, 8.0 and 8.1 (aka php-src master).

To install easily various versions of PHP, use the ondrej repository. Check The main PPA for PHP (8.0, 7.4, 7.3, 7.2, 7.1, 7.0, 5.6). You may also check the dotdeb repository, at dotdeb instruction or compile PHP yourself.

Installation guide for optional tools

Exakat is able to use a variety of tools to access PHP code to audit. Some external tools are necessary. You can check which tools are recognized locally with the exakat doctor -v command.

  • bazaar : the bzr command must be available.
  • composer : the composer command must be available.
  • CVS : the cvs command must be available
  • Git : the git command must be available.
  • mercurial : the hg must be available
  • Svn : the svn command must be available.
  • tgz : the tar and gunzip commands must be available
  • tbz : the tar and bunzip2 commands must be available.
  • rar : the rar commands must be available.
  • zip : the unzip command must be available.
  • 7z : the 7z command must be available

The binaries above are used with the init and update commands, to get the source code. They are optional.