3.3. Condition Object Schema

Conditions represent a powerful way to improve accuracy and reduce false positives. There are a number of search patterns that may only considered valid if additional conditions either are or are not met.

To solve that problem, rules support an array of "Conditions" - additional patterns that either must be, or must not be present in order to consider the original pattern dangerous.

When a pattern from the base Rule object is a match, and if a Condition has also been defined, then if and only if, every condition is met, the original matched code considered is recorded as a match.

Schema

{
    "pattern": type=Pattern  
    Required Value 

    "search_in": type=string (only specific values are accepted, but it isn't a traditional enum)
    Optional Value, default is "finding-region(0,0)"     

    "negate_finding": type=boolean
    Optional Value, default is false 

    "_comment": type=string  
    Optional Value  
}

Fields

pattern

An additional pattern to check for after the pattern in the patterns finds a possible match. This pattern either MUST match (if negate_finding is absent or false), or MUST NOT match (if negate_finding is true) for the rule pattern to be valid.

search_in

String, directing where the pattern in the condition should be run. Two formats are accepted:

finding-only: the pattern should only be run against the code originally matched by the root rule's pattern

finding-region(<integer>,<integer>): the values are line numbers relative to the line of code the root rule pattern matched (inclusive). Negative integers mean lines BEFORE the finding, 0 means line OF finding, and positive values are lines after the finding. the pattern should be applied to all of the code in the region specified. For example, finding-region(-5,0) designates that the pattern should apply to all code in the five lines prior to the finding up to and including the line the finding is on. To exclude the line the finding is on, finding-region(-5,-1) should be used. finding-region(-5,5) applies the pattern to the swath of code five lines prior to the finding, through five lines after the finding.

• Example: "search_in" : "finding-region(-5,5)"

Don't specify search_in if your Pattern is XPath or JSONPath based.

negate_finding

If set to true, specifies that if the pattern of the condition matches, the finding should be invalidated (i.e., the condition is really !pattern). The default value if absent is false (i.e. the pattern needs to be present, as opposed to the pattern needs to be absent)

• Example: "negate_finding" : true

_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

• Example: "_comment" : "this regex is a catchall for all of the banned c functions that don't otherwise have their own rule"