Conversing with TanREST Part II: Taking Action

This post is the second entry of a multi-part series leading toward dynamically targeting endpoints for administrative activity by leveraging questions and actions issued via the Tanium API.  The plan for the series is as follows:

1. Starting the Conversation – Asking basic questions via the Tanium API
2. Taking Action – Issuing basic Actions via the Tanium API
3. Going to the Max – Writing basic automation to dynamically target an online audience with consideration for hard maximums
4. Bringing it Home – A real-world example of how this capability can be utilized to supplement most environments in simple, effective ways

I have written a primer for Tanium Core Platform concepts below for those that are still learning the platform. Click here to jump straight to the TanREST API content.

A Brief Primer of Tanium Core Concepts

The Tanium Core Platform is too deep to cover here but we can boil down the fundamental principles of some elements for the purposes of this post.

Sensors

The Tanium platform uses purpose-built scripts known as Sensors to gather live information from a fleet. Tanium develops their Sensors as narrowly as possible for the sake of efficiency, scalability, and interoperability with other mechanisms within the platform.

They are your eyes across the enterprise and gather information that enables you to filter down on a specific audience. Do not use Sensors to make changes to your endpoints.

Packages

Packages are perform some manner of change on a given audience. They can be comprised exclusively of a script file but may also have supplemental content as demonstrated in Updating Microsoft Teams with a Tanium Core Package and PSADT.

Questions

Questions are queries that are assembled with one or more of the aforementioned Sensors. They are comprised of a Get clause and a From clause. The Get clause defines the information of interest and the From clause defines the audience to gather that information from. For instance, one might ask the following:

Get Computer Name and IP Address and Tanium Client Subnet from all machines

This Question uses three individual Sensors (Computer Name, IP Address, Tanium Client Subnet) and presents that information in a columnar view similar to what a user can typically expect to see in a spreadsheet.

Taking Action with TanREST

We covered the basics of using TanREST in Part I: Starting the Conversation and will now build upon that foundation using two new functions; New-TaniumActionObject and New-TaniumAction. New-TaniumActionObject can be syntactically finicky to work with. I have structured the companion script to be both functional and legible.

Creating the Action Object

The example uses the New-TaniumActionObject function:

1. Name – The name of the action you intend to issue.
2. Package – The package invoked by the action on the defined audience.
3. Parameters – Parameterized packages require input to achieve the desired outcome.
4. Filter – The filtering logic used to define your target audience in tandem with Action Groups.
5. ActionGroup – Action Groups limit scoping by having the administrator choose a predefined Computer Group.
6. Expiration – The time when you wish for the action deployment to end.
7. DOT – This parameter defines the Distribute Over Time configuration

The New-TaniumActionObject validates a given input and returns a valid Tanium object as a Hashtable. The Hashtable values stored in the actionObject property of the $exampleObject PSCustomObject.

You can explore the makeup of any of these values with the understanding that some of the values may be Hashtables themselves. For example:

Sending the Action Object via TanREST

The next step in the process is to leverage the New-TaniumAction function. This function sends our newly constructed action object to the Tanium API for processing.

The snippet above may look a bit odd if you have not worked with many objects before. We can summarize that command in the following way:

• Use the validated action object, stored in the actionObject property of the $exampleObject PSCustomObject, by passing it to the -Data parameter of the New-TaniumAction function.
• Capture the returned output of the command in the action property of the $exampleObject PSCustomObject.

The action property of the $exampleObject PSCustomObject is populated with details about the action that we submitted via TanREST.

The reason that these details are valuable is because one can begin creating chains of programmatic logic depending on the outcomes of a given action. If I wanted to create a follow-up action based on the outcome of the action I just submitted, I could easily use the Get-TaniumCoreAction function and pass the id subproperty of the action property in the $exampleObject PSCustomObject. One can monitor the status property, for example, and make subsequent automation contingent upon that status transitioning from Open to Closed.

We can also view the action we created with TanREST via the Action History page.

Disclaimer: Any code made available on this site is free to use at your own discretion but it is provided without any explicit or implied guarantees of support, reliability, or functionality. I accept no responsibility in the event that the code, in its original form or any derivative versions thereafter, malfunctions or causes problems . Anything from this site that you decide to work with should be tested thoroughly in development environments in collaboration with your Technical Account Manager (TAM) until such time that you, the responsible party, decides that you are satisfied with its outcomes.