collect_client

VQL Reference

Server

collect_client

Function

Arg	Description	Type
client_id	The client id to schedule a collection on	string (required)
flow_id	If a flow id is specified we do not create a new flow, but instead add the collection to this flow.	string
artifacts	A list of artifacts to collect	list of string (required)
env	Parameters to apply to the artifact (an alternative to a full spec)	ordereddict.Dict
spec	Parameters to apply to the artifacts	ordereddict.Dict
timeout	Set query timeout (default 10 min)	uint64
ops_per_sec	Set query ops_per_sec value	float64
cpu_limit	Set query cpu_limit value	float64
iops_limit	Set query iops_limit value	float64
max_rows	Max number of rows to fetch	uint64
max_bytes	Max number of bytes to upload	uint64
urgent	Set the collection as urgent - skips other queues collections on the client.	bool
org_id	If set the collection will be started in the specified org.	string

Required permissions: COLLECT_CLIENT, COLLECT_SERVER, COLLECT_BASIC

Description

Launch an artifact collection against a client. If the client_id is “server” then the collection occurs on the server itself. In that case the caller needs the SERVER_ADMIN permission.

There are two way of specifying how to collect the artifacts. The simplest way is to specify the environment string using the env parameter, and a list of artifacts to collect in the artifacts parameter.

In this case all artifacts will receive the same parameters.

For example:

SELECT collect_client(
    client_id='C.11a3013ccaXXXXX',
    artifacts='Windows.KapeFiles.Targets',
    env=dict(Device ='C:', VSSAnalysis='Y', KapeTriage='Y')).request AS Flow
FROM scope()

Sometimes we have a number of artifacts that use the same parameter name for different purposes. In that case we wish to specify precisely which artifact receives which parameter. This more complex way of specifying the collection using the spec parameter:

SELECT collect_client(
    client_id='C.11a3013ccaXXXXX',
    artifacts='Windows.KapeFiles.Targets',
    spec=dict(`Windows.KapeFiles.Targets`=dict(
        Device ='C:', VSSAnalysis='Y', KapeTriage='Y'))).request AS Flow
FROM scope()

In this case the artifact names are repeated in the spec and the artifacts parameter.

Example - conditional collections

In this example we wish to create an artifact with check buttons for selecting groups of artifacts to launch. Assume Do1 and Do2 are boolean parameters:

Depending on the checkbox condition we set a set of dicts and potential arguments.
Next we rely on the fact that dict additions merge the keys of each dict to create a merged dict. The Spec dict is constructed by joining the different parts together
To obtain the list of unique artifacts we use the items() plugin to extract the keys from the spec dict.

LET X1 = if(condition=Do1, then=dict(`Generic.Client.Info`=dict()), else=dict())
LET X2 = if(condition=Do2, then=dict(`Generic.System.Pstree`=dict()), else=dict())

LET Spec = X1 + X2

LET ArtifactNames = SELECT _key FROM items(item=Spec)

SELECT collect_client(
         spec=Spec,
         artifacts=ArtifactNames._key,
         client_id='C.49982ba4c2ccef20') AS collection
FROM scope()

Notes

When constructing the dictionaries for the spec parameter you will often need to specify a field name containing full stop. You can escape this using the backticks like the example above.