Tanium Direct Endpoint Connect (DEC)

Direct Endpoint Connect is Tanium's method to dive deeper into events on the endpoint whether that be performance or security. Tanium's architecture leverages data storage on endpoints rather than centralized locations, Direct Endpoint Connect is a tool to access full data sets. Before continuing, please read the following documentation for an introduction into DEC Tanium DEC

Use Cases

DEC is primarily used to gather full context of events that are brought about within the console. For instance, a SOC analyst wants to understand how a certain alert occurred, a DEC connection will allow to user to exam the Recorder database Client Recorder and filesystem.

Here are just a few of the many example use cases for DEC:

  1. View running processes on an endpoint
  2. Check endpoint alerts
  3. Review endpoint performance
  4. Browse an endpoint file system
  5. Retrieve files from an endpoint

Getting Started

To start using DEC, the necessary tools must be installed within the console and on the endpoint. Once the tools are installed, administrators will be able to see Direct Connect under the Administration tab. In order to make connections, first following requirements in the documentation, the user must know the ip address or computer name of desired machines. Once targeted and Direct Connect initiated, the console will track the status to indicate success or failures. Upon success, the user can follow various actions on the endpoint detailed in the documentation.

If connections are failing to initiate, a first step is to check firewall rules that would allow line of site to the module server. Review the documentation for further considerations. Tanium DEC Troubleshooting

API Gateway Examples

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


Open a connection to an 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.

Direct Connect connections close after two minutes of inactivity.

POST /plugin/products/gateway/graphql

Header Value
Content-Type application/json
session token or session id


Example request query:

mutation {
  openDirectConnection(input: {endpointID: "12323"}) {
    connectionID
  }
}

Example response body:

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

Example cURL request:

curl --request POST \
  --url https://tanium_server/plugin/products/gateway/graphql \
  --header 'Content-Type: application/json' \
  --header 'session: token-0000000000000000000000000000000000000000000000000000000000' \
  --data '{"query":"mutation { openDirectConnection(input: { endpointID: 12323 }) { connectionID } }"}'

Example Powershell request:

$headers=
$headers.Add("Content-Type", "application/json")
$headers.Add("session", "token-0000000000000000000000000000000000000000000000000000000000")
$response = Invoke-RestMethod -Uri 'https://tanium_server/plugin/products/gateway/graphql' -Method POST `
-Headers $headers -ContentType 'application/json' -Body '{"query":"mutation { openDirectConnection(input: { endpointID: 12323 }) { connectionID } }"}'

Example Python request:

import requests

url = "https://tanium_server/plugin/products/gateway/graphql"

payload = "{\"query\":\"mutation { openDirectConnection(input: { endpointID: 12323 }) { connectionID } }\"}"
headers = {
    "Content-Type": "application/json",
    "session": "token-0000000000000000000000000000000000000000000000000000000000"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Ping the connection to an endpoint

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

Direct Connect connections close after two minutes of inactivity.

POST /plugin/products/gateway/graphql

Header Value
Content-Type application/json
session token or session id


Example request query:

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


Include the connection ID in the QUERY VARIABLES panel: 

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


Example response body:

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

Example cURL request:

curl --request POST \
  --url https://tanium_server/plugin/products/gateway/graphql \
  --header 'Content-Type: application/json' \
  --header 'session: token-0000000000000000000000000000000000000000000000000000000000' \
  --data '{"query":"mutation ($connectionID: ID!) { pingDirectConnection(input: {connectionID: $connectionID}) { result } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Powershell request:

$headers=
$headers.Add("Content-Type", "application/json")
$headers.Add("session", "token-0000000000000000000000000000000000000000000000000000000000")
$response = Invoke-RestMethod -Uri 'https://tanium_server/plugin/products/gateway/graphql' -Method POST `
-Headers $headers -ContentType 'application/json' -Body '{"query":"mutation ($connectionID: ID!) { pingDirectConnection(input: {connectionID: $connectionID}) { result } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Python request:

import requests

url = "https://tanium_server/plugin/products/gateway/graphql"

