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.

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	list of string (required)
regex	A regex to test each item	list of string (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)