Each rules file is an array of one or more Rules object, conforming to the following Schema:
Schema
{
"id" : type=string
Required Value
Unique Value
"name": type=string
Required Value
"overrides": type=array of string
Optional Value
"tags": type=array of strings
Optional value, no default value
"depends_on_tags": type=array of strings
Optional value, no default value,
When set this matches for this rule won't be returned unless all the tags in this field are present (from any rule matching any file)
"applies_to": type=array of strings
Optional value, no default value (default behavior is applies to everything)
"applies_to_file_regex": type=array of strings
Optional value, no default value (default behavior is applies to everything)
"severity": type=enum (string)
Required Value
"description": type=string
Required Value, a human friendly description for the rule for use in report output. May not be null or empty string.
"patterns": type=array of Pattern
Required Value
"conditions": type=array of Conditions
Optional Value
"must-match": type=array of string
Optional Value
"must-not-match": type=array of string
Optional Value
"_comment": type=string
Optional Value
}
Definitions of each Key/Value Pair
id
id should be in the form AI######. It must be unique per rule.
- Example: "id":"AI168931"
name
Short text identifier of the rule intended for humans. Does NOT need to be unique per rule
- Example: "name" : "Detect broken/weak cryptographic hash algorithms"
overrides
Optionally, an array of ids (see above) this rule overrides. If both this rule, and one or more of the ids in overrides fires on the same code, only this rule should be shown. This is most often used when there is a generic catch all rule as well as a language specific rule. For example, there is a rule that flags the string MD5 in any file. The second rule therefore overrides the first so that they aren't both shown.
- Example: "overrides": [ "AI197800" ]
tags
Array of strings representing the "category" of rule this corresponds to, roughly analogous to CWE hierarchy. e.g. "Cryptography.HashAlgorithm". They can be empty. The tags are documented in tags section.
- Example : "tags": [ "Cryptography.HashAlgorithm" ]
applies_to
Array of strings dictating what languages/files a rule should be run on. If absent, a rule runs on every file MATCHING a supported language. When specifying a particular file, i.e. project.json, the rule will only run on that specific file, not on all JSON files. The list of supported values for various languages are documented in applies_to section.
- Example: "applies_to": [ "objective-c" ]
applies_to_file_regex
Array of regular expressions to choose which filenames to apply to.
- Example: "applies_to_file_regex": [ ".*.foo" ]
severity
One of the values for the Severity enum: Unspecified, Critical, Important, Moderate, BestPractice, ManualReview.
description
A short human friendly string that describes what the rule intents to detect. This field may not be null or empty string.
patterns
Array of one or more pattern objects. If any of the patterns in the array find a match then one of two things happens. If a conditions array (see below) is provided, that is then processed for further logic to determine a rule match. If it is not provided, the rule matches
- Example: "patterns" : [ { "pattern" : "CC_(MD2|MD4|MD5|SHA1)","type" : "regex","scope" : "code"}]
conditions
Optional Array of one or more conditions used to further analyze the code after a pattern matches, for additional details that would signify a finding. If present conditions are invoked AFTER a pattern matches code, and while with a pattern (above) a hit from any item in the array constitutes a finding, ALL conditions in the array (if present) must match to signify a finding (patterns[above] is OR, conditions is AND).
- Example: "conditions" : [{"pattern" : {"pattern": "xmlns","type": "regex", "scopes": ["code"], "_comment": ""}, "negate_finding": true,"_comment": "" } ]
must-match
Optional array of strings. When running rule verification, the verifier will check that the Rule matches every string in must-match.
must-not-match
Optional array of strings. When running rule verification, the verifier will check that the Rule does not match every string in must-not-match.
_comment
Optional string to allow the author of a rule to leave comments or notes to others reading the json file, providing a place to explain things like complicated regex logic, since the json format doesn't provide native comment syntax.