payload = "{\"query\":\"mutation ($connectionID: ID!) { pingDirectConnection(input: {connectionID: $connectionID}) { result } }\",\"variables\":{\"connectionID\":\"5fc564d6-5767-47fc-abb6-25cba65409d8\"}}"
headers = {
    "Content-Type": "application/json",
    "session": "token-0000000000000000000000000000000000000000000000000000000000"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Get CPU Usage from an 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:

POST /plugin/products/gateway/graphql

Header Value
Content-Type application/json
session token or session id


Example request query:

{
  directEndpoint (input : {endpointID: "12323"}) {
    performance {
      cpuUsagePercent
    }
  }
}


Example response body:

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

Example cURL request:

curl --request POST \
  --url https://tanium_server/plugin/products/gateway/graphql \
  --header 'Content-Type: application/json' \
  --header 'session: token-0000000000000000000000000000000000000000000000000000000000' \
  --data '{"query":"{directEndpoint (input : {endpointID: \"12323\"}) { performance { cpuUsagePercent } } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Powershell request:

$headers=
$headers.Add("Content-Type", "application/json")
$headers.Add("session", "token-0000000000000000000000000000000000000000000000000000000000")
$response = Invoke-RestMethod -Uri 'https://tanium_server/plugin/products/gateway/graphql' -Method POST `
-Headers $headers -ContentType 'application/json' -Body '{"query":"{directEndpoint (input : {endpointID: \"12323\"}) { performance { cpuUsagePercent } } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Python request:

import requests

url = "https://tanium_server/plugin/products/gateway/graphql"

payload = "{\"query\":\"{directEndpoint (input : {endpointID: \\\"12323\\\"}) { performance { cpuUsagePercent } } }\",\"variables\":{\"connectionID\":\"5fc564d6-5767-47fc-abb6-25cba65409d8\"}}"
headers = {
    "Content-Type": "application/json",
    "session": "token-0000000000000000000000000000000000000000000000000000000000"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Get processes from an 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:

POST /plugin/products/gateway/graphql

Header Value
Content-Type application/json
session token or session id


Example request query:

{
  directEndpoint (input : {endpointID: "12323"}) {
    processes {
      all {
        pid
        ppid
        name
        commandLine
        userName
        groupName
        memoryResidentBytes
      }
    }
  }
}


Example response body:

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

Example cURL request:

curl --request POST \
  --url https://tanium_server/plugin/products/gateway/graphql \
  --header 'Content-Type: application/json' \
  --header 'session: token-0000000000000000000000000000000000000000000000000000000000' \
  --data '{"query":"{ directEndpoint (input : {endpointID: \"12323\"}) { processes { all { pid ppid name commandLine userName groupName memoryResidentBytes } } } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Powershell request:

$headers=
$headers.Add("Content-Type", "application/json")
$headers.Add("session", "token-0000000000000000000000000000000000000000000000000000000000")
$response = Invoke-RestMethod -Uri 'https://tanium_server/plugin/products/gateway/graphql' -Method POST `
-Headers $headers -ContentType 'application/json' -Body '{"query":"{ directEndpoint (input : {endpointID: \"12323\"}) { processes { all { pid ppid name commandLine userName groupName memoryResidentBytes } } } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Python request:

import requests

url = "https://tanium_server/plugin/products/gateway/graphql"

payload = "{\"query\":\"{ directEndpoint (input : {endpointID: \\\"12323\\\"}) { processes { all { pid ppid name commandLine userName groupName memoryResidentBytes } } } }\",\"variables\":{\"connectionID\":\"5fc564d6-5767-47fc-abb6-25cba65409d8\"}}"
headers = {
    "Content-Type": "application/json",
    "session": "token-0000000000000000000000000000000000000000000000000000000000"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Get alerts from an endpoint

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

POST /plugin/products/gateway/graphql

Header Value
Content-Type application/json
session token or session id


Example request query:

{
  directEndpoint (input : {endpointID: "12323"}) {
    alerts {
      all {
        schema
        key
        type
        ref
        topProcessesExpr
        labels
        pendingAt
        start
        resolvedAt
        leadup
        value 
      }
    }
  }
}


Example response body:

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

Example cURL request:

curl --request POST \
  --url https://tanium_server/plugin/products/gateway/graphql \
  --header 'Content-Type: application/json' \
  --header 'session: token-0000000000000000000000000000000000000000000000000000000000' \
  --data '{"query":"{ directEndpoint (input : {endpointID: \"12323\"}) { alerts { all { schema key type ref topProcessesExpr labels pendingAt start resolvedAt leadup value } } } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Powershell request:

$headers=
$headers.Add("Content-Type", "application/json")
$headers.Add("session", "token-0000000000000000000000000000000000000000000000000000000000")
$response = Invoke-RestMethod -Uri 'https://tanium_server/plugin/products/gateway/graphql' -Method POST `
-Headers $headers -ContentType 'application/json' -Body '{"query":"{ directEndpoint (input : {endpointID: \"12323\"}) { alerts { all { schema key type ref topProcessesExpr labels pendingAt start resolvedAt leadup value } } } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Python request:

import requests

url = "https://tanium_server/plugin/products/gateway/graphql"

payload = "{\"query\":\"{ directEndpoint (input : {endpointID: \\\"12323\\\"}) { alerts { all { schema key type ref topProcessesExpr labels pendingAt start resolvedAt leadup value } } } }\",\"variables\":{\"connectionID\":\"5fc564d6-5767-47fc-abb6-25cba65409d8\"}}"
headers = {
    "Content-Type": "application/json",
    "session": "token-0000000000000000000000000000000000000000000000000000000000"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Stop a process on an endpoint

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.

POST /plugin/products/gateway/graphql

Header Value
Content-Type application/json
session token or session id


Example request query:

mutation {
  killProcess(
    input: {connectionID: "5fc564d6-5767-47fc-abb6-25cba65409d8", name: "notepad.exe", pid: 7056, signal: SIGKILL}
  ) {
    result
  }
}


Example response body:

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

Example cURL request:

curl --request POST \
  --url https://tanium_server/plugin/products/gateway/graphql \
  --header 'Content-Type: application/json' \
  --header 'session: token-0000000000000000000000000000000000000000000000000000000000' \
  --data '{"query":"mutation { killProcess( input: {connectionID: \"5fc564d6-5767-47fc-abb6-25cba65409d8\", name: \"notepad.exe\", pid: 7056, signal: SIGKILL} ) { result } }"}'

Example Powershell request:

$headers=
$headers.Add("Content-Type", "application/json")
$headers.Add("session", "token-0000000000000000000000000000000000000000000000000000000000")
$response = Invoke-RestMethod -Uri 'https://tanium_server/plugin/products/gateway/graphql' -Method POST `
-Headers $headers -ContentType 'application/json' -Body '{"query":"mutation { killProcess( input: {connectionID: \"5fc564d6-5767-47fc-abb6-25cba65409d8\", name: \"notepad.exe\", pid: 7056, signal: SIGKILL} ) { result } }"}'

Example Python request:

import requests

url = "https://tanium_server/plugin/products/gateway/graphql"

payload = "{\"query\":\"mutation { killProcess( input: {connectionID: \\\"5fc564d6-5767-47fc-abb6-25cba65409d8\\\", name: \\\"notepad.exe\\\", pid: 7056, signal: SIGKILL} ) { result } }\"}"
headers = {
    "Content-Type": "application/json",
    "session": "token-0000000000000000000000000000000000000000000000000000000000"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Close connection to an endpoint

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

Direct Connect connections close after two minutes of inactivity.

POST /plugin/products/gateway/graphql

Header Value
Content-Type application/json
session token or session id


Example request query:

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


Include the connection ID in the QUERY VARIABLES panel: 

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


Example response body:

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

Example cURL request:

curl --request POST \
  --url https://tanium_server/plugin/products/gateway/graphql \
  --header 'Content-Type: application/json' \
  --header 'session: token-0000000000000000000000000000000000000000000000000000000000' \
  --data '{"query":"mutation ($connectionID: ID!) { closeDirectConnection(input: {connectionID: $connectionID}) { result } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Powershell request:

$headers=
$headers.Add("Content-Type", "application/json")
$headers.Add("session", "token-0000000000000000000000000000000000000000000000000000000000")
$response = Invoke-RestMethod -Uri 'https://tanium_server/plugin/products/gateway/graphql' -Method POST `
-Headers $headers -ContentType 'application/json' -Body '{"query":"mutation ($connectionID: ID!) { closeDirectConnection(input: {connectionID: $connectionID}) { result } }","variables":{"connectionID":"5fc564d6-5767-47fc-abb6-25cba65409d8"}}'

Example Python request:

import requests

url = "https://tanium_server/plugin/products/gateway/graphql"

payload = "{\"query\":\"mutation ($connectionID: ID!) { closeDirectConnection(input: {connectionID: $connectionID}) { result } }\",\"variables\":{\"connectionID\":\"5fc564d6-5767-47fc-abb6-25cba65409d8\"}}"
headers = {
    "Content-Type": "application/json",
    "session": "token-0000000000000000000000000000000000000000000000000000000000"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Get endpoints IDs from Tanium Data Service

The following query retrieves all endpoint IDs from Tanium Data Service. The remaining mutations will use Direct Connect to establish a connection to the endpoint with an ID of 12323.

POST /plugin/products/gateway/graphql

Header Value
Content-Type application/json
session token or session id


Example request query:

{
  endpoints {
    edges {
      node {
        id
      }
    }
  }
}


Example response body:

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

Example cURL request:

curl --request POST \
  --url https://tanium_server/plugin/products/gateway/graphql \
  --header 'Content-Type: application/json' \
  --header 'session: token-0000000000000000000000000000000000000000000000000000000000' \
  --header 'tanium_server: ' \
  --data '{"query":"{ endpoints { edges { node { id } } } }"}'

Example Powershell request:

$headers=
$headers.Add("Content-Type", "application/json")
$headers.Add("session", "token-0000000000000000000000000000000000000000000000000000000000")
$response = Invoke-RestMethod -Uri 'https://tanium_server/plugin/products/gateway/graphql' -Method POST -Headers $headers -ContentType 'application/json' -Body '{"query":"{ endpoints { edges { node { id } } } }"}'

Example Python request:

import requests

url = "https://tanium_server/plugin/products/gateway/graphql"

payload = "{\"query\":\"{ endpoints { edges { node { id } } } }\"}"
headers = {
    "Content-Type": "application/json",
    "session": "token-0000000000000000000000000000000000000000000000000000000000"
}

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)