# Tanium EDR Integration

Connect your Tanium deployment to Capsule Security to inventory your managed endpoints and discover the AI coding agents running on them.

## Overview

This integration uses Tanium's REST API to sync:

- **Devices** — Endpoint inventory from a Tanium sensor question (computer name, operating system, IP address, last logged-in user)
- **AI coding agents** — Claude Code, Cursor, GitHub Copilot, Windsurf, and similar developer agents detected from the running-process telemetry Tanium already collects on each endpoint


Capsule asks standard, out-of-the-box Tanium **sensor questions** — it does not rely on customer-specific saved questions and never installs software, deploys packages, or writes to your Tanium server. Connection is read-only, using a long-lived API token.

Tanium answers each question with a point-in-time snapshot of the endpoints currently online, so discovery reflects the fleet as it was the moment Capsule asked. Endpoints that were offline during a sync simply reappear on the next run.

> **Tanium Cloud and on-prem are both supported.** Capsule accepts any HTTPS Tanium server URL — Tanium Cloud (`https://<tenant>.cloud.tanium.com`) or a self-hosted on-prem console.


## Prerequisites

Before you begin, ensure you have:

- An active **Tanium** deployment (Tanium Cloud or on-prem) with endpoints reporting in
- Permission to create an **API token** in the Tanium console (**Administration → Permissions → API Tokens**) — typically an administrator role
- Your **Tanium Server URL** (e.g. `https://your-tenant.cloud.tanium.com`)
- The ability to add Capsule's egress IP addresses to the token's **Trusted IP allowlist** (Tanium binds API tokens to a fixed set of source IPs)
- A **Capsule Security** account with admin access


> **Required — allowlist Capsule's egress IPs.** Tanium API tokens are locked to a **Trusted IP allowlist**. Requests from any other address are rejected even when the token is valid. You must add Capsule's egress IPs to the token before the connection will succeed — contact Capsule support (support@capsule.security) for the current list.
**Recommended — grant the token fleet-wide read scope.** Capsule asks its questions over *all machines*. If the token's role is scoped to a single computer group or content set, discovery only covers that subset. For full inventory and agent discovery, mint the token from a role whose computer-group scope covers every endpoint you want inventoried. Read access is sufficient — no write or administrative action is ever taken.


## Step 1: Create an API Token in the Tanium Console

Capsule authenticates to Tanium with a long-lived **API token**. Tanium does not use OAuth — you generate the token once in the console and Capsule stores it encrypted. There is no automatic refresh, so token rotation is operator-managed.

### Steps

1. Sign in to your **Tanium console** at your server URL (e.g. `https://your-tenant.cloud.tanium.com`).
2. Navigate to **Administration → Permissions → API Tokens**.
3. Click **New API Token**.
  - **Notes / description**: Enter a descriptive label (e.g. `Capsule Security Integration`)
  - **Trusted IP addresses**: Add Capsule's egress IPs (see prerequisites). The token will only authenticate from these addresses.
  - **Expiration**: Set per your security policy. Note the expiry — Capsule cannot refresh the token automatically, so you'll re-enter a new one when it expires.
4. Confirm the token's effective role can **ask questions across all machines** and **read** the standard sensors Capsule uses: *Computer Name*, *Operating System*, *IP Address*, *Last Logged In User*, and *Running Processes*. These ship out-of-the-box with Tanium; no custom sensors are required.
5. Generate the token and **copy it immediately**. Tanium shows the token only once; if you lose it you must create a new one.
6. Note your **Server URL** — the base address of your Tanium console (e.g. `https://your-tenant.cloud.tanium.com`). This is the value you'll enter in Step 2. Capsule strips any path automatically; only the host (and port, if any) matters.


### Why a least-privilege, read-only token

Capsule only ever **asks questions and reads sensor results** — it never deploys packages, runs actions, or modifies configuration. Issue the token from a role that grants read and question-asking permission and nothing more. Avoid attaching action or administrative permissions to the token's role.

