YAML files

Format

Rules and queries are stored in YAML files with a .yml extension and have the following format:

(* denotes required fields)

*name: string
*description: string
*source: string
type: string
severity: string
references:
 - string
tags:
 - string

Field

Required

Description

Acceptable values

name

true

Name for the rule or query

Any string

source

true

Raw MQL

Any string

description

true

Digestible description of the rule and its purpose

Any string

type

false

Entity type

rule
query

severity

false

Criticality of a triggered rule

low
medium
high
critical

references

false

References to where the rule was derived from. Blogs, tweets, papers, etc.

A list of strings (typically URLs)

tags

false

A way to categorize the rule or query

A list of any strings

false_positives

false

Descriptions of known false positives that can occur

A list of any strings

Multi-line strings in YAML are denoted using a | like so:

name: "Mismatched link"
source: |
    type.inbound
    and any(body.links, .mismatched)
type: rule

Multiple rules or queries

One YAML file can contain multiple rules or queries.

Multiple rules should be saved as a list using the rules key, and multiple queries should be saved as a list using the queries key. Elements of a list in YAML are denoted using -. Example:

rules:
    - name: "Inbound message"
      source: type.inbound

    ...

queries:
  - name: "Message type"
    source: type

  - name: "Sender display name"
    source: sender.display_name

Each of the rules in the list can have any or all of the optional fields defined above, but still must have the required name and source fields.