# Audit

An ORL audit query is how ORL finds [findings](https://docs.gomboc.ai/orl/concepts/finding) to remediate. They are [templated](https://docs.gomboc.ai/orl/concepts/template) AST patterns in the form of [S-Expressions](https://tree-sitter.github.io/tree-sitter/using-parsers/queries/1-syntax.html) 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.

```lisp
(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-".

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

    (#match? @key "^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](https://docs.gomboc.ai/orl/concepts/languages) for details.