Reference: API Gateway examples

Use the following query examples to learn about the functionality and syntax of queries and mutations in API Gateway.

General examples

The following queries retrieve data from the endpoints in your environment.

ClosedGet server time (query.now)

Get server time

The following query retrieves the local time from the Tanium ServerTanium Cloud.

Copy
query getServerTime {
  now
}

Example response:

Copy
{
  "data": {
    "now": "2021-11-08T19:22:03Z"
  }
}

ClosedGet endpoints (query.endpoints(source))

Get endpoints

The following query retrieves known endpoints from the Tanium ServerTanium Cloud.

Copy
query getEndpoints($count: Int, $time: Int) {
  endpoints(source: {ts: {expectedCount: $count, stableWaitTime: $time}}) {
    edges {
      node {
        computerID
        name
        serialNumber
        ipAddress
      }
    }
  }
}

Include the count and time variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "count": 1,
  "time": 10
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "937672696",
            "name": "ubuntu-test",
            "serialNumber": "Not Specified",
            "ipAddress": "10.168.20.30"
          }
        },
        {
          "node": {
            "computerID": "1867570226",
            "name": "CentOS-test-1",
            "serialNumber": "Not Specified",
            "ipAddress": "10.168.20.40"
          }
        },
        {
          "node": {
            "computerID": "2711217959",
            "name": "CentOS-test-2",
            "serialNumber": "Not Specified",
            "ipAddress": "10.168.20.50"
          }
        }
      ]
    }
  }
}

ClosedGet endpoints IDs from Tanium Data Service (query.endpoints)

Get endpoints IDs from Tanium Data Service

The following query retrieves all endpoint IDs from Tanium Data Service.

Copy
query getTDSEndpointIDs {
  endpoints {
    edges {
      node {
        id
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "id": "12345"
          }
        },
        {
          "node": {
            "id": "54321"
          }
        },
        {
          "node": {
            "id": "21212"
          }
        }
      ]
    }
  }
}

ClosedGet endpoints with filter excluding errors (query.endpoints (source.ts.excludeErrors | source.tds.excludeErrors)

Get endpoints without field values containing common errors

Retrieved endpoints might contain error messages as field values. You can exclude endpoints retrieved from either the ts or tds data source from the response if they contain common error messages within returned fields. The following query retrieves the first 2 endpoints from Tanium Data Service, and does not exclude endpoints with common error values in returned fields.

Copy
query excludeEndpointsErrors($first: Int, $excludeErrors: Boolean!) {
  endpoints(first: $first, source: {tds: {excludeErrors: $excludeErrors}}) {
    edges {
      node {
        name 
        ipAddress
        manufacturer
        model
      }
    }
  }
}

Include the pagination and excludeErrors variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2,
  "excludeErrors": false
}

Example response containing an endpoint with a common error value in the manufacturer and model fields:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host-1",
            "ipAddress": "192.0.2.10",
            "manufacturer": "VMware, Inc.",
            "model": "VMware Virtual Platform"
          }
        },
        {
          "node": {
            "name": "example-host-2",
            "ipAddress": "192.0.2.20",
            "manufacturer": "TSE-Error: Unknown - dmidecode unavailable",
            "model": "TSE-Error: Unknown - dmidecode unavailable"
          }
        }
      ]
    }
  }
}

If you update the excludeErrors variable definition to true, the query response excludes endpoints with common error values in the returned fields:

Copy
{
  "first": 2,
  "excludeErrors": true
}

Example response containing no endpoints with a common error value in the manufacturer and model fields:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host-1",
            "ipAddress": "192.0.2.10",
            "manufacturer": "VMware, Inc.",
            "model": "VMware Virtual Platform"
          }
        },
        {
          "node": {
            "name": "example-host-3",
            "ipAddress": "192.0.2.30",
            "manufacturer": "Apple",
            "model": "MacPro6,1"
          }
        }
      ]
    }
  }
}

ClosedGet endpoints with filter excluding [no results] (query.endpoints (source.ts.excludeNoResults | source.tds.excludeNoResults)

Get endpoints without field values containing [no results]

Retrieved endpoints might contain [no results] as field values. You can exclude endpoints retrieved from either the ts or tds data source from the response if they contain [no results] in returned fields. The following query retrieves the first 2 endpoints from Tanium Data Service, and does not exclude endpoints with [no results] in returned fields.

Copy
query excludeEndpointsNoResults($first: Int, $excludeNoResults: Boolean!) {
  endpoints(first: $first, source: {tds: {excludeNoResults: $excludeNoResults}}) {
    edges {
      node {
        name
        ipAddress
        macAddresses
      }
    }
  }
}

Include the pagination and excludeErrors variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2,
  "excludeNoResults": false
}

Example response containing an endpoint with [no results] in the macAddresses fiels:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host-1",
            "ipAddress": "192.0.2.10",
            "macAddresses": [
              "00:00:5E:00:53:10"
            ]
          }
        },
        {
          "node": {
            "name": "example-host-2",
            "ipAddress": "192.0.2.20",
            "macAddresses": [
              "[no results]"
            ]
          }
        }
      ]
    }
  }
}

If you update the excludeNoResults variable definition to true, the query response excludes endpoints with [no results] in the returned fields:

Copy
{
  "first": 2,
  "excludeNoResults": true
}

Example response containing no endpoints with [no results] in the macAddresses field:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host-1",
            "ipAddress": "192.0.2.10",
            "macAddresses": [
              "00:00:5E:00:53:10"
            ]
          }
        },
        {
          "node": {
            "name": "example-host-3",
            "ipAddress": "192.0.2.30",
            "macAddresses": [
              "00:00:5E:00:53:30"
            ]
          }
        }
      ]
    }
  }
}

ClosedGet endpoints using aliases (query.endpoints(source))

Use aliases in an endpoints query request

The following query retrieves known endpoints using aliases to rename the information returned and prevent data collision due to overlapping field names. The tds alias retrieves the id and name of known endpoints from Tanium Data Service. The ts alias retrieves the IPv6 address value of known endpoints from the Tanium ServerTanium as a Service and the sensor name.

Copy
query getEndpointsAliases($time: Int) {
  tds: endpoints {
    edges {
      node {
        id
        name
      }
    }
  }
  ts: endpoints(source: {ts: {stableWaitTime: $time}}) {
    edges {
      node {
        sensorReadings(sensors: [{name: "IPv6 Address"}]) {
          columns {
            name
            values
          }
        }
      }
    }
  }
}

Include the time and sensor name variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "time": 10
}

Example response:

