collect_client

Function

ArgDescriptionType
client_idThe client id to schedule a collection onstring (required)
artifactsA list of artifacts to collectlist of string (required)
envParameters to apply to the artifact (an alternative to a full spec)ordereddict.Dict
specParameters to apply to the artifactsordereddict.Dict
timeoutSet query timeout (default 10 min)uint64
ops_per_secSet query ops_per_sec valuefloat64
cpu_limitSet query cpu_limit valuefloat64
iops_limitSet query iops_limit valuefloat64
max_rowsMax number of rows to fetchuint64
max_bytesMax number of bytes to uploaduint64
urgentSet the collection as urgent - skips other queues collections on the client.bool
org_idIf set the collection will be started in the specified org.string

Required permissions:COLLECT_CLIENT COLLECT_SERVER

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

NOTE: 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.

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:

  1. Depending on the checkbox condition we set a set of dicts and potential arguments.

  2. 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

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