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)

Arg	Description	Type
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.

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().

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

watch_monitoring

Plugin

Watch clients’ monitoring log. This is an event plugin. If client_id is not provided we watch the global journal which contains events from all clients.

Arg	Description	Type
client_id	A list of client ids to watch. If not provided we watch all clients.	list of string
artifact	The event artifact name to watch	string (required)
source	An optional artifact named source	string

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)