velociraptor

Submits VQL to a Velociraptor server and returns the response as events.

velociraptor [request_name=str, org_id=str, max_rows=int,
              subscribe=str, query=str, max_wait=duration, profile=str]

Description

The velociraptor source operator provides a request-response interface to a Velociraptor server:

The pipeline operator is the client and it establishes a connection to a Velociraptor server. The client request contains a query written in the Velociraptor Query Language (VQL), a SQL-inspired language with a SELECT .. FROM .. WHERE structure.

You can either send a raw VQL query via velociraptor query "<vql>" to a server and processs the response, or hook into a continuous feed of artifacts via velociraptor subscribe <artifact>. Whenever a hunt runs that contains this artifact, the server will forward it to the pipeline and emit the artifact payload in the response field HuntResults.

All Velociraptor client-to-server communication is mutually authenticated and encrypted via TLS certificates. This means you must provide client-side certificate, which you can generate as follows. (Velociraptor ships as a static binary that we refer to as velociraptor-binary here.)

1. Create a server configuration server.yaml:

   velociraptor-binary config generate > server.yaml

2. Create an API client:

   velociraptor-binary -c server.yaml config api_client name tenzir client.yaml

   Copy the generated client.yaml to your Tenzir plugin configuration directory as velociraptor.yaml so that the operator can find it:

   cp client.yaml /etc/tenzir/plugin/velociraptor.yaml

3. Run the frontend with the server configuration:

   velociraptor-binary -c server.yaml frontend

Now you are ready to run VQL queries!

request_name = str (optional)

An identifier for the request to the Velociraptor server.

Defaults to a randoum UUID.

org_id = str (optional)

The ID of the Velociraptor organization.

Defaults to "root".

query = str (optional)

The VQL query string.

max_rows = int (optional)

The maxium number of rows to return in a the stream gRPC messages returned by the server.

Defaults to 1000.

subscribe = str (optional)

Subscribes to a flow artifact.

This option generates a larger VQL expression under the hood that creates one event per flow and artifact. The response contains a field HuntResult that contains the result of the hunt.

max_wait = duration (optional)

Controls how long to wait before releasing a partial result set.

Defaults to 1s.

profile = str (optional)

Specifies the configuration profile for the Velociraptor instance. This enables connecting to multiple Velociraptor instances from the same Tenzir node.

To use profiles, edit your velociraptor.yaml configuration like this, where <config> refers to the contents of the configuration file created by Velociraptor, and <profile> to the desired profile name.

# before
<config>
 
# after
profiles:
  <profile>:
    <config>

If profiles are defined, the operator defaults to the first profile.

Examples

Show all processes:

velociraptor query="select * from pslist()"

Subscribe to a hunt flow that contains the Windows artifact:

velociraptor subscribe="Windows"