### Security notes

- Store the API token in a secrets manager. Tanium displays it only once at creation.
- The token is a bearer credential scoped to its Trusted IP allowlist — treat it as a secret.
- If the token is ever exposed, **revoke it** in **Administration → Permissions → API Tokens** and create a new one. There is no in-place rotate.
- Capsule stores the token encrypted at rest and sends it only over HTTPS, in Tanium's `session` header.


## Step 2: Configure the Integration in Capsule

Once you have the **Server URL** and **API token**, you can install the integration.

### Steps

1. Log in to the **Capsule Security** portal.
2. Click **Integrations** in the left sidebar.
3. Find the **Tanium EDR** card and click **Set up Integration**.
4. The setup form asks for two values:
  - **Server URL** — your Tanium console address (e.g. `https://your-tenant.cloud.tanium.com`). Must be a valid `https` URL.
  - **API Token** — paste the token from Step 1.
5. Click **Test connection**. Capsule makes a read-only call against your Tanium server to confirm the token is accepted and reachable from its allowlisted IPs.
6. Click **Save**.


### After setup

- Initial sync begins automatically.
- The first sync time depends on fleet size and how long Tanium takes for online endpoints to answer each question.
- View synced endpoints in **Inventory → Devices**.
- View detected AI coding agents in **Discovery → Agents**, mapped back to the device and last logged-in user they ran on.


Discovery runs on a recurring schedule to pick up new endpoints, decommissioned endpoints, and newly observed AI agents.

## How discovery works

Capsule issues two standard Tanium sensor questions per sync:

- **Device inventory** — `Get Computer Name and Operating System and IP Address and Last Logged In User from all machines`
- **AI coding agents** — a `Running Processes` query filtered to the known AI-agent process names Capsule tracks (e.g. `Get Computer Name and Running Processes from all machines with Running Processes contains "claude" or Running Processes contains "cursor" …`)


For each question, Capsule submits the query, then polls Tanium for results until enough online endpoints have answered. Because Tanium returns a point-in-time snapshot rather than an event stream, a single missed snapshot does not remove a previously discovered agent — discovered agents persist across syncs until they're consistently absent.

## Troubleshooting

### `Invalid Tanium API token` / connection test fails with 401 or 403

- The token is wrong, expired, or has been revoked. Create a fresh token in **Administration → Permissions → API Tokens** and re-enter it.
- **Most common cause:** the request's source IP isn't on the token's **Trusted IP allowlist**. Confirm Capsule's egress IPs are added to the token (contact support for the current list).
- Confirm the **Server URL** points at the same Tanium deployment the token was issued from — tokens are not portable across servers.


### Server URL rejected

- The **Server URL** must be a valid `https` URL (e.g. `https://your-tenant.cloud.tanium.com`). `http`, bare hostnames, and non-URL values are rejected. Capsule strips any path or query string — enter just the host.


### Devices appear but no AI agents are discovered

- Agent discovery depends on the matching processes actually running on managed endpoints when Capsule asks. If no AI coding agents were active on online endpoints during the sync, none are reported — they'll appear once they run and are picked up on a later sync.
- Confirm the token's role can read the **Running Processes** sensor across the computer groups you expect.


### Fewer endpoints than expected

- Tanium answers each question with the endpoints that are **online and in scope** at that moment. Offline endpoints reappear on later syncs.
- If whole segments of the fleet are missing, the token's role is likely scoped to a subset of computer groups. Re-issue the token from a role whose scope covers all the endpoints you want inventoried.


## Support

For help with this integration:

- **Email**: support@capsule.security
- **Include**: Your tenant ID, integration status, Tanium server URL, and any error messages from the Capsule portal


For Tanium API token, permission, or Trusted-IP issues:

- **Tanium console**: **Administration → Permissions → API Tokens**
- **Reference**: [Tanium Developer Portal — Introduction to APIs](https://developer.tanium.com/apis/api_intro)