How to use message header values in a rule

Background

Email headers are metadata within a raw message that contain information like the path the message took from source to destination, authentication results, originating mail client, and more. Often we can use information from within the headers to signature an attacker or attack type.

To see how headers are parsed and normalized on the MDM, see the Message Data Model reference.

Each mail server a message traverses is called a "mail hop." In the MDM, each hop is stored in the headers.hops list. Within each hop, Sublime further normalizes common header values into structured objects like authentication_results, received_spf, and more.

Use Authentication-Results in a rule

Header values like ‘Authentication-Results’ and ‘ARC-Authentication-Results’ are all normalized into the authentication_results MDM object within the headers.hops list. This MQL snippet will return true whenever there's a DMARC "fail":

any(headers.hops, .authentication_results.dmarc =~ "fail")

Use raw header values in a rule

Raw header values are stored within each hop object on the MDM, with their order preserved. This MQL snippet will return true whenever there's a header field by the name (case insensitive) "Received-SPF" and the value containing "spf=temperror".

any(headers.hops, any(.fields, .name =~ "Received-SPF") and strings.ilike(.value, "*spf=temperror*")))