When an integration is being developed, the focus is on getting the code right: Make sure it is efficient, has proper error handling, is sufficiently tested, etc. While this is all critically important, sometimes the integrator will neglect to devote as much attention to the equally important work around roles, permissions, and user accounts associated with the configuration of the integration. There are serious security, risk, and continuity repercussions to these decisions.
Tanium uses API Tokens to authenticate calls into the REST and GraphQL APIs and these API Tokens have all the permissions of the User/Persona that generated them. Previously, session tokens were generated using a username and password. This is no longer a supported authentication method for API calls.
This article will explain how to create a minimally permissioned role and service account for an integration. It will explain how to generate API tokens with this service account for authentication with the Tanium APIs.
If you are not familiar with Tanium's RBAC model, it is strongly recommended that you familiarize yourself with it in the Tanium Resource Center before proceeding.
Creating a Custom Role
A custom role needs to be created that will grant a user the minimal required permissions needed for the integration to operate. Roles control the actions you can perform (permissions) and the data you can access with those permissions (content sets). The predefined roles that Tanium includes are designed for users interacting with Tanium via the console and are not appropriate for integrations.
In the Tanium Console, navigate to Administration > Permission > Roles and click New Role. Give your role a name and description indicating which integration it is for. You will then need to select the Permissions for your role, followed by the Content Sets.
Permissions
Choose the permissions your integration needs and add them to the role. This will vary depending on what your code does, but the table below maps the most common functions performed by integration code to the permissions required. The GraphQL schema will mention required permissions on some queries and mutations, so check this as well. Each requirement below is being done via API unless otherwise noted.
Content Sets
A Content Set is a group of Tanium Content objects that a permission is applied against. Some permissions will require you to specify a collection of content they should be used with. For example, Sensor(Read) permission will require you to select the content sets that contain the sensors that you wish to grant the integration access to read.
This will be indicated by a gray circle with a 0+ appearing next to the permission after you add it to the role.
Click the gray circle and select the necessary content sets, which will be determined by which specific data your API calls are accessing.
Direct Access of Sensors
If you are using Saved Questions, Reports, or sensorReadings in a GraphQL Endpoints query, you are accessing the sensors by their actual names. You will need to collect a list of all of the sensors that your questions, reports, or sensorReadings reference and lookup their content sets.
The Sensor Inventory List can be used to look up which content set each sensor you are accessing belongs to.
Indirect Access of Sensors
GraphQL schema fields access underlying sensors using field names that may not match the actual sensor name. Therefore, you will need to look up what those underlying sensor names are in order to find the content sets you need. Some have more have more than one sensor underlying it, so be sure to include the content sets for all of them.
The underlying sensor will be in the description of the field in the schema. Some fields with subfields use multiple sensors, in which case the sensor name will be found in the subfields.
Finding a Sensor's Content Set
Once you have the list of sensors you are accessing, both directly and indirectly, you need to look up which content set each of them belongs to. The easiest way to do that is using the sensor inventory list. It contains all of the script-based as well as the virtual sensors supplied by Tanium. If you are accessing any custom sensors, you can find their content set by navigating to Administration>Content>Sensors in the Tanium Console and searching for their name.
Common Integration Scenarios
This chart covers the permission and content set requirements for most common integration scenarios. It is intended to help you create a custom role, but is not an exhaustive list of everything you might need to include. This chart is a work in progress and we are continuing to add content to it.
Integration Requirement
Relevant APIs
Role Requirements
Generate an API Token with UI
Permissions
Content Sets
Administration>Token - Use
-
Administration>Token - View
-
Use Any Tanium API
GraphQL, All REST
Permissions
Content Sets
Administration>Token - Use
-
Use GraphQL API
GraphQL
Permissions
Content Sets
Gateway>Gateway API(Execute)
-
Rotate an API Token
GraphQL, Platform REST
Permissions
Content Sets
Administration>Token - Rotate
-
Administration>Token - Use
-
Create a Report
GraphQL reportImport mutation
Permissions
Content Sets
Reporting>Report(Write)
The content set you will create a report in
Reporting>Report API(User)
-
Create a Report with UI
Permissions
Content Sets
Reporting>Report(Write)
The content set you will create a report in
Report API(User)
-
Reporting>Reporting>Report API(Operator)
-
Read a Report
GraphQL reportResultData query
Permissions
Content Sets
Platform Content Permissions>Sensor(Read)
"Tanium Data Service" The Content Sets that contain the sensors in your repor
Reporting>Report>Reporting(Read)
The content set that contain the Report you are accessing
Reporting>Report API(User)
-
Reporting>Report API(Operator)
-
Interact>Data Collection(Operator)
-
Interact>Data Collection(Start)
-
Every report, whether custom or Tanium-managed, belongs to a content set. You'll need to select the content sets that the reports you are reading belong to. You can find the name of the content set a report belongs to by click the Data tab in the Tanium Console and selection Reports. Locate your Report Name in the list and find the corresponding value in the Content Set column in the table.
Query Endpoint Data
GraphQL endpoints query
Permissions
Content Sets
Administration>Computer Group(Read)
-
Platform Content Permissions>Sensor(Read)
"Tanium Data Service" The content sets that contain the underlying sensors for the fields you are accessing
Register Sensor for Collection
GraphQL sensorHarvest mutation
Permissions
Content Sets
Interact>Data Collection Registration(Write)
-
Interact>Ask Dynamic Questions
-
Platform Content Permissions>Sensor(Read)
"Tanium Data Service" The content set that contains the sensor you are registering
Run an Action
GraphQL actionPerform mutation
Permissions
Content Sets
Administration>Action Group(Read)
-
Administration>Computer Group(Read)
-
Platform Content Permissions>Sensor(Read)
"Tanium Data Service" The content sets that contain the sensors used in the targeting parameters
Platform Content Permissions>Package(Read)
The content set that contains the package to deploy
Platform Content Permissions>Action(Write)
The content set that contains the package to deploy
Get an Action's Status
GraphQL action query
Permissions
Content Sets
Administration>Action Group(Read)
-
Administration>Computer Group(Read)
-
Platform Content Permissions>Action(Read)
The content set that contains the package that was deployed
Platform Content Permissions>Saved Questions(Read) (not required after Platform version 7.6.2.1055)
Threat Response>Threat Response Live Connection(Write)
-
Create Saved Evidence From File (DEC)
Create Saved Evidence From Process (DEC)
Retrieve Saved Evidence
Delete Saved Evidence
Create a Snapshot (DEC)
Retrieve a Snapshot
Delete a Snapshot
Perform Threat Response Live Response Action
Insert Threat Response Intel
Terminate a Process (DEC)
Delete a File (DEC)
Retrieve a File (DEC)
Resolve Threat Response Alert
Create Computer Group
Delete Computer Group
Create Action Group
Delete Action Group
Create Patch Deployment
Stop Patch Deployment
Testing a Custom Role
Tanium Personas are a great tool for testing out a custom role. If you aren't familiar with Personas yet, please start by reading about them in the Tanium Console User Guide.
Create a new Persona to test out your custom integration role.
Assign your custom role to it.
Assign your user account to it. It is recommended to use an administrator user account in a lab for testing to ensure that any permission issues found are in the custom role rather than in your user's default role.
Add any Computer Groups your integration needs access to to the persona. If your integration needs access to all Computer Groups, then check the "Unrestricted Management Rights" option.
Once you have created your Persona, click on your account profile at the top right in the Tanium Console and select the Persona option. Apply the Persona you just created. If your new persona isn't showing up or you don't see the Persona option, you may need to refresh your browser.
Generate an API token with your account while your new persona is applied and use it to authenticate your API calls for testing. Test out all other features of your integration using this persona such as connect jobs or reports.
If any issues are found, switch back to your default role and make adjustments to the role and then try again. You can keep testing using the API token you already generated since changes to the underlying role/persona/user combination will be automatically applied to any tokens previously generated by it. Continue iterating and testing until your integration is working properly with the custom role you created.
Congratulations, this role is now ready to be used with a Service Account to run your integration!
Tanium Asset RBAC
The Tanium Asset module does not use standard Tanium RBAC rules to control which views and reports can be accessed. If access is granted with RBAC to read Asset Views with the API, then all Views will be accessible. Asset uses a different concept called Permission Groups to limit access to which endpoints a user can view data for. You can read more about setting up Asset Permission Groups in the Configuring Asset Guide.
Tanium Connect RBAC
Each connection in Tanium Connect has a user account assigned as the owner, and optionally a persona. The data that is exported from Connect is limited to the data that is accessible to the user/persona that owns it. It is recommended to set each connection's owner to a Service Account that has the minimum permissions required to access the data that you want Connect to deliver.
For more information, please read about Managing Connections in the Tanium Resource Center.
Computer Groups
We've covered how Permissions and Content Sets in a role are used to control which content can be accessed and how it can be used. Computer Groups are the other part of the Tanium RBAC model. They control which endpoints are in scope for the permissions granted by the role. The can be configured at the User, User Group, or Persona level in Tanium. You should review the documentation in the Tanium Resource Center to learn about Computer Groups and how they are used and configured for RBAC.
For the majority of integration scenarios, there is a requirement to access data about all endpoints. For this reason, selecting Unrestricted Management Rights is usually appropriate.
Creating an Integration Service Account
Why is this important?
Security: It is very unlikely that any user has the exact same permission needs as an integration. An integration is typically designed to do a narrow set of things on a narrow set of data, and security best practices dictate that roles should always be minimally provisioned to grant access to only those capabilities and data that are required. This limits the impact of a breach or misuse.
Continuity: An integration is not a person. People regularly change jobs or depart organizations, meaning their Tanium account could be deactivated or changed suddenly. If you have an integration running with an API token generated by this user account, this is likely to cause an unexpected failure. It is unlikely that you want your integrations to stop working because a personnel change. Creating a proper service account mitigates this risk.
Auditability: Having each integration run under its own service account makes it much easier to audit activity on the Tanium platform. If a human's user account is used to generate the API token that an integration is using, it can be hard to distinguish what or who initiated a particular activity when multiple integrations or integrations and humans are sharing an account. We all know that account sharing is generally considered bad practice for people, but it is also bad practice for integrations for similar reasons.
API Tokens are associated to a particular user account. A user account configured with the specific roles and computer groups required for your integration should be created. A separate user account should be created for each integration so that the permissions can be properly tailored and for auditing purposes. Following security best practices, excess permissions on any user account, including integration users, should be avoided.
This user will need to be granted access to all computer groups that contain endpoints that your integration needs to view or control. In most cases, this means Unrestricted Management Rights, but will ultimately depend on your specific use case.
A customer will need to provision this user account in their IdP. For on-prem testing, you can create a “Local Tanium User” in the TanOS menu.
Service Accounts should be used to create all Connect Jobs and API Tokens that an integration relies on.
When an integration is being developed, the focus is on getting the code right: Make sure it is efficient, has proper error handling, is sufficiently tested, etc. While this is all critically important, sometimes the integrator will neglect to devote as much attention to the equally important work around roles, permissions, and user accounts associated with the configuration of the integration. There are serious security, risk, and continuity repercussions to these decisions.
