Event Plugins

VQL Event plugins are plugins which never terminate - but instead generate rows based on events. Event plugins are useful for creating client monitoring artifacts. Currently, client side monitoring artifacts are specified in the Events section of the server configuration file. When clients connect to the server, they receive a list of monitoring artifacts they are to run. The client runs all artifacts in parallel and their results are streamed to the server.

clock

Plugin

Generate a timestamp periodically. This is mostly useful for event queries.

This plugin generates events periodically. The periodicity can be controlled either via the period or the ms parameter. Each row will be a go time.Time object. You can access its unix epoch time with the Sec column.

Example

The following will generate an event every 10 seconds.

SELECT Sec FROM clock(period=10)

The start parameter can be used to schedule the plugin to start at a particular time. This can be an integer (which will be interpreted as seconds since the epoch), a string or a time value.

Arg Description Type
start Start at this time. Any
period Wait this many seconds between events. int64
ms Wait this many ms between events. int64

diff

Plugin

Executes ‘query’ periodically and emit differences from the last query.

The diff() plugin runs a non-event query periodically and calculates the difference between its result set from the last run.

This can be used to create event queries which watch for changes from simpler non-event queries.

The key parameter is the name of the column which is used to determine row equivalency.

There is only a single equivalence row specified by the key parameter, and it must be a string. If you need to watch multiple columns you need to create a new column which is the concatenation of other columns. For example format(format="%s%d", args=[Name, Pid])

Example

The following VQL monitors all removable drives and lists files on newly inserted drives, or files that have been added to removable drives.

LET removable_disks = SELECT Name AS Drive, Size
FROM glob(globs="/*", accessor="file")
WHERE Data.Description =~ "Removable"

LET file_listing = SELECT FullPath, timestamp(epoch=Mtime.Sec) As Modified, Size
FROM glob(globs=Drive+"\\**", accessor="file") LIMIT 1000

SELECT * FROM diff(
  query={ SELECT * FROM foreach(row=removable_disks, query=file_listing) },
  key="FullPath",
  period=10)
  WHERE Diff = "added"
Arg Description Type
query Source for cached rows. StoredQuery (required)
key The column to use as key. string (required)
period Number of seconds between evaluation of the query. int64

fifo

Plugin

Executes ‘query’ and cache a number of rows from it. For each invocation we present the set of past rows.

The fifo() plugin allows for VQL queries to apply across historical data. The fifo plugin accepts another event query as parameter, then retains the last max_rows rows from it in an internal queue. Every subsequent evaluation from the query will return the full set of rows in the queue. Older rows are expired from the queue according to the max_age parameter.

Fifos are usually used to form queries that look for specific pattern of behavior. For example, a successful logon followed by failed logons. In this case the fifo retains the recent history of failed logons in its internal queue, then when a successful logon occurs we can check the recent failed ones in its queue.

Example

The following checks for 5 failed logons followed by a successful logon.

LET failed_logon = SELECT EventData as FailedEventData,
   System as FailedSystem
FROM watch_evtx(filename=securityLogFile)
WHERE System.EventID.Value = 4625

LET last_5_events = SELECT FailedEventData, FailedSystem
    FROM fifo(query=failed_logon,
              max_rows=500,
              max_age=atoi(string=failedLogonTimeWindow))

LET success_logon = SELECT EventData as SuccessEventData,
   System as SuccessSystem
FROM watch_evtx(filename=securityLogFile)
WHERE System.EventID.Value = 4624

SELECT * FROM foreach(
  row=success_logon,
  query={
   SELECT SuccessSystem.TimeCreated.SystemTime AS LogonTime,
          SuccessSystem, SuccessEventData,
          enumerate(items=FailedEventData) as FailedEventData,
          FailedSystem, count(items=SuccessSystem) as Count
   FROM last_5_events
   WHERE FailedEventData.SubjectUserName = SuccessEventData.SubjectUserName
   GROUP BY LogonTime
      })  WHERE Count > atoi(string=failureCount)
Arg Description Type
query Source for cached rows. StoredQuery (required)
max_age Maximum number of seconds to hold rows in the fifo. int64
max_rows Maximum number of rows to hold in the fifo. int64

watch_auditd

Plugin

Watch log files generated by auditd.

Arg Description Type
filename A list of log files to parse. list of string (required)
accessor The accessor to use. string

watch_csv

Plugin

Watch a CSV file and stream events from it. Note: This is an event plugin which does not complete.

This plugin is the event version of parse_csv(). When the CSV file grows this plugin will emit the new rows.

Arg Description Type
filename CSV files to open list of string (required)
accessor The accessor to use string

watch_evtx

Plugin

Watch an EVTX file and stream events from it.

This is the Event plugin version of parse_evtx().

It often takes several seconds for events to be flushed to the event log and so this plugin’s event may be delayed. For some applications this results in a race condition with the event itself - for example, files mentioned in the event may already be removed by the time the event is triggered.

Arg Description Type
filename A list of event log files to parse. list of string (required)
accessor The accessor to use. string
messagedb A Message database from https://github.com/Velocidex/evtx-data. string

watch_monitoring

Plugin

Watch clients’ monitoring log. This is an event plugin. This plugin will produce events from all clients.

Arg Description Type
artifact The event artifact name to watch string (required)

watch_syslog

Plugin

Watch a syslog file and stream events from it.

Arg Description Type
filename A list of log files to parse. list of string (required)
accessor The accessor to use. string

wmi_events

Plugin

Executes an evented WMI queries asynchronously.

This plugin sets up a WMI event listener query.

Arg Description Type
query WMI query to run. string (required)
namespace WMI namespace string (required)
wait Wait this many seconds for events and then quit. int64 (required)