Basic VQL functions and plugins

VQL provides a basic set of functions and plugins allowing queries to maniulate data and implement logic. This page details those plugins which are considered foundational to the VQL language and therefore may be useful in all types of artifacts.

VQL plugins are not the same as VQL functions. A plugin is the subject of the VQL query - i.e. plugins always follow the FROM keyword, while functions (which return a single value instead of a sequence of rows) are only present in column specification (e.g. after SELECT) or in condition clauses (i.e. after the WHERE keyword).

array

Function

Create an array with all the args.

This function accepts arbitrary arguments and creates an array by flattening the arguments. For example array(a=1, b=2) will return [1, 2].

You can use this to flatten a subquery as well:

SELECT array(a1={ SELECT User FROM Artifact.Windows.System.Users() }) as Users FROM scope()

Will return a single row with Users being an array of names.

atoi

Function

Convert a string to an int.

Arg Description Type
string A string to convert to int string (required)

base64decode

Function

Decodes a base64 encoded string.

Arg Description Type
string A string to decode string (required)

base64encode

Function

Encodes a string into base64.

Arg Description Type
string A string to decode string (required)

basename

Function

Return the basename of the path.

Arg Description Type
path Extract directory name of path string (required)

copy

Function

Copy a file.

Arg Description Type
filename The file to copy from. string (required)
accessor The accessor to use string
dest The destination file to write. string (required)

count

Function

Counts the items.

Arg Description Type
items Any (required)

dict

Function

Construct a dict from arbitrary keyword args.

dirname

Function

Return the directory path.

Arg Description Type
path Extract directory name of path string (required)

encode

Function

Encodes a string as as different type. Currently supported types include ‘hex’, ‘base64’.

Arg Description Type
string Any (required)
type string (required)

enumerate

Function

Collect all the items in each group by bin.

Arg Description Type
items Any (required)

environ

Function

Get an environment variable.

Arg Description Type
var Extract the var from the environment. string (required)

expand

Function

Expand the path using the environment.

This function expands environment variables into the path. It is normally needed after using registry values of type REG_EXPAND_SZ as they typically contain environment strings. Velociraptor does not automatically expand such values since environment variables typically depend on the specific user account which reads the registry value (different user accounts can have different environment variables).

Arg Description Type
path A path with environment escapes string (required)

filter

Function

Filters a strings array by regex.

Arg Description Type
list A list of items too filter list of string (required)
regex A regex to test each item list of string (required)

format

Function

Format one or more items according to a format string.

Arg Description Type
format Format string to use string (required)
args An array of elements to apply into the format string. Any

get

Function

Gets the member field from item.

This is useful to index an item from an array. For example:

Example

select get(item=[dict(foo=3), 2, 3, 4], member='0.foo') AS Foo from scope()

[
 {
   "Foo": 3
 }
]
Arg Description Type
item Any
member string
field string
default Any

getpid

Function

Returns the current pid of the process.

humanize

Function

Format items in human readable way.

Formats a byte count in human readable way (e.g. Mb, Gb etc).

Arg Description Type
bytes Format bytes with units int64

if

Function

Conditional execution of query

This function evaluates a condition. Note that the values used in the then or else clause are evaluated lazily. They may be expressions that involve stored queries (i.e. queries stored using the LET keyword). These queries will not be evaluated if they are not needed.

This allows a query to cheaply branch. For example, if a parameter is given, then perform hash or upload to the server. See the

Arg Description Type
condition Any (required)
then LazyExpr (required)
else LazyExpr

join

Function

Join all the args on a separator.

Joins the array into a string separated by the sep character.

Arg Description Type
array The array to join list of string (required)
sep The separator string

len

Function

Returns the length of an object.

Arg Description Type
list A list of items too filter Any (required)

log

Function

Log the message.

Arg Description Type
message Message to log. string (required)

lowcase

Function

Arg Description Type
string A string to lower string (required)

max

Function

Finds the largest item in the aggregate.

It is only meaningful in a group by query.

Example

The following query lists all the processes and shows the largest bash pid of all bash processes.

SELECT Name, max(items=Pid) as LargestPid from pslist() Where Name =~ 'bash' group by Name
Arg Description Type
items Any (required)

min

Function

Finds the smallest item in the aggregate.

It is only meaningful in a group by query.

Example

The following query lists all the processes and shows the smallest bash pid of all bash processes.

SELECT Name, min(items=Pid) as SmallestPid from pslist() Where Name =~ 'bash' group by Name
Arg Description Type
items Any (required)

now

Function

Returns current time in seconds since epoch.

Arg Description Type
string A string to convert to int string (required)

path_join

Function

Build a path by joining all components.

Arg Description Type
components Path components to join. list of string (required)

query

Function

Launch a subquery and materialize it into a list of rows.

Arg Description Type
vql StoredQuery (required)

rand

Function

Selects a random number.

Arg Description Type
range Selects a random number up to this range. int64

read_file

Function

Read a file into a string.

Arg Description Type
chunk length of each chunk to read from the file. int
max_length Max length of the file to read. int
filenames One or more files to open. list of string (required)
accessor An accessor to use. string

scope

Function

return the scope.

serialize

Function

Encode an object as a string (csv or json).

Arg Description Type
item The item to encode Any (required)
format Encoding format (csv,json) string

sleep

Function

Sleep for the specified number of seconds. Always returns true.

Arg Description Type
time The number of seconds to sleep int64

split

Function

Splits a string into an array based on a regexp separator.

Arg Description Type
string The value to split string (required)
sep The serparator that will be used to split string (required)

str

Function

Normalize a String.

Arg Description Type
str The string to normalize Any (required)

strip

Function

Strip a prefix from a string.

Arg Description Type
string The string to strip string (required)
prefix The prefix to strip string (required)

timestamp

Function

Convert from different types to a time.Time.

Arg Description Type
epoch Any
winfiletime int64
string Guess a timestamp from a string string
us_style US Style Month/Day/Year bool

upcase

Function

Arg Description Type
string A string to lower string (required)

url

Function

Construct a URL or parse one.

This function parses or constructs URLs. A URL may be constructed from scratch by providing all the components or it may be parsed from an existing URL.

The returned object is a golang URL and can be serialized again using its String method.

This function is important when constructing parameters for certain accessors which receive a URL. For example the zip accessor requires its file names to consist of URLs. The Zip accessor interprets the URL in the following way:

  • The scheme is the delegate accessor to use.
  • The path is the delegate accessor’s filename
  • The fragment is used by the zip accessor to retrieve the zip member itself.

In this case it is critical to properly escape each level - it is not possible in the general case to simply append strings. You need to use the url() function to build the proper url.

Arg Description Type
scheme The scheme to use string
host The host component string
path The path component string
fragment The fragment string
parse A url to parse string

utf16

Function

Parse input from utf16.

Arg Description Type
string A string to decode string (required)

utf16_encode

Function

Encode a string to utf16 bytes.

Arg Description Type
string A string to decode string (required)