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.

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.

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"

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)

watch_auditd

Plugin

Watch log files generated by auditd.

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.

watch_evtx

Plugin

Watch an EVTX file and stream events from it.

This is the Event plugin version of parse_evtx().

watch_monitoring

Plugin

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

watch_syslog

Plugin

Watch a syslog file and stream events from it.

wmi_events

Plugin

Executes an evented WMI queries asynchronously.

This plugin sets up a WMI event listener query.