> For the complete documentation index, see [llms.txt](https://docs.dispel.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dispel.com/integrate-and-administer/integrations/asset-discovery/darktrace.md).

# Darktrace

Connect Darktrace, through the ActiveAI Security Portal API, to pull discovered devices into Dispel — enriched with behavioural Model Alerts and a deep link to the Threat Visualizer — mapped to a Wick

## Overview

The Darktrace integration lets Dispel pull the devices that Darktrace's self-learning AI has discovered on your network and bring them in as Dispel devices, enriched with Darktrace's behavioural detections. You connect to your Darktrace instance once, map it to a Dispel facility and Wicket, and Dispel imports the matching devices and keeps them current on a recurring sync.

Darktrace is a cloud asset-discovery integration. Dispel authenticates to the ActiveAI Security Portal and reads through Darktrace's cloud API, and only ever reads from it. You point Dispel at your Darktrace master URL; Dispel derives your instance name from it and reaches the API through Darktrace's cloud proxy.

Because a Darktrace master represents a single environment, Dispel treats it as one site that you map to a single Wicket — there is no per-site list to work through.

#### What Dispel imports

* Devices Darktrace has discovered, matched to your existing Dispel devices by IP and MAC address and imported as new devices where there's no match.
* Darktrace Model Alerts (its behavioural detections) as findings on the matching devices, with severity derived from the model's category.
* A rich device view: an "Enriched by Darktrace" badge, a deep link to the device in the Darktrace Threat Visualizer, and a Darktrace panel showing Autonomous Response (Antigena) status, device intelligence, connectivity, and a behavioural risk score.

{% hint style="info" %}
**Where to find it.** Sign in as an organization administrator and open **Settings → Integrations**. Darktrace appears in the **Asset Discovery / Network Visibility** section. Click **Connect** on the Darktrace card to begin.
{% endhint %}

## Before you begin

You'll need the following from Darktrace:

* A Client Application created in the ActiveAI Security Portal, under **Manage Client Applications**. Creating it gives you a **Client ID** and a **Client Secret**.
* The **Darktrace Master URL** of your instance — for example `https://usw1-00000-01.cloud.darktrace.com`.

{% hint style="warning" %}
**Use ActiveAI client-application credentials — not legacy tokens.** Darktrace's cloud requires the ActiveAI Security Portal client-application (OAuth2) credentials. The older Threat-Visualizer API token/secret pair will not authenticate.
{% endhint %}

{% hint style="info" %}
**The Client Secret is shown once.** Darktrace displays the secret only when the Client Application is created. Copy it then; if you lose it, create a new Client Application.
{% endhint %}

## Connecting Darktrace

1. Go to **Settings → Integrations** and click **Connect** on the Darktrace card.
2. Optionally set a **Display Name** to tell this integration apart from others (you can connect more than one instance).
3. Fill in the connection fields:

| Field                    | Type       | Notes                                                                                                                  |
| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Darktrace Master URL** | Config     | Your Darktrace master URL, e.g. `https://your-instance.cloud.darktrace.com`. Dispel derives the instance name from it. |
| **Client ID**            | Credential | The Client ID of a Client Application created in the ActiveAI Security Portal.                                         |
| **Client Secret**        | Credential | The Client Secret shown once when the Client Application is created. Stored encrypted and never shown again.           |

4. Click **Test Connection** to confirm Dispel can authenticate. Fix any reported error before saving.
5. Click **Save**. Dispel saves the integration and immediately runs the initial sync.

{% hint style="info" %}
**How the connection works.** Dispel exchanges your Client ID and Client Secret for a short-lived token at the ActiveAI authorization server and calls the Darktrace API through the `api.darktrace.com` cloud proxy, using the instance derived from your master URL. Tokens are refreshed automatically.
{% endhint %}

{% hint style="info" %}
**Your credentials are encrypted.** The Client Secret is encrypted at rest and is never displayed again after you save. When editing later, leave credential fields blank to keep the stored values.
{% endhint %}

## Mapping the instance to a Wicket

Once the initial sync finishes, open the integration to find the **Site Mapping** section. Darktrace appears as a single site representing your instance.

> Map each vendor site to a Dispel facility and Wicket. Devices from mapped sites will be synced into Dispel.

1. Pick a **Facility**.
2. Pick a **Wicket**. If the facility has only one Wicket, Dispel selects it for you.
3. Click **Save Mappings & Import**.

Dispel imports Darktrace's devices into the mapped Wicket — you'll see progress move from waiting, to fetching, to syncing, to complete — and then reports how many devices were imported. Imported devices appear in the mapped Wicket alongside any devices you've added manually, with their Darktrace enrichment and Model Alerts attached.

## Keeping your inventory current

* Dispel re-syncs automatically on a recurring schedule, so newly discovered devices, changed details, and new Model Alerts are picked up without any action from you.
* To pull the latest inventory immediately, open the integration and choose **Refresh**.
* To change connection details or rotate credentials, edit the integration and use **Save & Sync**. Leave credential fields blank to keep the current Client Secret.

Model Alert findings refresh on every sync, and alerts Darktrace no longer reports drop off automatically.

## Connection status

Each integration shows a status so you always know where it stands:

| Status              | Meaning                                                 |
| ------------------- | ------------------------------------------------------- |
| **Not Initialized** | Saved, but the first sync hasn't run yet.               |
| **Initializing**    | Running the first sync.                                 |
| **Ready**           | Connected and synced; the mapping is applied.           |
| **Needs Refresh**   | New vendor data is available; run a refresh to pull it. |
| **Refreshing**      | A sync is in progress.                                  |
| **Pending Changes** | Mapping changes are saved but not yet applied.          |
| **Applying**        | Importing devices for your saved mapping.               |
| **Failed**          | The last operation failed — see the error guidance.     |

A separate **health badge** (Connected, Degraded, Unreachable) reflects whether Dispel can currently reach the Darktrace API.

## Troubleshooting

If a sync or test connection fails, Dispel classifies the error and suggests a fix:

| Error                     | What it usually means and how to fix it                                                                                                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Authentication Failed** | The Client ID or Client Secret was rejected. Confirm the Client Application is active in the ActiveAI Security Portal and that the secret is current — it's shown only once, so recreate the application if it was lost. |
| **Endpoint Unreachable**  | Dispel couldn't reach Darktrace. Verify the Darktrace Master URL is correct.                                                                                                                                             |
| **Connection Timed Out**  | Darktrace took too long to respond — usually a transient network issue; try again.                                                                                                                                       |
| **Configuration Error**   | The master URL looks wrong. It must be your Darktrace cloud master URL (for example `https://your-instance.cloud.darktrace.com`); Dispel derives the instance name from it.                                              |

## Frequently asked questions

<details>

<summary>Which credentials do I use — ActiveAI or the legacy API tokens?</summary>

Use ActiveAI Security Portal client-application credentials (a Client ID and Client Secret created under **Manage Client Applications**). Darktrace's cloud requires the OAuth2 client-credentials flow; the legacy Threat-Visualizer API token/secret pair will not authenticate.

</details>

<details>

<summary>What is the "master URL"?</summary>

It's the URL of your Darktrace master instance, for example `https://usw1-00000-01.cloud.darktrace.com`. Dispel derives your instance name from it and proxies API requests through `api.darktrace.com`, so you only need to provide the master URL.

</details>

<details>

<summary>What findings does Darktrace bring into Dispel?</summary>

Darktrace's Model Alerts — its behavioural detections — attached to the matching devices as findings, with severity derived from the model category. These are behavioural detections rather than CVE-based vulnerabilities.

</details>

<details>

<summary>Does Dispel trigger or change Autonomous Response (Antigena)?</summary>

No. The integration is read-only. Dispel displays Antigena status as part of the device enrichment but never triggers, modifies, or clears Autonomous Response actions in Darktrace.

</details>

<details>

<summary>Can I connect more than one Darktrace instance?</summary>

Yes. Darktrace supports multiple integrations, so you can connect several instances side by side. Give each a distinct **Display Name** to tell them apart.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dispel.com/integrate-and-administer/integrations/asset-discovery/darktrace.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.