Install and Use an Exakat Module

Exakat comes with a long list of analysis, reading to deal with any PHP code. Nowadays, PHP applications are also built with a framework, that takes place between PHP and the final code. It provides structure to the application and a great amount of ready-to-use features. It is time to install and use an Exakat module.

Using a framework introduces a host of new features, supported by new definitions in the code. For example, the framework may introduce the MVC pattern, with standard classes such as Controller, Model and View, stored neatly in a separate namespace. 

All those definitions must be taken into account when auditing the code. Generally speaking, the framework itself should not be audited with the code. After all, this is the work of a separate team, which should audit the framework by itself.

Yet, the names of the namespaces, classes, interfaces, functions, constants… are useful to avoid flagging them as undefined. Sometimes, they are quite numerous. 

Moreover, using a framework introduces specific rules for coding. In an MVC framework, it is recommended avoiding accessing the database from a controller; nor to manipulate the incoming values inside the model. There may be PHP native functions to avoid, and others that should be replaced by framework native calls. 

Exakat supports 13 frameworks and libraries with modules. Those modules are separate from the main Exakat engine : they have to be downloaded separately. The good news is that they are just as easy to use. Let’s set up one together.

We’ll be reviewing the following steps : you may skip one or two of them if you are already experienced with them.

  • Exakat installation
  • Extension installation
  • New audit
  • Extension usage
  • Report access

Exakat installation

The Exakat installation requires the following software : 

  • PHP 
  • Java

PHP should be 7.3 ideally, but anything beyond 7.0 will work. It is also better if you have several PHP versions, as they may be used to build a richer audit.

From the command line, you may use the following instruction to install everything in one go : 

mkdir exakat cd exakat curl -o exakat.phar http://dist.exakat.io/index.php?file=latest curl -o apache-tinkerpop-gremlin-server-3.3.5-bin.zip http://dist.exakat.io/apache-tinkerpop-gremlin-server-3.3.5-bin.zip unzip apache-tinkerpop-gremlin-server-3.3.5-bin.zip mv apache-tinkerpop-gremlin-server-3.3.5 tinkergraph rm -rf apache-tinkerpop-gremlin-server-3.3.5-bin.zip

cd tinkergraph ./bin/gremlin-server.sh -i org.apache.tinkerpop neo4j-gremlin 3.3.5
cd ..

php exakat.phar version

php exakat.phar doctor 

The version command checks that exakat is ready for action. It may display the following banner : 

 ________                 __              _    
|_   __  |               [  |  _         / |_  
  | |_ \_| _   __  ,--.   | | / ]  ,--. `| |-' 
  |  _| _ [ \ [  ]`'_\ :  | '' <  `'_\ : | |   
 _| |__/ | > '  < // | |, | |`\ \ // | |,| |,  
