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 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": "4267468:0",
        "endCursor": "4267468:1",
        "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]"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

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": "4277520:0",
        "endCursor": "4277520:19"
      }
    }
  }
}

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": "4277520:4",
  "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": "4277520:5",
        "endCursor": "4277520:9"
      }
    }
  }
}

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

Comply examples

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

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

Get endpoint compliance finding information

The following query 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": "2602009:0",
        "endCursor": "2602009:0",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

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

Get endpoint vulnerability finding information

The following query retrieves the first endpoint and associated vulnerability findings.

Copy
query endpointVulnerability($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": "2602137:0",
        "endCursor": "2602137:0",
        "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 alerts from endpoint

After you establish a connection to an endpoint through Direct Connect, you can query the endpoint for alert information. The following query retrieves alerts from an endpoint.

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
          }
        ]
      }
    }
  }
}

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

Risk examples

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

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

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

Get endpoint Risk overview information

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

Copy
query endpointRiskOverview($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": "2599746:0",
        "endCursor": "2599746:0",
        "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 endpointRiskAdminAccess($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": "2599820:0",
        "endCursor": "2599820:0",
        "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 endpointRiskExpiredCerts($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": "2599886:0",
        "endCursor": "2599886:0",
        "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 endpointRiskInsecureTLS($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": "2599916:0",
        "endCursor": "2599916:0",
        "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 endpointRiskPWIdent($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": "2599934:0",
        "endCursor": "2599934:0",
        "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 endpointRiskCompliance($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": "2599968:0",
        "endCursor": "2599968:0",
        "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 endpointRiskVulnerability($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": "2599986:0",
        "endCursor": "2599986:0",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

Sensor examples

The following queries and mutation retrieve sensors and sensor parameters, and register a sensor for harvest.

ClosedGet normal sensors (query.getNormalSensors)

Get normal sensor information

The following query retrieves the first 5 normal sensors managed by the Tanium ServerTanium Cloud. When querying the Tanium ServerTanium Cloud, you can use normal sensors, as opposed to using virtual sensors when querying Tanium Data Service.

Copy
query getNormalSensors ($first: Int, $path: String, $op: FieldFilterOp!, $value: String){
  sensors(first: $first, filter:{path: $path, op: $op, value: $value}) {
    edges {
      node {
        contentSetName
        description
        endpointQueryPaths
        harvested
        name
        parameterizations {
          harvested
          values {
            name
            value
          }
        }
        parameters {
          defaultValue
          name
        }
        virtual
      }
    }
    pageInfo {
      endCursor
      startCursor
      hasNextPage
      hasPreviousPage
    }
  }
}

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

Copy
{
  "first": 5,
  "path": "virtual",
  "op": "EQ",
  "value": "false"
}

Example response:

Copy
{
  "data": {
    "sensors": {
      "edges": [
        {
          "node": {
            "contentSetName": "Core Content",
            "description": "The full Active Directory distinguished name for the computer\nExample: CN=Win8-test5,CN=Computers,DC=corp,DC=com",
            "endpointQueryPaths": [],
            "harvested": false,
            "name": "AD Distinguished Name",
            "parameterizations": null,
            "parameters": null,
            "virtual": false
          }
        },
        {
          "node": {
            "contentSetName": "Core Content",
            "description": "The Active Directory domain name (if any) that the computer is joined to.\nExample: intra.company.com",
            "endpointQueryPaths": [],
            "harvested": false,
            "name": "AD Domain",
            "parameterizations": null,
            "parameters": null,
            "virtual": false
          }
        },
        {
          "node": {
            "contentSetName": "Core Content",
            "description": "Returns the name of the Active Directory Forest that a machine is a member of.  This may produce the same value that the Sensor named AD Domain produces.\nExample: corp.domain.com",
            "endpointQueryPaths": [],
            "harvested": false,
            "name": "AD Forest",
            "parameterizations": null,
            "parameters": null,
            "virtual": false
          }
        },
        {
          "node": {
            "contentSetName": "Core Content",
            "description": "The Active Directory organizational unit (OU) where the machine is located.\nExample: CN=Computers,DC=corp,DC=com",
            "endpointQueryPaths": [],
            "harvested": false,
            "name": "AD Organizational Unit",
            "parameterizations": null,
            "parameters": null,
            "virtual": false
          }
        },
        {
          "node": {
            "contentSetName": "Core Content",
            "description": "Returns the short, NetBIOS name of a machine's domain.\nExample: CORP",
            "endpointQueryPaths": [],
            "harvested": true,
            "name": "AD Short Domain",
            "parameterizations": null,
            "parameters": null,
            "virtual": false
          }
        }
      ],
      "pageInfo": {
        "endCursor": "sensors:4",
        "startCursor": "sensors:0",
        "hasNextPage": true,
        "hasPreviousPage": false
      }
    }
  }
}

ClosedGet virtual sensors (query.getVirtualSensors)

Get virtual sensor information

The following query retrieves the first 5 virtual sensors managed by Tanium Data Service. When querying Tanium Data Service, you can use virtual sensors, as opposed to using normal sensors when querying the Tanium ServerTanium Cloud.

Copy
query getVirtualSensors ($first: Int, $path: String, $op: FieldFilterOp!, $value: String){
  sensors(first: $first, filter:{path: $path, op: $op, value: $value}) {
    edges {
      node {
        contentSetName
        description
        endpointQueryPaths
        harvested
        name
        parameterizations {
          harvested
          values {
            name
            value
          }
        }
        parameters {
          defaultValue
          name
        }
        virtual
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

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

Copy
{
  "first": 5,
  "path": "virtual",
  "op": "EQ",
  "value": "true"
}

Example response:

Copy
{
  "data": {
    "sensors": {
      "edges": [
        {
          "node": {
            "contentSetName": "Tanium Data Service",
            "description": null,
            "endpointQueryPaths": [],
            "harvested": false,
            "name": "Computer Groups",
            "parameterizations": null,
            "parameters": null,
            "virtual": true
          }
        },
        {
          "node": {
            "contentSetName": "Tanium Data Service",
            "description": null,
            "endpointQueryPaths": [],
            "harvested": false,
            "name": "EID First Seen",
            "parameterizations": null,
            "parameters": null,
            "virtual": true
          }
        },
        {
          "node": {
            "contentSetName": "Tanium Data Service",
            "description": null,
            "endpointQueryPaths": [],
            "harvested": false,
            "name": "EID Last Changed",
            "parameterizations": null,
            "parameters": null,
            "virtual": true
          }
        },
        {
          "node": {
            "contentSetName": "Tanium Data Service",
            "description": null,
            "endpointQueryPaths": [],
            "harvested": false,
            "name": "EID Last Seen",
            "parameterizations": null,
            "parameters": null,
            "virtual": true
          }
        },
        {
          "node": {
            "contentSetName": "Tanium Data Service",
            "description": null,
            "endpointQueryPaths": [
              [
                "id"
              ]
            ],
            "harvested": false,
            "name": "Endpoint ID",
            "parameterizations": null,
            "parameters": null,
            "virtual": true
          }
        }
      ],
      "pageInfo": {
        "startCursor": "sensors:0",      
        "endCursor": "sensors:4",
        "hasPreviousPage": false,
        "hasNextPage": true
      }
    }
  }
}

ClosedGet sensor parameters (query.getSensorParameters)

Get a sensor's parameters

The following query retrieves sensors whose description contains the text custom tag, and returns both the sensor's parameters and sensor parameterizations, or sets of parameterized values harvested within Tanium Data Service or otherwise registered.

Copy
query getSensorParameters($path: String, $op: FieldFilterOp!, $value: String) {
  sensors(filter: {path: $path, op: $op, value: $value}) {
    edges {
      node {
        contentSetName
        description
        name
        parameterizations {
          harvested
          values {
            name
            value
          }
        }
        parameters {
          defaultValue
          name
        }
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
  }
}

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

Copy
{
  "path": "description",
  "op": "CONTAINS",
  "value": "custom tag"
}

Example response:

Copy
{
  "data": {
    "sensors": {
      "edges": [
        {
          "node": {
            "contentSetName": "Core Content",
            "description": "Checks to see if a given custom tag exists on the endpoint. The input can either be a substring or an exact match, and the check is case insensitive.\nExample: True",
            "name": "Custom Tag Exists",
            "parameterizations": [
              {
                "harvested": true,
                "values": [
                  {
                    "name": "exactMatch",
                    "value": "1"
                  },
                  {
                    "name": "tag",
                    "value": "testCustomTag"
                  }
                ]
              },
              {
                "harvested": true,
                "values": [
                  {
                    "name": "exactMatch",
                    "value": "0"
                  },
                  {
                    "name": "tag",
                    "value": "testedTag"
                  }
                ]
              },
              {
                "harvested": true,
                "values": [
                  {
                    "name": "exactMatch",
                    "value": "1"
                  },
                  {
                    "name": "tag",
                    "value": "customTagApplied"
                  }
                ]
              }
            ],
            "parameters": [
              {
                "defaultValue": "1",
                "name": "tag"
              },
              {
                "defaultValue": "1",
                "name": "exactMatch"
              }
            ]
          }
        },
        {
          "node": {
            "contentSetName": "Core Content",
            "description": "Any specified custom tags that have been set for this machine.  See the Custom Tagging Dashboard.\nExample:  Development, Test-Machines",
            "name": "Custom Tags",
            "parameterizations": null,
            "parameters": null
          }
        }
      ],
      "pageInfo": {
        "startCursor": "sensors:0",
        "endCursor": "sensors:1",
        "hasPreviousPage": false,
        "hasNextPage": false
      }
    }
  }
}

ClosedRegister sensor for harvest (mutation.sensorHarvest)

Register a sensor for harvest

The following mutation registers a sensor for harvest by Tanium Data Service.

Wait 10 minutes after you create a sensor before submitting this mutation request.

Registration takes several minutes. The first time you submit this request, the response may contain a cursor, indicating an ongoing registration. If your response contains a cursor, wait several minutes, then pass the cursor as a sensorHarvest argument in the request to retrieve a success message or error message.

For the best results, pass the integrationName value in the format <companyName>-<productIntegration>, where <companyName> represents the company responsible for the integration, and <productIntegration> is the integration name or integration purpose.
Copy
mutation sensorHarvest($harvest: Boolean!, $integrationName: String!, $name: String!) {
  sensorHarvest(
    input: {harvest: $harvest, integrationName: $integrationName, name: $name}
  ) {
    cursor
    error {
      message
      retryable
      timedOut
    }
    success
  }
}

Include the harvest, integration name, and sensor name variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "harvest": true,
  "integrationName": "examplecompany-integratetanium",
  "name": "test-sensor"
}

Example response with a cursor:

Copy
{
  "data": {
    "sensorHarvest": {
      "cursor": "7551110",
      "error": null,
      "success": null
    }
  }
}

Register a sensor for harvest using a cursor

If the response contains a cursor, update your mutation request to pass the cursor:

Copy
mutation sensorHarvest($cursor: Cursor, $harvest: Boolean!, $integrationName: String!, $name: String!) {
  sensorHarvest(
    input: {cursor: $cursor, harvest: $harvest, integrationName: $integrationName, name: $name}
  ) {
    cursor
    error {
      message
      retryable
      timedOut
    }
    success
  }
}

Update your variables to include the cursor:

Copy
{
  "cursor": "7551110",
  "harvest": true,
  "integrationName": "examplecompany-integratetanium",
  "name": "test-sensor"
}

Example response after sensor registration completes:

Copy
{
  "data": {
    "sensorHarvest": {
      "cursor": null,
      "error": null,
      "success": true
    }
  }
}

Threat Response example

The following mutation requires Threat Response and assigns the Resolved status to a Threat Response alert.

ClosedAssign Resolved status to an alert (mutation.threatResponseAlertResolve)

Assign Resolved status to alert

The following request assigns the Resolved status to the Threat Response alert matching the GUID.

Copy
mutation cresolveTHRAlert ($guid: ID){
  threatResponseAlertResolve (ref: {guid: $guid}) {
    resolved 
    guid 
    error 
  }
}

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

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

Example response:

Copy
{
  "data" : {
    "threatResponseAlertResolve" : {
      "resolved" : true,
      "guid" : "12345678-90ab-cdef-1234-567890abcdef",
      "error" : null
    }
  }
}