User rules

Users can create and use their own rules for analysis of configuration files. To create a rule, do the following:

1. Describe necessary rules following the requirements.
2. Save the rules to a file.
3. Start PT.Config with the following arguments:

[main.py|conf.exe] --user-rules <filename> [other options] <scan target>

Learn more about startup parameters here.

File format

Data in a file must be structured as JSON (an object or list of objects). Each JSON object is interpreted as a separate rule. Object format:

{
    "conftype": "",
    "name": "",
    "xpath": ["", [“”]*] or “”,                                    
    "default": "",
    "recommended": ["", [“”]*] or “” or {“”=>””, [“”=>””]*},
    "not_recommended": ["", [“”]*]  or “” or {“”=>””, [“”=>””]*},
    "comparison_type": ["in", "equal", "<=", "regexp"], 
    "regexp": "some_regexp" or [“some_regexp_0”, [“some_regexp_n”]*],
    "comparison_method":  ["all", "any"]
}

• conftype: a configuration file type, mandatory parameter. Supported types: ".htaccess", "apache.conf", "applicationHost.config", "domain.xml", "lighttpd.conf", "machine.config", "nginx.conf", "php.ini", "server.xml_tomcat", "server.xml_websphere", "standalone.xml", "web.config", "web.xml".

• name: name of an option, directive, or attribute; mandatory parameter. For configuration files expressed as XML, an attribute name must start with @.

• xpath: a string or list of strings that describe a possible context or contexts for option positioning. Optional parameter. Acceptable context: Apache, Nginx. For Lighttpd ["root"] xpath indicates that search within conditional blocks is deactivated. For XML-based configuration files xpath describes partial or full XPath.

• default: a default option value, mandatory parameter.

• recommended: a single option value or list of recommended option values, mandatory parameter.

• not_recommended: a single option value or list of not recommended option values, optional parameter. Note: if this parameter is specified, the "recommended" field is not analyzed.

• comparison_type: a comparison type, optional parameter ("equal" by default). Possible values:

  • "equal" checks if the current value equals to values described in a rule.
  • "in" checks if values described in a rule are present in the current value.
  • "<=" checks if a binary operator is executed:

  <current_value> <= <(not)recommended value>;

  • "regexp" checks if the current value matches a regular expression described in the **regexp ** parameter.

• regexp: if comparison_type equals to 'regexp', the parameter contains a regular expression (or a list of regular expressions), used for comparison, otherwise it is ignored. Optional parameter.

• comparison_method: a method for comparison of the default value with the list of values specified in the rule ("any" by default), optional parameter. Allowed values:

  • "all" stands for all values specified in the rule;
  • "any" means that a single match with any value is enough.

Composite rules

To describe more complicated rules that require analysis of more than one option, directive, or attribute, create a list of rules, where each rule describes a single option. All rules, except the final one, specify conditions required for the final rule to be applied.

Examples

Rule with a minimum number of fields:

{
    "conftype": "foo.conf",
    "name": "foo",
    "default": "bar",
    "recommended": "baz"
}

This rule checks if the "foo" option exists in the configuration file with the "foo.conf" type and compares the option's default value with the recommended value. A warning will be displayed if the option value is not "baz" or if the option is missing.

Composite rule:

[
    {
        "conftype": "foo.conf",
        "name": "foo",
        "default": "true",
        "recommended": "false",
    },
    {
        "conftype": "foo.conf",
        "name": "bar",
        "default": true,
        "recommended": "true"
    }
]

This rule checks if the "bar" option exists in the configuration file with the "foo.conf" type providing that the option "foo" is set to "true" or is missing. A warning will be displayed if the "bar" option does not equal to "true".