OSQuery Access API

The OSQuery API requires you to send two different requests in a specific order:

  1. Send the OSQuery statement to computers so that the Cytomic EPDR agent prepares the information stored in the database on each computer and sends it to the Cytomic platform. Two API calls are available (/api/v1/osQuery/client and /api/v1/osQuery/machine) depending on whether you want to retrieve information from all computers of one or more clients or from a specific list of computers. As a result, you get an operation ID for each client that reports information from their computers.

  2. Send each operation ID to get the download URL of the file with information from each client’s computers, or to get the query status.

  3. Download a file for each client. This file contains all the information collected from the client’s computers. You can access this resource through the URL obtained in step 2 which, for security reasons, remain actives only for five minutes. After this time, go back to step 2 to get a new download URL

Because there might be computers that are turned off or unavailable, OSQuery statements can be extended indefinitely over time. That is why you must specify a TTL (Time To Live) value, after which Cytomic Orion considers the operation to be completed.

Send a Request to Get Information from One or Multiple Computers

Run an OSQuery-compatible SQL statement on specific computers that belong to the IT infrastructure of one or more clients.

Request

Command

POST

URL

/api/v1/osQuery/machine

Required parameters in the HTTP message body

JSON object with the OSQuery query and a list of MUIDs.

  • query: OSQuery-compatible SQL statement.

  • Ttl: Maximum wait time in minutes for getting the results. 0 to 24 hours.

  • MUIDs: List of identifiers of the computers where you want the statement to run.

Headers

  • Accept: application/json

  • Content-Type: application/json-patch+json

Format of the call to get information from one or multiple computers
Response

List of JSON objects, each with the ID of the operation performed for a client.

JSON object field Description

pandaID

Identifier of the client to which the computers that returned data belong.

operationId

Identifier of the operation performed. This is necessary to access the URL that contains the OSQuery query results. See Get an OSQuery Query Results.

MUIDs

List of identifiers of the client’s computers that returned data

JSON object with information from one or multiple computers

Send a Request to Get Information from All Computers of One or Multiple Clients

Run an OSQuery-compatible SQL statement on all computers belonging to the IT infrastructure of specific clients.

Request

Command

POST

URL

/api/v1/osQuery/client

Required parameters in the HTTP message body

JSON object with the OSQuery query and a list of client IDs.

  • query: OSQuery-compatible SQL statement.

  • Ttl: Maximum wait time in minutes for getting the results. 0 to 24 hours.

  • pandaIDs: List of identifiers of the clients where you want the statement to run.

Headers

  • Accept: application/json

  • Content-Type: application/json-patch+json

Format of the call to get information from the computers of one or more clients
Response

List of JSON objects, each with information from a client.

JSON object field Description

pandaID

Identifier of the client to which the computers that returned data belong.

operationId

Identifier of the operation performed. This is necessary to access the URL that contains the OSQuery query results. See Get an OSQuery Query Results.

MUIDs

List of identifiers of the client’s computers that returned data

JSON object with information from all of a client’s computers

Get an OSQuery Query Results

Get the URL that points to the file that contains the data collected from the specified computers.

Request

Command

POST

URL

/api/v1/osQuery/state

Required parameters in the HTTP message body

List of JSON objects, each with the ID of the operation whose data you want to retrieve.

  • pandaId: Identifier of the client to which the computers that returned data belong.

  • operationId: Identifier of the operation performed.

Headers

  • Accept: application/json

  • Content-Type: application/json-patch+json

Format of the call to get an OSQuery query results
Response

List of JSON objects, one for each client, with information about the query results.

JSON object field Description

panda

Identifier of the client to which the computers that returned data belong.

operationId

Identifier of the operation performed.

url

Download URL for the file that contains the information collected from computers. This link is valid for five minutes, For more information about the file format, see Download File Format.

counters

JSON object with the operation statistics:

  • totalOperationElements: Number of computers to which the request for information was sent.

  • totalSuccess: Number of computers that returned information successfully.

  • totalPartiallySucceeded: Number of computers that returned information but there were problems interpreting the results.

  • totalError: Number of computers that returned an error code.

  • errors: List of JSON objects with the errors received from computers. See Error Types.

    • errorCode: Error code.

    • errorDescription: Error description.

    • occurrences: Number of computers where the error occurred.

Response JSON object with the URL and operation result
Monitor Computers Turned Off, Unavailable, or with Delayed Responses

totalOperationElements is equal to the sum of totalSuccess + totalPartiallySucceeded + totalError if all computers respond, either with information or with an error. Because OSQuery statements can take an unspecified time to run, if totalOperationElements is not equal to the sum of totalSuccess + totalPartiallySucceeded + totalError this means there are computers on the client’s network that have not responded yet. In such case, you must send the operationId repeatedly until the totalOperationElements value is the right one or until the timeout established in the ttl field occurs.

Download File Format

The file that contains the data collected from the client’s computers has these features:

  • Name: “osquery_” + operation ID.

  • Format: Text.

  • Header: File fields separated by the “;” character.

  • Body: Lines with the content of the fields extracted by OSQuery from the computer database.

Error Types
Name Code Description Comments

ErrorExecutingOsQuery

201

near "name": syntax error

OSQuery is compatible with the 4.2.0 data schema. See OSQuery Requirements and check the OSQuery statement syntax.

ErrorOsNotSupported

202

Operating system not supported

OSQuery is compatible with Windows systems. See OSQuery Requirements.

ErrorOsQueryNotInstalled

203

OSQuery not installed

OSQuery is available from version 3.71 of Cytomic EDR. See OSQuery Requirements.

Error codes and their meanings

Get an OSQuery Query Status

Get a list of JSON objects with information about the status of in-progress or completed operations.

Request

Command

POST

URL

/api/v1/osQuery/info

Required parameters in the HTTP message body

List of JSON objects, each with the ID of the operation whose status you want to retrieve.

  • pandaId: Identifier of the client to which the computers that returned data belong.

  • operationId: Identifier of the operation performed.

Optional parameters in the HTTP message body

  • trackingStateType: Returns only operations with the specified status:

  • Pending (0): In-progress operations.

  • Success (1): Operations completed successfully.

  • PartiallySucceeded (2): Operations for which results were received from some computers.

  • Error (3): Operations that failed.

  • Canceled (4): Operations canceled because they timed out.

Headers

  • Accept: application/json

  • Content-Type: application/json-patch+json

Format of the call to get the status of a list of OSQuery queries
Response

List of JSON objects, one for each client, with information about the query results.

JSON object field Description

panda

Identifier of the client to which the operation belongs.

operationId

Identifier of the operation performed.

info

List of JSON objects, one for each client operation, with information about the operation status:

  • pandaId: Identifier of the client affected by the operation.

  • hostname: Name of the computer affected by the operation.

  • deviceId: Identifier of the computer affected by the operation.

  • trackingStateType: Operation status.

    • Pending (0): In-progress operation.

    • Success (1): Operation completed successfully.

    • PartiallySucceeded (2): Operation for which results were received from some computers.

    • Error (3): The operation failed. See Error Types.

    • Canceled (4): Operation canceled because it timed out.

  • date: Date the operation status last changed.

  • errorCode: Error code.

  • errorDescription: Error description.

Response JSON object with the operation status
Error Types
Name Code Description Comments

ErrorExecutingOsQuery

201

near "name": syntax error

OSQuery is compatible with the 4.2.0 data schema. See OSQuery Requirements and check the OSQuery statement syntax.

ErrorOsNotSupported

202

Operating system not supported

OSQuery is compatible with Windows systems. See OSQuery Requirements.

ErrorOsQueryNotInstalled

203

OSQuery not installed

OSQuery is available from version 3.71 of Cytomic EDR. See OSQuery Requirements.

Error codes and their meanings