Tanium Integration

In this guide we will cover:

• Connecting to Tanium
• Determine Asset Site
• Asset Imports
• Import Assets automatically on a schedule
• Alerting

What is the Tanium integration?#

The Tanium integration with Halo can be used to import sites and assets from Tanium into Halo. Assets can be set to import automatically on a schedule so that any changes made to assets in Tanium sync over to Halo automatically. Alerts can be synced from Tanium into Halo too, having a ticket logged automatically in Halo when an alert is raised in Tanium. This integration is multi-tenanted, allowing you to connect multiple Tanium tenants to your Halo instance. 

Note: This integration is only available for cloud hosted instances of Tanium. 

Connecting to Tanium#

First head to Configuration > Integrations and enable the Tanium module.

Fig 1. Enable integration module

Once enabled click into the module to begin configuration. Click new to create a new connection.

Now you will need to enter connection details to connect your Halo instance to Tanium. 

Fig 2. Tanium connection details

Name - Here, give your connection a sensible name. 

URL - Here, enter the URL of your Tanium instance. 

API Url - Here, enter the API URL of your Tanium instance, this will usually follow the format https://YOURDOMAIN-api.cloud.tanium.com

API Token - Here, you will need to enter an API token, this will need to be generated in Tanium. 

• Expiry Date- Here, you will need to enter the expiry date of the API Token, more information on this below

Creating an API Token in Tanium#

The permissions the API token has will be inherited from the user that generates the token. Therefore, before generating the token ensure the user generating the token has a persona containing the following permissions (these permissions are required for the integration):

• 'Gateway User'
• 'Interact Basic User'

For information on how to create an API token in Tanium check out Tanium's documentation.

Note: Ensure the access token generated has permission to query assets and have the IP address of the server the integration is running from as a trusted IP address.

When generating a token in Tanium you can specify the expiry of the token (Tanium does not allow lifetime tokens), the access token will expire on this date but Halo will obtain a new token automatically prior to expiry. To allow us to automatically rotate the tokens, you will need to enter the expiry date of the token in the integration setup in Halo. This will then get automatically updated when Halo rotates the token, this only needs to be manually updated if you change the token yourself.

Once you have entered your connection details you can test the connection using the 'Test Configuration' button on the integration setup page. 

Determine Asset Site#

Now head to the 'Sites' tab. Assets in Halo need to belong to a site, as Tanium does not have a concept of 'sites' or 'customers' so you will need to configure some site rules to determine which Halo sites assets are imported into.  

Fig 3. Site import setup

To create a site mapping rule add to the 'Site Rules' table. Here you can set some criteria based on an asset field, if an asset meets this criteria it will be imported to the selected site. In the figure 4 example any assets that have the 'asset number' field starting with 'Terrys-' will be imported to the customer Terry's Chocolate and the site 'Melbourne'. 

Fig 4. Example site rule 

You will also need to set a default site, this is the site that assets will be imported to if they do not match a mapping. If you would not like assets to be imported if they do not match a site rule select 'Don't import Assets that do not match any rules'. 

Asset Imports#

Head to the 'Assets' tab. Here you will need to complete some configuration to control how assets are imported. 

Fig 5. Asset import configuration

Asset matching Field - Here you can set which field is used to match assets in Tanium to assets in Halo. The asset unique identifier field should be selected here. 

Asset Fields#

In the field mappings table you can map a Tanium field to a Halo field, this determines which field data from Tanium gets imported into in Halo. 

Fig 6. Asset field mappings

Field Type - This will be the type of Halo field the data will be imported into. See our guide on Asset Fields if you are unsure on the difference between asset fields and custom fields in Halo. 

You can also have a Tanium field create a new field against an asset in Halo by selecting '*Create a new Field during the next import*' in the Halo service desk field. 

Determine Asset types#

All assets in Halo must be assigned an asset type. Tanium does not have a concept of asset types so you will need to configure how asset types are determined for assets imported from Tanium. There are three options in Halo to control how asset types for new assets created from Tanium are determined.

Fig 7. Fields to determine asset types

First set a default asset group, this will be the group new asset types are created under (each asset type in Halo sits within an asset group). 

Use the 'Determining an Asset's type' field to determine how asset types are assigned to imported assets. The asset types of the assets can either use a fixed type for all assets, be determined from a field, or use asset type mappings that are determined using rules based on the values of the mapped asset fields.

Use a Fixed Type

If you would like all imported assets to have the same asset type when imported set the 'Determining an Asset's type' field to be 'use the same type for all Assets' then set the 'Default Asset Type' field to be the asset type you would like assets from Tanium to be. Figure 8 shows how to set this so all assets are imported as the 'Application Server' asset type. 

Fig 8. Settings for assets to be imported as the same type

Determine Asset type using a field

If you would like all imported assets' types to be determined by a particular field, set the set the 'Determining an Asset's type' field to be 'Use a field to determine each Asset's type'. Then in 'Field for determining an Asset's type' choose the field you would like the type to depend on. The field you choose must contain the name of the desired asset type, if this name can be matched to an existing asset type in Halo, it will be assigned this asset type. If the name is not the same as an asset type in Halo, a new asset type will be created. Note that the names must be identical in order to match. 

