# SentinelOne Integration

Connect your SentinelOne (Singularity) console to Capsule Security to inventory your managed endpoints and discover the AI coding agents running on them.

## Overview

This integration uses the SentinelOne Singularity Management API to sync:

- **Devices** — Endpoint inventory from the Agents API (hostnames, OS and version, agent version, IP addresses, last-logged-in user, account / site / group, last-active time)
- **AI coding agents** — Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf, and similar developer agents detected from process-launch telemetry via **Deep Visibility**


Device inventory comes from the synchronous Agents list; shadow-AI detection comes from a Deep Visibility process query run over a rolling 7-day window. Capsule connects with a read-only API token and never installs software on endpoints or writes to your SentinelOne tenant.

## Prerequisites

Before you begin, ensure you have:

- An active **SentinelOne Singularity** deployment with endpoints reporting to the console
- Access to create a **Service User** and generate an **API token** in the SentinelOne console (a console administrator role)
- Your tenant-specific **Console URL** (e.g. `https://your-instance.sentinelone.net`)
- A **Capsule Security** account with admin access


> **Recommended — Service-User token with Viewer scope at Account or Global level.** Capsule needs read access across the endpoints you want inventoried. A token scoped to a single Site only sees that Site's data; for full coverage, issue the token from a Service User scoped at the Account or Global level. Viewer is sufficient — no write scope is required.
**Recommended — Deep Visibility licensed.** Runtime detection of AI coding agents relies on **Deep Visibility** (the historical event store). If your tenant does not license Deep Visibility, the integration still installs and provides full device inventory — see [Feature availability](#feature-availability) below.


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

Capsule authenticates to SentinelOne with a long-lived API token. SentinelOne 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 **SentinelOne console** at your tenant URL (e.g. `https://your-instance.sentinelone.net`).
2. Navigate to **Settings → Users → Service Users**.
3. Click **Create New Service User** (or open an existing one).
  - **Name**: Enter a descriptive name (e.g. `Capsule Security Integration`)
  - **Scope**: Select **Account** or **Global** so the token sees all the endpoints you want inventoried. A **Site**-only scope limits the integration to that Site.
  - **Role / API permission**: Grant at least **Viewer** — this is read-only.
4. Generate the **API token** and **copy it immediately**. SentinelOne shows the token only once; if you lose it you must regenerate.
5. Note your **Console URL** — the base address of your console (e.g. `https://your-instance.sentinelone.net`). This is the value you'll enter in Step 2. Capsule strips any path automatically; only the host matters.


> **Reference:** SentinelOne's [Generating API Tokens](https://usea1-support.sentinelone.net/hc/en-us/articles/360004195934-Generating-API-Tokens) article documents the token-creation flow for your console version.


### Why a Service-User token (not a personal token)

A personal API token is tied to an individual console user — it inherits that user's scope and is revoked if the user is disabled or removed. A **Service User** token is purpose-built for integrations: it has an independent lifecycle, an explicit scope, and won't break when staff change. Always prefer a Service-User token for Capsule.

### Security notes

- Store the API token in a secrets manager. SentinelOne displays it only once at creation.
- The token is a bearer credential — anyone holding it can read your console data within its scope. Treat it as a secret.
- If the token is ever exposed, **revoke it** in **Settings → Users → Service Users** and generate a new one.
- Capsule stores the token encrypted at rest and uses it only to call the SentinelOne Management API over HTTPS.


## Step 2: Configure the Integration in Capsule

Once you have the **Console 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 **SentinelOne** card and click **Set up Integration**.
4. The setup form asks for two values:
  - **Console URL** — your tenant console address (e.g. `https://your-instance.sentinelone.net`). Must be a valid `https` URL.
  - **API Token** — paste the token from Step 1.
5. Capsule validates the credentials by making a read-only call against your console. A green **Connection successful** message confirms the token is accepted.
6. Click **Save**.


### After setup

- Initial sync begins automatically.
- The first sync typically completes in a few minutes, depending on endpoint count and the size of the 7-day Deep Visibility window Capsule queries.
- 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.

## Feature Availability

The integration runs with whatever your API token's scope and your tenant's licensing allow. Use this matrix to understand what you'll see in Capsule.

| Capsule feature | Requires |
|  --- | --- |
| **Device inventory** (hostnames, OS, agent version, IPs, last-logged-in user) | API token with **Viewer** scope |
| **AI coding-agent detection** (Claude Code, Cursor, Copilot, Codex, and others) | **Deep Visibility** licensed + token can run DV |


### Without Deep Visibility

If your tenant does not license Deep Visibility — or the Deep Visibility query times out or is unavailable during a sync — Capsule **downgrades gracefully**: device inventory still syncs in full, and the run completes without error. The **Discovery → Agents** view simply won't reflect SentinelOne-sourced runtime activity until Deep Visibility is available.

To enable AI-agent discovery, work with your SentinelOne account team to license Deep Visibility, then confirm the integration token can run DV queries — no other reconfiguration is needed.

## Troubleshooting

### `Invalid SentinelOne API token` / connection test fails with 401

- The API token is wrong, expired, or has been revoked. Generate a fresh token in **Settings → Users → Service Users** and re-enter it.
- Confirm the **Console URL** points at the same tenant the token was issued from — tokens are not portable across consoles.


### `SentinelOne API token lacks the required scope` (403)

- The token's Service User is scoped too narrowly. Re-issue the token at **Account** or **Global** scope with at least **Viewer** so it can read the endpoints you expect.


### Console URL rejected

- The **Console URL** must be a valid `https` URL (e.g. `https://your-instance.sentinelone.net`). `http`, bare hostnames, and non-URL values are rejected. Capsule strips any path or query string — enter just the console host.


### Devices appear but no AI agents are discovered

- This is expected when **Deep Visibility** is not licensed or the DV query couldn't complete — device inventory still syncs. See [Feature availability](#feature-availability).
- If Deep Visibility is licensed, confirm AI coding agents have actually launched on managed endpoints within the last 7 days, and that the token's Service User can run Deep Visibility queries.


## Support

For help with this integration:

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


For SentinelOne API token or scope issues:

- **SentinelOne console**: **Settings → Users → Service Users**
- **Reference**: [Generating API Tokens](https://usea1-support.sentinelone.net/hc/en-us/articles/360004195934-Generating-API-Tokens)