Skip to main content

runLiveSearchQuery

Use this method to create task that retrieves information about events and system statistics directly from online endpoints. The task makes use of Osquery, an operating system instrumentation framework that uses the SQLite query language.

For more information on live search, refer to Live Search. For more information on

Osquery retrieves data from endpoints and uploads it to an S3 bucket for centralized storage. To upload the results of a live search to an S3 bucket, You need to set up your AWS (Amazon Web Services) cloud platform in advance. For a step by step buide, refer to Set up AWS for Live Search and runLiveSearchQuery.

Parameters

Parameter

Description

Included in request

Type

Values

companyId

The ID of the company that the target endpoints belong to.

Mandatory

String

No additional requirements.

query

The query that will run on all endpoints.

Mandatory

String

Refer to this KB article for more information on queries.

endpoints

A list of endpoint IDs. Determines where the query is ran.

Mandatory

Note

Although the parameter is mandatory, you can leave the array blank, which will trigger the default value.

Array of strings

The ID must belong to an endpoint managed by the target company.

Default value: all endpoints in the target company.

Note

The default value is automatically used when the array does not contain any values.

operatingSystems

The operating system of the target endpoints.

Tip

This parameter is best suited to run a query on all the endpoints of the target company that use a specific operating system. To do this, leave the endpoints array blank.

Mandatory

Note

Although the parameter is mandatory, you can leave the array blank, which will trigger the default value.

Array of strings

No additional requirements.

Possible values:

  • windows

  • linux

  • mac

Default value: all operating systems.

Note

The default value is automatically used when the array does not contain any values.

s3UploadConfig

The S3 bucket where the returned data is stored.

Mandatory

Object

Refer to s3UploadConfig

s3UploadConfig

Parameter

Description

Included in request

Type

bucket

The name of the S3 bucket where the data is stored.

Mandatory

String

region

The AWS region where the bucket is located.

Mandatory

String

roleArn

The Amazon Resource Name (ARN) of the IAM role GravityZone will assume when accessing the bucket.

Mandatory

String

externalId

The unique identifier set in the role trust policy.

It is used to enable secure cross-account access by verifying that the requester is authorized to assume the IAM role.

Mandatory

String

Return value

Attribute

Type

Description

result

String

The ID of the task created by the request.

Example

Request:

{
    "params": {
        "companyId": "669659908c2fa1ace601****",
        "query": "select * from time;",
        "endpoints": [
            "1234567890abcdef12345678",
            "a1b2c3d4e5f6078901234567"
            "0987654321fedcba87654321"
        ],
        "operatingSystems": [
            "windows", "linux", "mac"
        ],
        "s3UploadConfig": {
            "bucket": "osquery-bucket-test",
            "region": "eu-north-1",
            "roleArn": "arn:aws:iam::000000000000:role/osquery-role",
            "externalId": "000000000000000000000"
        }
    },
    "jsonrpc": "2.0",
    "method": "runLiveSearchQuery",
    "id": "123-456-789-1011"
}

Response:

{
     "id": "123-456-789-1011",
     "jsonrpc": "2.0",
     "result": "000000000000000000000000"
}
In this section: