Using the MQL Editor

Tips and tricks to improve rule writing and debugging

Learning how to write new detection rules with MQL can be easy, with the smarts that are baked into the editor. It has builtin syntax highlighting, autocompletion, live error checking, and debugging so that you can write rules effectively and spot mistakes quickly. Once you start writing a rule or crafting a hunt, you may recognize a familiar look and feel if you've used the Visual Studio Code editor before. Sublime uses the same core framework, tailored to improve the MQL experience.

You don't have to have the Sublime editor to try out MQL! Navigate to mql.new to open the Sublime Sandbox. You can also upload an EML to test, and they are only stored if you generate a sharing link that includes the EML.

Live completion and error checking

As you type, you'll notice that fields from the Message Data Model (MDM) are automatically suggested and you can see the corresponding types. As function names, like any are typed, you can see the names and types of arguments it accepts, and what type of value it returns.

When writing an expression inside an array function, the attributes for the current value are also autocompleted as soon as you type dot..

If you need a refresher on parts of the MDM, hover over a field to reveal its type and description. If it is limited in output, you'll see an additional line with possible values: ..., enumerating each possible value.

Fields that have a finite set of values are automatically completed, even within a string. Note that MQL doesn't enforce this restriction when a rule is created, but the editor does try to nudge you in the right direction.

Testing and debugging rules

When writing rules, it's valuable to get feedback ASAP. Instead of saving the rule and hoping it works after activating it, upload an EML file to test it against. When an EML is attached to the editor, additional functionality is available to test and debug a rule.

When Test Rule is pressed, the matching parts of the rule (evaluate to true) are immediately highlighted and underlined. If the entire rule matches, a satisfying :white-check-mark: is displayed. If not then an :exclamation: will show.

If you get an :exclamation: and aren't sure why, try running Evaluate to debug the intermediate output. Click on any function name, to see the :bulb::arrow-forward: button to see the intermediate output in a JSON viewer. This is especially useful for functions with a lot of output, such as enrichment functions.

If you eval on a function that's inside another array function, such as any or all, the debug output will be an array, as if the function was evaluated with map(source_array, function(.)). This can help debug a partial match. Note in the screenshot, that iregex_match was highlighted because it matched at least once. However, the resulting any wasn't flagged. Evaluating iregex_match can identify which items matched.

Detecting logical bugs

Writing correct syntax and using functions and types correctly is half the battle to writing a strong detection. Sometimes, even the most clean looking rules can have the most dangerous of bugs: logical errors.

The MQL editor tries to detect logical errors like using an or when you mean an and, or if you forgot parentheses. Sometimes, these bugs are easy to spot, but MQL isn't psychic and doesn't know what you really meant. If one of these cases is detected, a warning is presented that there may be a logical error. These go away as soon as you add parentheses, adjust the indentation or switch to the expected operator. Warnings don't prevent MQL from compiling, but just show up when something looks like a mistake.

More on this particular bug in Common logical errors.

Stuck?

Unsure what functions and fields are at your disposal? At any time, you can view autocomplete suggestions with the shortcut Ctrl+Space. Since the MQL editor is built on top of the same core as VS Code, it has many of the same default keyboard shortcuts.