Reference: API Gateway examples
Use the following request examples to learn about the functionality and syntax of queries and mutations in API Gateway. For information on integrating with the Insomnia API client, downloading request examples in Insomnia JSON format, and generating code examples from the request examples using Insomnia, see Reference: Integration with Insomnia API Client.
System examples
The following requests retrieve data about your Tanium instance.
Get server time (query.now)
Get server time
The following query retrieves the local time from
1
2
3
query getServerTime {
now
}
Example response:
1
2
3
4
5
{
"data": {
"now": "2021-11-08T19:22:03Z"
}
}
General examples
The following queries retrieve data from the endpoints in your environment.
Get endpoints (query.endpoints(source))
Get endpoints
The following query retrieves known endpoints from
1
2
3
4
5
6
7
8
9
10
11
12
13
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:
1
2
3
4
{
"count": 1,
"time": 10
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
"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"
}
}
]
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
query getTDSEndpointIDs {
endpoints {
edges {
node {
id
}
}
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"id": "12345"
}
},
{
"node": {
"id": "54321"
}
},
{
"node": {
"id": "21212"
}
}
]
}
}
}
Get endpoints with filter excluding errors (query.endpoints (source.ts.excludeErrors | source.tds.excludeErrors)
Get endpoints without field values containing common errors
Retrieved endpoints might contain error messages as field values. You can exclude endpoints retrieved from either the ts or tds data source from the response if they contain common error messages within returned fields. The following query retrieves the first 2 endpoints from Tanium Data Service, and does not exclude endpoints with common error values in returned fields.
1
2
3
4
5
6
7
8
9
10
11
12
query excludeEndpointsErrors($first: Int, $excludeErrors: Boolean!) {
endpoints(first: $first, source: {tds: {excludeErrors: $excludeErrors}}) {
edges {
node {
name
ipAddress
manufacturer
model
}
}
}
}
Include the pagination and excludeErrors variables in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
4
{
"first": 2,
"excludeErrors": false
}
Example response containing an endpoint with a common error value in the manufacturer and model fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-host-1",
"ipAddress": "192.0.2.10",
"manufacturer": "VMware, Inc.",
"model": "VMware Virtual Platform"
}
},
{
"node": {
"name": "example-host-2",
"ipAddress": "192.0.2.20",
"manufacturer": "TSE-Error: Unknown - dmidecode unavailable",
"model": "TSE-Error: Unknown - dmidecode unavailable"
}
}
]
}
}
}
If you update the excludeErrors variable definition to true, the query response excludes endpoints with common error values in the returned fields:
1
2
3
4
{
"first": 2,
"excludeErrors": true
}
Example response containing no endpoints with a common error value in the manufacturer and model fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-host-1",
"ipAddress": "192.0.2.10",
"manufacturer": "VMware, Inc.",
"model": "VMware Virtual Platform"
}
},
{
"node": {
"name": "example-host-3",
"ipAddress": "192.0.2.30",
"manufacturer": "Apple",
"model": "MacPro6,1"
}
}
]
}
}
}
Get endpoints with filter excluding [no results] (query.endpoints (source.ts.excludeNoResults | source.tds.excludeNoResults)
Get endpoints without field values containing [no results]
Retrieved endpoints might contain [no results] as field values. You can exclude endpoints retrieved from either the ts or tds data source from the response if they contain [no results] in returned fields. The following query retrieves the first 2 endpoints from Tanium Data Service, and does not exclude endpoints with [no results] in returned fields.
1
2
3
4
5
6
7
8
9
10
11
query excludeEndpointsNoResults($first: Int, $excludeNoResults: Boolean!) {
endpoints(first: $first, source: {tds: {excludeNoResults: $excludeNoResults}}) {
edges {
node {
name
ipAddress
macAddresses
}
}
}
}
Include the pagination and excludeErrors variables in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
4
{
"first": 2,
"excludeNoResults": false
}
Example response containing an endpoint with [no results] in the macAddresses field:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-host-1",
"ipAddress": "192.0.2.10",
"macAddresses": [
"00:00:5E:00:53:10"
]
}
},
{
"node": {
"name": "example-host-2",
"ipAddress": "192.0.2.20",
"macAddresses": [
"[no results]"
]
}
}
]
}
}
}
If you update the excludeNoResults variable definition to true, the query response excludes endpoints with [no results] in the returned fields:
1
2
3
4
{
"first": 2,
"excludeNoResults": true
}
Example response containing no endpoints with [no results] in the macAddresses field:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-host-1",
"ipAddress": "192.0.2.10",
"macAddresses": [
"00:00:5E:00:53:10"
]
}
},
{
"node": {
"name": "example-host-3",
"ipAddress": "192.0.2.30",
"macAddresses": [
"00:00:5E:00:53:30"
]
}
}
]
}
}
}
Get 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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:
1
2
3
{
"time": 10
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
"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"
]
}
]
}
}
}
]
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
query getEndpointsApplications {
endpoints {
edges {
node {
computerID
sensorReadings(sensors: [{name: "Installed Applications"}, {name: "Running Applications"}]) {
columns {
name
values
sensor {
name
}
}
}
}
}
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
{
"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"
}
}
]
}
}
}
]
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "Test-01",
"computerID": "1234567890",
"ipAddress": "192.0.2.10",
"isVirtual": false,
"chassisType": "TSE-Error: Unknown - dmidecode unavailable",
"systemUUID": "TSE-Error: Unknown - dmidecode unavailable",
"domainName": "(none)",
"os": {
"name": "Red Hat Enterprise Linux Server release 5.11 (Tikanga)",
"platform": "Linux",
"generation": "Red Hat Enterprise Linux 5"
},
"processor": {
"architecture": "x86_64",
"cacheSize": "16384 KB",
"consumption": "9.9 %",
"cpu": "Intel Core Processor (Haswell, no TSX, IBRS)",
"family": "6",
"manufacturer": "GenuineIntel",
"speed": "2600 Mhz"
},
"lastLoggedInUser": "reboot"
}
},
{
"node": {
"name": "Test-02",
"computerID": "3216549870",
"ipAddress": "192.0.2.20",
"isVirtual": true,
"chassisType": "Virtual",
"systemUUID": "[no results]",
"domainName": "(none)",
"os": {
"name": "CentOS Linux release 8.4.2105",
"platform": "Linux",
"generation": "CentOS 8"
},
"processor": {
"architecture": "x86_64",
"cacheSize": "35840 KB",
"consumption": "18.6 %",
"cpu": "Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz",
"family": "6",
"manufacturer": "GenuineIntel",
"speed": "2400 Mhz"
},
"lastLoggedInUser": "tester-5"
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasNextPage": true
}
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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:
1
2
3
4
5
6
{
"first": 3,
"filterOp": "MATCHES",
"path": "name",
"value": "t.*"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
"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"
]
}
]
}
}
}
]
}
}
}
Unregistered 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
query getEndpointsUnregisteredSensor {
endpoints {
edges {
node {
id
name
sensorReadings(sensors: [{name: "OS Platform"}]) {
columns {
name
values
}
}
}
}
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
"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"
]
}
]
}
}
}
]
}
}
}
Unregistered 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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:
1
2
3
4
{
"paramName1": "file",
"paramValue1": "C:\\Windows\\py.exe"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
{
"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]"
]
}
]
}
}
}
]
}
}
}
Get selected columns from sensor query (query.endpoints.edges.node.sensorReadings.columns)
Get selected columns from a sensor query
The following query retrieves the first 2 endpoint results, and returns only the Name and Silent Uninstall String columns from the Installed Applications sensor.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
query getEndpointsApplicationsColumns ($first: Int) {
endpoints (first: $first) {
edges {
node {
computerID
sensorReadings(sensors: [{name: "Installed Applications", columns: ["Name", "Silent Uninstall String"]}]) {
columns {
name
values
sensor {
name
}
}
}
}
}
}
}
Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"computerID": "987654321",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"Tanium Client 7.4.7.1094"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Silent Uninstall String",
"values": [
"\"C:\\Program Files (x86)\\Tanium\\Tanium Client\\uninst.exe\""
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
}
]
}
}
}
Get hidden columns from a sensor query
The following query retrieves the first 2 endpoint results, and based on includeHiddenColumns: true, returns all columns from the Application Crashes in Last X Days sensor, including a non-hidden column (Process) and a hidden column (Date).
To return hidden columns, you can also specify column names in the filter. By default, hidden columns are not returned.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
query getEndpointsHiddenColumns ($first: Int) {
endpoints (first: $first) {
edges {
node {
computerID
sensorReadings(sensors: [{name: "Application Crashes in Last X Days"}], includeHiddenColumns: true
) {
columns {
name
values
sensor {
name
}
}
}
}
}
}
}
Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"computerID": "1814669575",
"sensorReadings": {
"columns": [
{
"name": "Process",
"values": [
"example.exe"
],
"sensor": {
"name": "Application Crashes in Last X Days"
}
},
{
"name": "Date",
"values": [
"12/30/2022"
],
"sensor": {
"name": "Application Crashes in Last X Days"
}
}
]
}
}
},
{
"node": {
"computerID": "2508280668",
"sensorReadings": {
"columns": [
{
"name": "Process",
"values": [
"example2.exe"
],
"sensor": {
"name": "Application Crashes in Last X Days"
}
},
{
"name": "Date",
"values": [
"12/29/2022"
],
"sensor": {
"name": "Application Crashes in Last X Days"
}
}
]
}
}
}
]
}
}
}
Filter sensor query results (query.endpoints.edges.node.sensorReadings (sensors.filter))
Filter the results from a sensor query
The following query retrieves the first 2 endpoint results, and returns the application Name and Version columns for only the endpoints that have the tar application installed, based on the results from the Installed Applications sensor.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
query getEndpointsInstalledTar ($first: Int) {
endpoints (first: $first){
edges {
node {
computerID
sensorReadings(
sensors: [{name: "Installed Applications", filter: {column: "Name", op: EQ, value: "tar", restrictOwner: false}}]
) {
columns {
name
values
sensor {
name
}
}
}
}
}
}
}
Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"computerID": "1234567890",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"tar"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Version",
"values": [
"1.34"
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
},
{
"node": {
"computerID": "2345678901",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"tar"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Version",
"values": [
"1.33"
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
}
]
}
}
}
Filter sensor query results from a filtered set of endpoints
The following query retrieves the first 2 endpoints that are a member of the All Linux computer group, and returns the application Name and Version columns for only the endpoints that have the tar application installed, based on the results from the Installed Applications sensor.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
query getLinuxEndpointsInstalledTar ($first: Int){
endpoints(first: $first, filter: {memberOf: {name: "All Linux"}}) {
edges {
node {
computerID
sensorReadings(
sensors: [{name: "Installed Applications", filter: {column: "Name", op: EQ, value: "Tar", restrictOwner: false}}]
) {
columns {
name
values
sensor {
name
}
}
}
}
}
}
}
Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"computerID": "3456789012",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"tar"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Version",
"values": [
"1.32"
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
},
{
"node": {
"computerID": "4567890123",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"tar"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Version",
"values": [
"1.30"
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
}
]
}
}
}
Apply multi-column filter to sensor query results
The following query retrieves the first 2 endpoints, and returns the application Name and Version columns for only the endpoints that have the tar application version 1.30 installed, based on the results from the Installed Applications sensor.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query getEndpointsInstalledTar13 ($first: Int){
endpoints (first: $first){
edges {
node {
computerID
sensorReadings(
sensors: [{name: "Installed Applications",
filter: {
restrictOwner: false,
filters: [
{column: "Name", op: EQ, value: "Tar"},
{column: "Version" op: EQ, value: "1.30"}]
}
}]
) {
columns {
name
values
sensor {
name
}
}
}
}
}
}
}
Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"computerID": "4567890123",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"tar"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Version",
"values": [
"1.30"
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
},
{
"node": {
"computerID": "5678901234",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"tar"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Version",
"values": [
"1.30"
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
}
]
}
}
}
Apply multi-column filter to sensor query results for filtered endpoints
The following query retrieves the first 2 endpoints that are members of the All Linux computer group, and returns the application Name and Version columns for only the endpoints that have the tar application version 1.30 installed, based on the results from the Installed Applications sensor.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query getLinuxEndpointsInstalledTar130 ($first: Int){
endpoints(first: $first, filter: {memberOf: {name: "All Linux"}}) {
edges {
node {
computerID
sensorReadings(
sensors: [{name: "Installed Applications",
filter: {
restrictOwner: false,
filters: [
{column: "Name", op: EQ, value: "Tar", },
{column: "Version" op: EQ, value: "1.30"}]
}
}]
) {
columns {
name
values
sensor {
name
}
}
}
}
}
}
}
Include the pagination variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"computerID": "6789012345",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"tar"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Version",
"values": [
"1.30"
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
},
{
"node": {
"computerID": "7890123456",
"sensorReadings": {
"columns": [
{
"name": "Name",
"values": [
"tar"
],
"sensor": {
"name": "Installed Applications"
}
},
{
"name": "Version",
"values": [
"1.30"
],
"sensor": {
"name": "Installed Applications"
}
}
]
}
}
}
]
}
}
}
Endpoint 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.
1
2
3
4
5
6
7
8
9
10
query getEndpointCursors {
endpoints {
pageInfo {
hasPreviousPage
hasNextPage
startCursor
endCursor
}
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
{
"data": {
"endpoints": {
"pageInfo": {
"hasPreviousPage": false,
"hasNextPage": true,
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ=="
}
}
}
}
Paginated 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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:
1
2
3
4
{
"cursor": "NTc2NTM4MDow",
"first": 5
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "Test-06",
"id": "6172",
"ipAddress": "192.0.2.10"
}
},
{
"node": {
"name": "Test-07",
"id": "87654",
"ipAddress": "192.0.2.20"
}
},
{
"node": {
"name": "Test-14",
"id": "43584",
"ipAddress": "192.0.2.30"
}
},
{
"node": {
"name": "Test-03",
"id": "37233",
"ipAddress": "[no results]"
}
},
{
"node": {
"name": "Test-55",
"id": "12139",
"ipAddress": "[no results]"
}
}
],
"pageInfo": {
"hasNextPage": true,
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ=="
}
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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:
1
2
3
4
5
6
{
"first": 1,
"path": "name",
"value": "slow-endpoint",
"expectedCount": 1
}
Example response for an ongoing collection with a startCursor value:
1
2
3
4
5
6
7
8
9
10
11
12
{
"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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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:
1
2
3
4
5
6
7
{
"refresh": "4t2cB0ZGNPqy4J4P7O7opwz/24/5zgPi6OinDAA=:0",
"first": 1,
"path": "name",
"value": "slow-endpoint",
"expectedCount": 1
}
Example response with a completed collection:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"id": 1
}
],
"collectionInfo": {
"startCursor": "4t2cB0ZGNPqy4J4P7O7opwz/24/5zgPi6OinDAA=:0",
"success": true,
"active": true
}
}
}
}
Software 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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:
1
2
3
4
{
"value1": "123",
"value2": "Installed"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
"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"
}
]
}
}
]
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
"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"
}
]
}
}
]
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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:
1
2
3
{
"first" : 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
"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.
Approve a scheduled action (mutation.scheduledActionApprove)
Approve scheduled action
The following mutation approves the scheduled action that matches the action ID.
1
2
3
4
5
6
7
8
9
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:
1
2
3
{
"id": 12345
}
Example response:
1
2
3
4
5
6
7
8
9
{
"data": {
"scheduledActionApprove": {
"approved": true,
"id": "12345",
"error": null
}
}
}
Create 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.
1
2
3
4
5
6
7
8
9
10
11
12
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:
1
2
3
4
5
6
7
8
9
{
"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:
1
2
3
4
5
6
7
8
9
10
{
"data": {
"actionCreate": {
"action": {
"id": "123"
},
"error": null
}
}
}
Create 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
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:
1
2
3
4
5
6
7
8
9
10
11
{
"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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
"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
}
}
}
Delete action or scheduled action (mutation.scheduledActionDelete)
Delete action
The following mutation deletes an action or scheduled action based on the ID.
1
2
3
4
5
6
7
8
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:
1
2
3
{
"id": 12345
}
Example response:
1
2
3
4
5
6
7
8
{
"data": {
"scheduledActionDelete": {
"id": "12345",
"error": null
}
}
}
Get action information (query.action)
Get action information
The following query retrieves information about an action that matches the ID.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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:
1
2
3
{
"id": "12345"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{
"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
}
}
}
Get package spec information (query.packageSpecs)
Get package spec object information
The following query retrieves the first 2 package spec objects.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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:
1
2
3
{
"first" : 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
"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"
}
]
}
}
]
}
}
}
Get scheduled action information (query.scheduledAction)
Get scheduled action information
The following query retrieves information about a scheduled action that matches the ID.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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:
1
2
3
{
"id": 12345
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
"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"
}
}
}
Get scheduled actions (query.scheduledActions)
Get multiple scheduled actions
The following query retrieves the first 2 scheduled actions.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
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:
1
2
3
4
5
{
"path" : "name",
"op" : EQ,
"value" : "Example scheduled action"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
"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"
}
}
}
}
]
}
}
}
Perform 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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:
1
2
3
4
5
6
7
8
9
10
{
"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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"data": {
"actionPerform": {
"scheduledActions": [
{
"platforms": [
"Solaris"
],
"scheduledAction": {
"id": "12345"
}
}
],
"error": null
}
}
}
Stop an action (mutation.actionStop)
Stop action
The following mutation stops an action that matches the ID.
1
2
3
4
5
6
7
8
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:
1
2
3
{
"id": 12345
}
Example response:
1
2
3
4
5
6
7
8
{
"data": {
"actionStop": {
"id": "12345",
"error": null
}
}
}
DEPRECATED - 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.
1
2
3
4
5
6
7
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:
1
2
3
4
5
6
7
{
"description": "Increasing log verbosity level on all debian endpoints for troubleshooting",
"group": "All Debian",
"platform": "Linux",
"setting": "LOG_VERBOSITY_LEVEL",
"settingValue": "41"
}
Example response:
1
2
3
4
5
6
7
{
"data": {
"createAction": {
"id": "82"
}
}
}
DEPRECATED - 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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:
1
2
3
{
"id": 12323
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"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.
Create 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.
1
2
3
4
5
6
7
8
9
10
11
12
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:
1
2
3
4
5
6
{
"any": false,
"computerGroupName": "Example computer group",
"actionGroupName": "Example action group",
"visibility": "ALL"
}
Example response:
1
2
3
4
5
6
7
8
9
10
{
"data": {
"actionCreate": {
"action": {
"id": "12345"
},
"error": null
}
}
}
Delete action group by ID or name (mutation.actionGroupDelete)
Delete action group by ID
The following mutation deletes the action group that matches the ID.
1
2
3
4
5
6
7
8
9
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:
1
2
3
{
"id": 12345
}
Example response:
1
2
3
4
5
6
7
8
{
"data": {
"actionGroupDelete": {
"error": null,
"id": "12345"
}
}
}
Delete action group by name
You can also delete an action group that matches a name.
1
2
3
4
5
6
7
8
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:
1
2
3
{
"name": "Example action group"
}
Get action group by ID or name (query.actionGroup)
Get action group by ID
The following query retrieves an action group that matches the ID.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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:
1
2
3
{
"id": 12345
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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:
1
2
3
{
"name" : "Example action group"
}
Get multiple action groups (query.actionGroups)
Get action groups
The following query retrieves the first 2 action groups. For more information on pagination, see Pagination.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
"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.
Create 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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:
1
2
3
4
5
6
7
{
"trustedIPAddress1": "192.0.2.0/24",
"trustedIPAddress2": "198.51.100.10",
"expiresInDays": 365,
"personaName": "testPersona",
"notes": "API Gateway token"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"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
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
query getMyAPITokens {
myAPITokens {
tokens {
created
expiration
id
lastUsed
notes
persona {
name
}
trustedIPAddresses
}
error {
message
retryable
timedOut
}
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"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
}
}
}
Rotate 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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:
1
2
3
{
"tokenString": "token-9668a9a11e082ea9b062f204f4e9b98e8785d006388e99e00fb6efbaaa"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"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
}
}
}
Delete API token (mutation.apiTokenRevoke)
Delete API token
The following mutation deletes an existing API token. This requires the Token - Revoke permission.
1
2
3
4
5
6
7
8
9
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:
1
2
3
{
"id": 10
}
Example response:
1
2
3
4
5
6
7
{
"data": {
"apiTokenRevoke": {
"error": null
}
}
}
Asset examples
The following requests require Asset and retrieve Asset products or endpoints based on Asset products, update Asset product tracking, or import assets to update existing assets or create new assets.
Asset requests have the following feature-specific dependencies at the specified minimum versions:
-
Asset 1.23.8 or later is required to submit a mutation request to import assets (mutation.assetsImport).
- Asset 1.24.76 or later is required to submit a request that retrieves Asset products (query.assetProducts) or endpoints based on installed Asset products (query.assetProductEndpoints), or to submit a mutation request that updates Asset product tracking (mutation.assetProducts).
Import assets (mutation.assetsImport)
Import assets
Before you submit this mutation request, you must configure an Asset custom source. For more information and an example workflow, see Tanium Asset User Guide: Create an Import API source.
The assetsImport mutation
-
If an imported asset key matches an existing asset key imported using the sourceName custom source, that existing asset updates.
-
If no existing asset from the configured source matches, but values in the imported asset match an existing asset key imported using a source different from the sourceName custom source, and the other source allows the sourceName custom source to update, the existing asset from the other source updates.
-
Otherwise, if no existing asset matches the imported asset, the asset is imported as a new asset using the sourceName custom source.
If the request is structurally and syntactically valid, each asset object imports separately. A failed asset import does not prevent other valid asset objects in that request from importing.
Define the json attribute as a JSON object array, with each object corresponding to an asset. Ensure that the Asset custom source passes the JSON object array according to the following guidelines:
- Use the backslash escape character with each quotation mark (\") in the JSON array.
- You must define key field values for each object. If you do not define the key field values, the object does not import and the response returns
ErrorMissingKeystatus for that object. - You can define source field mappings to destination fields for each object. If you do not define a source field mapping, values from those source fields are imported as
nullvalues for that object. - Field values are defined per object; you cannot globally define a single field value in the request to apply to every imported asset object.
- You can define up to 5000 asset objects per array, and by extension, per request.
The following example Asset custom source, named test-name, defines two field mappings for computer_name and serial_number and defines computer_name as a key field.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"keys": [
"computer_name"
],
"fieldMaps": [
{
"destination": "computer_name",
"source": "computerName"
},
{
"destination": "serial_number",
"source": "serialNumber"
}
]
}
The following mutation request imports assets based on the variables definition:
1
2
3
4
5
6
7
8
9
mutation importAssets($source: String!, $json: String!) {
assetsImport(input: {sourceName: $source, json: $json}) {
assets {
id
index
status
}
}
}
Include the variables in the QUERY VARIABLES panel or in your variables dictionary.
The following variables manually define the test-name source for importing and two asset objects in the JSON object array. Each object has a value for the key field (computerName) and for the serialNumber field mapping.
1
2
3
4
{
"source": "test-name",
"json": "[{\"computerName\": \"computer123\", \"serialNumber\": \"testSerial123\"}, {\"computerName\": \"computer234\", \"serialNumber\": \"testSerial234\"}]"
}
As the request is evaluated, each asset object defines a value for the computerName key field, matching the key field defined for the test-name custom source, and both are imported using that source. The example response shows both objects with a status of Created:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"data": {
"assetsImport": {
"assets": [
{
"id": 6,
"index": 0,
"status": "Created"
},
{
"id": 7,
"index": 1,
"status": "Created"
}
]
}
}
}
To verify the import, create a report based on the custom source definition, and filter the report to search for imported assets. For example, creating a report with Computer Name and Serial Number as columns, then filtering Computer Name for values containing computer and 23 returns the imported assets.
For more information, see Tanium Asset User Guide: Create a report.
Get Asset products (query.assetProducts)
Get Asset product information
The following query requires Asset
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
query getAssetProducts($first: Int) {
assetProducts(
first: $first
) {
edges {
node {
vendor
name
installation {
installedCount
usedCount
unusedCount
pendingUsage
}
usage {
usageNotDetected
notInstalled
baselining
limited
normal
high
}
tracking {
state
reportingPeriodDays
normalMinutesUsedPerDay
highMinutesUsedPerDay
baselinePeriodDays
}
versions {
version
installs
}
}
}
}
}
Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
{
"data": {
"assetProducts": {
"edges": [
{
"node": {
"vendor": "Example vendor",
"name": "Example product",
"installation": {
"installedCount": 8,
"usedCount": 0,
"unusedCount": 0,
"pendingUsage": null
},
"usage": {
"usageNotDetected": 0,
"notInstalled": 0,
"baselining": 0,
"limited": 0,
"normal": 0,
"high": 0
},
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 90,
"normalMinutesUsedPerDay": 60,
"highMinutesUsedPerDay": 240,
"baselinePeriodDays": 7
},
"versions": [
{
"version": "1.2.3",
"installs": 2
},
{
"version": "1.2.4",
"installs": 2
}
]
}
},
{
"node": {
"vendor": "Example vendor 2",
"name": "Example product 2",
"installation": {
"installedCount": 1,
"usedCount": 0,
"unusedCount": 0,
"pendingUsage": null
},
"usage": {
"usageNotDetected": 0,
"notInstalled": 0,
"baselining": 0,
"limited": 0,
"normal": 0,
"high": 0
},
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 90,
"normalMinutesUsedPerDay": 60,
"highMinutesUsedPerDay": 240,
"baselinePeriodDays": 7
},
"versions": [
{
"version": "0.1.2",
"installs": 1
}
]
}
}
]
}
}
}
The following query request filters and retrieves only Asset products with a vendor name of Example vendor, an Asset state of Cataloged, and the search string Product in either the vendor name or product name:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
query getAssetProductsFiltered($first: Int, $vendor: String!, $search: String, $states: AssetProductState!) {
assetProducts(
first: $first, filter: {
vendors: [$vendor],
search: $search,
states: [$states]
}
) {
edges {
node {
vendor
name
installation {
installedCount
usedCount
unusedCount
pendingUsage
}
usage {
usageNotDetected
notInstalled
baselining
limited
normal
high
}
tracking {
state
reportingPeriodDays
normalMinutesUsedPerDay
highMinutesUsedPerDay
baselinePeriodDays
}
versions {
version
installs
}
}
}
}
}
Include the cursor and filter variables in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
4
5
6
{
"first": 2,
"vendor": "Example vendor",
"search": "Product",
"states": "Cataloged"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
{
"data": {
"assetProducts": {
"edges": [
{
"node": {
"vendor": "Example vendor",
"name": "Example product",
"installation": {
"installedCount": 8,
"usedCount": 0,
"unusedCount": 0,
"pendingUsage": null
},
"usage": {
"usageNotDetected": 0,
"notInstalled": 0,
"baselining": 0,
"limited": 0,
"normal": 0,
"high": 0
},
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 90,
"normalMinutesUsedPerDay": 60,
"highMinutesUsedPerDay": 240,
"baselinePeriodDays": 7
},
"versions": [
{
"version": "0.1.2",
"installs": 2
},
{
"version": "3.4.5",
"installs": 2
}
]
}
},
{
"node": {
"vendor": "Example vendor",
"name": "Product example",
"installation": {
"installedCount": 1,
"usedCount": 0,
"unusedCount": 0,
"pendingUsage": null
},
"usage": {
"usageNotDetected": 0,
"notInstalled": 0,
"baselining": 0,
"limited": 0,
"normal": 0,
"high": 0
},
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 90,
"normalMinutesUsedPerDay": 60,
"highMinutesUsedPerDay": 240,
"baselinePeriodDays": 7
},
"versions": [
{
"version": "6.7.8",
"installs": 1
}
]
}
}
]
}
}
}
Get endpoints based on Asset products (query.assetProductEndpoints)
Get endpoints filtered based on Asset products
The following query requires Asset
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
query getEndpointsAssetProduct($first: Int, $vendor: String, $name: String, $version: String) {
assetProductEndpoints(
first: $first
filter: {vendor: $vendor, name: $name, version: $version, usage: Normal}
) {
edges {
node {
id
eid
computerName
computerId
serialNumber
osPlatform
operatingSystem
servicePack
manufacturer
ipAddress
userName
createdAt
updatedAt
}
}
}
}
Include the cursor and filtering variables in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
4
5
6
{
"first": 2,
"vendor": "Example vendor",
"name": "Example name",
"version": "1.2.3"
}}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{
"data": {
"assetProductEndpoints": {
"edges": [
{
"node": {
"id": 123,
"eid": 456789,
"computerName": "example-host-1",
"computerId": "123456789",
"serialNumber": "1234567890abcdef",
"osPlatform": "Windows",
"operatingSystem": "Windows 10 Enterprise",
"servicePack": "No Service Pack found",
"manufacturer": "VMware, Inc.",
"ipAddress": "192.0.2.10",
"userName": "example-user",
"createdAt": "2022-09-29T07:00:16.000Z",
"updatedAt": "2022-11-10T23:00:06.000Z"
}
},
{
"node": {
"id": 456,
"eid": 789012,
"computerName": "example-host-2",
"computerId": "987654321",
"serialNumber": "fedcba0987654321",
"osPlatform": "Windows",
"operatingSystem": "Windows 10 Enterprise",
"servicePack": "No Service Pack found",
"manufacturer": "VMware, Inc.",
"ipAddress": "192.0.2.20",
"userName": "example-user",
"createdAt": "2022-09-29T07:00:16.000Z",
"updatedAt": "2022-10-31T14:00:05.000Z"
}
}
]
}
}
}
Update Asset products tracking (mutation.assetProducts)
Update Asset product tracking
The following mutation requires Asset
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
mutation updateAssetTracking($vendor: String!, $name: String!, $tracking: AssetProductTrackingInput!) {
assetProducts(input: {vendor: $vendor, name: $name, tracking: $tracking}) {
products {
vendor
name
tracking {
state
reportingPeriodDays
normalMinutesUsedPerDay
highMinutesUsedPerDay
baselinePeriodDays
}
failureReason
}
}
}
Include the product tracking variables in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
4
5
6
7
8
9
10
11
{
"vendor": "Example vendor",
"name": "Example product",
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 90,
"normalMinutesUsedPerDay": 120,
"highMinutesUsedPerDay": 480,
"baselinePeriodDays": 5
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"data": {
"assetProducts": {
"products": [
{
"vendor": "Example vendor",
"name": "Example product",
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 120,
"normalMinutesUsedPerDay": 120,
"highMinutesUsedPerDay": 480,
"baselinePeriodDays": 5
},
"failureReason": null
}
]
}
}
}
You can update multiple Asset product tracking metrics in one mutation request. The following request adds a second object to the input array for the Example vendor product Second example product:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
mutation updateAssetTrackingMultiple($vendor: String!, $name: String!, $name2: String!, $tracking: AssetProductTrackingInput!, $tracking2: AssetProductTrackingInput!) {
assetProducts(
input: [{vendor: $vendor, name: $name, tracking: $tracking}, {vendor: $vendor, name: $name2, tracking: $tracking2}]
) {
products {
vendor
name
tracking {
state
reportingPeriodDays
normalMinutesUsedPerDay
highMinutesUsedPerDay
baselinePeriodDays
}
failureReason
}
}
}
Include the product tracking variables in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"vendor": "Example vendor",
"name": "Example product",
"name2": "Second example product",
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 120,
"normalMinutesUsedPerDay": 120,
"highMinutesUsedPerDay": 480,
"baselinePeriodDays": 5
},
"tracking2": {
"state": "Cataloged",
"reportingPeriodDays": 90,
"normalMinutesUsedPerDay": 60,
"highMinutesUsedPerDay": 480,
"baselinePeriodDays": 7
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
"data": {
"assetProducts": {
"products": [
{
"vendor": "Example vendor",
"name": "Example product",
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 120,
"normalMinutesUsedPerDay": 120,
"highMinutesUsedPerDay": 480,
"baselinePeriodDays": 5
},
"failureReason": null
},
{
"vendor": "Example vendor",
"name": "Second example product",
"tracking": {
"state": "Cataloged",
"reportingPeriodDays": 90,
"normalMinutesUsedPerDay": 60,
"highMinutesUsedPerDay": 480,
"baselinePeriodDays": 7
},
"failureReason": null
}
]
}
}
}
Benchmark examples
The following queries retrieve endpoints and use Benchmark to also retrieve related risk overview or risk vector information.
Certain risk vector queries require additional Tanium solutions. For more information, see Tanium Benchmark User Guide - Solution dependencies.
Get endpoints with Benchmark overview information (query.endpoints.edges.node.risk)
Get endpoint Benchmark overview information
The following query retrieves the first endpoint and associated Benchmark overview information.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
query endpointBenchmarkOverview($first: Int) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
risk {
totalScore
riskLevel
assetCriticality
criticalityScore
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-endpoint",
"ipAddress": "198.51.100.10",
"risk": {
"totalScore": 208.06799999999998,
"riskLevel": "Low",
"assetCriticality": "Low",
"criticalityScore": 1
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
query endpointBenchmarkAdminAccess($first: Int) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
risk {
totalScore
vectors {
administrativeAccess {
direct
impactRating
impactRatingScore
inbound
indirect
outbound
score
sessions
}
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-admin",
"ipAddress": "192.0.2.10",
"risk": {
"totalScore": 208.06799999999998,
"vectors": {
"administrativeAccess": {
"direct": 0,
"impactRating": "Low",
"impactRatingScore": 4,
"inbound": 0,
"indirect": 0,
"outbound": 1,
"score": 0,
"sessions": 1
}
}
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
query endpointBenchmarkExpiredCerts($first: Int) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
risk {
totalScore
vectors {
expiredCertificates {
certificatesCount
ports
score
}
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "endpoint-expired",
"ipAddress": "192.0.2.20",
"risk": {
"totalScore": 208.06799999999998,
"vectors": {
"expiredCertificates": {
"certificatesCount": 1,
"ports": "443",
"score": 420
}
}
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
query endpointBenchmarkInsecureTLS($first: Int) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
risk {
totalScore
vectors {
insecureTLS {
ports
protocols
score
}
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "endpoint-insecure",
"ipAddress": "192.0.2.30",
"risk": {
"totalScore": 208.06799999999998,
"vectors": {
"insecureTLS": {
"ports": "3389",
"protocols": "TLS 1.0, TLS 1.1",
"score": 440
}
}
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
query endpointBenchmarkPWIdent($first: Int) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
risk {
totalScore
vectors {
passwordIdentification {
filesConfirmed
score
}
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "endpoint-pw",
"ipAddress": "192.0.2.40",
"risk": {
"totalScore": 208.06799999999998,
"vectors": {
"passwordIdentification": {
"filesConfirmed": "6",
"score": 830
}
}
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
query endpointBenchmarkCompliance($first: Int) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
risk {
totalScore
vectors {
compliance {
complianceFailCount
score
}
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "endpoint-compliance",
"ipAddress": "192.0.2.50",
"risk": {
"totalScore": 208.06799999999998,
"vectors": {
"compliance": {
"complianceFailCount": 669,
"score": 333.06
}
}
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
query endpointBenchmarkVulnerability($first: Int) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
risk {
totalScore
vectors {
systemVulnerability {
cveCount
score
}
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include a variable for the number of endpoints to return in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "endpoint-vuln",
"ipAddress": "192.0.2.60",
"risk": {
"totalScore": 208.06799999999998,
"vectors": {
"systemVulnerability": {
"cveCount": 14,
"score": 353.64
}
}
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Comply examples
The following queries retrieve endpoints and use Comply to also retrieve associated compliance findings or vulnerability findings.
Comply requests have the following feature-specific dependencies at the specified minimum versions:
-
Comply 2.10.940 or later is required to submit a request involving the System Vulnerability and System Compliance risk vectors.
- Comply 2.16.97 or later is required to submit a request that filters specific System Vulnerability and System Compliance risk vector fields.
Get endpoints with compliance findings information (query.endpoints.edges.node.compliance.complianceFindings)
Get endpoint compliance findings information
The following query retrieves the first endpoint and associated compliance findings.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
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:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "comply-findings",
"ipAddress": "192.0.2.10",
"compliance": {
"complianceFindings": [
{
"category": "Fail",
"id": "CIS Microsoft Windows 10 Enterprise Release 20H2 Benchmark;1.10.1;MB Custom Win10;xccdf_com.tanium.comply_tailoring_1639024882628;xccdf_org.cisecurity.benchmarks_rule_18.9.4.1_L2_Ensure_Allow_a_Windows_app_to_share_application_data_between_users_is_set_to_Disabled",
"profile": "MB Custom Win10",
"profileVersion": "xccdf_com.tanium.comply_tailoring_1639024882628",
"rule": "(L2) Ensure 'Allow a Windows app to share application data between users' is set to 'Disabled'",
"ruleId": "xccdf_org.cisecurity.benchmarks_rule_18.9.4.1_L2_Ensure_Allow_a_Windows_app_to_share_application_data_between_users_is_set_to_Disabled",
"standard": "CIS Microsoft Windows 10 Enterprise Release 20H2 Benchmark",
"standardVersion": "1.10.1",
"state": "fail"
}
]
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get filtered endpoint compliance findings information
The following query
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
query filterComplianceFindings ($first: Int) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
compliance {
complianceFindings (filter: {
path: "category"
value: "Error"
}) {
category
id
profile
profileVersion
rule
ruleId
standard
standardVersion
state
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-host",
"ipAddress": "192.0.2.10",
"compliance": {
"complianceFindings": [
{
"category": "Error",
"id": "CIS Microsoft IIS 10 Benchmark;1.1.1;Level 1 - IIS 10;1;xccdf_org.cisecurity.benchmarks_rule_4.8_L1_Ensure_Handler_is_not_granted_Write_and_ScriptExecute",
"profile": "Level 1 - IIS 10",
"profileVersion": "1",
"rule": "(L1) Ensure Handler is not granted Write and Script/Execute",
"ruleId": "xccdf_org.cisecurity.benchmarks_rule_4.8_L1_Ensure_Handler_is_not_granted_Write_and_ScriptExecute",
"standard": "CIS Microsoft IIS 10 Benchmark",
"standardVersion": "1.1.1",
"state": "error"
},
{
"category": "Error",
"id": "CIS Microsoft IIS 10 Benchmark;1.1.1;Level 1 - IIS 10;1;xccdf_org.cisecurity.benchmarks_rule_1.6_L1_Ensure_application_pool_identity_is_configured_for_anonymous_user_identity",
"profile": "Level 1 - IIS 10",
"profileVersion": "1",
"rule": "(L1) Ensure 'application pool identity' is configured for anonymous user identity",
"ruleId": "xccdf_org.cisecurity.benchmarks_rule_1.6_L1_Ensure_application_pool_identity_is_configured_for_anonymous_user_identity",
"standard": "CIS Microsoft IIS 10 Benchmark",
"standardVersion": "1.1.1",
"state": "error"
}
]
}
}
}
],
"pageInfo": {
"startCursor": "NjEwMzg2Nzow",
"endCursor": "NjEwMzg2Nzow",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get filtered endpoint compliance findings information from filtered set of endpoints
The following query
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
query filterWindowsComplianceFindings($first: Int!) {
endpoints(first: $first, filter: {memberOf: {name: "All Windows"}}) {
edges {
node {
name
ipAddress
compliance {
complianceFindings(
filter: {any: false, filters: [{path: "category", value: "Error"}, {path: "standardVersion", value: "1.1.1"}]}
) {
category
id
profile
profileVersion
rule
ruleId
standard
standardVersion
state
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-host-2",
"ipAddress": "192.0.2.20",
"compliance": {
"complianceFindings": [
{
"category": "Error",
"id": "CIS Microsoft IIS 10 Benchmark;1.1.1;Level 1 - IIS 10;1;xccdf_org.cisecurity.benchmarks_rule_4.6_L1_Ensure_HTTP_Trace_Method_is_disabled",
"profile": "Level 1 - IIS 10",
"profileVersion": "1",
"rule": "(L1) Ensure 'HTTP Trace Method' is disabled",
"ruleId": "xccdf_org.cisecurity.benchmarks_rule_4.6_L1_Ensure_HTTP_Trace_Method_is_disabled",
"standard": "CIS Microsoft IIS 10 Benchmark",
"standardVersion": "1.1.1",
"state": "error"
},
{
"category": "Error",
"id": "CIS Microsoft IIS 10 Benchmark;1.1.1;Level 1 - IIS 10;1;xccdf_org.cisecurity.benchmarks_rule_3.4_L1_Ensure_IIS_HTTP_detailed_errors_are_hidden_from_displaying_remotely",
"profile": "Level 1 - IIS 10",
"profileVersion": "1",
"rule": "(L1) Ensure IIS HTTP detailed errors are hidden from displaying remotely",
"ruleId": "xccdf_org.cisecurity.benchmarks_rule_3.4_L1_Ensure_IIS_HTTP_detailed_errors_are_hidden_from_displaying_remotely",
"standard": "CIS Microsoft IIS 10 Benchmark",
"standardVersion": "1.1.1",
"state": "error"
}
]
}
}
}
],
"pageInfo": {
"startCursor": "NjA5ODg0MDow",
"endCursor": "NjA5ODg0MDow",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get endpoints with vulnerability findings information (query.endpoints.edges.node.compliance.cveFindings)
Get endpoint vulnerability findings information (CVSS v2)
The following query retrieves the first endpoint and associated vulnerability findings
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query endpointVulnerabilityCVSSv2($first: Int!) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
compliance {
cveFindings {
cveId
cveYear
cvssScore
firstFound
lastFound
severity
summary
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "comply-vuln",
"ipAddress": "192.0.2.20",
"compliance": {
"cveFindings": [
{
"cveId": "CVE-2020-9698",
"cveYear": "2020",
"cvssScore": 9.3,
"firstFound": "2022-02-17",
"lastFound": "2022-05-06",
"severity": "High",
"summary": "Adobe Acrobat and Reader versions 2020.009.20074 and earlier, 2020.001.30002, 2017.011.30171 and earlier, and 2015.006.30523 and earlier have a buffer error vulnerability. Successful exploitation could lead to arbitrary code execution ."
},
{
"cveId": "CVE-2020-9699",
"cveYear": "2020",
"cvssScore": 9.3,
"firstFound": "2022-02-17",
"lastFound": "2022-05-06",
"severity": "High",
"summary": "Adobe Acrobat and Reader versions 2020.009.20074 and earlier, 2020.001.30002, 2017.011.30171 and earlier, and 2015.006.30523 and earlier have a buffer error vulnerability. Successful exploitation could lead to arbitrary code execution ."
},
{
"cveId": "CVE-2020-9700",
"cveYear": "2020",
"cvssScore": 9.3,
"firstFound": "2022-02-17",
"lastFound": "2022-05-06",
"severity": "High",
"summary": "Adobe Acrobat and Reader versions 2020.009.20074 and earlier, 2020.001.30002, 2017.011.30171 and earlier, and 2015.006.30523 and earlier have a buffer error vulnerability. Successful exploitation could lead to arbitrary code execution ."
}
]
}
}
}
],
"pageInfo": {
"startCursor": "NTc2NTM4MDow",
"endCursor": "NTc2NTM4MDoxOQ==",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get endpoint vulnerability findings information (CVSS v3)
The following query retrieves the first endpoint and associated vulnerability findings, including CVSS v3 score and severity.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query endpointVulnerabilityCVSSv3($first: Int!) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
compliance {
cveFindings {
cveId
cveYear
cvssScoreV3
firstFound
lastFound
severityV3
summary
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Get filtered endpoint vulnerability findings information
The following query
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query filterEndpointVulnerability($first: Int!) {
endpoints(first: $first) {
edges {
node {
name
ipAddress
compliance {
cveFindings(filter: {path: "cveYear", value: "2020"}) {
cveId
cveYear
cvssScore
firstFound
lastFound
severity
summary
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-host-3",
"ipAddress": "192.0.2.30",
"compliance": {
"cveFindings": [
{
"cveId": "CVE-2020-10754",
"cveYear": "2020",
"cvssScore": 4,
"firstFound": "2022-09-24",
"lastFound": "2022-11-30",
"severity": "Medium",
"summary": "It was found that nmcli, a command line interface to NetworkManager did not honour 802-1x.ca-path and 802-1x.phase2-ca-path settings, when creating a new profile. When a user connects to a network using this profile, the authentication does not happen and the connection is made insecurely."
}
]
}
}
}
],
"pageInfo": {
"startCursor": "NjEwNDEyMzow",
"endCursor": "NjEwNDEyMzow",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Get filtered endpoint vulnerability findings information from filtered set of endpoints
The following query
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
query filterMacOSEndpointVulnerability($first: Int!) {
endpoints(first: $first, filter: {memberOf: {name: "All Mac"}}) {
edges {
node {
name
ipAddress
compliance {
cveFindings(
filter: {any: false, filters: [{path: "cveYear", value: "2020"}, {path: "cvssScore", value: "5"}]}
) {
cveId
cveYear
cvssScoreV3
firstFound
lastFound
severityV3
summary
}
}
}
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
}
}
Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"first": 1
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
"data": {
"endpoints": {
"edges": [
{
"node": {
"name": "example-host-3",
"ipAddress": "192.0.2.30",
"compliance": {
"cveFindings": [
{
"cveId": "CVE-2020-8037",
"cveYear": "2020",
"cvssScore": 5,
"firstFound": "2022-09-06",
"lastFound": "2022-11-30",
"severity": "Medium",
"summary": "The ppp decapsulator in tcpdump 4.9.3 can be convinced to allocate a large amount of memory."
}
]
}
}
}
],
"pageInfo": {
"startCursor": "NjEwNDEyMzow",
"endCursor": "NjEwNDEyMzow",
"hasPreviousPage": false,
"hasNextPage": true
}
}
}
}
Computer group examples
The following queries and mutations create, retrieve, and delete computer groups.
Create 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
managementRightsEnabledas 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
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:
1
2
3
4
5
{
"name": "Example computer group",
"groupName": "No Computers",
"mrEnabled": true
}
Example response:
1
2
3
4
5
6
7
8
9
10
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
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:
1
2
3
4
5
6
{
"name": "Example computer group",
"contentSetName": "Default",
"groupName": "No Computers",
"mrEnabled": false
}
Example response:
1
2
3
4
5
6
7
8
9
10
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
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:
1
2
3
4
5
6
{
"name": "Example computer group that filters",
"contentSetName": "Default"
"groupName": "No Computers",
"mrEnabled": true
}
Example response:
1
2
3
4
5
6
7
8
9
10
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
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:
1
2
3
4
5
6
7
{
"cgName": "Windows or Mac example group",
"mrEnabled": true,
"filterAny": true,
"groupName1": "All Windows",
"groupName2": "All Mac"
}
Example response:
1
2
3
4
5
6
7
8
9
10
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
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:
1
2
3
4
5
6
7
{
"cgName": "All Mac example group",
"mrEnabled": true,
"sensorName": "Is Mac",
"sensorOp": "EQ",
"sensorValue": "true"
}
Example response:
1
2
3
4
5
6
7
8
9
10
{
"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
1
2
3
4
5
6
7
8
9
10
11
12
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"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:
1
2
3
4
5
6
7
8
9
10
{
"data": {
"computerGroupCreate": {
"group": {
"id": "12345"
},
"error": null
}
}
}
Delete computer group by ID or name (mutation.computerGroupDelete)
Delete computer group by ID
The following mutation deletes the computer group that matches the ID.
1
2
3
4
5
6
7
8
9
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:
1
2
3
{
"id": 12345
}
Example response:
1
2
3
4
5
6
7
8
{
"data": {
"computerGroupDelete": {
"error": null,
"id": "12345"
}
}
}
Delete computer group by name
You can also delete a computer group that matches a name.
1
2
3
4
5
6
7
8
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:
1
2
3
{
"name": "Example computer group"
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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:
1
2
3
{
"id": 12345
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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:
1
2
3
{
"name" : "Example computer group"
}
Get 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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:
1
2
3
{
"first": 2
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"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).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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:
1
2
3
4
{
"first": 2,
"type": "MANUAL"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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:
1
2
3
4
{
"first": 2,
"type": "STANDARD"
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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:
1
2
3
4
{
"first": 2,
"filterEnabled": true
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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:
1
2
3
4
{
"first": 2,
"mrEnabled": true
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
"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.
Deploy a package to all endpoints (mutation.manageSoftware)
Deploy package to endpoints
The following mutation deploys a package to All Computers.
1
2
3
4
5
6
7
8
9
10
11
12
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:
1
2
3
{
"group": "All Computers"
}
Example response:
1
2
3
4
5
6
7
8
{
"data": {
"manageSoftware": {
"ID": "2",
"name": "Install Tanium Standard Utilities (Linux)"
}
}
}
Get package details (query.packages)
Get details of all packages
The following query retrieves multiple fields for all packages.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
"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
}
]
}
}
}
Get Deploy packages (query.softwarePackages)
Get all deploy packages
The following query retrieves all Deploy packages.
1
2
3
4
5
6
7
8
9
10
11
12
query getDeployPackages{
softwarePackages {
edges {
node {
id
productName
productVendor
productVersion
}
}
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
"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"
}
}
]
}
}
}
Get software deployment status (query.softwareDeployment)
Get status of software deployment
The following query retrieves the deployment status of all Deploy packages.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
query getSoftwareDeploymentStatus {
softwareDeployment {
ID
name
status {
completeCount
downloadCompleteWaitingCount
downloadingCount
failedCount
notApplicableCount
runningCount
waitingCount
}
errors {
error
count
}
}
}
Example response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
"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 or terminate processes on endpoints require Performance.
Direct Connect requests have the following feature-specific dependencies at the specified minimum versions:
-
Direct Connect 1.10.39 or later is required to submit a request opening, closing, or getting status of Direct Connect connections (mutation.directConnectClose, mutation.directConnectOpen, mutation.directConnectPing, mutation.directConnectConnectionStatus).
-
Performance 1.10.57 or later is required to submit a request retrieving Performance data from endpoints using Direct Connect or terminating processes using Direct Connect (mutation.directConnectProcessTerminate, query.directConnectEndpoint).
Note: For the best results, install Direct Connect 2.7.43 or later.
Open a connection to an endpoint (mutation.directConnectOpen)
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 Get endpoints IDs from Tanium Data Service query. If a direct connection status is not READY (such as CONNECTING or UNKNOWN) after you use this mutation, you can use the Get direct connection status query to check the direct connection status.
Direct Connect connections close after five minutes of inactivity.
1
2
3
4
5
6
mutation openEndpointConnection ($id: ID!){
directConnectOpen(input: {endpointID: $id}) {
connectionID
status
}
}
Include the endpoint ID in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"id": "12323"
}
Example response:
1
2
3
4
5
6
7
8
{
"data": {
"directConnectOpen": {
"connectionID": "86d9a9ac-0229-481b-9d88-5f1bcb1b177b",
"status": "READY"
}
}
}
Get the status of a connection to an endpoint (query.directConnectConnectionStatus)
Get direct connection status
The following query uses Direct Connect to retrieve the status of a direct connection. If a direct connection status is not READY (such as CONNECTING or UNKNOWN) after you use the Open direct connection to endpoint mutation to establish a direct connection to an endpoint, you can use the connection ID from that response in this query to determine whether the direct connection is established.
Direct Connect connections close after five minutes of inactivity.
1
2
3
4
5
query getDCStatus ($id: ID!){
directConnectConnectionStatus(input: {connectionID: $id}) {
status
}
}
Include the connection ID in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"id": "86d9a9ac-0229-481b-9d88-5f1bcb1b177b"
}
Example response:
1
2
3
4
5
6
7
{
"data": {
"directConnectConnectionStatus": {
"status": "READY"
}
}
}
Ping the connection to an endpoint (mutation.directConnectPing)
Ping direct connection to endpoint
The following mutation retrieves whether a Direct Connect connection is active. 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 five minutes of inactivity.
1
2
3
4
5
mutation pingDirectConnection($connectionID: ID!) {
directConnectPing(input: {connectionID: $connectionID}) {
result
}
}
Include the connection ID in the QUERY VARIABLES panel or in your variables dictionary:
1
2
3
{
"connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8"