Copy
{
  "data": {
    "tds": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "example-name"
          }
        },
        {
          "node": {
            "id": "54321",
            "name": "example-name-2"
          }
        }
      ]
    },
    "ts": {
      "edges": [
        {
          "node": {
            "sensorReadings": {
              "columns": [
                {
                  "name": "IPv6 Address",
                  "values": [
                    "2001:db8::3"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "sensorReadings": {
              "columns": [
                {
                  "name": "IPv6 Address",
                  "values": [
                    "2001:db8::2"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedGet endpoints using multiple sensors (query.endpoints.edges.node.sensorReadings)

Get endpoints using multiple sensors

The following query retrieves known endpoints using multiple sensors. The request specifies the sensor name as one of the fields returned in the request, to identify the sensor that reported the information.

Copy
query getEndpointsApplications {
  endpoints {
    edges {
      node {
        computerID
        sensorReadings(sensors: [{name: "Installed Applications"}, {name: "Running Applications"}]) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "987654321",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "Tanium Client 7.4.7.1094"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "7.4.7.1094"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Silent Uninstall String",
                  "values": [
                    "\"C:\\Program Files (x86)\\Tanium\\Tanium Client\\uninst.exe\""
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Uninstallable",
                  "values": [
                    "Is Uninstallable"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Name",
                  "values": [
                    "Tanium Client"
                  ],
                  "sensor": {
                    "name": "Running Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "7.4.7.1094"
                  ],
                  "sensor": {
                    "name": "Running Applications"
                  }
                },
                {
                  "name": "Process Name",
                  "values": [
                    "TaniumClient.exe"
                  ],
                  "sensor": {
                    "name": "Running Applications"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedGet rich endpoint data (query.endpoints(first))

Get rich endpoint data

The following query demonstrates using nested fields to retrieve categorized endpoint data.

The first: $first argument passes the query variable value 2 and retrieves two records; set this value higher to retrieve more records at a time. For more information on pagination arguments, see Pagination.

Copy
query getRichEndpointData($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        computerID
        ipAddress
        isVirtual
        chassisType
        systemUUID
        domainName
        os {
          name
          platform
          generation
        }
        processor {
          architecture
          cacheSize
          consumption
          cpu
          family
          manufacturer
          speed
        }
        lastLoggedInUser
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasNextPage
    }
  }
}

Include the first pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "Test-01",
            "computerID": "1234567890",
            "ipAddress": "192.0.2.10",
            "isVirtual": false,
            "chassisType": "TSE-Error: Unknown - dmidecode unavailable",
            "systemUUID": "TSE-Error: Unknown - dmidecode unavailable",
            "domainName": "(none)",
            "os": {
              "name": "Red Hat Enterprise Linux Server release 5.11 (Tikanga)",
              "platform": "Linux",
              "generation": "Red Hat Enterprise Linux 5"
            },
            "processor": {
              "architecture": "x86_64",
              "cacheSize": "16384 KB",
              "consumption": "9.9 %",
              "cpu": "Intel Core Processor (Haswell, no TSX, IBRS)",
              "family": "6",
              "manufacturer": "GenuineIntel",
              "speed": "2600 Mhz"
            },
            "lastLoggedInUser": "reboot"
          }
        },
        {
          "node": {
            "name": "Test-02",
            "computerID": "3216549870",
            "ipAddress": "192.0.2.20",
            "isVirtual": true,
            "chassisType": "Virtual",
            "systemUUID": "[no results]",
            "domainName": "(none)",
            "os": {
              "name": "CentOS Linux release 8.4.2105",
              "platform": "Linux",
              "generation": "CentOS 8"
            },
            "processor": {
              "architecture": "x86_64",
              "cacheSize": "35840 KB",
              "consumption": "18.6 %",
              "cpu": "Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz",
              "family": "6",
              "manufacturer": "GenuineIntel",
              "speed": "2400 Mhz"
            },
            "lastLoggedInUser": "tester-5"
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasNextPage": true
      }
    }
  }
}

ClosedGet a set of endpoints (query.endpoints(filter).edges.node.sensorReadings)

Get first three endpoints with names containing the letter t

The following query retrieves a set of endpoints. The query demonstrates the use of the sensorReadings field and contains a filter argument to retrieve endpoints whose names contain the letter t. The results are paginated to 3 records.

Copy
query getEndpointNamesWithT($first: Int, $filterOp: FieldFilterOp!, $path: String, $value: String) {
  endpoints(first: $first, filter: {op: $filterOp, path: $path, value: $value}) {
    edges {
      node {
        name
        ipAddress
        sensorReadings(sensors: [{name: "EID Last Seen"}]) {
          columns {
            name
            values
          }
        }
      }
    }
  }
}

Include the filter-related and sensor name variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 3,
  "filterOp": "MATCHES",
  "path": "name",
  "value": "t.*"
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "test-1",
            "ipAddress": "192.0.2.10",
            "sensorReadings": {
              "columns": [
                {
                  "name": "EID Last Seen",
                  "values": [
                    "Mon, 08 Nov 2021 21:29:28 +0000"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "test-2",
            "ipAddress": "192.0.2.20",
            "sensorReadings": {
              "columns": [
                {
                  "name": "EID Last Seen",
                  "values": [
                    "Mon, 08 Nov 2021 21:29:28 +0000"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "test-3",
            "ipAddress": "192.0.2.30",
            "sensorReadings": {
              "columns": [
                {
                  "name": "EID Last Seen",
                  "values": [
                    "Mon, 08 Nov 2021 21:17:17 +0000"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedUnregistered sensor query (query.endpoints.edges.node.sensorReadings)

Get operating systems on endpoints

The following query retrieves the operating system platform from all endpoints.

In API Gateway, a sensor is unregistered if the sensor is not represented by a named field in the API Gateway schema. This has no correlation to registering sensors in Tanium Data Service.

Copy
query getEndpointsUnregisteredSensor {
  endpoints {
    edges {
      node {
        id
        name
        sensorReadings(sensors: [{name: "OS Platform"}]) {
          columns {
            name
            values
          }
        }
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "Test-01",
            "sensorReadings": {
              "columns": [
                {
                  "name": "OS Platform",
                  "values": [
                    "Linux"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "id": "54321",
            "name": "Test-03",
            "sensorReadings": {
              "columns": [
                {
                  "name": "OS Platform",
                  "values": [
                    "Linux"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedUnregistered parameterized sensor query (query.endpoints.edges.node.sensorReadings)

Get endpoints with a file

The following query checks to see if each endpoint contains the C:\Windows\py.exe file.

In API Gateway, a sensor is unregistered if the sensor is not represented by a named field in the API Gateway schema. This has no correlation to registering sensors in Tanium Data Service.

Copy
query getEndpointsParams($paramName1: String!, $paramValue1: String!) {
  endpoints(source: {ts: {}}) {
    edges {
      node {
        name
        id
        sensorReadings(
          sensors: [{name: "File Exists", params: [{name: $paramName1, value: $paramValue1}]}]
        ) {
          columns {
            sensor {
              name
              params {
                name
                value
              }
            }
            values
          }
        }
      }
    }
  }
}

Include the sensor name and parameter variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "paramName1": "file",
  "paramValue1": "C:\\Windows\\py.exe"
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "Test-01",
            "id": "12345",
            "sensorReadings": {
              "columns": [
                {
                  "sensor": {
                    "name": "File Exists",
                    "params": [
                      {
                        "name": "file",
                        "value": "C:\\Windows\\py.exe"
                      }
                    ]
                  },
                  "values": [
                    "File does not exist"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "[no results]",
            "id": "54225",
            "sensorReadings": {
              "columns": [
                {
                  "sensor": {
                    "name": "File Exists",
                    "params": [
                      {
                        "name": "file",
                        "value": "C:\\Windows\\py.exe"
                      }
                    ]
                  },
                  "values": [
                    "[no results]"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "[no results]",
            "id": "65456",
            "sensorReadings": {
              "columns": [
                {
                  "sensor": {
                    "name": "File Exists",
                    "params": [
                      {
                        "name": "file",
                        "value": "C:\\Windows\\py.exe"
                      }
                    ]
                  },
                  "values": [
                    "[no results]"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedGet selected columns from sensor query (query.endpoints.edges.node.sensorReadings.columns)

Get selected columns from a sensor query

The following query retrieves the first 2 endpoint results, and returns only the Name and Silent Uninstall String columns from the Installed Applications sensor.

Copy
query getEndpointsApplicationsColumns ($first: Int) {
  endpoints (first: $first) {
    edges {
      node {
        computerID
        sensorReadings(sensors: [{name: "Installed Applications", columns: ["Name", "Silent Uninstall String"]}]) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "987654321",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "Tanium Client 7.4.7.1094"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Silent Uninstall String",
                  "values": [
                    "\"C:\\Program Files (x86)\\Tanium\\Tanium Client\\uninst.exe\""
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Get hidden columns from a sensor query

The following query retrieves the first 2 endpoint results, and based on includeHiddenColumns: true, returns all columns from the Application Crashes in Last X Days sensor, including a non-hidden column (Process) and a hidden column (Date).

To return hidden columns, you can also specify column names in the filter. By default, hidden columns are not returned.

Copy
query getEndpointsHiddenColumns ($first: Int) {
  endpoints (first: $first) {
    edges {
      node {
        computerID
        sensorReadings(sensors: [{name: "Application Crashes in Last X Days"}], includeHiddenColumns: true
        ) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "1814669575",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Process",
                  "values": [
                    "example.exe"
                  ],
                  "sensor": {
                    "name": "Application Crashes in Last X Days"
                  }
                },
                {
                  "name": "Date",
                  "values": [
                    "12/30/2022"
                  ],
                  "sensor": {
                    "name": "Application Crashes in Last X Days"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "computerID": "2508280668",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Process",
                  "values": [
                    "example2.exe"
                  ],
                  "sensor": {
                    "name": "Application Crashes in Last X Days"
                  }
                },
                {
                  "name": "Date",
                  "values": [
                    "12/29/2022"
                  ],
                  "sensor": {
                    "name": "Application Crashes in Last X Days"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedFilter sensor query results (query.endpoints.edges.node.sensorReadings (sensors.filter))

Filter the results from a sensor query

The following query retrieves the first 2 endpoint results, and returns the application Name and Version columns for only the endpoints that have the tar application installed, based on the results from the Installed Applications sensor.

Copy
query getEndpointsInstalledTar ($first: Int) {
  endpoints (first: $first){
    edges {
      node {
        computerID
        sensorReadings(
          sensors: [{name: "Installed Applications", filter: {column: "Name", op: EQ, value: "tar", restrictOwner: false}}]
        ) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "1234567890",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "tar"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "1.34"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "computerID": "2345678901",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "tar"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "1.33"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}       

Filter sensor query results from a filtered set of endpoints

The following query retrieves the first 2 endpoints that are a member of the All Linux computer group, and returns the application Name and Version columns for only the endpoints that have the tar application installed, based on the results from the Installed Applications sensor.

Copy
query getLinuxEndpointsInstalledTar ($first: Int){
  endpoints(first: $first, filter: {memberOf: {name: "All Linux"}}) {
    edges {
      node {
        computerID
        sensorReadings(
          sensors: [{name: "Installed Applications", filter: {column: "Name", op: EQ, value: "Tar", restrictOwner: false}}]
        ) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "3456789012",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "tar"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "1.32"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "computerID": "4567890123",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "tar"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "1.30"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}       

Apply multi-column filter to sensor query results

The following query retrieves the first 2 endpoints, and returns the application Name and Version columns for only the endpoints that have the tar application version 1.30 installed, based on the results from the Installed Applications sensor.

Copy
query getEndpointsInstalledTar13 ($first: Int){
  endpoints (first: $first){
    edges {
      node {
        computerID
        sensorReadings(
          sensors: [{name: "Installed Applications", 
            filter: {
              restrictOwner: false,
              filters: [
                {column: "Name", op: EQ, value: "Tar"},
                {column: "Version" op: EQ, value: "1.30"}]
              }
            }]
        ) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "4567890123",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "tar"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "1.30"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "computerID": "5678901234",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "tar"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "1.30"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}       

Apply multi-column filter to sensor query results for filtered endpoints

The following query retrieves the first 2 endpoints that are members of the All Linux computer group, and returns the application Name and Version columns for only the endpoints that have the tar application version 1.30 installed, based on the results from the Installed Applications sensor.

Copy
query getLinuxEndpointsInstalledTar130 ($first: Int){
  endpoints(first: $first, filter: {memberOf: {name: "All Linux"}}) {
    edges {
      node {
        computerID
        sensorReadings(
          sensors: [{name: "Installed Applications", 
            filter: { 
              restrictOwner: false,
              filters: [
                {column: "Name", op: EQ, value: "Tar", },
                {column: "Version" op: EQ, value: "1.30"}]
              }
            }]
        ) {
          columns {
            name
            values
            sensor {
              name
            }
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "6789012345",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "tar"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "1.30"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        },
        {
          "node": {
            "computerID": "7890123456",
            "sensorReadings": {
              "columns": [
                {
                  "name": "Name",
                  "values": [
                    "tar"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                },
                {
                  "name": "Version",
                  "values": [
                    "1.30"
                  ],
                  "sensor": {
                    "name": "Installed Applications"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}       

ClosedEndpoint cursor query (query.endpoints.pageInfo)

Get endpoint pagination information

The following query retrieves cursors for endpoint records. You can use these cursors to retrieve specific endpoint records on a page. For more information on cursors, see Pagination.

Copy
query getEndpointCursors {
  endpoints {
    pageInfo {
      hasPreviousPage 
      hasNextPage
      startCursor 
      endCursor
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "pageInfo": {
        "hasPreviousPage": false,
        "hasNextPage": true,
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ=="
      }
    }
  }
}

ClosedPaginated query (query.endpoints(after, first))

Get first five endpoints

The following query retrieves the first five endpoint records after the given cursor. For more information on cursors, see Pagination.

Copy
query getFirstFiveEndpoints($cursor: Cursor, $first: Int) {
  endpoints(after: $cursor, first: $first) {
    edges {
      node {
        name
        id
        ipAddress
      }
    }
    pageInfo {
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Include the pagination-related variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "cursor": "NTc2NTM4MDow",
  "first": 5
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "Test-06",
            "id": "6172",
            "ipAddress": "192.0.2.10"
          }
        },
        {
          "node": {
            "name": "Test-07",
            "id": "87654",
            "ipAddress": "192.0.2.20"
          }
        },
        {
          "node": {
            "name": "Test-14",
            "id": "43584",
            "ipAddress": "192.0.2.30"
          }
        },
        {
          "node": {
            "name": "Test-03",
            "id": "37233",
            "ipAddress": "[no results]"
          }
        },
        {
          "node": {
            "name": "Test-55",
            "id": "12139",
            "ipAddress": "[no results]"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ=="
      }
    }
  }
}

ClosedGet refreshed collection of endpoints (query.endpoints.collectionInfo.startCursor, query.endpoints(refresh))

Retrieve collection start cursor

The following query retrieves an endpoint that is slow to respond, with collectionInfo.startCursor included in the response to use for refreshing the request. For more information on refreshing a collection, see Refreshing Collections.

Copy
query getSlowEndpoint($first: Int, $path: String, $value: String, $expectedCount: Int) {
  endpoints(
    first: $first
    filter: {path: $path, value: $value}
    source: {ts: {expectedCount: $expectedCount}}
  ) {
    edges {
      node {
        id
      }
    }
    collectionInfo {
      startCursor
      success
      active
    }
  }
}

Add the pagination and filter variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1,
  "path": "name",
  "value": "slow-endpoint",
  "expectedCount": 1
}

Example response for an ongoing collection with a startCursor value:

Copy
{
  "data": {
    "endpoints": {
      "edges": [],
      "collectionInfo": {
        "startCursor": "4t2cB0ZGNPqy4J4P7O7opwz/24/5zgPi6OinDAA=:0",
        "success": false,
        "active": true
      }
    }
  }
}

Refresh collection using starting cursor

The following query refreshes the collection using the returned startCursor value:

Copy
query getEndpointRefresh($refresh: Cursor, $first: Int, $path: String, $value: String, $expectedCount: Int) {
  endpoints(
    refresh: $refresh
    first: $first
    filter: {path: $path, value: $value}
    source: {ts: {expectedCount: $expectedCount}}
  ) {
    edges {
      node {
        id
      }
    }
    collectionInfo {
      startCursor
      success
      active
    }
  }
}

Add the pagination and filter variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "refresh": "4t2cB0ZGNPqy4J4P7O7opwz/24/5zgPi6OinDAA=:0",
  "first": 1,
  "path": "name",
  "value": "slow-endpoint",
  "expectedCount": 1
}

Example response with a completed collection:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "id": 1
          }     
      ],
      "collectionInfo": {
        "startCursor": "4t2cB0ZGNPqy4J4P7O7opwz/24/5zgPi6OinDAA=:0",
        "success": true,
        "active": true
      }
    }
  }
}

ClosedSoftware characteristics query with filter (query.endpoints.edges.node.deployedSoftwarePackages)

Get endpoint software installed using Deploy

The following query retrieves endpoints that contain software installed by Deploy, where the package ID is 123.

Copy
query getEndpointsPackage123($value1: String, $value2: String) {
  endpoints {
    edges {
      node {
        ipAddress
        isVirtual
        domainName
        os {
          generation
        }
        lastLoggedInUser
        deployedSoftwarePackages(
          filter: {filters: [{op: EQ, path: "id", value: $value1}, {op: EQ, path: "applicability", value: $value2}]}
        ) {
          id
        }
      }
    }
  }
}

Include the value variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "value1": "123",
  "value2": "Installed"
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "ipAddress": "192.0.2.10",
            "isVirtual": true,
            "domainName": "(none)",
            "os": {
              "generation": "Debian 9"
            },
            "lastLoggedInUser": "[no results]",
            "deployedSoftwarePackages": [
              {
                "id": "123"
              }
            ]
          }
        },
        {
          "node": {
            "ipAddress": "192.0.2.20",
            "isVirtual": true,
            "domainName": "(none)",
            "os": {
              "generation": "CentOS 7"
            },
            "lastLoggedInUser": "admin",
            "deployedSoftwarePackages": [
              {
                "id": "123"
              }
            ]
          }
        },
        {
          "node": {
            "ipAddress": "192.0.2.30",
            "isVirtual": true,
            "domainName": "(none)",
            "os": {
              "generation": "Ubuntu 20.04"
            },
            "lastLoggedInUser": "admin",
            "deployedSoftwarePackages": [
              {
                "id": "123"
              }
            ]
          }
        }
      ]
    }
  }
}

ClosedGet applications installed on endpoint (query.endpoints.edges.node.installedApplications)

Get endpoint installed applications

The following query retrieves the applications installed on the first 2 endpoints, the application version, the program used to uninstall the application, and whether you can uninstall the application using Tanium.

Copy
query getInstalledApplications($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        id
        name
        installedApplications {
          name
          silentUninstallString
          uninstallable
          version
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "example-host",
            "installedApplications": [
              {
                "name": "Notepad++ (64-bit x64)",
                "silentUninstallString": "\"C:\\Program Files\\Notepad++\\uninstall.exe\"",
                "uninstallable": false,
                "version": "8.4.2"
              },
              {
                "name": "Microsoft Edge",
                "silentUninstallString": "\"C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\103.0.1264.49\\Installer\\setup.exe\" --uninstall --msedge --channel=stable --system-level --verbose-logging",
                "uninstallable": false,
                "version": "103.0.1264.62"
              },
              {
                "name": "Tanium Client 7.4.8.1042",
                "silentUninstallString": "\"C:\\Program Files (x86)\\Tanium\\Tanium Client\\uninst.exe\"",
                "uninstallable": false,
                "version": "7.4.8.1042"
              }
            ]
          }
        },
        {
          "node": {
            "id": "23456",
            "name": "example-host-2",
            "installedApplications": [
            {
              "name": "Google Chrome",
              "silentUninstallString": "MsiExec.exe /X{6C53E336-8514-3BA8-8852-427A9FB5DC91}",
              "uninstallable": true,
              "version": "103.0.5060.114"
            },
            {
              "name": "Tanium Client 7.4.8.1042",
              "silentUninstallString": "\"C:\\Program Files (x86)\\Tanium\\Tanium Client\\uninst.exe\"",
              "uninstallable": false,
              "version": "7.4.8.1042"
            }
            ]
          }
        }
      ]
    }
  }
}

ClosedGet Microsoft Sentinel endpoint information (query.endpoints.edges.node.sentinel)

Get Microsoft Sentinel endpoint information

The following query retrieves Microsoft Sentinel information for the first 2 endpoints, including Windows Defender and System Center Configuration Manager (SCCM) client details.

Copy
query getSentinelInfo ($first: Int) {
  endpoints (first: $first){
    edges {
      node {
        id 
        name
        sentinel {
          sccmClient {
            health 
            reason 
          }
          windowsDefender {
            antiSpywareEnabled
            antivirusEnabled
            antivirusSignatureUpdateAge
            clientVersion
            healthy
            installed
            processEnabled
            processStartType
            quickScanAge
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first" : 2
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "Example_host",
            "sentinel": {
              "sccmClient": {
                "health": "Healthy",
                "reason": ""
              },
              "windowsDefender": {
                "antiSpywareEnabled": "True",
                "antivirusEnabled": "True",
                "antivirusSignatureUpdateAge": "0",
                "clientVersion": "1.1.19500.2",
                "healthy": "true",
                "installed": "True",
                "processEnabled": "True",
                "processStartType": "Normal",
                "quickScanAge": "1"
              }
            }
          }
        },
        {
          "node": {
            "id": "23456",
            "name": "Example_host_2",
            "sentinel": {
              "sccmClient": {
                "health": "Needs Attention",
                "reason": "SCCM Not Installed"
              },
              "windowsDefender": {
                "antiSpywareEnabled": "True",
                "antivirusEnabled": "True",
                "antivirusSignatureUpdateAge": "1",
                "clientVersion": "1.1.19500.2",
                "healthy": "true",
                "installed": "True",
                "processEnabled": "True",
                "processStartType": "Normal",
                "quickScanAge": "0"
              }
            }
          }
        }
      ]
    }
  }
}

Action examples

The following queries and mutations create actions, retrieve action details, stop actions, approve scheduled actions, and delete actions.

ClosedApprove a scheduled action (mutation.scheduledActionApprove)

Approve scheduled action

The following mutation approves the scheduled action that matches the action ID.

Copy
mutation approveScheduledAction($id: ID!) {
  scheduledActionApprove(ref: {id: $id}) {
    approved
    id
    error {
      message
    }
  }
}                

Include the scheduled action ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 12345
}

Example response:

Copy
{
  "data": {
    "scheduledActionApprove": {
      "approved": true,
      "id": "12345",
      "error": null
    }
  }
}

ClosedCreate action (mutation.actionCreate)

Create action

The following mutation creates an action, referencing a package and target computer group, and setting distribute over time and expiration details.

Copy
mutation createAction($comment: String, $distributeSeconds: Int, $expirationTime: Time, $expireSeconds: Int, $name: String, $packageID: ID, $targetGroupID: ID) {
  actionCreate(
    input: {comment: $comment, distributeSeconds: $distributeSeconds, expirationTime: $expirationTime, expireSeconds: $expireSeconds, name: $name, package: {id: $packageID}, targets: {actionGroup: {id: $targetGroupID}}}
  ) {
    action {
      id
    }
    error {
      message
    }
  }
}

Include the action creation variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "comment": "Example created action",
  "distributeSeconds": 60,
  "expirationTime": "2023-01-01T00:00:00+00:00",
  "expireSeconds": 120,
  "name": "Example created action",
  "packageID": 12345,
  "targetGroupID": 67890
}

Example response:

Copy
{
  "data": {
    "actionCreate": {
      "action": {
        "id": "123"
      },
      "error": null
    }
  }
}

ClosedCreate scheduled action (mutation.scheduledActionCreate)

Create scheduled action

The following query creates a scheduled action, referencing a package and target computer group, and setting start and end time, distribute over time, and expiration details.

Copy
mutation createScheduledAction($comment: String, $distributeSeconds: Int, $endTime: Time, $expireSeconds: Int, $issueSeconds: Int, $name: String, $packageID: ID, $startTime: Time, $targetGroupID: ID) {
  scheduledActionCreate(
    input: {comment: $comment, distributeSeconds: $distributeSeconds, endTime: $endTime, expireSeconds: $expireSeconds, issueSeconds: $issueSeconds, name: $name, package: {id: $packageID}, startTime: $startTime, targets: {actionGroup: {id: $targetGroupID}}}
  ) {
    scheduledAction {
      approved
      approver {
        persona {
          id
        }
        user {
          id
        }
      }
      comment
      creator {
        persona {
          id
        }
        user {
          id
        }
      }
      distributeSeconds
      endTime
      expireSeconds
      id
      issueCount
      issueSeconds
      lastAction {
        id
      }
      lastStartTime
      name
      nextStartTime
      package {
        id
      }
      startTime
      status
      targets {
        actionGroup {
          id
        }
        targetGroup {
          id
        }
      }
    }
    error {
      message
    }
  }
}

Include the action-related variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "comment": "Example scheduled action",
  "distributeSeconds": 60,
  "endTime": "2023-01-01T00:00:00+00:00",
  "expireSeconds": 1200,
  "issueSeconds": 60,
  "name": "Example scheduled action",
  "packageID": 12345,
  "startTime": "2022-01-01T00:00:00+00:00",
  "targetGroupID": 67890
}

Example response:

Copy
{
  "data": {
    "scheduledActionCreate": {
      "scheduledAction": {
        "approved": true,
        "approver": {
          "persona": null,
          "user": {
            "id": "1"
          }
        },
        "comment": "Example scheduled action",
        "creator": {
          "persona": null,
          "user": {
            "id": "1"
          }
        },
        "distributeSeconds": 60,
        "endTime": "2023-01-01T00:00:00Z",
        "expireSeconds": 1200,
        "id": "123",
        "issueCount": 0,
        "issueSeconds": 60,
        "lastAction": {
          "id": "12345"
        },
        "lastStartTime": null,
        "name": "Example scheduled action",
        "nextStartTime": "2022-07-14T18:08:19Z",
        "package": {
          "id": "12345"
        },
        "startTime": "2022-01-01T00:00:00Z",
        "status": "ENABLED",
        "targets": {
          "actionGroup": {
            "id": "67890"
          },
          "targetGroup": {
            "id": "34567"
          }
        }
      },
      "error": null
    }
  }
}

ClosedDelete action or scheduled action (mutation.scheduledActionDelete)

Delete action

The following mutation deletes an action or scheduled action based on the ID.

Copy
mutation deleteScheduledAction($id: ID!) {
  scheduledActionDelete(ref: { id: $id }) {
    id
    error {
      message
    }
  }
}

Include the action ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 12345
}

Example response:

Copy
{
  "data": {
    "scheduledActionDelete": {
      "id": "12345",
      "error": null
    }
  }
}

ClosedGet action information (query.action)

Get action information

The following query retrieves information about an action that matches the ID.

Copy
query getAction($id: ID!) {
  action(ref: {id: $id}) {
    approver {
      persona {
        id
        name
      }
      user {
        id
        name
      }
    }
    comment
    creationTime
    creator {
      persona {
        id
        name
      }
      user {
        id
        name
      }
    }
    distributeSeconds
    expirationTime
    expireSeconds
    id
    name
    package {
      id
      name
      params
      sensorSourcedParams {
        name 
        value
      }      
    }
    results {
      completed
      downloading
      expired
      failed
      failedVerification
      id
      pendingVerification
      running
      verified
      waiting
      waitingToRetry
    }
    scheduledAction {
      approved
      comment
      distributeSeconds
      endTime
      expireSeconds
      id
      issueCount
      issueSeconds
      lastAction {
        id
      }
      lastStartTime
      name
      nextStartTime
      package {
        id
      }
      startTime
      status
    }
    startTime
    status
    stopped
    stoppedFlag
  }
}

Include the action ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": "12345"
}

Example response:

Copy
{
  "data": {
    "action": {
      "approver": {
        "persona": null,
        "user": {
          "id": "1",
          "name": "Admin"
        }
      },
      "comment": "",
      "creationTime": "2022-07-10T09:40:20Z",
      "creator": {
        "persona": null,
        "user": {
          "id": "1",
          "name": "Admin"
        }
      },
      "distributeSeconds": 1800,
      "expirationTime": "2022-07-10T10:10:12Z",
      "expireSeconds": 1800,
      "id": "12345",
      "name": "Example action",
      "package": {
        "id": "23456",
        "name": "Example package",
        "params": null,
        "sensorSourcedParams": [
          {
            "name": "Example parameter",
            "value": "example_value"
          }
        ]
      },
      "results": {
        "completed": 4,
        "downloading": 0,
        "expired": 0,
        "failed": 0,
        "failedVerification": 0,
        "id": "",
        "pendingVerification": 0,
        "running": 0,
        "verified": 0,
        "waiting": 0,
        "waitingToRetry": 0
      },
      "scheduledAction": {
        "approved": true,
        "comment": "",
        "distributeSeconds": 1800,
        "endTime": null,
        "expireSeconds": 1800,
        "id": "34567",
        "issueCount": 146,
        "issueSeconds": 3600,
        "lastAction": {
          "id": "45678"
        },
        "lastStartTime": "2022-07-14T17:40:12Z",
        "name": "Example scheduled action",
        "nextStartTime": "2022-07-14T18:40:12Z",
        "package": {
          "id": "56789"
        },
        "startTime": "2022-07-08T16:40:12Z",
        "status": "ENABLED"
      },
      "startTime": "2022-07-10T09:40:12Z",
      "status": null,
      "stopped": false,
      "stoppedFlag": false
    }
  }
}

ClosedGet package spec information (query.packageSpecs)

Get package spec object information

The following query retrieves the first 2 package spec objects.

Copy
query getPackageSpecs($first: Int) {
  packageSpecs(first: $first) {
    edges {
      node {
        id
        name
        contentSetName
        command
        commandTimeoutSeconds
        expireSeconds
        params {
          key
          label
          defaultValue
        }
        sensorSourcedParams {
          name
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first" : 2
}

Example response:

Copy
{
  "data": {
    "packageSpecs": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "Example package 1",
            "contentSetName": "Base",
            "command": "cmd.exe /d /c" $1,
            "commandTimeoutSeconds": 60,
            "expireSeconds": 660,
            "params": [
              {
                "key": "$1",
                "label": "Example parameter",
                "defaultValue": null
              }
            ],
            "sensorSourcedParams": []
          }
        },
        {
          "node": {
            "id": "23456",
            "name": "Example package 2",
            "contentSetName": "Base",
            "command": "cmd.exe /d /c ||Example sensor||",
            "commandTimeoutSeconds": 60,
            "expireSeconds": 660,
            "params": [],
            "sensorSourcedParams": [
              {
                "name": "Example sensor"
              }
            ]
          }
        }
      ]
    }
  }
}

ClosedGet scheduled action information (query.scheduledAction)

Get scheduled action information

The following query retrieves information about a scheduled action that matches the ID.

Copy
query getScheduledAction($id: ID!) {
  scheduledAction(ref: {id: $id}) {
    approver {
      persona {
        id
        name
      }
      user {
        id
        name
      }
    }
    comment
    creator {
      persona {
        id
        name
      }
      user {
        id
        name
      }
    }
    distributeSeconds
    expireSeconds
    id
    lastAction {
      comment 
      id 
      name 
      results {
        completed 
        downloading 
        expired 
        failed
      } 
      startTime 
    }    
    name
    package {
      id
      name
      params 
      sensorSourcedParams {
        name
        value
      }
    }
    startTime
    status
  }
}

Include the count and time variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 12345
}

Example response:

Copy
{
  "data": {
    "scheduledAction": {
      "approver": {
        "persona": null,
        "user": {
          "id": "1",
          "name": "Admin"
        }
      },
      "comment": "Example scheduled action",
      "creator": {
        "persona": null,
        "user": {
          "id": "1",
          "name": "Admin"
        }
      },
      "distributeSeconds": 60,
      "expireSeconds": 1200,
      "id": "12345",
      "lastAction": {
        "comment": "",
        "id": "56789",
        "name": "Example scheduled action",
        "results": {
           "completed": 18,
          "downloading": 0,
          "expired": 0,
          "failed": 0
        },
        "startTime": "2022-07-29T04:34:35Z"
      },      
      "name": "Example scheduled action",
      "package": {
        "id": "23456",
        "name": "Example package",
        "params": null,
        "sensorSourcedParams": [
          {
            "name": "Example parameter",
            "value": "example_value"
          }
        ]
      },
      "startTime": "2022-07-17T14:05:35Z",
      "status": "ENABLED"
    }
  }
}

ClosedGet scheduled actions (query.scheduledActions)

Get multiple scheduled actions

The following query retrieves the first 2 scheduled actions.

Copy
query getScheduledActions ($first: Int) {
  scheduledActions (first: $first) {
    edges {
      node {
        approved 
        approver {
          user {
            name
          }
        }
        comment 
        creator {
          user {
            name 
          }
        }  
        distributeSeconds 
        endTime 
        expireSeconds 
        id 
        issueCount 
        issueSeconds 
        lastAction {
          id
        } 
        lastStartTime
        name 
        nextStartTime 
        package {
          id
          name 
          params 
          sensorSourcedParams {
            name 
            value 
          }
        }  
        startTime 
        status 
        targets {
          actionGroup {
            id 
            name 
          }
          targetGroup {
            id 
            name 
          }
        }
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "scheduledActions": {
      "edges": [
        {
          "node": {
            "approved": true,
            "approver": {
              "user": {
                "name": "Admin"
              }
            },
            "comment": "Example scheduled action",
            "creator": {
              "user": {
                "name": "Admin"
              }
            },
            "distributeSeconds": 1800,
            "endTime": null,
            "expireSeconds": 1800,
            "id": "12345",
            "issueCount": 358,
            "issueSeconds": 3600,
            "lastAction": {
              "id": "23456"
            },
            "lastStartTime": "2022-08-10T14:26:25Z",
            "name": "Example scheduled action",
            "nextStartTime": "2022-08-10T15:26:25Z",
            "package": {
              "id": "34567",
              "name": "Example package",
              "params": [
                "1"
              ],
              "sensorSourcedParams": null
            },
            "startTime": "2022-07-26T17:26:25Z",
            "status": "ENABLED",
            "targets": {
              "actionGroup": {
                "id": "45678",
                "name": "Example action group"
              },
              "targetGroup": {
                "id": "56789",
                "name": "Example target group"
              }
            }
          }
        },
        {
          "node": {
            "approved": true,
            "approver": {
              "user": {
                "name": "Admin"
              }
            },
            "comment": "Example scheduled action 2",
            "creator": {
              "user": {
                "name": "Admin"
              }
            },
            "distributeSeconds": 1800,
            "endTime": null,
            "expireSeconds": 2100,
            "id": "98765",
            "issueCount": 191,
            "issueSeconds": 5400,
            "lastAction": {
              "id": "87654"
            },
            "lastStartTime": "2022-08-10T14:27:15Z",
            "name": "Example scheduled action 2",
            "nextStartTime": "2022-08-10T15:57:15Z",
            "package": {
              "id": "76543",
              "name": "Example package 2",
              "params": null,
              "sensorSourcedParams": null
            },
            "startTime": "2022-07-29T18:57:15Z",
            "status": "ENABLED",
            "targets": {
              "actionGroup": {
                "id": "65432",
                "name": "Example action group 2"
              },
              "targetGroup": {
                "id": "54321",
                "name": "Example target group 2"
              }
            }
          }
        }
      ]
    }
  }
}

Get scheduled actions (filter by name)

The following query retrieves the scheduled action with a name matching Example scheduled action.

Copy
query getScheduledActions($path: String, $op: FieldFilterOp!, $value: String) {
  scheduledActions(filter: {path: $path, op: $op, value: $value}) {
    edges {
      node {
        approved
        approver {
          user {
            name
          }
        }
        comment
        creator {
          user {
            name
          }
        }
        distributeSeconds
        endTime
        expireSeconds
        id
        issueCount
        issueSeconds
        lastAction {
          id
        }
        lastStartTime
        name
        nextStartTime
        package {
          id
          name
          params
          sensorSourcedParams {
            name
            value
          }
        }
        startTime
        status
        targets {
          actionGroup {
            id
            name
          }
          targetGroup {
            id
            name
          }
        }
      }
    }
  }
}

Include the filter variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "path" : "name",
  "op" : EQ,
  "value" : "Example scheduled action"
}

Example response:

Copy
{
  "data": {
    "scheduledActions": {
      "edges": [
        {
          "node": {
            "approved": true,
            "approver": {
              "user": {
                "name": "Admin"
              }
            },
            "comment": "Example scheduled action",
            "creator": {
              "user": {
                "name": "Admin"
              }
            },
            "distributeSeconds": 1800,
            "endTime": null,
            "expireSeconds": 1800,
            "id": "12345",
            "issueCount": 358,
            "issueSeconds": 3600,
            "lastAction": {
              "id": "23456"
            },
            "lastStartTime": "2022-08-10T14:26:25Z",
            "name": "Example scheduled action",
            "nextStartTime": "2022-08-10T15:26:25Z",
            "package": {
              "id": "34567",
              "name": "Example package",
              "params": [
                "1"
              ],
              "sensorSourcedParams": null
            },
            "startTime": "2022-07-26T17:26:25Z",
            "status": "ENABLED",
            "targets": {
              "actionGroup": {
                "id": "45678",
                "name": "Example action group"
              },
              "targetGroup": {
                "id": "56789",
                "name": "Example target group"
              }
            }
          }
        }
      ]
    }
  }
}

ClosedPerform an action operation (mutation.actionPerform)

Perform action operation

The actionPerform field allows one of the following enumerated action operations:

  • addTags - add tags to targeted endpoints
  • changeClientSetting - update one of the following settings on targeted endpoints:
    • HotCachePercentage - the hot cache to cold cache setting percentage
    • LogVerbosityLevel - the logging level
    • RandomSensorDelayInSeconds - the sensor execution randomization value
    • StateProtectedFlag - whether queries are encrypted and protected in certain states
  • collectActiveDirectoryInfo - collect AD information needed for sensors
  • reboot - reboot targeted endpoints
  • removeTags - remove tags from targeted endpoints
  • restartService - restart a service on targeted endpoints
  • startService - start a service on targeted endpoints
  • stopService - stop a service on targeted endpoints

You can configure only one action operation per mutation request, but can target any number of endpoints per request.

The following example adds tags to endpoints running Solaris operating systems.

Copy
mutation performActionOperation($comment: String, $name: String, $addTags: String!, $endTime: Time, $expireSeconds: Int, $distributeSeconds: Int, $reissueSeconds: Int, $platform: EndpointPlatform!) {
  actionPerform(
    input: {comment: $comment, name: $name, operation: {addTags: [$addTags]}, schedule: {endTime: $endTime, expireSeconds: $expireSeconds, distributeSeconds: $distributeSeconds, reissueSeconds: $reissueSeconds}, targets: {platforms: [$platform]}}
  ) {
    scheduledActions {
      platforms
      scheduledAction {
        id
      }
    }
    error {
      message
      retryable
      timedOut
    }
  }
}

Include the action operation variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "comment": "Example action perform",
  "name": "Example action perform",
  "addTags": "example-tag",
  "endTime": "2022-08-01T14:59:35+00:00",
  "expireSeconds": 660,
  "distributeSeconds": 10,
  "reissueSeconds": 700,
  "platform": "Solaris"
}

Example response:

Copy
{
  "data": {
    "actionPerform": {
      "scheduledActions": [
        {
          "platforms": [
            "Solaris"
          ],
          "scheduledAction": {
            "id": "12345"
          }
        }
      ],
      "error": null
    }
  }
}

ClosedStop an action (mutation.actionStop)

Stop action

The following mutation stops an action that matches the ID.

Copy
mutation stopAction($id: ID!) {
  actionStop(ref: { id: $id }) {
    id
    error {
      message
    }
  }
}

Include the action ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 12345
}

Example response:

Copy
{
  "data": {
    "actionStop": {
      "id": "12345",
      "error": null
    }
  }
}

ClosedDEPRECATED - Create action (subset of endpoints) (mutation.createAction)

Deploy a package

This is deprecated in favor of mutation.createAction. For more information, see the example syntax.

The following mutation deploys an action to increase the verbosity of log levels on Debian endpoints.

Copy
mutation createActionLogging($description: String, $group: String, $platform: EndpointPlatform!, $setting: SettingName!, $settingValue: Any!) {
  createAction(
    action: {description: $description, target: {targetGroup: $group, platforms: [$platform]}, changeClientSetting: {name: $setting, value: $settingValue}}
  ) {
    id
  }
}

Include the action-related variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "description": "Increasing log verbosity level on all debian endpoints for troubleshooting",
  "group": "All Debian",
  "platform": "Linux",
  "setting": "LOG_VERBOSITY_LEVEL",
  "settingValue": "41"
}

Example response:

Copy
{
  "data": {
    "createAction": {
      "id": "82"
    }
  }
}

ClosedDEPRECATED - Get action details (query.lastActionDetails, query.lastActionResults)

Get action details

This is deprecated in favor of query.scheduledAction. For more information, see the example syntax.

The following parameterized query retrieves details and any results for an action.

Copy
query getActionDetails($id: ID!) {
  lastActionDetails(id: $id) {
    id
    name
    comment
    expireSeconds
    creationTime
    startTime
    expirationTime
    distributeSeconds
    status
    stoppedFlag
  }
  lastActionResults(id: $id) {
    id
    waiting
    downloading
    running
    waitingToRetry
    completed
    expired
    failed
    pendingVerification
    verified
    failedVerification
  }
}

Include the endpoint ID in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 12323
}

Example response:

Copy
{
  "data": {
    "lastActionDetails": {
      "id": "219",
      "name": "Distribute Tanium Standard Utilities",
      "comment": "Distribute Tanium Standard Utilities",
      "expireSeconds": 3900,
      "creationTime": "2022-03-14T18:05:41Z",
      "startTime": "2022-03-14T18:05:35Z",
      "expirationTime": "2022-03-14T19:10:35Z",
      "distributeSeconds": 3600,
      "status": "OPEN",
      "stoppedFlag": false
    },
    "lastActionResults": {
      "id": "219",
      "waiting": 0,
      "downloading": 0,
      "running": 0,
      "waitingToRetry": 0,
      "completed": 1,
      "expired": 0,
      "failed": 0,
      "pendingVerification": 0,
      "verified": 0,
      "failedVerification": 0
    }
  }
}

Action group examples

The following queries and mutations create, retrieve, and delete action groups.

ClosedCreate action group (mutation.actionGroupCreate)

Create an action group

The following mutation creates an action group that targets the defined computer group. All user groups can view this action group, and endpoints must be a member of the defined computer group to be targeted by the action group.

Copy
mutation createActionGroup($any: Boolean!, $computerGroupName: String, $actionGroupName: String!, $visibility: ActionGroupVisibility!) {
  actionGroupCreate(
    input: {any: $any, computerGroups: [{name: $computerGroupName}], name: $actionGroupName, visibility: $visibility}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the targeting, targeted computer group, action group name, and visibility variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
    "any": false,
    "computerGroupName": "Example computer group",
    "actionGroupName": "Example action group",
    "visibility": "ALL"
}

Example response:

Copy
{
  "data": {
    "actionCreate": {
      "action": {
        "id": "12345"
      },
      "error": null
    }
  }
}

ClosedDelete action group by ID or name (mutation.actionGroupDelete)

Delete action group by ID

The following mutation deletes the action group that matches the ID.

Copy
mutation deleteActionGroup($id: ID) {
  actionGroupDelete(ref: {id: $id}) {
    error {
      message
    }
    id
  }
}

Include the action group ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
    "id": 12345
}

Example response:

Copy
{
  "data": {
    "actionGroupDelete": {
      "error": null,
      "id": "12345"
    }
  }
}

Delete action group by name

You can also delete an action group that matches a name.

Copy
mutation deleteActionGroup($name: String) {
  actionGroupDelete(ref: {name: $name}) {
    error {
      message
    }
    id
  }
}

Include the action group name variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
    "name": "Example action group"
}

ClosedGet action group by ID or name (query.actionGroup)

Get action group by ID

The following query retrieves an action group that matches the ID.

Copy
query getActionGroupByID($id: ID!) {
  actionGroup(ref: {id: $id}) {
    any
    computerGroups {
      id
      name
      contentSet {
        id
        name
      }
      expression
      filterEnabled
      managementRightsEnabled
    }
    id
    name
    userGroups {
      id
      name
    }
    visibility
  }
}

Include the action group ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
    "id": 12345
}

Example response:

Copy
{
  "data": {
    "actionGroup": {
      "any": false,
      "computerGroups": [
        {
          "id": "23456",
          "name": "Example computer group",
          "contentSet": {
            "id": "1",
            "name": "Reserved"
          },
          "expression": " any Computer Name not matches .*",
          "filterEnabled": true,
          "managementRightsEnabled": true
        }
      ],
      "id": "12345",
      "name": "Example action group",
      "userGroups": null,
      "visibility": "ALL"
    }
  }
}

Get action group by name

You can also retrieve an action group that matches a name.

Copy
query getActionGroupByName($name: String!) {
    actionGroup(ref: { name: $name }) {
        any
        computerGroups {
            id
            name
            contentSet {
                id
                name
            }
            expression
            filterEnabled
            managementRightsEnabled
        }
        id
        name
        userGroups {
            id
            name
        }
        visibility
    }
}

Include the action group name variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "name" : "Example action group"
}

ClosedGet multiple action groups (query.actionGroups)

Get action groups

The following query retrieves the first 2 action groups. For more information on pagination, see Pagination.

Copy
query getActionGroups($first: Int) {
  actionGroups(first: $first) {
    edges {
      node {
        id
        name
        visibility
        userGroups {
          id
          name
        }
        computerGroups {
          id
          name
          type
          contentSet {
            id
          }
          expression
          filterEnabled
          managementRightsEnabled
        }
        any
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "actionGroups": {
      "edges": [
        {
          "node": {
            "id": "1",
            "name": "Example action group",
            "visibility": "ALL",
            "userGroups": null,
            "computerGroups": [
              {
                "id": "1",
                "name": "Example computer group",
                "type": "STANDARD",
                "contentSet": {
                  "id": "1"
                },
                "expression": "All Computers",
                "filterEnabled": true,
                "managementRightsEnabled": true
              }
            ],
            "any": true
          }
        },
        {
          "node": {
            "id": "2",
            "name": "Example action group 2",
            "visibility": "ALL",
            "userGroups": null,
            "computerGroups": [
              {
                "id": "2",
                "name": "No Computers",
                "type": "STANDARD",
                "contentSet": {
                  "id": "1"
                },
                "expression": "No Computers",
                "filterEnabled": true,
                "managementRightsEnabled": true
              }
            ],
            "any": true
          }
        }
      ]
    }
  }
}

API token examples

The following mutations create, rotate, and delete API tokens.

ClosedCreate API token (mutation.apiTokenGrant)

Create API token

The following mutation creates an API token associated with the IP addresses and persona, valid for 365 days. This requires the Token - Use permission.

Include the apiTokenGrant.token.tokenString field in your request, then copy the token string in the response. You cannot view the token string in the response after you navigate to another page or send another request and receive a different response from the gateway service.

Copy
mutation createAPIToken($trustedIPAddress1: String!, $trustedIPAddress2: String!, $personaName: String!, $expiresInDays: Int!, $notes: String!) {
  apiTokenGrant(
    input: {trustedIPAddresses: [$trustedIPAddress1, $trustedIPAddress2], personaName: $personaName, expiresInDays: $expiresInDays, notes: $notes}
  ) {
    token {
      created
      expiration
      id
      lastUsed
      notes
      persona {
        name
      }
      tokenString
      trustedIPAddresses
    }
    error {
      message
      retryable
      timedOut
    }
  }
}

Include the variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "trustedIPAddress1": "192.0.2.0/24",
  "trustedIPAddress2": "198.51.100.10",
  "expiresInDays": 365,
  "personaName": "testPersona",
  "notes": "API Gateway token"
}

Example response:

Copy
{
  "data": {
    "apiTokenGrant": {
      "token": {
        "created": "2022-05-10T15:22:13Z",
        "expiration": "2023-05-10T15:22:13Z",
        "id": "4029",
        "lastUsed": "2022-05-10T15:22:13Z",
        "notes": "API Gateway token",
        "persona": {
          "name": "testPersona"
        },
        "tokenString": "token-9ab934979aea20a3d56a822441a4329f470326f5e7ef2af66783147533",
        "trustedIPAddresses": [
          "192.0.2.0/24",
          "198.51.100.10"
        ]
      },
      "error": null
    }
  }
}

ClosedGet API tokens for current user (query.myAPITokens)

Get API tokens

The following query retrieves API tokens associated with the active session user. This requires the Token - Use permission.

You cannot view API token strings in the response.

Copy
query getMyAPITokens {
  myAPITokens {
    tokens {
      created
      expiration
      id
      lastUsed
      notes
      persona {
        name
      }
      trustedIPAddresses
    }
    error {
      message
      retryable
      timedOut
    }
  }
}

Example response:

Copy
{
  "data": {
    "myAPITokens": {
      "tokens": [
        {
          "created": "2022-05-10T17:10:23Z",
          "expiration": "2023-05-10T17:10:23Z",
          "id": "4036",
          "lastUsed": "2022-05-10T17:10:23Z",
          "notes": "API Gateway token",
          "persona": null,
          "trustedIPAddresses": [
            "192.0.2.0/24",
            "198.51.100.10"
          ]
        }
      ],
      "error": null
    }
  }
}

ClosedRotate API token (mutation.apiTokenRotate)

Rotate API token

The following mutation rotates an existing API token, deleting it and creating a new one with the same properties. This requires the Token - Use permission.

Include the apiTokenRotate.token.tokenString field in your request, then copy the token string in the response. You cannot view the token string in the response after you navigate to another page or send another request and receive a different response from the gateway service.

Copy
mutation RotateAPIToken($tokenString: String!) {
  apiTokenRotate(input: {tokenString: $tokenString}) {
    token {
      created
      expiration
      id
      lastUsed
      notes
      persona {
        name
      }
      tokenString
      trustedIPAddresses
    }
    error {
      message
      retryable
      timedOut
    }
  }
}

Include the token string variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "tokenString": "token-9668a9a11e082ea9b062f204f4e9b98e8785d006388e99e00fb6efbaaa"
}

Example response:

Copy
{
  "data": {
    "apiTokenRotate": {
      "token": {
        "created": "2022-05-10T17:14:05Z",
        "expiration": "2023-05-10T17:14:05Z",
        "id": "4038",
        "lastUsed": "2022-05-10T17:14:05Z",
        "notes": "API Gateway token",
        "persona": "testPersona",
        "tokenString": "token-9a4b38683e26bd6fa19c085b11850e3f5aec96cd89e4a0e6a0b8fdb2c6",
        "trustedIPAddresses": [
          "192.0.2.0/24",
          "198.51.100.10"
        ]
      },
      "error": null
    }
  }
}

ClosedDelete API token (mutation.apiTokenRevoke)

Delete API token

The following mutation deletes an existing API token. This requires the Token - Revoke permission.

Copy
mutation deleteAPIToken($id: ID!) {
  apiTokenRevoke(input: {id: $id}) {
    error {
      message
      retryable
      timedOut
    }
  }
}

Include the token ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 10
}

Example response:

Copy
{
  "data": {
    "apiTokenRevoke": {
      "error": null
    }
  }
}

Asset examples

The following mutation requires Asset and imports assets; the import either updates existing assets or creates new assets.

ClosedImport assets (mutation.assetsImport)

Import assets

Before you submit this mutation request, you must configure an Asset custom source. For more information and an example workflow, see Tanium Asset User Guide: Create an Import API source.

The assetsImport mutation imports assets defined in the request json variable value, using the defined sourceName custom source. To determine whether an existing asset updates, or a new asset is created:

  1. If an imported asset key matches an existing asset key imported using the sourceName custom source, that existing asset updates.

  2. If no existing asset from the configured source matches, but values in the imported asset match an existing asset key imported using a source different from the sourceName custom source, and the other source allows the sourceName custom source to update, the existing asset from the other source updates.

  3. Otherwise, if no existing asset matches the imported asset, the asset is imported as a new asset using the sourceName custom source.

If the request is structurally and syntactically valid, each asset object imports separately. A failed asset import does not prevent other valid asset objects in that request from importing.

Define the json attribute as a JSON object array, with each object corresponding to an asset. Ensure that the Asset custom source passes the JSON object array according to the following guidelines:

  • Use the backslash escape character with each quotation mark (\") in the JSON array.
  • You must define key field values for each object. If you do not define the key field values, the object does not import and the response returns ErrorMissingKey status for that object.
  • You can define source field mappings to destination fields for each object. If you do not define a source field mapping, values from those source fields are imported as null values for that object.
  • Field values are defined per object; you cannot globally define a single field value in the request to apply to every imported asset object.
  • You can define up to 5000 asset objects per array, and by extension, per request.

The following example Asset custom source, named test-name, defines two field mappings for computer_name and serial_number and defines computer_name as a key field.

Copy
{
  "keys": [
    "computer_name"
  ],
  "fieldMaps": [
    {
      "destination": "computer_name",
      "source": "computerName"
    },
    {
      "destination": "serial_number",
      "source": "serialNumber"
    }
  ]
}

The following mutation request imports assets based on the variables definition:

Copy
mutation importAssets($source: String!, $json: String!) {
  assetsImport(input: {sourceName: $source, json: $json}) {
    assets {
      id
      index
      status
    }
  }
}

Include the variables in the QUERY VARIABLES panel or in your variables dictionary.

The following variables manually define the test-name source for importing and two asset objects in the JSON object array. Each object has a value for the key field (computerName) and for the serialNumber field mapping.

Copy
{
  "source": "test-name",
  "json": "[{\"computerName\": \"computer123\", \"serialNumber\": \"testSerial123\"}, {\"computerName\": \"computer234\", \"serialNumber\": \"testSerial234\"}]"
}

As the request is evaluated, each asset object defines a value for the computerName key field, matching the key field defined for the test-name custom source, and both are imported using that source. The example response shows both objects with a status of Created:

Copy
{
  "data": {
    "assetsImport": {
      "assets": [
        {
          "id": 6, 
          "index": 0,
          "status": "Created"
        },
        {
          "id": 7, 
          "index": 1,
          "status": "Created"
        }
      ]
    }
  }
}

To verify the import, create a report based on the custom source definition, and filter the report to search for imported assets. For example, creating a report with Computer Name and Serial Number as columns, then filtering Computer Name for values containing computer and 23 returns the imported assets.

Example Asset import report

For more information, see Tanium Asset User Guide: Create a report.

Benchmark examples

The following queries retrieve endpoints and use Benchmark to also retrieve related risk overview or risk vector information.

Certain risk vector queries require additional Tanium solutions. For more information, see Tanium Benchmark User Guide - Solution dependencies.

ClosedGet endpoints with Benchmark overview information (query.endpoints.edges.node.risk)

Get endpoint Benchmark overview information

The following query retrieves the first endpoint and associated Benchmark overview information.

Copy
query endpointBenchmarkOverview($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        risk {
          totalScore
          riskLevel
          assetCriticality
          criticalityScore
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-endpoint",
            "ipAddress": "198.51.100.10",
            "risk": {
              "totalScore": 208.06799999999998,
              "riskLevel": "Low",
              "assetCriticality": "Low",
              "criticalityScore": 1
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

ClosedGet endpoints with Administrative Access risk vector information (query.endpoints.edges.node.risk.vectors.administrativeAccess)

Get endpoint Administrative Access risk vector information

The following query retrieves the first endpoint and associated Administrative Access risk vector information.

This query also requires Impact.

Copy
query endpointBenchmarkAdminAccess($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        risk {
          totalScore
          vectors {
            administrativeAccess {
              direct
              impactRating
              impactRatingScore
              inbound
              indirect
              outbound
              score
              sessions
            }
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-admin",
            "ipAddress": "192.0.2.10",
            "risk": {
              "totalScore": 208.06799999999998,
              "vectors": {
                "administrativeAccess": {
                  "direct": 0,
                  "impactRating": "Low",
                  "impactRatingScore": 4,
                  "inbound": 0,
                  "indirect": 0,
                  "outbound": 1,
                  "score": 0,
                  "sessions": 1
                }
              }
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

ClosedGet endpoints with Expired Certificates risk vector information (query.endpoints.edges.node.risk.vectors.expiredCertificates)

Get endpoint Expired Certificates risk vector information

The following query retrieves the first endpoint and associated Expired Certificates risk vector information.

Copy
query endpointBenchmarkExpiredCerts($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        risk {
          totalScore
          vectors {
            expiredCertificates {
              certificatesCount
              ports
              score
            }
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "endpoint-expired",
            "ipAddress": "192.0.2.20",
            "risk": {
              "totalScore": 208.06799999999998,
              "vectors": {
                 "expiredCertificates": {
                   "certificatesCount": 1,
                   "ports": "443",
                   "score": 420
                 }
              }
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

ClosedGet endpoints with Insecure SSL/TLS risk vector information (query.endpoints.edges.node.risk.vectors.insecureTLS)

Get endpoint Insecure SSL/TLS risk vector information

The following query retrieves the first endpoint and associated Insecure SSL/TLS risk vector information.

Copy
query endpointBenchmarkInsecureTLS($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        risk {
          totalScore
          vectors {
            insecureTLS {
              ports
              protocols
              score
            }
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "endpoint-insecure",
            "ipAddress": "192.0.2.30",
            "risk": {
              "totalScore": 208.06799999999998,
              "vectors": {
                 "insecureTLS": {
                   "ports": "3389",
                   "protocols": "TLS 1.0, TLS 1.1",
                   "score": 440
                 }
              }
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

ClosedGet endpoints with Password Identification risk vector information (query.endpoints.edges.node.risk.vectors.passwordIdentification)

Get endpoint Password Identification risk vector information

The following query retrieves the first endpoint and associated Password Identification risk vector information.

This query also requires Reveal.

Copy
query endpointBenchmarkPWIdent($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        risk {
          totalScore
          vectors {
            passwordIdentification {
              filesConfirmed
              score
            }
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "endpoint-pw",
            "ipAddress": "192.0.2.40",
            "risk": {
              "totalScore": 208.06799999999998,
              "vectors": {
                "passwordIdentification": {
                  "filesConfirmed": "6",
                  "score": 830
                }
              }
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

ClosedGet endpoints with System Compliance risk vector information (query.endpoints.edges.node.risk.vectors.compliance)

Get endpoint System Compliance risk vector information

The following query retrieves the first endpoint and associated System Compliance risk vector information.

This query also requires Comply.

Copy
query endpointBenchmarkCompliance($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        risk {
          totalScore
          vectors {
            compliance {
              complianceFailCount
              score
            }
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "endpoint-compliance",
            "ipAddress": "192.0.2.50",
            "risk": {
              "totalScore": 208.06799999999998,
              "vectors": {
                "compliance": {
                  "complianceFailCount": 669,
                  "score": 333.06
                }
              }
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

ClosedGet endpoints with System Vulnerability risk vector information (query.endpoints.edges.node.risk.vectors.systemVulnerability)

Get endpoint System Vulnerability risk vector information

The following query retrieves the first endpoint and associated System Vulnerability risk vector information.

This query also requires Comply.

Copy
query endpointBenchmarkVulnerability($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        risk {
          totalScore
          vectors {
            systemVulnerability {
              cveCount
              score
            }
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "endpoint-vuln",
            "ipAddress": "192.0.2.60",
            "risk": {
              "totalScore": 208.06799999999998,
              "vectors": {
                "systemVulnerability": {
                  "cveCount": 14,
                  "score": 353.64
                }
              }
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

Comply examples

The following queries retrieves endpoints and use Comply to also retrieve associated compliance findings or vulnerability findings.

Comply requests have the following feature-specific dependencies at the specified minimum versions:

  • Comply 2.10.940 or later is required to submit a request involving the System Vulnerability and System Compliance risk vectors.

  • Comply 2.16.97 or later is required to submit a request that filters specific System Vulnerability and System Compliance risk vector fields.

ClosedGet endpoints with compliance findings information (query.endpoints.edges.node.compliance.complianceFindings)

Get endpoint compliance findings information

The following query requires Comply 2.10.940 or later and retrieves the first endpoint and associated compliance findings.

Copy
query endpointComplianceFindings($first: Int!) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        compliance {
          complianceFindings {
            category
            id
            profile
            profileVersion
            rule
            ruleId
            standard
            standardVersion
            state
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "comply-findings",
            "ipAddress": "192.0.2.10",
            "compliance": {
              "complianceFindings": [
                {
                  "category": "Fail",
                  "id": "CIS Microsoft Windows 10 Enterprise Release 20H2 Benchmark;1.10.1;MB Custom Win10;xccdf_com.tanium.comply_tailoring_1639024882628;xccdf_org.cisecurity.benchmarks_rule_18.9.4.1_L2_Ensure_Allow_a_Windows_app_to_share_application_data_between_users_is_set_to_Disabled",
                  "profile": "MB Custom Win10",
                  "profileVersion": "xccdf_com.tanium.comply_tailoring_1639024882628",
                  "rule": "(L2) Ensure 'Allow a Windows app to share application data between users' is set to 'Disabled'",
                  "ruleId": "xccdf_org.cisecurity.benchmarks_rule_18.9.4.1_L2_Ensure_Allow_a_Windows_app_to_share_application_data_between_users_is_set_to_Disabled",
                  "standard": "CIS Microsoft Windows 10 Enterprise Release 20H2 Benchmark",
                  "standardVersion": "1.10.1",
                  "state": "fail"
                }
              ]
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

Get filtered endpoint compliance findings information

The following query requires Comply 2.16.97 or later and retrieves the first endpoint with a compliance finding category of Error and returns that endpoint's associated compliance findings with a category of Error.

Copy
query filterComplianceFindings ($first: Int) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        compliance {
          complianceFindings (filter: {
            path: "category"
            value: "Error"
          }) {
            category
            id
            profile
            profileVersion
            rule
            ruleId
            standard
            standardVersion
            state
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host",
            "ipAddress": "192.0.2.10",
            "compliance": {
              "complianceFindings": [
                {
                  "category": "Error",
                  "id": "CIS Microsoft IIS 10 Benchmark;1.1.1;Level 1 - IIS 10;1;xccdf_org.cisecurity.benchmarks_rule_4.8_L1_Ensure_Handler_is_not_granted_Write_and_ScriptExecute",
                  "profile": "Level 1 - IIS 10",
                  "profileVersion": "1",
                  "rule": "(L1) Ensure Handler is not granted Write and Script/Execute",
                  "ruleId": "xccdf_org.cisecurity.benchmarks_rule_4.8_L1_Ensure_Handler_is_not_granted_Write_and_ScriptExecute",
                  "standard": "CIS Microsoft IIS 10 Benchmark",
                  "standardVersion": "1.1.1",
                  "state": "error"
                },
                {
                  "category": "Error",
                  "id": "CIS Microsoft IIS 10 Benchmark;1.1.1;Level 1 - IIS 10;1;xccdf_org.cisecurity.benchmarks_rule_1.6_L1_Ensure_application_pool_identity_is_configured_for_anonymous_user_identity",
                  "profile": "Level 1 - IIS 10",
                  "profileVersion": "1",
                  "rule": "(L1) Ensure 'application pool identity' is configured for anonymous user identity",
                  "ruleId": "xccdf_org.cisecurity.benchmarks_rule_1.6_L1_Ensure_application_pool_identity_is_configured_for_anonymous_user_identity",
                  "standard": "CIS Microsoft IIS 10 Benchmark",
                  "standardVersion": "1.1.1",
                  "state": "error"
                }
              ]
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NjEwMzg2Nzow",
        "endCursor": "NjEwMzg2Nzow",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

Get filtered endpoint compliance findings information from filtered set of endpoints

The following query requires Comply 2.16.97 or later and retrieves the first endpoint that is a member of the All Windows computer group, with a compliance finding category of Error and standardVersion value of 1.1.1, and returns that endpoint's associated compliance findings with a category of Error and standardVersion value of 1.1.1.

Copy
query filterWindowsComplianceFindings($first: Int!) {
  endpoints(first: $first, filter: {memberOf: {name: "All Windows"}}) {
    edges {
      node {
        name
        ipAddress
        compliance {
          complianceFindings(
            filter: {any: false, filters: [{path: "category", value: "Error"}, {path: "standardVersion", value: "1.1.1"}]}
          ) {
            category
            id
            profile
            profileVersion
            rule
            ruleId
            standard
            standardVersion
            state
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host-2",
            "ipAddress": "192.0.2.20",
            "compliance": {
              "complianceFindings": [
                {
                  "category": "Error",
                  "id": "CIS Microsoft IIS 10 Benchmark;1.1.1;Level 1 - IIS 10;1;xccdf_org.cisecurity.benchmarks_rule_4.6_L1_Ensure_HTTP_Trace_Method_is_disabled",
                  "profile": "Level 1 - IIS 10",
                  "profileVersion": "1",
                  "rule": "(L1) Ensure 'HTTP Trace Method' is disabled",
                  "ruleId": "xccdf_org.cisecurity.benchmarks_rule_4.6_L1_Ensure_HTTP_Trace_Method_is_disabled",
                  "standard": "CIS Microsoft IIS 10 Benchmark",
                  "standardVersion": "1.1.1",
                  "state": "error"
                },
                {
                  "category": "Error",
                  "id": "CIS Microsoft IIS 10 Benchmark;1.1.1;Level 1 - IIS 10;1;xccdf_org.cisecurity.benchmarks_rule_3.4_L1_Ensure_IIS_HTTP_detailed_errors_are_hidden_from_displaying_remotely",
                  "profile": "Level 1 - IIS 10",
                  "profileVersion": "1",
                  "rule": "(L1) Ensure IIS HTTP detailed errors are hidden from displaying remotely",
                  "ruleId": "xccdf_org.cisecurity.benchmarks_rule_3.4_L1_Ensure_IIS_HTTP_detailed_errors_are_hidden_from_displaying_remotely",
                  "standard": "CIS Microsoft IIS 10 Benchmark",
                  "standardVersion": "1.1.1",
                  "state": "error"
                }
              ]
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NjA5ODg0MDow",
        "endCursor": "NjA5ODg0MDow",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

ClosedGet endpoints with vulnerability findings information (query.endpoints.edges.node.compliance.cveFindings)

Get endpoint vulnerability findings information (CVSS v2)

The following query requires Comply 2.10.940 or later and retrieves the first endpoint and associated vulnerability findings, including CVSS v2 score and severity.

Copy
query endpointVulnerabilityCVSSv2($first: Int!) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        compliance {
          cveFindings {
            cveId
            cveYear
            cvssScore
            firstFound
            lastFound
            severity
            summary
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "comply-vuln",
            "ipAddress": "192.0.2.20",
            "compliance": {
              "cveFindings": [
                {
                  "cveId": "CVE-2020-9698",
                  "cveYear": "2020",
                  "cvssScore": 9.3,
                  "firstFound": "2022-02-17",
                  "lastFound": "2022-05-06",
                  "severity": "High",
                  "summary": "Adobe Acrobat and Reader versions 2020.009.20074 and earlier, 2020.001.30002, 2017.011.30171 and earlier, and 2015.006.30523 and earlier have a buffer error vulnerability. Successful exploitation could lead to arbitrary code execution ."
                },
                {
                  "cveId": "CVE-2020-9699",
                  "cveYear": "2020",
                  "cvssScore": 9.3,
                  "firstFound": "2022-02-17",
                  "lastFound": "2022-05-06",
                  "severity": "High",
                  "summary": "Adobe Acrobat and Reader versions 2020.009.20074 and earlier, 2020.001.30002, 2017.011.30171 and earlier, and 2015.006.30523 and earlier have a buffer error vulnerability. Successful exploitation could lead to arbitrary code execution ."
                },
                {
                  "cveId": "CVE-2020-9700",
                  "cveYear": "2020",
                  "cvssScore": 9.3,
                  "firstFound": "2022-02-17",
                  "lastFound": "2022-05-06",
                  "severity": "High",
                  "summary": "Adobe Acrobat and Reader versions 2020.009.20074 and earlier, 2020.001.30002, 2017.011.30171 and earlier, and 2015.006.30523 and earlier have a buffer error vulnerability. Successful exploitation could lead to arbitrary code execution ."
                }
              ]
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NTc2NTM4MDow",
        "endCursor": "NTc2NTM4MDoxOQ==",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

Get endpoint vulnerability findings information (CVSS v3)

The following query requires Comply 2.10.940 or later and retrieves the first endpoint and associated vulnerability findings, including CVSS v3 score and severity.

Copy
query endpointVulnerabilityCVSSv3($first: Int!) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        compliance {
          cveFindings {
            cveId
            cveYear
            cvssScoreV3
            firstFound
            lastFound
            severityV3
            summary
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Get filtered endpoint vulnerability findings information

The following query requires Comply 2.16.97 or later and retrieves the first endpoint with a vulnerability finding cveYear of 2020 and returns that endpoint's associated vulnerability findings with a finding cveYear of 2020.

Copy
query filterEndpointVulnerability($first: Int!) {
  endpoints(first: $first) {
    edges {
      node {
        name
        ipAddress
        compliance {
          cveFindings(filter: {path: "cveYear", value: "2020"}) {
            cveId
            cveYear
            cvssScore
            firstFound
            lastFound
            severity
            summary
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host-3",
            "ipAddress": "192.0.2.30",
             "compliance": {
             "cveFindings": [
               {
                 "cveId": "CVE-2020-10754",
                 "cveYear": "2020",
                 "cvssScore": 4,
                 "firstFound": "2022-09-24",
                 "lastFound": "2022-11-30",
                 "severity": "Medium",
                 "summary": "It was found that nmcli, a command line interface to NetworkManager did not honour 802-1x.ca-path and 802-1x.phase2-ca-path settings, when creating a new profile. When a user connects to a network using this profile, the authentication does not happen and the connection is made insecurely."
                }
              ]
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NjEwNDEyMzow",
        "endCursor": "NjEwNDEyMzow",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

Get filtered endpoint vulnerability findings information from filtered set of endpoints

The following query requires Comply 2.17.167 or later and retrieves the first endpoint that is a member of the All Mac computer group, with a vulnerability finding cveYear of 2020 and cvssScore value of 5, and returns that endpoint's associated vulnerability findings with a cveYear of 2020 and cvssScore value of 5.

Copy
query filterMacOSEndpointVulnerability($first: Int!) {
  endpoints(first: $first, filter: {memberOf: {name: "All Mac"}}) {
    edges {
      node {
        name
        ipAddress
        compliance {
          cveFindings(
            filter: {any: false, filters: [{path: "cveYear", value: "2020"}, {path: "cvssScore", value: "5"}]}
          ) {
            cveId
            cveYear
            cvssScoreV3
            firstFound
            lastFound
            severityV3
            summary
          }
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 1
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host-3",
            "ipAddress": "192.0.2.30",
             "compliance": {
             "cveFindings": [
               {
                 "cveId": "CVE-2020-8037",
                 "cveYear": "2020",
                 "cvssScore": 5,
                 "firstFound": "2022-09-06",
                 "lastFound": "2022-11-30",
                 "severity": "Medium",
                 "summary": "The ppp decapsulator in tcpdump 4.9.3 can be convinced to allocate a large amount of memory."
                }
              ]
            }
          }
        }
      ],
      "pageInfo": {
        "startCursor": "NjEwNDEyMzow",
        "endCursor": "NjEwNDEyMzow",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

Computer group examples

The following queries and mutations create, retrieve, and delete computer groups.

ClosedCreate a type of computer group (mutation.computerGroupCreate)

You can create the following computer group types:

  • computer management group (computer group) - A Tanium user can view question results from, and deploy actions to, only those endpoints that belong to a computer group that is assigned to the user persona selected for the current session. You can view computer groups in the Tanium Console at Administration > Permissions > Computer Groups. To create a computer group, in your mutation request, configure managementRightsEnabled as true. For more information, see Create computer group.

  • computer filter group (filter group) - Tanium users use filter groups as filters in questions and question results. You can view filter groups in the Tanium Console at Administration > Permissions > Filter Groups. To create a filter group, in your mutation request, configure a content set reference at contentSetRef.name. For more information, see Create filter group.

You can configure a computer group to also function as a filter group. In your mutation request, configure managementRightsEnabled as true and a content set reference at contentSetRef.name. For more information, see Create computer group that also filters.

For more information on computer groups, see Tanium Console User Guide: Computer groups overview.

Create computer group

The following mutation creates a computer group, configuring managementRightsEnabled as true.

Copy
mutation createComputerGroup($name: String!, $groupName: String, $mrEnabled: Boolean!) {
  computerGroupCreate(
    input: {name: $name, filter: {memberOf: {name: $groupName}}, managementRightsEnabled: $mrEnabled}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the name, filter condition, and management rights flag variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "name": "Example computer group",
  "groupName": "No Computers",
  "mrEnabled": true
}

Example response:

Copy
{
  "data": {
    "computerGroupCreate": {
      "group": {
        "id": "12345"
      },
      "error": null
    }
  }
}

Create filter group

The following mutation creates a filter group by defining a content set (Default) to which the group belongs.

Copy
mutation createComputerGroup($name: String!, $contentSetName: String, $groupName: String, $mrEnabled: Boolean!) {
  computerGroupCreate(
    input: {name: $name, contentSetRef: {name: $contentSetName}, filter: {memberOf: {name: $groupName}}, managementRightsEnabled: $mrEnabled}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the name, content set, filter condition, and management rights flag variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
    "name": "Example computer group",
    "contentSetName": "Default",
    "groupName": "No Computers",
    "mrEnabled": false
}

Example response:

Copy
{
  "data": {
    "computerGroupCreate": {
      "group": {
        "id": "12345"
      },
      "error": null
    }
  }
}

Create computer group that also filters

The following mutation creates a computer group that can also be used as a filter group. This request configures managementRightsEnabled as true and references the Default content set.

Copy
mutation createComputerGroupFilter($name: String!, $contentSetName: String, $groupName: String, $mrEnabled: Boolean!) {
  computerGroupCreate(
    input: {name: $name, contentSetRef: {name: $contentSetName}, filter: {memberOf: {name: $groupName}}, managementRightsEnabled: $mrEnabled}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the name, filter condition, and management rights flag variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "name": "Example computer group that filters",
  "contentSetName": "Default"                    
  "groupName": "No Computers",
  "mrEnabled": true
}

Example response:

Copy
{
  "data": {
    "computerGroupCreate": {
      "group": {
        "id": "12345"
      },
      "error": null
    }
  }
}

Create computer group based on existing computer groups

The following mutation creates a computer group, defining membership based on existing computer groups. Endpoints in Windows or Mac example group belong to either the All Windows or the All Mac computer group.

If you set any in the filter to false, and the computer groups you define have mutually exclusive criteria, no endpoints are members of your created computer group because no endpoints can meet all of the mutually exclusive criteria.

Copy
mutation createComputerGroup($cgName: String!, $mrEnabled: Boolean!, $filterAny: Boolean!, $groupName1: String, $groupName2: String) {
  computerGroupCreate(
    input: {name: $cgName, managementRightsEnabled: $mrEnabled, filter: {any: $filterAny, filters: [{memberOf: {name: $groupName1}}, {memberOf: {name: $groupName2}}]}}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "cgName": "Windows or Mac example group",
  "mrEnabled": true,
  "filterAny": true,
  "groupName1": "All Windows",
  "groupName2": "All Mac"
}

Example response:

Copy
{
  "data": {
    "computerGroupCreate": {
      "group": {
        "id": "12345"
      },
      "error": null
    }
  }
}

Create computer group based on sensor

The following mutation creates a computer group, defining membership based on a sensor. All Mac example group contains endpoints that match when the Is Mac sensor returns true for that endpoint.

Copy
mutation createComputerGroup($cgName: String!, $mrEnabled: Boolean!, $sensorName: String, $sensorOp: FieldFilterOp!, $sensorValue: String) {
  computerGroupCreate(
    input: {name: $cgName, managementRightsEnabled: $mrEnabled, filter: {sensor: {name: $sensorName}, op: $sensorOp, value: $sensorValue}}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "cgName": "All Mac example group",
  "mrEnabled": true,
  "sensorName": "Is Mac",
  "sensorOp": "EQ",
  "sensorValue": "true"
}

Example response:

Copy
{
  "data": {
    "computerGroupCreate": {
      "group": {
        "id": "12345"
      },
      "error": null
    }
  }
}

Create computer group using multiple criteria

The following mutation creates a computer group using multiple filters to define membership based on existing computer groups and sensors. Based on the filter logic, the following endpoints are members of Example multiple filters computer group:

  • All virtual endpoints running Linux

  • All virtual endpoints running macOS

  • All virtual endpoints running Windows with a high memory consumption

Copy
mutation createComputerGroup($cgName: String!, $mrEnabled: Boolean!, $filterAny1: Boolean!, $sensorName1: String, $sensorColumn1: String, $sensorOp1: FieldFilterOp!, $sensorValue1: String, $filterAny2: Boolean!, $cGroup1: String, $cGroup2: String, $filterAny3: Boolean!, $cGroup3: String, $sensorName2: String, $sensorColumn2: String, $sensorOp2: FieldFilterOp!, $sensorValue2: String, $sensorNegated2: Boolean!) {
  computerGroupCreate(
    input: {name: $cgName, managementRightsEnabled: $mrEnabled, filter: {any: $filterAny1, filters: [{sensor: {name: $sensorName1, column: $sensorColumn1}, op: $sensorOp1, value: $sensorValue1}, {any: $filterAny2, filters: [{memberOf: {name: $cGroup1}}, {memberOf: {name: $cGroup2}}, {any: $filterAny3, filters: [{memberOf: {name: $cGroup3}}, {sensor: {name: $sensorName2, column: $sensorColumn2}, op: $sensorOp2, negated: $sensorNegated2, value: $sensorValue2}]}]}]}}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

Include the variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "cgName": "Example multiple filters computer group",
  "mrEnabled": true,
  "filterAny1": false,
  "sensorName1": "Is Virtual",
  "sensorColumn1": "Is Virtual",
  "sensorOp1": "EQ",
  "sensorValue1": "true",
  "filterAny2": true,
  "cGroup1": "All Linux",
  "cGroup2": "All Mac",
  "filterAny3": false,
  "cGroup3": "All Windows",
  "sensorName2": "High Memory Consumption",
  "sensorColumn2": "High Memory Consumption",
  "sensorOp2": "EQ",
  "sensorValue2": "Under Threshold",
  "sensorNegated2": true
}

Example response:

Copy
{
  "data": {
    "computerGroupCreate": {
      "group": {
        "id": "12345"
      },
      "error": null
    }
  }
}

ClosedDelete computer group by ID or name (mutation.computerGroupDelete)

Delete computer group by ID

The following mutation deletes the computer group that matches the ID.

Copy
mutation deleteComputerGroup($id: ID) {
  computerGroupDelete(ref: {id: $id}) {
    error {
      message
    }
    id
  }
}

Include the computer group ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 12345
}

Example response:

Copy
{
  "data": {
    "computerGroupDelete": {
      "error": null,
      "id": "12345"
    }
  }
}

Delete computer group by name

You can also delete a computer group that matches a name.

Copy
mutation deleteComputerGroup($name: String) {
  computerGroupDelete(ref: {name: $name}) {
    error {
      message
    }
    id
  }
}

Include the computer group name variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "name": "Example computer group"
}

ClosedGet a computer group by ID or name (query.computerGroup)

Get computer group by ID

The following query retrieves a computer group that matches an ID.

Copy
query getComputerGroupByID($id: ID) {
  computerGroup(ref: {id: $id}) {
    id
    name
    contentSet {
      id
      name
    }
    expression
    type
    filterEnabled
    managementRightsEnabled
  }
}

Include the computer group ID variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 12345
}

Example response:

Copy
{
  "data": {
    "computerGroup": {
      "id": "12345",
      "name": "Example computer group",
      "contentSet": {
        "id": "5",
        "name": "Client Management"
      },
      "expression": "No Computers",
      "type": "STANDARD",
      "filterEnabled": true,
      "managementRightsEnabled": false
    }
  }
}

Get computer group by name

You can also retrieve a computer group that matches a name.

Copy
query getComputerGroupByName($name: String!) {
  computerGroup(ref: {name: $name}) {
    id
    name
    contentSet {
      id
      name
    }
    expression
    type
    filterEnabled
    managementRightsEnabled
  }
}

Include the computer group name variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "name" : "Example computer group"
}

ClosedGet multiple computer groups, filter groups, or management rights groups (query.computerGroups)

Get computer groups

The following query retrieves the first 2 computer groups. For more information on pagination, see Pagination.

Copy
query getComputerGroups($first: Int) {
  computerGroups(first: $first) {
    edges {
      node {
        id
        name
        contentSet {
          id
          name
        }
        expression
        type
        filterEnabled
        managementRightsEnabled
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "computerGroups": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "Example computer group",
            "contentSet": {
              "id": "5",
              "name": "Client Management"
            },
            "expression": "No Computers",
            "type": "STANDARD",
            "filterEnabled": true,
            "managementRightsEnabled": false
          }
        },
        {
          "node": {
            "id": "23456",
            "name": "Example computer group 2",
            "contentSet": {
              "id": "2",
              "name": "Default"
            },
            "expression": "Computer Name contains example",
            "type": "STANDARD",
            "filterEnabled": true,
            "managementRightsEnabled": false
          }
        }
      ]
    }
  }
}

Get manual computer groups

The following query retrieves the first 2 manual computer groups, whose membership is based on a manually entered list of computer names or fully qualified domain names (FQDNs).

Copy
query getManualGroups($first: Int, $type: ComputerGroupType) {
  computerGroups(first: $first, filter: {type: $type}) {
    edges {
      node {
        id
        name
        contentSet {
          id
          name
        }
        expression
        type
        filterEnabled
        managementRightsEnabled
      }
    }
  }
}

Include the pagination and type variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2,
  "type": "MANUAL"
}

Example response:

Copy
{
  "data": {
    "computerGroups": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "Manual Group 1",
            "contentSet": {
              "id": "23456",
              "name": ""
            },
            "expression": " Manual Group Membership equals 12345",
            "type": "MANUAL",
            "filterEnabled": true,
            "managementRightsEnabled": true
          }
        },
        {
          "node": {
            "id": "34567",
            "name": "Manual Group 2",
            "contentSet": null,
            "expression": " Manual Group Membership equals 34567",
            "type": "MANUAL",
            "filterEnabled": false,
            "managementRightsEnabled": true
          }
        }
      ]
    }
  }
}

Get standard computer groups

The following query retrieves the first 2 standard computer groups, whose membership is based on the results of a sensor filter expression.

Copy
query getStandardGroups($first: Int, $type: ComputerGroupType) {
  computerGroups(first: $first, filter: {type: $type}) {
    edges {
      node {
        id
        name
        contentSet {
          id
          name
        }
        expression
        type
        filterEnabled
        managementRightsEnabled
      }
    }
  }
}

Include the pagination and type variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2,
  "type": "STANDARD"
}

Example response:

Copy
{
  "data": {
    "computerGroups": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "Standard group test",
            "contentSet": {
              "id": "2",
              "name": "Default"
            },
            "expression": " Computer Name contains test ",
            "type": "STANDARD",
            "filterEnabled": true,
            "managementRightsEnabled": true
          }
        },
        {
          "node": {
            "id": "23456",
            "name": "Domain test",
            "contentSet": {
              "id": "3",
              "name": "Default Filter Groups"
            },
            "expression": " ( Domain Name contains test.example )",
            "type": "STANDARD",
            "filterEnabled": true,
            "managementRightsEnabled": true
          }
        }
      ]
    }
  }
}

Get filter groups

The following query retrieves the first 2 filter groups.

Copy
query getFilterGroups($first: Int, $filterEnabled: Boolean) {
  computerGroups(first: $first, filter: {filterEnabled: $filterEnabled}) {
    edges {
      node {
        id
        name
        contentSet {
          id
          name
        }
        expression
        type
        filterEnabled
        managementRightsEnabled
      }
    }
  }
}

Include the pagination and filter enabled variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2,
  "filterEnabled": true
}

Example response:

Copy
{
  "data": {
    "computerGroups": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "All Windows Workstations - x64",
            "contentSet": {
              "id": "3",
              "name": "Default Filter Groups"
            },
            "expression": " ( Windows OS Type contains windows workstation and \"x64/x86?\" contains x64 )",
            "type": "STANDARD",
            "filterEnabled": true,
            "managementRightsEnabled": true
          }
        },
        {
          "node": {
            "id": "23456",
            "name": "All Windows Server 2008 R2",
            "contentSet": {
              "id": "3",
              "name": "Default Filter Groups"
            },
            "expression": " Operating System Generation equals Windows Server 2008 R2",
            "type": "STANDARD",
            "filterEnabled": true,
            "managementRightsEnabled": true
          }
        }
      ]
    }
  }
}

Get management rights groups

The following query retrieves the first 2 management rights groups.

Copy
query getMRGroups($first: Int, $mrEnabled: Boolean) {
  computerGroups(first: $first, filter: {managementRightsEnabled: $mrEnabled}) {
    edges {
      node {
        id
        name
        contentSet {
          id
          name
        }
        expression
        type
        filterEnabled
        managementRightsEnabled
      }
    }
  }
}

Include the pagination and management rights enabled variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2,
  "mrEnabled": true
}

Example response:

Copy
{
  "data": {
    "computerGroups": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "Test Filter",
            "contentSet": {
              "id": "3",
              "name": "Default Filter Groups"
            },
            "expression": " Computer Name starts with test",
            "type": "STANDARD",
            "filterEnabled": true,
            "managementRightsEnabled": true
          }
        },
        {
          "node": {
            "id": "23456",
            "name": "All Windows Workstations",
            "contentSet": {
              "id": "3",
              "name": "Default Filter Groups"
            },
            "expression": " ( Windows OS Type contains windows workstation )",
            "type": "STANDARD",
            "filterEnabled": true,
            "managementRightsEnabled": true
          }
        }
      ]
    }
  }
}

Deploy examples

The following queries and mutation require Deploy, retrieve information about software packages deployed in your environment, and allow you to deploy a software package to endpoints.

ClosedDeploy a package to all endpoints (mutation.manageSoftware)

Deploy package to endpoints

The following mutation deploys a package to All Computers.

Copy
mutation deployPackage ($group:String){
  manageSoftware(
    operation: INSTALL
    softwarePackageID: 2
    start: "2021-10-27T00:00:00Z"
    end: "2021-11-03T00:00:00Z"
    target: {targetGroup: $group}
  ) {
    ID
    name
  }
}

Include the computer group variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "group": "All Computers"
}

Example response:

Copy
{
  "data": {
    "manageSoftware": {
      "ID": "2",
      "name": "Install Tanium Standard Utilities (Linux)"
    }
  }
}

ClosedGet package details (query.packages)

Get details of all packages

The following query retrieves multiple fields for all packages.

Copy
query PackagesQuery {
  packages {
    items {
      id
      name
      displayName
      command
      commandTimeout
      expireSeconds
      contentSet {
        id
        name
      }
      processGroupFlag
      skipLockFlag
      metadata {
        adminFlag
        name
        value
      }
      sourceHash
      sourceHashChangedFlag
      sourceID
      sourceName
      parameters {
        key
        value
      }
      rawParameterDefinition
      parameterDefinition {
        parameterType
        model
        parameters {
          model
          parameterType
          key
          label
          helpString
          defaultValue
          validationExpressions {
            model
            parameterType
            expression
            helpString
          }
          promptText
          heightInLines
          maxChars
          values
          restrict
          allowEmptyList
          minimum
          maximum
          stepSize
          snapInterval
          dropdownOptions {
            model
            parameterType
            name
            value
          }
          componentType
          startDateRestriction {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          endDateRestriction {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          startTimeRestriction {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          endTimeRestriction {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          allowDisableEnd
          defaultRangeStart {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          defaultRangeEnd {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          separatorText
        }
      }
      verifyExpireSeconds
    }
  }
}

Example response:

Copy
{
  "data": {
    "packages": {
      "items": [
        {
          "id": "1",
          "name": "Distribute Tanium Standard Utilities",
          "displayName": "Distribute Tanium Standard Utilities",
          "command": "cmd.exe /c cscript.exe //E:VBScript install-standard-utils.vbs \"Tools\\StdUtils\"",
          "commandTimeout": 2700,
          "expireSeconds": 3300,
          "contentSet": {
            "id": "5",
            "name": "Client Management"
          },
          "processGroupFlag": true,
          "skipLockFlag": false,
          "metadata": [],
          "sourceHash": "60b3e906f92929da67341792db9675d5cd91686546f01b57857686c8c6d84fa8",
          "sourceHashChangedFlag": false,
          "sourceID": 0,
          "sourceName": "",
          "parameters": [],
          "rawParameterDefinition": null,
          "parameterDefinition": null,
          "verifyExpireSeconds": 600
        },
        {
          "id": "2",
          "name": "Distribute Tanium Standard Utilities (Linux)",
          "displayName": "Distribute Tanium Standard Utilities (Linux)",
          "command": "/bin/bash distribute-tools.sh STRICT",
          "commandTimeout": 120,
          "expireSeconds": 720,
          "contentSet": {
            "id": "5",
            "name": "Client Management"
          },
          "processGroupFlag": true,
          "skipLockFlag": false,
          "metadata": [],
          "sourceHash": "4ed7a30a1ca6c81be5a71b892dfadcdb489122cc641fa4b644f53255134215c9",
          "sourceHashChangedFlag": false,
          "sourceID": 0,
          "sourceName": "",
          "parameters": [],
          "rawParameterDefinition": null,
          "parameterDefinition": null,
          "verifyExpireSeconds": 600
        }
      ]
    }
  }
}

ClosedGet Deploy packages (query.softwarePackages)

Get all deploy packages

The following query retrieves all Deploy packages.

Copy
query getDeployPackages{
  softwarePackages {
    edges {
      node {
        id
        productName
        productVendor
        productVersion
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "softwarePackages": {
      "edges": [
        {
          "node": {
            "id": "19",
            "productName": "Firefox (x64 en-US)",
            "productVendor": "Mozilla",
            "productVersion": "98.0"
          }
        },
        {
          "node": {
            "id": "30",
            "productName": "Power BI Desktop (x64)",
            "productVendor": "Microsoft",
            "productVersion": "2.102.845.0"
          }
        },
        {
          "node": {
            "id": "43",
            "productName": "VLC media player (64-bit)",
            "productVendor": "VideoLAN",
            "productVersion": "3.0.16.0"
          }
        },
        {
          "node": {
            "id": "46",
            "productName": "Visual Studio Code (x64 en-us)",
            "productVendor": "Microsoft",
            "productVersion": "1.65.2"
          }
        }
      ]
    }
  }
}

ClosedGet software deployment status (query.softwareDeployment)

Get status of software deployment

The following query retrieves the deployment status of all Deploy packages.

Copy
query getSoftwareDeploymentStatus {
  softwareDeployment {
    ID
    name
    status {
      completeCount
      downloadCompleteWaitingCount
      downloadingCount
      failedCount
      notApplicableCount
      runningCount
      waitingCount
    }
    errors {
      error
      count
    }
  }
}

Example response:

Copy
{
  "data": {
    "softwareDeployment": [
      {
        "ID": "5",
        "name": "Install Tanium Standard Utilities",
        "status": {
          "completeCount": 1,
          "downloadCompleteWaitingCount": 0,
          "downloadingCount": 0,
          "failedCount": 0,
          "notApplicableCount": 0,
          "runningCount": 0,
          "waitingCount": 0
        },
        "errors": null
      },
      {
        "ID": "6",
        "name": "Install Tanium Standard Utilities (Linux)",
        "status": {
          "completeCount": 0,
          "downloadCompleteWaitingCount": 0,
          "downloadingCount": 1,
          "failedCount": 0,
          "notApplicableCount": 0,
          "runningCount": 0,
          "waitingCount": 0
        },
        "errors": null
      }
    ]
  }
}

Direct Connect examples

The following queries and mutations use Direct Connect to connect to a single endpoint, retrieve data, stop a process, and then close the connection. Queries that retrieve information from endpoints require Performance.

ClosedOpen a connection to an endpoint (mutation.openDirectConnection)

Open direct connection to endpoint

The following mutation uses Direct Connect to establish a connection to the endpoint with an ID of 12323. You can retrieve IDs through the Reference: API Gateway examples query.

Direct Connect connections close after two minutes of inactivity.

Copy
mutation openEndpointConnection ($id: ID){
  openDirectConnection(input: {endpointID: $id}) {
    connectionID
  }
}

Include the endpoint ID in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": "12323"
}

Example response:

Copy
{
  "data": {
    "openDirectConnection": {
      "connectionID": "86d9a9ac-0229-481b-9d88-5f1bcb1b177b"
    }
  }
}

ClosedPing the connection to an endpoint (mutation.pingDirectConnection)

Ping direct connection to endpoint

The following mutation retrieves the status for a Direct Connect connection. Use this mutation to check connection details or to keep the connection active. You need the connectionID that is returned by the mutation to open the connection.

Direct Connect connections close after two minutes of inactivity.

Copy
mutation ($connectionID: ID!) {
  pingDirectConnection(input: {connectionID: $connectionID}) {
    result
  }
}

Include the connection ID in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8"
}

Example response:

Copy
{
  "data": {
    "pingDirectConnection": {
      "result": true
    }
  }
}

ClosedGet data from an endpoint (query.directEndpoint.performance)

Get data from endpoint

After you establish a connection to an endpoint through Direct Connect, you can query the endpoint for specific information. The following query retrieves the CPU usage on the endpoint:

Copy
query getEndpointData ($id: ID){
  directEndpoint (input : {endpointID: $id}) {
    performance {
      cpuUsagePercent
    }
  }
}

Include the endpoint ID in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": "12323"
}

Example response:

Copy
{
  "data": {
    "directEndpoint": {
      "performance": {
        "cpuUsagePercent": 28.751501243887798
      }
    }
  }
}

ClosedGet process from an endpoint (query.directEndpoint.processes)

Get process from endpoint

After you establish a connection to an endpoint through Direct Connect, you can query the endpoint for process information. The following query retrieves the state of all processes running on the endpoint.

Copy
query getEndpointProcess ($id: ID){
  directEndpoint (input : {endpointID: $id}) {
    processes {
      all {
        pid
        ppid
        name
        commandLine
        userName
        groupName
        memoryResidentBytes
      }
    }
  }
}

Include the endpoint ID in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": "12323"
}

Example response:

Copy
{
  "data": {
    "directEndpoint": {
      "processes": {
        "all": [
          {
            "pid": 2092,
            "ppid": 496,
            "name": "TaniumReceiver.exe",
            "commandLine": "\"C:\\Program Files\\Tanium\\Tanium Server\\TaniumReceiver.exe\" --service",
            "userName": "admin",
            "groupName": "test-group",
            "memoryResidentBytes": 59842560
          },
          {
            "pid": 5760,
            "ppid": 1112,
            "name": "TaniumClient.exe",
            "commandLine": "\"C:\\Program Files (x86)\\Tanium\\Tanium Client\\TaniumClient.exe\" -c",
            "userName": "SYSTEM",
            "groupName": "NT AUTHORITY",
            "memoryResidentBytes": 17965056
          },
          {
            "pid": 1036,
            "ppid": 496,
            "name": "TaniumBlobService.exe",
            "commandLine": "\"C:\\Program Files\\Tanium\\Tanium Module Server\\services\\blob-service\\TaniumBlobService.exe\"",
            "userName": "SYSTEM",
            "groupName": "NT AUTHORITY",
            "memoryResidentBytes": 7426048
          }
        ]
      }
    }
  }
}

ClosedGet alerts from an endpoint (query.directEndpoint.alerts)

Get past 24 hours of alerts from endpoint

After you establish a connection to an endpoint through Direct Connect, you can query the endpoint for alert information. You can also define a time period for retrieving events based on the following rules:

  • The end time must be before the current time.
  • The start time must be before the end time.
  • If you define a start time without an end time, the request time period retrieves alerts from the start time to the current time.
  • If you do not define a start time or end time, the request defaults to the past 24 hours.

The following query retrieves alerts from an endpoint that occurred during the past 24 hours.

Copy
query getEndpointAlerts ($id: ID){
  directEndpoint (input : {endpointID: $id}) {
    alerts {
      all {
        schema
        key
        type
        ref
        topProcessesExpr
        labels
        pendingAt
        start
        resolvedAt
        leadup
        value 
      }
    }
  }
}

Include the endpoint ID in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": "12323"
}

Example response:

Copy
{
  "data": {
    "directEndpoint": {
      "alerts": {
        "all": [
          {
            "schema": 1,
            "key": "available-mem{heuristic=\"available-mem\"}",
            "type": "available-mem",
            "ref": null,
            "topProcessesExpr": null,
            "labels": {
              "heuristic": "available-mem"
            },
            "pendingAt": "2022-03-15T15:54:38.574990164Z",
            "start": "2022-03-15T15:54:38.574990164Z",
            "resolvedAt": null,
            "leadup": 300000000000,
            "value": 168.48828125
          }
        ]
      }
    }
  }
}

Get 48 hours of alerts from endpoint

The following query sets a time period of 48 hours from January 1, 2022 to January 3, 2022 and retrieves alerts for an endpoint from that period.

Copy
query getEndpointAlerts48Hours ($id: ID, $startTime: Time!, $endTime: Time){
  directEndpoint (input : {endpointID: $id}) {
    alerts {
      all (scope: {startTime: $startTime, endTime: $endTime}) {
        schema
        key
        type
        ref
        topProcessesExpr
        labels
        pendingAt
        start
        resolvedAt
        leadup
        value 
      }
    }
  }
}

Include the endpoint ID and time period variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 123,
  "startTime": "2022-01-01T00:00:00Z",
  "endTime": "2022-01-03T00:00:00Z"
}

Get alerts from prior date from endpoint

The following query sets a time period start date of January 1, 2022 and retrieves alerts for an endpoint from that date to the current time.

Copy
query getEndpointAlertsPriorDate ($id: ID, $startTime: Time!){
  directEndpoint (input : {endpointID: $id}) {
    alerts {
      all (scope: {startTime: $startTime}) {
        schema
        key
        type
        ref
        topProcessesExpr
        labels
        pendingAt
        start
        resolvedAt
        leadup
        value 
      }
    }
  }
}

Include the endpoint ID and start time variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "id": 123,
  "startTime": "2022-01-01T00:00:00Z"
}

ClosedStop a process on an endpoint (mutation.killProcess)

Stop endpoint process

After you establish a connection to an endpoint through Direct Connect, you can stop running processes on the endpoint. The following mutation stops a process named notepad.exe on an endpoint. You need the connectionID that is returned by the mutation to open the connection.

Copy
mutation stopEndpointProcess ($connectionID: ID, $processName: String!, $pid: Int!, $signal: Signal!){
  killProcess(
    input: {connectionID: $connectionID, name: $processName, pid: $pid, signal: $signal}
  ) {
    result
  }
}

Include the connection ID and process name variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8",
  "processName": "notepad.exe",
  "pid": 7056,
  "signal": "SIGKILL"
}

Example response:

Copy
{
  "data": {
    "killProcess": {
      "result": true
    }
  }

ClosedClose connection to an endpoint (mutation.closeDirectConnection)

Close endpoint connection

The following mutation closes a Direct Connect connection to an endpoint. You need the connectionID that is returned by the mutation to open the connection.

Direct Connect connections close after two minutes of inactivity.

Copy
mutation closeEndpointConnection($connectionID: ID!) {
  closeDirectConnection(input: {connectionID: $connectionID}) {
    result
  }
}

Include the connection ID in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8"
}

Example response:

Copy
{
  "data": {
    "closeDirectConnection": {
      "result": true
    }
  }
}

Reporting examples

The following queries and mutation require Reporting and retrieve reports or report results, export report definitions, and import report definitions.

ClosedGet a report (query.report)

Get a report by ID

The following query retrieves the report that matches the referenced ID.

Copy
query getReportByID ($id: ID!) {
  report(ref: {id: $id}) {
    id
    author {
      user {
        id
      }
      persona {
        id
      }
    }
    contentSet {
      id
    }
    createdTime
    description
    favorite
    labels
    lastModifiedBy {
      user {
        id
      }
      persona {
        id
      }
    }
    modifiedTime
    moduleName
    name
    viewDetails {
      columns {
        name
      }
    }
  }
}

Include the report ID variable in the QUERY VARIABLES panel or in your variables dictionary.

Copy
{
  "id": "12345678-90ab-cdef-1234-567890abcdef"
}

Example response:

Copy
{
  "data": {
    "report": {
      "id": "12345678-90ab-cdef-1234-567890abcdef",
      "author": {
        "user": {
          "id": "1"
        },
        "persona": {
          "id": "0"
        }
      },
      "contentSet": {
        "id": "21"
      },
      "createdTime": "2022-01-01T05:33:35.838686969Z",
      "description": "",
      "favorite": false,
      "labels": null,
      "lastModifiedBy": {
        "user": {
          "id": "1"
        },
        "persona": {
          "id": "0"
        }
      },
      "modifiedTime": "2022-06-01T05:33:35.838686969Z",
      "moduleName": null,
      "name": "Example report",
      "viewDetails": {
        "columns": [
          {
            "name": "Example report column"
          }
        ]
      }
    }
  }
}

ClosedGet multiple reports (query.reports)

Get reports

The following query retrieves the first 2 reports.

Copy
query getReports($first: Int) {
  reports(first: $first) {
    edges {
      node {
        id
        author {
          user {
            id
          }
          persona {
            id
          }
        }
        contentSet {
          id
        }
        createdTime
        description
        favorite
        labels
        lastModifiedBy {
          user {
            id
          }
          persona {
            id
          }
        }
        modifiedTime
        moduleName
        name
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary.

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "reports": {
      "edges": [
        {
          "node": {
            "id": "12345678-90ab-cdef-1234-567890abcdef",
            "author": {
              "user": {
                "id": "1"
              },
              "persona": {
                "id": "0"
              }
            },
            "contentSet": {
              "id": "21"
            },
            "createdTime": "2022-01-01T05:33:35.838686969Z",
            "description": "Example description",
            "favorite": false,
            "labels": null,
            "lastModifiedBy": {
              "user": {
                "id": "1"
              },
              "persona": {
                "id": "0"
              }
            },
            "modifiedTime": "2022-03-17T05:33:35.838686969Z",
            "moduleName": null,
            "name": "Example report"
          }
        },
        {
          "node": {
            "id": "abcdef12-3456-7890-abcd-ef1234567890",      
            "author": {
              "user": {
                "id": "2"
              },
              "persona": {
                "id": "1"
              }
            },
            "contentSet": {
              "id": "123"
            },
            "createdTime": "2022-01-01T19:58:08.175603337Z",
            "description": "Example report 2",
            "favorite": false,
            "labels": null,
            "lastModifiedBy": {
              "user": {
                "id": "3"
              },
              "persona": {
                "id": "0"
              }
            },
            "modifiedTime": "2022-06-01T19:58:08.175603337Z",
            "moduleName": null,
            "name": "Example report 2"
          }
        }
      ]
    }
  }
}

ClosedGet report result data (query.reportResultData)

Get report results by report ID

The following query retrieves column values for the first 2 report results. The query also retrieves report definition details, including report column name, sourceName, and sourceColumnName.

Copy
query getReportResultData($id: ID!, $first: Int) {
  reportResultData(id: $id, first: $first) {
    edges {
      node {
        columns {
          values
        }
      }
    }
    viewDetails {
      columns {
        name
        sourceName
        sourceColumnName
      }
    }
  }
}

Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary.

Copy
{
  "id": "12345678-90ab-cdef-1234-567890abcdef",
  "first": 2
}

Example response:

Copy
{
  "data": {
    "reportResultData": {
      "edges": [
        {
          "node": {
            "columns": [
              {
                "values": [
                  "Example computer 1"
                ]
              },
              {
                "values": [
                  "2001:DB8::1234",
                  "192.0.2.10"
                ]
              }
            ]
          }
        },
        {
          "node": {
            "columns": [
              {
                "values": [
                  "Example computer 2"
                ]
              },
              {
&#