|________|[__]`\_]\'-;__/[__|  \_]\'-;__/\__/  
                                               


Exakat : @ 2014-2019 Damien Seguy. 
Version : 1.7.4 - Build 905 - Tue, 02 Apr 2019 13:32:35 +0000 

The doctor command checks that Exakat is healthy. It is your go-to command for troubleshooting Exakat. It may display something like this : 

exakat : 
executable           : exakat
version              : 1.7.4
build                : 905
exakat.ini           : ./config/exakat.ini,
graphdb              : gsneo4j
reports              : Ambassador,
Diplomat
rulesets             :
extra rulesets       : 
tokenslimit          : 1 000 000 000
extensions           : 

PHP : 
binary               : 7.3.3
memory_limit         : -1
ext/curl             : Yes
ext/hash             : Yes
ext/phar             : Yes
ext/sqlite3          : Yes
ext/tokenizer        : Yes
ext/mbstring         : Yes
ext/json             : Yes
ext/xmlwriter        : Yes

java : 
installed            : Yes
type                 : Java(TM) SE Runtime Environment (build 1.8.0_201-b09)
version              : java
$JAVA_HOME           : /Library/Java/JavaVirtualMachines/jdk1.8.0_201.jdk/Contents/Home
$JAVA_OPTIONS        : -Xms32m -Xmx16512m

tinkergraph : 
installed            : Yes (folder : /home/exakat/tinkergraph)
host                 : 127.0.0.1
port                 : 8182
gremlin version      : 3.3.5

gsneo4j : 
installed            : Yes (folder : /home/exakat/tinkergraph)
host                 : 127.0.0.1
port                 : 8182
gremlin version      : 3.3.5
neo4j version        : 3.2.3

folders : 
projects folder      : Yes
projects/test        : Yes
projects/default     : No
projects/onepage     : Yes

php52 : 
configured           : No

php53 : 
configured           : No

php54 : 
configured           : No

php55 : 
configured           : No

php56 : 
configured           : No

php70 : 
configured           : No

php71 : 
configured           : No

php72 : 
configured           : Yes (/usr/local/sbin/php72)

php73 : 
configured           : Yes (/usr/local/sbin/php73)

php74 : 
configured           : No

php80 : 
configured           : No 

There, you can check various values that we used during installation : Java, tinkergraph, PHP extensions and memory limit. If the doctor doesn’t recommend anything, we are good to go! 

Exakat module installation

We may now install Exakat’s modules. The installation process is managed from within exakat’s binary, and it hits the central repository, hosted at https://www.exakat.io/. There are several commands available.

> php exakat.phar extension list

You will see a list, like the following table : 

+ Extension             Version Build
---------------------------------------
+ Cakephp                   0.5   (8)
+ Codeigniter               0.1   (5)
+ Drupal                    0.1   (7)
+ Laravel                   0.1   (6)
+ Melis                     0.5  (25)
+ Monolog                   0.1   (3)
+ Prestashop                0.1   (5)
+ Shopware                  0.1   (5)
+ Slim                      0.1  (22)
+ Symfony                   0.6  (15)
+ Twig                      0.1   (3)
+ WordPress                 0.5  (28)
+ ZendF                     0.5   (5)

Total : 13 extensions

Each extension has a name, for example Prestashop, and a version number, here 0.1 and a build number, here 5. The build is incremented with each compilation of the extensions. The set of features is related to the version number. 

Those are the extensions, ready to be installed. To do some, use the install command.

php exakat.phar extension install Prestashop
Prestashop installed with success 

The Prestashop extension is now installed. You can check your current installation with the local command. This is also the default command. 

> php exakat.phar extension local

This displays the following list, unless you have already experimented with other extension’s installation.

+ Extension             Version Build
----------------------------------------
+ Prestashop                0.1   (5)

Total : 1 extension 

You may learn more about the content of an extension in the documentation. For example, the Prestashop extension is documented here : Prestashop.

New Audit

Now that the installation phase is finished, we need some fresh code to test it. Let us install a new project : we’ll install ‘smartblog’, a starred Prestashop module, that adds a blogging tool to the e-commerce platform.

> php exakat.phar init -p smartblog -R https://github.com/smartdatasoft/smartblog.git

This command download the code from github, and run the first checks. This command is only run once : later, you may simply use the update command to pull the next version of the plug-in and run another audit.

Extension Usage

Using the extension means incorporating the analysis and rule sets in the auditing process. There are two options for that : one per-project, and one global. 

The global configuration is available to all the projects : both for the currently installed and the future ones. This is convenient when the audits share some common configuration.

The per-project configuration is suitable for specific projects. For example, if you only have one Prestashop module to audit, then this configuration style is good for you. 

Adding the extension per project

To add the Prestashop extension to the ‘smartblog’ project, edit the project/smartblog/config.ini file. You shall see a configuration file like this one : 

;Main PHP version for this code.
;default is to use config/exakat.ini ;phpversion = 7.3

;Ignored dirs and files, relative to code source root.
ignore_dirs[] = "/assets";
ignore_dirs[] = "/cache";
ignore_dirs[] = "/css";
ignore_dirs[] = "/data";
ignore_dirs[] = "/doc";
ignore_dirs[] = "/docker";
ignore_dirs[] = "/docs";
ignore_dirs[] = "/example";
ignore_dirs[] = "/examples";
ignore_dirs[] = "/images";
ignore_dirs[] = "/js";
ignore_dirs[] = "/lang";
ignore_dirs[] = "/spec";
ignore_dirs[] = "/sql";
ignore_dirs[] = "/test";
ignore_dirs[] = "/tests";
ignore_dirs[] = "/tmp";
ignore_dirs[] = "/version";
ignore_dirs[] = "/var";
ignore_dirs[] = "/vendor";

;Included dirs or files, relative to code source root. Default to all.
;Those are added after ignoring directories include_dirs[] = "";

;Accepted file extensions file_extensions = php,php3,inc,tpl,phtml,tmpl,phps,ctp,module

;Description of the project project_name        = "smartblog";
project_url         = "https://github.com/smartdatasoft/smartblog.git";
project_vcs         = "git";
project_description = "";
project_branch      = "";
project_tag         = "";

You may see the name, URL and VCS of the project, by the end of the file. A the bottom of it, add the following : 

project_themes[]         = "Prestashop";

Note that project_themes is an array : you may add as many Extensions as you want, and run them all at the next audit.

That’s it. If you want to run the audit, skip the next section. Or read it, and learn how to configure the same globally.

Adding the extension globally

The global configuration is available in the config/exakat.ini file. This file contains the same configuration as the previous per-project configuration file, plus some extra ones. 

; use tinkergraph or gsneo4j graphdb = 'gsneo4j';

; where is tinkergraph host ;tinkergraph_host     = '127.0.0.1';
;tinkergraph_port     = '8182';
;tinkergraph_folder   = 'tinkergraph';

; where is neo4j inside a gremlin server host gsneo4j_host     = '127.0.0.1';
gsneo4j_port     = '8182';
gsneo4j_folder   = 'tinkergraph';

; where is janusgraph host (alpha stage, use with caution) ;janusgraph_host     = '127.0.0.1';
;janusgraph_port     = '8182';
;janusgraph_folder   = 'janusgraph';

;php52 =  ;php53 =  ;php54 =  ;php55 = /usr/local/sbin/php55 ;php56 = /usr/local/sbin/php56 ;php70 = /usr/local/sbin/php70 ;php71 = /usr/local/sbin/php71 ;php72 = /usr/local/sbin/php72 ;php73 = /usr/local/sbin/php73 php73 = /usr/local/Cellar/php/7.3.3/bin/php

token_limit = 1000000000

; Default themes to run project_themes[] = 'CompatibilityPHP53';
project_themes[] = 'CompatibilityPHP54';
project_themes[] = 'CompatibilityPHP55';
project_themes[] = 'CompatibilityPHP56';
project_themes[] = 'CompatibilityPHP70';
project_themes[] = 'CompatibilityPHP71';
project_themes[] = 'CompatibilityPHP72';
project_themes[] = 'Analyze';
project_themes[] = 'Preferences';
project_themes[] = 'Appinfo';
project_themes[] = 'Appcontent';
project_themes[] = '"Dead code"';
project_themes[] = 'Security';
project_themes[] = 'Custom';

; Default reports to generate project_reports[] = 'Ambassador';

; where is neo4j host ;neo4j_host     = '127.0.0.1';
;neo4j_port     = '7777';
;neo4j_folder   = 'neo4j';
;neo4j_login    = 'neo4j';
;neo4j_password = 'oui';

You may see that there are already several project_themes directive available. Add the one with your extension here. Simple and double quotes are both valid.

project_themes[] = "Prestashop";

Save the configuration file, and now, head to the audit! 

Run the audit with an Extension

With the configuration as described above, it is now time to run the audit on our code. Type this in the command line, and come back here to read the rest, while Exakat crunches some numbers.

> php exakat.phar project -p smartblog

There, Exakat will now proceed with the review of the code. It will first compile it with PHP, then load it in the database, and then perform the analysis. Then, it will produce the ‘Diplomat’ report, which is the default report for any audit. You may have noticed that there are some projects_reports directives in the configuration files : they are here for configuring the name of the final reports. 

Currently, the Prestashop Extension has no specific report. This means that the results will not appear directly into Diplomat or Ambassador. So, we’ll see another way to reach those results.

The most versatile report type is Text. This is a simple reporting tool, which displays the diagnostic, the file name and line number, then, a short explanation about the diagnosis. Here is one example: 

/library/Exakat/Reports/Text.php:72 Use List With Foreach 

Once Exakat has finished processing, we may request the results : 

php exakat report -p smartblog -T Prestashop -format Text 

With this command, Exakat outputs all the results from the Prestashop rule sets, with the format Text, for the smartblog project. You’ll see it on the command line. Here is an excerpt : 

/controllers/admin/AdminBlogCategoryController.php:192 Prestashop Usage 
/controllers/admin/AdminBlogCategoryController.php:191 Prestashop Usage 
/controllers/admin/AdminBlogCategoryController.php:110 Should Use Tools class 
/controllers/admin/AdminBlogCategoryController.php:108 Should Use Tools class 
/controllers/admin/AdminBlogCategoryController.php:108 Should Use Tools class 
/controllers/admin/AdminBlogCategoryController.php:116 Should Use Tools class 
/controllers/admin/AdminBlogCategoryController.php:107 Should Use Tools class 
/controllers/admin/AdminBlogCategoryController.php:465 Should Use Tools::getValue 
/controllers/admin/AdminBlogCategoryController.php:465 Should Use Tools::getValue 
/controllers/admin/AdminBlogCategoryController.php:464 Should Use Tools::getValue 
/controllers/admin/AdminBlogCategoryController.php:464 Should Use Tools::getValue 
/controllers/admin/AdminBlogCategoryController.php:464 Should Use Tools::getValue 
/controllers/admin/AdminBlogCategoryController.php:464 Should Use Tools::getValue 
/controllers/admin/AdminBlogCategoryController.php:464 Should Use Tools::getValue 
/controllers/admin/AdminBlogCategoryController.php:471 Should Use Tools::getValue 
/controllers/admin/AdminBlogCategoryController.php:471 Should Use Tools::getValue 
/controllers/admin/AdminImageType.php:82 Should Use Tools class 
/controllers/admin/AdminImageType.php:83 Should Use Tools class 
/controllers/admin/AdminImageType.php:83 Should Use Tools class 
/controllers/admin/AdminImageType.php:85 Should Use Tools class 

Specific rules from Extension

Currently, the Prestashop extension has two specific analysis : Should use Tools::getValue, that report access to PHP superglobals, such as $_GETor $_POST, while prestashop recommends using Tools::getValue() for the same feature; and Should Use Tools class for usage of PHP native functions, such as strtolower() or ucfirst(), while prestashop has set up alternatives for those functions.

Compatibility, version by version

You will also find results of compatibility : the Prestashop extension for Exakat includes the description of the version 1.5, 1.6 and 1.7 framework. It reports any usage of classes that are not part of those versions : if the code has to ensure compabitility with any version, it should only use classes, interfaces and traits from the right versions.

Less false positives in the classic analysis

Extensions are used automatically when testing for a large number of analysis. For example, classes are considered undefined if they have no definition, no PHP native support (like stdClass or Sqlite3), and are not part of the extension databases. This applies to other PHP structures, such as functions, or constants. It also applies to methods and class constants. 

Better PHP Code Reviews

You have now successfully installed Exakat, and one extension. You may add more of them, or try them on other repositories. Extensions are compatible with each other, so you may add several of them, so as to process various projects, or a Frankencode, that handles multiple frameworks at the same time.

Extensions are in constant progress. Definitions databases, rule-sets, specific analysis and even specific reports are added regularly, so make surer to update your extension repository on a regular basis.