Event Queues

Velociraptor supports stream-based data collection (also referred to as Client Monitoring and Server Monitoring ), which means that events are sent in near-realtime rather than being batched, as occurs with normal collections, or possibly awaiting collection completion as would occur if aggregation functions are applied to the results.

Event queues are the internal mechanism that supports this capability.

Event queues are basically like pipes:

• VQL in an artifact generates data (on a client or the server) and sends it to the (server-side) queue.
• VQL in a server event artifact (using the watch_monitoring plugin) reads the data from the queue, and potentially does something with it - for example, sends it to an Elastic server.

You can think of event artifacts as having 2 parts:

1. a name which establishes the event queue on the server.
2. the rest of the artifact (optional, except in the case of CLIENT_EVENT artifacts), including VQL in it’s sources which generates data and sends it to the event queue identified by the artifact’s name.

Artifacts of type SERVER_EVENT, CLIENT_EVENT or INTERNAL establish message queues on the server. The artifact’s name is used as the message queue’s name. This means that such artifacts don’t always need to be collected in order to be useful - as soon as they are created in the server’s artifact repository the associated message queues are set up. However, in the case of client event queues, such artifacts also always contain sources which generate messages on the client, and these messages are forwarded to the corresponding event queue on the server.

Many internally-generated events are sent to server event queues. For example, client enrollment events, flow completion events, and server audit events are each sent to their own queue.

Server event queues

An artifact of type SERVER_EVENT establish a server event queue on the server, using the artifact name.

The following are some built-in SERVER_EVENT artifacts which only establish server event queues. You can monitor events sent to these queues using the watch_monitoring() plugin.

SELECT name, description FROM artifact_definitions() WHERE NOT sources AND type =~ "server_event"

Sending events to server event queues.

To send events to any server event queue you use the send_event VQL function.

For example, if you set up a server event queue with the following artifact:

name: Server.Events.Receive
type: SERVER_EVENT

then send an event to it:

SELECT send_event(row=dict(a=1,b=2,c=3), artifact="Server.Events.Receive") FROM scope()

The event should appear in the selected server event queue:

Internal event queues

Artifacts of type INTERNAL establishes a server event queue on the server using the artifact name. Functionally they are very similar to the SERVER_EVENT artifact type, except that they are intended to handle internal messaging and are not backed by disk (unlike the SERVER_EVENT type) for performance reasons.

You can’t send messages to internal event queues with the send_event VQL function, but you can use the watch_monitoring plugin to monitor them for events.

The following are built-in INTERNAL artifacts which only establish server event queues.

SELECT name, description FROM artifact_definitions() WHERE NOT sources AND type =~ "internal"

Client event queues

An artifact of type CLIENT_EVENT establishes a client event queue on the server, using the artifact name.

With this type of artifact, the event queue and artifact sources are more tightly coupled: all rows emitted by the artifact’s sources are sent to the corresponding event queue. That is, sources in a CLIENT_EVENT artifact generate data on the client. This differs from sources in server event artifacts which generally receive/process data (although they too can generate data and send it to a queue).

Unlike server event queues, you can’t send messages to client event queues with the send_event VQL function.

Viewing active event queues

You can view the current queues on your server by going to the Debug Server . Client event queues are shown under the section Client -> Client Monitoring Manager and server event queues under the section Org <org_name> > Services -> QueueManager Org (event queues are created and run independently for each org).

Alerts queue

An alert is a special type of log message which is generated by VQL specifically to be routed into the high-priority alerts queue on the server. Alerts are time deduplicated (within a 2 hour window, by default) as they are meant to just direct attention to some important activity rather than providing a running log of all events that happened.

Alert messages are sent to the alerts event queue – Server.Internal.Alerts – on the server, which is a built-in queue for this specific purpose.

name: Server.Internal.Alerts
description: |
  An internal event queue for alerts. All alerts sent from clients are
  collected in this event queue.

  Alerts are expected to be low frequency and high value and may be
  generated client or server side.

type: SERVER_EVENT

An alert message is technically similar to a log message with the level set to “ALERT”, although this logging level is not available in normal logging. Alert messages are intercepted and directed to the alerts queue.

Custom alert messages are generated using the alert VQL function.

To act on messages in the alerts queue you need to create a Server Monitoring artifact which retrieves events from this queue using the VQL query SELECT * FROM watch_monitoring(artifact='Server.Internal.Alerts')

To test it: From a notebook on the server, or via an artifact collected on a client, run:

SELECT alert(dedup=-1, name="Test Alert") FROM scope()

You should then be able to see that your test message reached the alerts queue: