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 MQL

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":

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

Use raw header values in MQL

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".

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

Use sensitivity labels in MQL

Microsoft Purview sensitivity labels applied to a message are normalized into the sensitivity_label object on headers. Unlike authentication_results, which lives inside each headers.hops entry, sensitivity_label is already resolved to a single value, the label from the hop closest to the final recipient, so no iteration over headers.hops is needed.

This MQL snippet returns true whenever an outbound message is labeled "Confidential":

type.outbound
and headers.sensitivity_label.name == "Confidential"

headers.sensitivity_label reads the label on the message itself, from the msip_labels email header. It does not read labels embedded in file attachments, for example a Word or PowerPoint document that carries its own, separate Purview label. Available for Microsoft 365 messages only, Google Workspace classification labels aren't supported.