Reference: API Gateway examples for Direct Connect

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

Example response:

1
2
3
4
5
6
7
{
  "data": {
    "directConnectPing": {
      "result": true
    }
  }
}

Get data from endpoint

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

1
2
3
4
5
6
7
query getEndpointData ($id: ID!){
  directConnectEndpoint (input : {ConnectionID: $id}) {
    performance {
      cpuUsagePercent
    }
  }
}

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

1
2
3
{
  "id": "12345678-90ab-cdef-1234-567890abcdef"
}

Example response:

1
2
3
4
5
6
7
8
9
{
  "data": {
    "directConnectEndpoint": {
      "performance": {
        "cpuUsagePercent": 28.751501243887798
      }
    }
  }
}

Get process from endpoint

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
query getEndpointProcess ($id: ID!){
  directConnectEndpoint (input : {connectionID: $id}) {
    processes {
      all {
        pid
        ppid
        name
        commandLine
        userName
        groupName
        memoryResidentBytes
      }
    }
  }
}

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
30
31
32
33
34
35
36
37
{
  "data": {
    "directConnectEndpoint": {
      "processes": {
        "all": [
          {
            "pid": 2092,
            "ppid": 496,
            "name": "TaniumReceiver.exe",
            "commandLine": "\"C:\\Program Files\\Tanium\\Tanium Server\\TaniumReceiver.exe\" --service",
            "userName": "admin",
            "groupName": "test-group",
            "memoryResidentBytes": 59842560
          },
          {
            "pid": 5760,
            "ppid": 1112,
            "name": "TaniumClient.exe",
            "commandLine": "\"C:\\Program Files (x86)\\Tanium\\Tanium Client\\TaniumClient.exe\" -c",
            "userName": "SYSTEM",
            "groupName": "NT AUTHORITY",
            "memoryResidentBytes": 17965056
          },
          {
            "pid": 1036,
            "ppid": 496,
            "name": "TaniumBlobService.exe",
            "commandLine": "\"C:\\Program Files\\Tanium\\Tanium Module Server\\services\\blob-service\\TaniumBlobService.exe\"",
            "userName": "SYSTEM",
            "groupName": "NT AUTHORITY",
            "memoryResidentBytes": 7426048
          }
        ]
      }
    }
  }
}

Get past 24 hours of alerts from endpoint

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
query getEndpointAlerts ($id: ID!){
  directConnectEndpoint (input : {connectionID: $id}) {
    alerts {
      all {
        schema
        key
        type
        ref
        topProcessesExpr
        labels
        pendingAt
        start
        resolvedAt
        leadup
        value 
      }
    }
  }
}

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

1
2
3
{
  "id": "12345678-90ab-cdef-1234-567890abcdef"
}

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
{
  "data": {
    "directConnectEndpoint": {
      "alerts": {
        "all": [
          {
            "schema": 1,
            "key": "available-mem{heuristic=\"available-mem\"}",
            "type": "available-mem",
            "ref": null,
            "topProcessesExpr": null,
            "labels": {
              "heuristic": "available-mem"
            },
            "pendingAt": "2022-03-15T15:54:38.574990164Z",
            "start": "2022-03-15T15:54:38.574990164Z",
            "resolvedAt": null,
            "leadup": 300000000000,
            "value": 168.48828125
          }
        ]
      }
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
query getEndpointAlerts48Hours ($id: ID!, $startTime: Time!, $endTime: Time){
  directConnectEndpoint (input : {connectionID: $id}) {
    alerts {
      all (scope: {startTime: $startTime, endTime: $endTime}) {
        schema
        key
        type
        ref
        topProcessesExpr
        labels
        pendingAt
        start
        resolvedAt
        leadup
        value 
      }
    }
  }
}

1
2
3
4
5
{
  "id": "12345678-90ab-cdef-1234-567890abcdef",
  "startTime": "2022-01-01T00:00:00Z",
  "endTime": "2022-01-03T00:00:00Z"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
query getEndpointAlertsPriorDate ($id: ID!, $startTime: Time!){
  directConnectEndpoint (input : {connectionID: $id}) {
    alerts {
      all (scope: {startTime: $startTime}) {
        schema
        key
        type
        ref
        topProcessesExpr
        labels
        pendingAt
        start
        resolvedAt
        leadup
        value 
      }
    }
  }
}

1
2
3
4
{
  "id": "12345678-90ab-cdef-1234-567890abcdef",
  "startTime": "2022-01-01T00:00:00Z"
}

Stop endpoint process

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

1
2
3
4
5
6
7
mutation stopEndpointProcess ($connectionID: ID!, $processName: String!, $pid: Int!, $signal: Signal!){
  directConnectProcessTerminate(
    input: {connectionID: $connectionID, name: $processName, pid: $pid, signal: $signal}
  ) {
    result
  }
}

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

1
2
3
4
5
6
{
  "connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8",
  "processName": "notepad.exe",
  "pid": 7056,
  "signal": "SIGKILL"
}

Example response:

1
2
3
4
5
6
7
{
  "data": {
    "directConnectProcessTerminate": {
      "result": true
    }
  }
} 

Close endpoint connection

The following mutation closes a Direct Connect connection to an endpoint.

Direct Connect connections close after five minutes of inactivity.

1
2
3
4
5
mutation closeEndpointConnection($connectionID: ID!) {
  directConnectClose(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"
}

Example response:

1
2
3
4
5
6
7
{
  "data": {
    "directConnectClose": {
      "result": true
    }
  }
}