Audit

An ORL audit query is how ORL finds findings to remediate. They are templated AST patterns in the form of S-Expressions based on the language that the rule remediates. Each positive match is considered a finding and all the capture groups are made available for remediation:

For example:

The following is an expression to find key value pairs within any object of a YAML file. It will find all key/value pairs - each as a separate finding - regardless of level of nesting. The @key and @value capture groups are made available to remediation steps as key, and value respectively.

(block_node
  (block_mapping
    (block_mapping_pair
      (flow_node) @key
      (flow_node) @value
    )
  )
)

Capture Group Evaluation

It is often useful to limit the number of findings based on the value contained within the capture group. This can be done with:

• #eq? - The capture group must match exactly

• #not-eq? - The capture group must NOT match

• #any-of? - The capture group must match one of the provided strings

• #match? - The capture group must match the provided regex

• #not-match? - The capture group must NOT match the provided regex

For example, say I only want to match key/value pairs if the key starts with "label-".

Template helpers

Audit queries can get very complex. ORL ships with a number of template helpers - based on the language - that help in doing common things in that language. For example {{ aResource("aws_s3_bucket") }} will generate the S-expression to find all S3 bucket resources in terraform files.

The template helpers can be found via orl language <language> for each supported language. See Languages for details.