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
The Exakat installation requires the following software :
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
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
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
php exakat.phar extension install Prestashop
Prestashop installed with success
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.
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.
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";
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.
Prestashop Extension has no specific report. This means that the results will not appear directly into
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
Prestashop extension has two specific analysis :
Should use Tools::getValue, that report access to PHP superglobals, such as
$_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.