> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Tailscale

> Connect Tailscale to Clarion to receive network and identity events such as device approvals, key expiry, policy changes, and user lifecycle as alerts.

This guide explains how to connect Tailscale to Clarion. Once configured, Clarion receives Tailscale webhook events and creates alerts that agents can triage and investigate.

> **Note:** **Estimated time:** 5-10 minutes. You will need **Tailscale Owner or Admin** access and access to the Clarion workspace where you want to connect Tailscale.

## Prerequisites

* A Tailscale account with Owner or Admin role
* Access to the Clarion workspace where you want to configure the integration

## Add a Tailscale monitor in Clarion

The Tailscale webhook is configured as a **monitor**, so each one has its own URL and signing secret.

1. Open Clarion and go to **Integrations** → **Tailscale**.
2. In the **Monitors** section, click **Add monitor** and choose **Tailscale**.
3. Copy the generated **Webhook URL** and **Secret** shown on the monitor. You will paste these into Tailscale in the next step.

## Configure the webhook in Tailscale

1. Sign in to the [Tailscale admin console](https://login.tailscale.com/admin).
2. Navigate to **Settings** → **Webhooks**.
3. Click **Add endpoint**.
4. Paste the **Webhook URL** from Clarion into the **Endpoint URL** field.
5. Paste the **Secret** from Clarion into the **Secret** field.
6. Select the event types you want to receive. Clarion handles all Tailscale event types:
   * **Device events**: `nodeNeedsApproval`, `nodeApproved`, `nodeKeyExpiringSoon`, `nodeKeyExpiryDisabled`, `nodeKeyExpiryEnabled`, `nodeNotSeen`
   * **Policy events**: `policyUpdate`
   * **User events**: `userNeedsApproval`, `userApproved`, `userSuspended`, `userRoleUpdated`, `userCreated`, `userDeleted`
7. Click **Save**.
8. Use **Send test event** to verify the connection. Clarion will create a test alert to confirm delivery.

## Enable agent tools (API access)

Beyond receiving events, you can let Clarion agents act on your tailnet - investigating devices, users, keys, DNS, and ACL policy, and (with approval) running remediation such as deauthorizing a device or suspending a user. This uses a Tailscale **OAuth client**; the client secret is stored encrypted and is never exposed to agents.

1. Sign in to the [Tailscale admin console](https://login.tailscale.com/admin).
2. Go to **Settings** → **OAuth clients** and click **Generate OAuth client**.
3. Grant the client the scopes for the capabilities you want. The minimal set for the full tool suite is:

   * `devices:core` - list/get devices, authorize/deauthorize, expire, set tags
   * `devices:routes:read` - list device subnet routes
   * `auth_keys:read` - list auth keys
   * `users` - list/get users, suspend/restore
   * `dns:read` - read DNS nameservers, preferences, and search paths
   * `policy_file:read` - read the ACL policy file
   * `account_settings:read` - read tailnet contacts

   Grant only the scopes you need - for read-only investigation, use the `:read` scopes and omit `devices:core` and `users`.
4. Copy the **Client ID** and **Client secret** (the secret is shown only once).
5. In Clarion, go to **Integrations** → **Tailscale** → **API access (agent tools)**, paste the Client ID and secret, and click **Save**. Leave **Tailnet** blank to use the OAuth client's default tailnet.

> **Note:** The five write actions - authorize/deauthorize a device, set device tags, expire a device, and suspend/restore a user - require explicit human approval before an agent can run them. You can review and adjust approval requirements per tool under **Settings** → **Tools**.

## How severity is mapped

| Event                                                                            | Severity |
| -------------------------------------------------------------------------------- | -------- |
| `nodeNotSeen`, `userSuspended`, `nodePolicyViolation`                            | Critical |
| `nodeNeedsApproval`, `userNeedsApproval`                                         | High     |
| `policyUpdate`, `userRoleUpdated`, `nodeKeyExpiringSoon`, `nodeKeyExpiryEnabled` | Medium   |
| All other events                                                                 | Low      |

## Verifying the connection

After saving the webhook in Tailscale, send a test event from the Tailscale admin console. A test alert will appear in Clarion under **Alerts**, confirming the integration is working.