.. _user-Configuration: Configuration =============== Summary ------- * `Common Behavior`_ * `Project Configuration`_ * `In-code Configuration`_ * `Commandline Configuration`_ * `Specific analysis configurations`_ 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 : 1. The command line options 2. The .exakat.ini or .exakat.yaml file at the root of the code 3. The environment variables 4. The config.ini file in the project directory 5. The exakat.ini file in the config directory 6. 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). .. _user-option-placements: 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 | | +---------------------+--------+---------+---------+----------+ .. _user-option-availability: 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. .. _user-in-code-configuration: 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_name: "" project_rulesets: - Analyze file_extensions: php,php3,phtml project_report: - - 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_name: project_rulesets: - - Analysis file_extensions: php,php3,phtml project_report: - - 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. :ref:`@ Operator <@-operator>` + authorizedFunctions : noscream_functions.json + Functions that are authorized to sports a @. :ref:`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. :ref:`Abstract Class Constants ` + minimum : 2 + Minimal number of constant found in children to report this as a potential abstract class. :ref:`Array() / [ ] Consistence ` + array_ratio : 10 + Percentage of arrays in one of the syntaxes, to trigger the other syntax as a violation. :ref:`Cancel Common Method ` + cancelThreshold : 75 + Minimal number of cancelled methods to suggest the cancellation of the parent. :ref:`Collect Vendor Structures ` + pdffList : [] + List of vendors, their version and related PDFF. {'vendor':['wordpress.5.9.pdff','wordpress.5.8.pdff']} :ref:`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. :ref:`Could Be Enumeration ` + minElements : 2 + Minimal number of elements to consider that a property may be an enumeration. :ref:`Could Be Parent Method ` + minChildren : 4 + Minimal number of children using this method. :ref:`Could Make A Function ` + centralizeThreshold : 8 + Minimal number of calls of the function with one common argument. :ref:`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. :ref:`Custom Class Usage ` + forbiddenClasses : + List of classes to be avoided :ref:`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. :ref:`Fossilized Method ` + fossilizationThreshold : 6 + Minimal number of overwriting methods to consider a method difficult to update. :ref:`Hardcoded Passwords ` + passwordsKeys : password_keys.json + List of array index and property names that shall be checked for potential secret key storages. :ref:`Immutable Signature ` + maxOverwrite : 8 + Minimal number of method overwrite to consider that any refactor on the method signature is now hard. :ref:`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 :ref:`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. :ref:`Large Try Block ` + tryBlockMaxSize : 5 + Maximal number of expressions in the try block. :ref:`Long Arguments ` + codeTooLong : 100 + Minimum size of a functioncall or a methodcall to be considered too long. :ref:`Long Preparation For Throw ` + preparationLineCount : 8 + Minimal number of lines before the throw. :ref:`Make Magic Concrete ` + magicMemberUsage : 1 + Minimal number of magic member usage across the code, to trigger a concrete property. :ref:`Max Level Of Nesting ` + maxLevel : 4 + Maximum level of nesting for control flow structures in one scope. :ref:`Memoize MagicCall ` + minMagicCallsToGet : 2 + Minimal number of calls of a magic property to make it worth locally caching. :ref:`Method Usage ` + searchFor : + Method to report in the codes : use static syntax to describe them : \a::foo(); \a\b\c::goo(). :ref:`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. :ref:`Multiline Expressions ` + min : 2 + Minimal number of lines in an expression to report. :ref:`Multiple Index Definition ` + arrayMaxSize : 15000 + Maximal size of arrays to be analyzed. This will speed up analysis, and leave the largest arrays untouched. :ref:`Nested Ifthen ` + nestedIfthen : 3 + Maximal number of acceptable nesting of if-then structures :ref:`Nested Ternary ` + minNestedTernary : 2 + Minimal number of nested ternary to report. :ref:`New On Functioncall Or Identifier ` + threshold : 10 + Maximal percentage for a syntax to be considered to be fixed. :ref:`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. :ref:`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 :ref:`Randomly Sorted Arrays ` + maxSize : 5 + Maximal size of arrays to survey. :ref:`Should Use Prepared Statement ` + queryMethod : query_methods.json + Methods that call a query. :ref:`Too Complex Expression ` + complexExpressionThreshold : 30 + Minimal number of operators in one expression to report. :ref:`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. :ref:`Too Many Array Dimensions ` + maxDimensions : 3 + Number of valid dimensions in an array. :ref:`Too Many Children ` + childrenClassCount : 15 + Threshold for too many children classes for one class. :ref:`Too Many Dereferencing ` + tooManyDereferencing : 7 + Maximum number of dereferencing. :ref:`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. :ref:`Too Many Injections ` + injectionsCount : 5 + Threshold for too many injected parameters for one class. :ref:`Too Many Local Variables ` + tooManyLocalVariableThreshold : 15 + Minimal number of variables in one function or method to report. :ref:`Too Many Native Calls ` + nativeCallCounts : 3 + Number of native calls found inside another call. :ref:`Too Many Parameters ` + parametersCount : 8 + Minimal number of parameters to report. :ref:`Too Many Stringed Elseif ` + maxIf : 5 + Maximum number of allowed stringed if-then-elseif structure. :ref:`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. :ref:`Used Once Trait ` + timeUsed : 2 + Maximal number of trait usage, before the trait is considered enough used. :ref:`Useless Argument ` + maxUsageCount : 30 + Maximum count of function usage. Use this to limit the amount of processed arguments. :ref:`Variables With Long Names ` + variableLength : 20 + Minimum size of a long variable name, including the initial $. :ref:`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.