This setting is used if you have a field in Tanium that already determines an asset's type and you would like the types to be consistent between Halo and Tanium. You will still need to populate the default asset type field, assets that do not have the selected field populated will be imported as the default asset type. In figure 9 asset types will be determined by the value in the field 'Chassis Type'.

Fig 9. Settings for asset types to be determined by a field

Determine Asset type using rules

If you would like asset types to be determined by asset rules set the set the 'Determining an Asset's type' field to be 'Determine asset type using rules'. Now you will be able to set asset's types based on rules, These rules are based on field values, and if matched will assign an asset to the chosen asset type. When creating a rule first add criteria for the rule, select the Halo field that you would like to base the criteria on, then set the rule type and the outcome needed in the field to match the rule. If an asset matches this rule it will be imported as this asset type. For example, in figure 10 the rule I have set up will check the name field of an asset, if the name begins with 'LAP' the asset will be imported with the 'Laptop' asset type. 

This method is used when you would like to organise the asset types assets are created as but do not already have this information stored in a field in Tanium.

Fig 10. Determining asset type with rule setup

If an asset is imported that does not match any of these rules, it will be created under the default asset type. Alternatively, if you would like to not import assets that do not match these rules, set the 'Default Asset type' to 'Don't import assets that do not match any rules'.

User Matching

You can enable user matching using the checkbox in the User Matching section of the 'Assets' tab. Here you can set the Halo and Tanium fields to match users on. For Tanium you can choose to match on the primary user or last user logged in using the drop down. This will default to the last logged in user in line with previous versions.  

The primary Halo matching field can be chosen using the "Halo User Matching Field" drop down. You can set a secondary field to match on if the primary field fails. These fields can be allowed to partially match by selecting the checkbox shown in Fig 11. 

Fig 11. User Matching

Miscellaneous Asset import settings#

Deactivate Assets in Halo when they are deleted from Tanium (Halo Integrator only) - When an asset is deleted from Tanium they are deactivated in Halo. This will only apply when the integrator is enabled. 

Don't create new Assets - When enabled the sync/import will only update existing assets, no new assets will be created. 
Don't update the Asset type for existing or matched Assets - If enabled, any assets that match to an existing asset when importing will not update the existing asset with a different asset type from Tanium. This allows you to change asset type data in Tanium without it affecting the existing assets in Halo.

Don't update the asset site for existing or matched assets - If enabled, any assets that match to an existing asset when importing will not update the existing asset with a different site (in line with site rules). This allows you to change asset data in Tanium without it affecting the site of the existing assets in Halo.

Once you have completed the asset import configuration begin the asset import using the 'Import Assets' button. 

Import Assets automatically on a schedule#

To have assets update on a scheduled basis you will need to enable the Halo integrator for this integration. This can be done under the 'Syncing' tab by checking 'Enable the Halo Integrator for the Tanium integration'. You will then need to select 'Assets' within the 'Entities to import' field. Once enabled the sync will take place daily.

Fig 12. Enable the Halo integrator for the integration

Alerting#

Alerts in Tanium can automatically log tickets in your Halo instance, allowing you to manage alerts from your Tanium instance. Tanium webhooks are utilised for alerting functionality.

Important: Before you can setup webhooks for alerting you will need to add the webhook destination URL (your Halo instance URL) to the egress allow list. You will need to contact Tanium's support team to do this, providing them with the URL of your Halo instance. 

First, head to the 'Alerts' tab within the integration setup page in Halo. From here enable alerts. Once enabled you will see the details required for the webhook setup. The webhook will need to be setup in Tanium, but details for this webhook can be obtained from the integration setup page in Halo.

Fig 13. General webhook setup

Now, generate a 'Basic Authentication Password' and copy this, along with the basic authentication username to a notepad. 

The details required for the webhook can be found on the integration setup page by selecting the 'webhook' button. This will contain the endpoint required and instructions for creating a payload. 

Fig 14. Details for webhook

The payload of the webhook will control what information is sent over to Halo from Tanium, therefore, how the ticket in Halo is logged. Tanium will generate a payload for you based on the 'columns' you configure for the webhook. 

To create a webhook, navigate to Tanium. Now in Tanium you will need to configure your alerts to use a webhook as their destination, this will trigger a webhook to be sent when the alert is triggered. When choosing webhook as the destination you can configure the webhook from here. 

The URL for the webhook will follow the format: https://YOURHALODOMAIN/api/notify/tanium

When setting up the webhook ensure to select the authentication type 'Basic', the username and password to authenticate the webhook are obtained from the integration setup page in Halo. Each time you generate a new password, you will need to update the password against the webhook. 

For information on how to setup alerts in Tanium check out: 

• https://help.tanium.com/bundle/ug_threat_response_cloud/page/threat_response/create_configurations.html

For information on setting up webhooks (HTTP destinations) in Tanium check out:

• https://help.tanium.com/bundle/ug_connect_cloud/page/connect/http.html

Now, each time this alert is triggered in Tanium a ticket will be logged in Halo almost instantly.