The Velociraptor Query language (VQL) is an expressive language designed for querying endpoint state. It was developed as a way to flexibly adapt new IOCs on endpoints without needing to rebuild or deploy new endpoints.
VQL is simple to use and simple to understand. Although it draws its
inspiration from SQL, VQL does not support complex operations such as
join. Unlike SQL, which can only query static tables of data, VQL
plugins which are provided parameters. This allows VQL
plugins to customize their output based on arguments provided to them.
The basic structure of a VQL query is:
SELECT Column1, Column2, Column3 FROM plugin(arg=1) WHERE Column1 = "X"
In the above we term the clause between the
the “Column Specification”. The clause between the
is termed the
plugin clause while the terms after the
The column specification is a comma delimited list of expressions which may consist of operations or VQL functions. The expressions operate on each row returned from the plugin. Each expression specifies a single Column to add to the transformed row. Alternatively the Column Specification may consist of “*” indicating no transformation shall be applied to the rows returned from the plugin.
A column expression may also use the keyword
AS to define an alias
for the expression (i.e. define a new name for the column).
For example the following will return a row with a column names “Now” containing the string representation of the current time:
SELECT timestamp(epoch=now()) AS Now FROM scope()
The plugin clause specifies a VQL plugin to run. VQL plugins are the data source for the VQL query and generate a sequence of rows. They also take keyword args.
Plugins must take keyword args (i.e. keyword=value). Positional args are currently not supported. You will receive a syntax error if no keyword is provided.
The names of the args are defined by the plugin itself which also defines which arg is required and which are simply optional. The references below explain the meaning of each arg for the different plugins.
Args also have a type and must receive the correct type. For example, providing a string to an arg which requires an integer will result in that arg being ignored. The VQL statement will not be aborted though! Such a syntax error will simply result in the plugin returning no rows and a log message generated.