Configuration¶
Summary¶
Common Behavior¶
General Philosophy¶
Exakat tries to avoid configuration as much as possible, so as to focus on working out of the box, rather than spend time on pre-requisite.
As such, it probably does more work, but that may be dismissed later, at reading time.
More configuration options appear with the evolution of the engine.
Precedence¶
The exakat engine read directives from six places, with the following precedence :
The command line options
The .exakat.ini or .exakat.yaml file at the root of the code
The environment variables
The config.ini file in the project directory
The exakat.ini file in the config directory
The default values in the code
The precedence of the directives is the same as the list above : command line options always have highest priority, config.ini files are in second, when command line are not available, and finally, the default values are read in the code.
Some of the directives are only available in the config.ini files, or at the engine level.
Common Options¶
All options are the same, whatever the command provided to exakat. -f always means files, and -q always means quick.
Any option that a command doesn’t understand is ignored.
Any option that is not recognized is ignored and reported (with visibility).
Option placements¶
This table show in which file the directive may be placed to be used. ‘exakat’ is the config/exakat.ini file, ‘project’ is the projects/–name–/config.ini file, and ‘in-code’ is the .exakat.yaml/ini file, directly in the code.
name |
exakat |
project |
in-code |
rule |
phpversion |
X |
X |
X |
|
ignore_dirs |
X |
X |
X |
X |
include_dirs |
X |
X |
X |
X |
ignore_rules |
X |
X |
X |
|
file_extensions |
X |
X |
X |
X |
project_name |
X |
X |
X |
|
project_description |
X |
X |
X |
|
project_url |
X |
|||
project_vcs |
X |
|||
project_reports |
X |
X |
||
project_rulesets |
X |
X |
||
project_vcs |
X |
|||
project_packagist |
X |
|||
project_cobblers |
X |
X |
X |
|
rulesets |
X |
Option availability¶
This table shows which operation (audit, cobbler) is parametered by which directive.
name |
project / analyze |
cobble |
phpversion |
X |
X |
ignore_dirs |
X |
X |
include_dirs |
X |
X |
ignore_rules |
X |
X |
file_extensions |
X |
X |
project_reports |
X |
|
project_rulesets |
X |
|
project_vcs |
X |
|
project_cobblers |
X |
Project Configuration¶
Project configuration are were the project specific configuration are stored. For example, the project name, the ignored directories or its external libraries are kept. Configurations only affect one project and not the others.
Project configuration file are called ‘config.ini’. They are located, one per project, in the ‘projects/<project name>/config.ini’ file.
Available Options¶
Here are the currently available options in Exakat’s project configuration file : projects/<project name>/config.ini
phpversion¶
PHP Version with which to run the code analysis.
It may be one of : 8.2, 8.1, 8.0, 7.4, 7.3, 7.2, 7.1, 7.0, 5.6, 5.5, 5.4, 5.3, 5.2. Default is 8.0 or the CLI version used to init the project. 8.2 is currently the development version. 5.* versions are available, but are less tested. phpversion it is a string.
include_dirs¶
This is the list of files and dir to include in the project’s directory. It is chrooted in the project’s folder. Values provided with a starting / are used as a path prefix.
Values without / are used as a substring, anywhere in the path. include_dirs are added AFTER ignore_dirs, so as to partially ignore a folder, such as the vendor folder from composer. include_dirs is an array of string.
ignore_dirs¶
This is the list of files and dir to ignore in the project’s directory. It is chrooted in the project’s folder. Values provided with a starting / are used as a path prefix. Values without / are used as a substring, anywhere in the path.
ignore_dirs is an array of string.
file_extensions¶
This is the list of file extensions that is considered as PHP scripts. All others are ignored. All files bearing those extensions are subject to check, though they are scanned first for PHP tags before being analyzed. The extensions are comma separated, without dot.
The default are : php, php3, inc, tpl, phtml, tmpl, phps, ctp file_extensions may be a comma-separated list of values as a string, or an array.
project_name¶
This is the project name, as it appears at the top left in the Ambassador report.
project_url¶
This is the repository URL for the project. It is used to get the source for the project.
project_vcs¶
This is the VCS used to fetch the project source.
project_description¶
This is the description of the project.
project_packagist¶
This is the packagist name for the code, when the code is fetched with composer.
In-code Configuration¶
In-code configuration is a configuration file that sits at the root of the code. When exakat finds it, it uses it for in-code auditing.
The file is .exakat.ini, and is a valid INI file. It has priority over the YAML version.
The file is .exakat.yaml, and is a valid YAML file. .exakat.yml is also valid, but not recommended.
In case those files are not found, or valid, Exakat reverts to default values.
Unrecognized values are ignored.
Exakat in-code YAML example¶
project: exakat
project_name: exakat
project_rulesets:
- my_ruleset
- Security
project_report:
- Diplomat
file_extensions: php,php3,phtml
include_dirs:
- /
ignore_dirs:
- /tests
- /vendor
- /docs
- /media
ignore_rules:
- Structures/AddZero
rulesets:
my_ruleset:
- Structures/AddZero
- Structures/MultiplyByOne
Exakat in-code INI example¶
project= exakat
project_name= exakat
project_rulesets[] = my_ruleset
project_rulesets[] = Security
project_report[] = Diplomat
file_extensions= php,php3,phtml
include_dirs[] = /
ignore_dirs[] = /tests
ignore_dirs[] = /vendor
ignore_dirs[] = /docs
ignore_dirs[] = /media
ignore_rules[] = Structures/AddZero
Exakat in-code skeleton¶
Copy-paste this YAML code into a file called .exakat.yaml, located at the root of your repository.
project: <project identifier>
project_name: "<project_name>"
project_rulesets:
- Analyze
file_extensions: php,php3,phtml
project_report:
- <list of reports to build>
- Ambassador
include_dirs:
- /
ignore_rules:
-
exclude_rules:
-
ignore_dirs:
- /tests
- /vendor
- /docs
- /media
Structures/AddZero:
php_extensions:
- php
- php3
namespaces:
- \\ns
Exakat in project’s config.ini file¶
Copy-paste this YAML code into a file called .exakat.yaml, located at the root of your repository.
This configuration is for the Structures/AddZero rule. It ignores directories at the root, starting with a c; it applies the rule only to files with tpl, php, php3 extensions and the namespaces \ns and \ns2.
[Structures/AddZero]
ignore_dirs = "/c";
file_extensions = "tpl,php,php3";
namespaces[] = "\\ns,"
namespaces[] = "\\ns2,"
Available Options¶
Here are the currently available options in Exakat’s project configuration file : projects/–project name–/config.ini.
When a value is ignored, it will be filled with the default value of the project, or the server. When defined, they replace those default values.
include_dirs¶
This is the list of files and dir to include in the project’s directory. It is chrooted in the project’s folder. Values provided with a starting / are used as a path prefix.
Values without / are used as a substring, anywhere in the path. include_dirs are added AFTER ignore_dirs, so as to partially ignore a folder, such as the vendor folder from composer.
This an array of strings, which are dirnames or filenames.
ignore_dirs¶
This is the list of files and dir to ignore in the project’s directory. It is chrooted in the project’s folder. Values provided with a starting / are used as a path prefix. Values without / are used as a substring, anywhere in the path.
This an array of strings, which are dirnames or filenames.
ignore_rules¶
The rules mentioned in this list are ignored when running the audit. Rules are ignored after loading the rulesets configuration : as such, it is possible to ignore rules inside a ruleset, without ignoring the whole ruleset.
The rules in this list are Exakat’s short name : ignore_rules[] = “Structures/AddZero”
This an array of strings, which are all rules names
include_rules¶
There is no include_rules directive. Create a custom Ruleset, and include it with project_rulesets (see below).
This an array of strings, which are all rules names.
file_extensions¶
This is the list of file extensions that is considered as PHP scripts. All others are ignored. All files bearing those extensions are subject to check, though they are scanned first for PHP tags before being analyzed. The extensions are comma separated, without dot.
This an array of strings, which are all extension names, without the ‘.’ dot.
project_name¶
This is the project name, as it appears at the top left in the Ambassador report.
This is a string.
project_url¶
This is the repository URL for the project. It is used to get the source for the project.
project_vcs¶
This is the VCS used to fetch the project source.
This is a string.
project_description¶
This is the description of the project.
This is free text, used in reports.
project_description¶
This is the description of the project.
This is free text, used in reports.
project_packagist¶
This is the packagist name for the code, when the code is fetched with composer.
This is a single string.
project_rulesets¶
This is the list of default rules to run for this project.
This an array of strings, which are ruleset names.
project_reports¶
This is the list of default reports to run for this project.
This an array of strings, which are all reports names
rulesets¶
This is a list of custom ruleset, along with the ruleset names.
This directive is only available with YAML format.
This an array of hashes. The keys of the hashes are the custom rulsets, and their value is an array of rule short names.
Rule-level Configuration¶
There are configuration which are available for each rule. They are common and always available.
namespaces¶
The namespaces where this rule applies. Only results within the listed namespaces will be reported. All others are omitted.
By défault, all namespaces are used.
Namespaces may be specified similarly to file paths : \ns, with the leading backslash, for absolute namespaces : then, they are treated as prefixes. ns, without the leading backslash, for relative namespaces : then, they are treated as any part of the namespace. It is possible to use * and ?, like for path in a file systems.
ignore_dirs¶
The folders where this rule applies. Only results within the listed folders will be reported. All others are omitted, unless added with include_dirs.
By défault, all folders are used.
folders may be specified similarly to file paths : /ns, with the leading backslash, for absolute path : then, they are treated as prefixes. ns, without the leading backslash, for relative folders : then, they are treated as any part of the path. It is possible to use * and ?, like for path in a file systems.
include_dirs¶
The folders where this rule applies. Only results within the listed folders will be reported. All others are omitted, unless added with include_dirs.
By défault, all folders are used.
folders may be specified similarly to file paths : /ns, with the leading backslash, for absolute path : then, they are treated as prefixes. ns, without the leading backslash, for relative folders : then, they are treated as any part of the path. It is possible to use * and ?, like for path in a file systems.
file_extensions¶
The file’s extensions where this rule applies. Only files with the listed extensions will be reported.
By default, all the configured extensions are used.
Note that this filter is applied after the file_extensions configuration is used to select the audited files in the repository. So, this directive shall, at worse, only use extensions that are already applied.
Configuration in .yaml file¶
Copy-paste this YAML code into a file called .exakat.yaml, located at the root of your repository.
file_extensions: php,php3,phtml
project: <project short name>
project_name: <project name, as displayed in reports>
project_rulesets:
- <list of rulesets to apply>
- Analysis
file_extensions: php,php3,phtml
project_report:
- <list of reports to build>
- Ambassador
include_dirs:
- /
ignore_rules:
-
exclude_rules:
-
ignore_dirs:
- /tests
- /vendor
- /docs
- /media
Commandline Configuration¶
Commandline configurations are detailled with each command, in the _Commands section.
Specific analysis configurations¶
Some analyzer may be configured individually. Those parameters are then specific to one analyzer, and it only affects their behavior.
Analyzers may be configured in the project/*/config.ini; they may also be configured globally in the config/exakat.ini file.
- @ Operator
authorizedFunctions : noscream_functions.json
Functions that are authorized to sports a @.
- Abstract Away
abstractableCalls :
Functions that shouldn’t be called directly, unless in a method.
abstractableClasses :
Classes that shouldn’t be instantiated directly, unless in a method.
- Abstract Class Constants
minimum : 2
Minimal number of constant found in children to report this as a potential abstract class.
- Array() / [ ] Consistence
array_ratio : 10
Percentage of arrays in one of the syntaxes, to trigger the other syntax as a violation.
- Cancel Common Method
cancelThreshold : 75
Minimal number of cancelled methods to suggest the cancellation of the parent.
- Collect Vendor Structures
pdffList : []
List of vendors, their version and related PDFF. {‘vendor’:[‘wordpress.5.9.pdff’,’wordpress.5.8.pdff’]}
- Could Be A Constant
minOccurences : 1
Minimal number of occurrences of the literal.
skipString : ,.php
List of omitted string values. For example, the empty string.
skipInteger : 1,-0,-1
List of omitted integer values. By default, 0, 1 and -1.
- Could Be Enumeration
minElements : 2
Minimal number of elements to consider that a property may be an enumeration.
- Could Be Parent Method
minChildren : 4
Minimal number of children using this method.
- Could Make A Function
centralizeThreshold : 8
Minimal number of calls of the function with one common argument.
- Could Use Existing Constant
omittedValues :
Comma-separated list of values that have to be ignored with this analysis. They replace the default values of 0 and 1.
- Custom Class Usage
forbiddenClasses :
List of classes to be avoided
- Duplicate Literal
minDuplicate : 15
Minimal number of duplication before the literal is reported.
ignoreList : 0,1,2,10
Common values that have to be ignored. Comma separated list.
- Fossilized Method
fossilizationThreshold : 6
Minimal number of overwriting methods to consider a method difficult to update.
- Hardcoded Passwords
passwordsKeys : password_keys.json
List of array index and property names that shall be checked for potential secret key storages.
- Immutable Signature
maxOverwrite : 8
Minimal number of method overwrite to consider that any refactor on the method signature is now hard.
- Injectable Version
injectableVersion : injectableversion
The FQN for the InjectableVersion attribute. By default, it is in the global space
checkInjectableVersion : checkinjectableversion
The FQN for the CheckInjectableVersion attribute. By default, it is in the global space
- Keep Files Access Restricted
filePrivileges : 0777
List of forbidden file modes (comma separated). This should be a decimal value : 511 instead of 777. The values will not be converted from octal to decimal.
- Large Try Block
tryBlockMaxSize : 5
Maximal number of expressions in the try block.
- Long Arguments
codeTooLong : 100
Minimum size of a functioncall or a methodcall to be considered too long.
- Long Preparation For Throw
preparationLineCount : 8
Minimal number of lines before the throw.
- Make Magic Concrete
magicMemberUsage : 1
Minimal number of magic member usage across the code, to trigger a concrete property.
- Max Level Of Nesting
maxLevel : 4
Maximum level of nesting for control flow structures in one scope.
- Memoize MagicCall
minMagicCallsToGet : 2
Minimal number of calls of a magic property to make it worth locally caching.
- Method Usage
searchFor :
Method to report in the codes : use static syntax to describe them : a::foo(); abc::goo().
- Missing Include
constant_or_variable_name : 100
Literal value to be used when including files. For example, by configuring ‘Files_MissingInclude[“HOME_DIR”] = “/tmp/myDir/”;’, then ‘include HOME_DIR . “my_class.php”; will be actually be used as ‘/tmp/myDir/my_class.php’. Constants must be configured with their correct case. Variable must be configured with their initial ‘$’. Configure any number of variable and constant names.
- Multiline Expressions
min : 2
Minimal number of lines in an expression to report.
- Multiple Index Definition
arrayMaxSize : 15000
Maximal size of arrays to be analyzed. This will speed up analysis, and leave the largest arrays untouched.
- Nested Ifthen
nestedIfthen : 3
Maximal number of acceptable nesting of if-then structures
- Nested Ternary
minNestedTernary : 2
Minimal number of nested ternary to report.
- New On Functioncall Or Identifier
threshold : 10
Maximal percentage for a syntax to be considered to be fixed.
- PHP Keywords As Names
reservedNames :
Other reserved names : all in a string, comma separated.
allowedNames :
PHP reserved names that can be used in the code. All in a string, comma separated.
- Prefix And Suffixes With Typehint
prefixedType : prefixedType[‘is’] = ‘bool’;
prefixedType[‘has’] = ‘bool’; prefixedType[‘set’] = ‘void’; prefixedType[‘list’] = ‘array’;
List of prefixes and their expected returntype
suffixedType : prefixedType[‘list’] = ‘bool’;
prefixedType[‘int’] = ‘int’; prefixedType[‘string’] = ‘string’; prefixedType[‘name’] = ‘string’; prefixedType[‘description’] = ‘string’; prefixedType[‘id’] = ‘int’; prefixedType[‘uuid’] = ‘Uuid’;
List of suffixes and their expected returntype
- Randomly Sorted Arrays
maxSize : 5
Maximal size of arrays to survey.
- Should Use Prepared Statement
queryMethod : query_methods.json
Methods that call a query.
- Too Complex Expression
complexExpressionThreshold : 30
Minimal number of operators in one expression to report.
- Too Long A Block
longBlock : 200
Size of a block for it to be too long. A block is commanded by a for, foreach, while, do…while, if/then else structure.
- Too Many Array Dimensions
maxDimensions : 3
Number of valid dimensions in an array.
- Too Many Children
childrenClassCount : 15
Threshold for too many children classes for one class.
- Too Many Dereferencing
tooManyDereferencing : 7
Maximum number of dereferencing.
- Too Many Finds
minimumFinds : 5
Minimal number of prefixed methods to report.
findPrefix : find
list of prefix to use when detecting the ‘find’. Comma-separated list, case insensitive.
findSuffix :
list of fix to use when detecting the ‘find’. Comma-separated list, case insensitive.
- Too Many Injections
injectionsCount : 5
Threshold for too many injected parameters for one class.
- Too Many Local Variables
tooManyLocalVariableThreshold : 15
Minimal number of variables in one function or method to report.
- Too Many Native Calls
nativeCallCounts : 3
Number of native calls found inside another call.
- Too Many Parameters
parametersCount : 8
Minimal number of parameters to report.
- Too Many Stringed Elseif
maxIf : 5
Maximum number of allowed stringed if-then-elseif structure.
- Too Much Indented
indentationAverage : 1
Minimal average of indentation in a method to report. Default is 1.0, which means that the method is on average at one level of indentation or more.
minimumSize : 3
Minimal number of expressions in a method to apply this analysis.
- Used Once Trait
timeUsed : 2
Maximal number of trait usage, before the trait is considered enough used.
- Useless Argument
maxUsageCount : 30
Maximum count of function usage. Use this to limit the amount of processed arguments.
- Variables With Long Names
variableLength : 20
Minimum size of a long variable name, including the initial $.
- Wrong Locale
otherLocales :
Other accepted locales, comma separated
maxPositions : 3
Number of argument in setLocale() to be tried.
Check Install¶
Once the prerequisite are installed, it is advised to run to check if all is found :
php exakat.phar doctor
After this run, you may edit ‘config/config.ini’ to change some of the default values. Most of the time, the default values will be OK for a quick start.