One of the exciting new features in Gravwell 3.3.0 is search macros. Anyone who's experimented much with Gravwell knows you may often end up crafting a long and complex regular expression which you'll want to use over and over, but such a long regex makes the query hard to work with. Macros let you turn that long regular expression (or any other part of a search query) into a much shorter name you can use again and again.
Macros are defined and managed in a new interface, located in the 'Library' section of the main menu:
Macro Basics
Macros are essentially string replacement rules. You define a macro that maps a short, all-caps name to a longer string. When parsing a search query, Gravwell looks for macro names preceded by a dollar sign and does the replacement before launching the search. We might have a particular regular expression we use to extract DHCP information from system logs. We'd like to make a macro so we don't have to type out the whole regex each time, so we define a macro as follows:
This tells Gravwell that when it sees $DHCPACK in the query, it should replace it with regex "DHCPACK on (?P<ip>\S+) to (?P<mac>\S+) via (?P<iface>\S+)". Now we can just use the macro in queries whenever we wish:
tag=syslog $DHCPACK | unique ip mac | table ip mac
Note that a macro can contain search modules, tag specifications, pipes, or render modules; behind the scenes, Gravwell is just doing string replacement. If you have a query you intend to run often, you can simply put the entire query into a macro named MYMACRO; typing $MYMACRO in the search box and hitting enter will run the full query for you.
When you type a macro in the query bar, Gravwell will show the actual expansion below for convenience:
Macro Arguments
Gravwell macros, like C macros, can take arguments. Suppose you have Bro/Zeek HTTP logs ingested under the 'bro-http' tag and you'd like to be able to rapidly pull out only those logs with a particular user agent. We can do that with a macro that contains an argument:
The query string, `tag=bro-http ax user_agent~"%%1%%"` contains a special form, %%1%%, which will be replaced by the first argument to the macro. Entering `$HTTPUSER(curl)` will expand to `tag=bro-http ax user_agent~curl`, which show us entries whose user_agent field contains the string "curl":
If you want more arguments, just use %%2%%, %%3%%, etc. There's no limit, and you can use any given argument multiple times in the expansion.
Nested Macros
A macro can contain other macros. The screenshot below shows a macro named $FOO whose expansion contains another macro, $BAR. When you type $FOO into the search bar, it first expands $FOO, then seeing that the query still contains a macro ($BAR), it expands again.
Macros can also take macros as arguments. The following macro defines a simple filter on the source IP of packets:
We have another macro which defines the IP address of the local network's router:
We can then use $ROUTER as an argument to $SRC:
Conclusion
Gravwell macros are pretty flexible; you can use them to simply reduce typing, or you can get tricky with nested macros. If you'd like some help coming up with good reusable macros for your Gravwell install, drop us a line at info@gravwell.io. If you're new to Gravwell but want to see what it's all about, you can sign up for our free Gravwell Trial below!
