> For the complete documentation index, see [llms.txt](https://docs.stoik.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stoik.io/help/help-center-fr/mdr/deploy/sentinelone/add-on/identity-security.md).

# Sécurité des identités

Configurez Identity Security, le SKU unifié de protection des identités de SentinelOne, sur votre Active Directory. Il couvre trois moteurs : ISPM (évaluation de la posture Active Directory), ISIDP (protection en temps réel des contrôleurs de domaine) et IDR (leurres sur les terminaux). L’intégration Microsoft Entra ID est facultative.

Tous les chemins ci-dessous font référence à la barre latérale du Singularity Operations Center (`Politiques et paramètres` est le bouton en bas de la barre latérale).

## Prérequis

* **Licences**: Endpoint (Core, Control ou Complete) + **Identity Security**, au niveau du compte *et* sur chaque Site.
* **Agents Windows**: **≥ 25.2.3.437** sur les DC, les serveurs et le serveur AD Connector. Postes de travail (IDR) : ≥ 24.1.5.277.
* **Agent Identity hérité**: les DC déjà sur l’agent Windows 25.2 : rien à faire. Uniquement si l’agent Identity hérité est encore présent : désinstallez-le, puis redémarrez (jamais en parallèle de l’agent Windows).
* **serveur AD Connector**: un serveur membre du domaine, voir [Choisir le serveur AD Connector](#choose-the-ad-connector-server).
* **Flux AD Connector → DC**: 53 · 88 · 389/636 · 445 · 5986 (WinRM HTTPS) · Journal des événements RPC.
* **Flux sortants**: HTTPS 443 / WebSocket vers la console S1 de votre région.
* **Compte de service AD**: un utilisateur standard en lecture seule, voir [Créer le compte de service AD](#create-the-ad-service-account).
* **WinRM HTTPS sur chaque DC**:

```
winrm quickconfig -transport:https     :: WinRM HTTPS (certificat émis pour le FQDN du DC)
winrm configsddl default               :: Lecture + exécution pour le compte de service
:: Pare-feu : autoriser TCP 5986 + "Remote Event Log Management (RPC / RPC-EPMAP)"
```

## Activer le moteur Identity

`Politiques et paramètres` > `Endpoint/Cloud Workload Security` > `Stratégie` > `Moteurs de détection`

1. Sélectionnez le périmètre Compte (ou Site pour un MSSP) dans le sélecteur de périmètre en haut, puis activez **Identity Detection & Response**.
2. Conservez les paramètres Identity par défaut, avec l’intervalle de mise à jour réglé sur au moins 60 min.
3. Dans `Politiques et paramètres` > `Comptes`, définissez **Mode de posture de sécurité des identités** à **Complet**.

<figure><img src="https://1428753877-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaDGGQ49Oui29Ft0kJjSm%2Fuploads%2Fgit-blob-ff47e3c5a07c99859df109907264e4d57060c7b6%2Fs1-identity-security-detection-engines-enabled.png?alt=media" alt=""><figcaption><p>Moteurs de détection > Identity Detection &#x26; Response.</p></figcaption></figure>

## Connecter Active Directory

`Politiques et paramètres` > `Identity Security` > `Active Directory` > `Connecter AD`

Les exemples de cette section utilisent une forêt fictive `acme.local`, avec le domaine enfant `corp.acme.local` (NetBIOS `CORP`).

### Créer le compte de service AD

ISPM, ISIDP et IDR n’ont besoin que de **l’accès en lecture**. Un compte Domain Admin est inutile et non recommandé. Les scripts de remédiation ISPM sont exécutés séparément, manuellement, par un Domain Admin.

<table data-search="false"><thead><tr><th>Exigence</th><th>Pourquoi</th></tr></thead><tbody><tr><td>Dédié <strong>standard</strong> utilisateur (par ex. <code>svc-s1-identity</code>)</td><td>La lecture seule suffit et garantit la traçabilité</td></tr><tr><td>Mot de passe long et aléatoire qui <strong>n’expire jamais</strong></td><td>Si le mot de passe change dans AD, la connexion est interrompue (statut <em>Désactivé</em>)</td></tr><tr><td>Créé dans la forêt <strong>domaine racine</strong></td><td>Requis pour évaluer toute la forêt avec Monitor subdomains</td></tr><tr><td>Kerberos <strong>AES 128 et AES 256</strong> coché</td><td>Requis pour l’évaluation</td></tr><tr><td>Membre de <strong>Utilisateurs de la gestion à distance</strong></td><td>Accès WinRM aux DC (menaces et certaines expositions)</td></tr><tr><td>Membre de <strong>Lecteurs du journal des événements</strong></td><td>Lit les journaux Security des DC (IP source et utilisateur dans les détections)</td></tr><tr><td>Lecture sur adminSDHolder, KRBTGT, Administrator, Domain / Schema / Enterprise Admins, conteneur MicrosoftDNS</td><td>Sinon, l’exposition « Insufficient permissions for AD exposure assessment » est levée</td></tr><tr><td>Lecture sur <code>CN=Deleted Objects</code></td><td>Détecte la suppression massive de comptes</td></tr></tbody></table>

<details>

<summary>Exemple PowerShell</summary>

À exécuter sur un DC ou avec RSAT, en ajustant les noms si nécessaire :

```powershell
# 1. Créer le compte
New-ADUser -Name "svc-s1-identity" -SamAccountName "svc-s1-identity" `
  -UserPrincipalName "svc-s1-identity@acme.local" -Path "OU=Service Accounts,DC=acme,DC=local" `
  -AccountPassword (Read-Host -AsSecureString "Password") -Enabled $true `
  -PasswordNeverExpires $true -CannotChangePassword $true `
  -KerberosEncryptionType AES128,AES256

# 2. Groupes intégrés
Add-ADGroupMember -Identity "Remote Management Users" -Members "svc-s1-identity"
Add-ADGroupMember -Identity "Event Log Readers"       -Members "svc-s1-identity"
```

```
:: 3. Droits de lecture (List Contents + Read Property), hérités
dsacls "DC=acme,DC=local" /I:T /g ACME\svc-s1-identity:LCRP
dsacls "CN=Deleted Objects,DC=acme,DC=local" /takeownership
dsacls "CN=Deleted Objects,DC=acme,DC=local" /I:T /g ACME\svc-s1-identity:LCRP

:: 4. Sur CHAQUE DC : accès WinRM et lecture du journal Security pour Network Service
winrm configsddl default                       :: ajouter le compte, vérifier Lecture + exécution
wevtutil gl security                           :: la sortie doit contenir (A;;0x1;;;S-1-5-20)
wevtutil sl security /ca:"<current SDDL>(A;;0x1;;;S-1-5-20)"
```

</details>

Avec *Surveiller les sous-domaines*, répétez les `dsacls` commandes dans chaque domaine où les autorisations par défaut ont été restreintes.

### Choisir le serveur AD Connector

* Domaine **membre** serveur, pas un DC. Exemple : `srv-s1adc01.corp.acme.local`.
* Toujours allumé et non mis en quarantaine réseau, 4 vCPU / 16 Go de RAM, agent Windows **≥ 25.2.3.437**.
* Il doit **se résoudre via DNS** et atteindre chaque domaine déclaré sur les ports 53, 88, 389/636, 445 et 5985/5986.
* Une seule forêt, même avec plusieurs domaines : **un connecteur** suffit. Forêts isolées sans relation d’approbation : un connecteur par forêt.

Vérifications rapides à exécuter depuis ce serveur :

```powershell
Resolve-DnsName corp.acme.local
Test-NetConnection dc01.corp.acme.local -Port 636     # LDAPS
Test-NetConnection dc01.corp.acme.local -Port 5986    # WinRM HTTPS
```

### Terminez l’assistant Connect AD

1. **AD Connector**: saisissez au moins 3 caractères du nom d’hôte (par ex. `srv`), choisissez le point de terminaison avec un statut vert, puis *Suivant*. Une bannière confirme la connexion au bout de quelques minutes.
2. **Domaine**: renseignez les champs du tableau ci-dessous, puis *Suivant*. La console exécute un test LDAP, et le domaine n’est enregistré que si le test réussit.
3. **Leurres**: configurez les leurres, voir [Leurres](#decoys), puis *Terminer*.

<figure><img src="https://1428753877-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaDGGQ49Oui29Ft0kJjSm%2Fuploads%2Fgit-blob-2948384debcb6e8660f9c15c95d090e84b53cdb7%2Fs1-identity-security-connect-ad-domain-form.png?alt=media" alt=""><figcaption><p>Étape Domaine de l’assistant. Dans cet exemple de documentation, LDAP et WinRM HTTP sont sélectionnés ; en production, privilégiez LDAPS et WinRM HTTPS.</p></figcaption></figure>

<table data-search="false"><thead><tr><th>Champ</th><th>Que saisir</th><th>Exemple</th></tr></thead><tbody><tr><td><strong>Site</strong></td><td>Au périmètre Compte : les sites qui héritent de ce domaine (utile pour IDR et ISIDP). « All » ne couvre pas les sites créés ultérieurement.</td><td>Paris, Lyon</td></tr><tr><td><strong>Nom de domaine</strong></td><td>Du domaine <strong>FQDN DNS</strong>, jamais le nom NetBIOS. Pour couvrir toute la forêt, saisissez le domaine racine.</td><td><code>acme.local</code> ou <code>corp.acme.local</code>, et non <code>CORP</code></td></tr><tr><td><strong>Surveiller les sous-domaines</strong></td><td>Évalue chaque domaine de la forêt (même arbre et autres arbres). Sans cette case, les sous-domaines sont détectés mais <strong>non évalués</strong>.</td><td>Coché</td></tr><tr><td><strong>FQDN du contrôleur de domaine</strong></td><td>Le FQDN de <strong>un</strong> DC du domaine, résoluble par l’AD Connector. Un RODC est accepté. Pas d’adresse IP. Les autres DC sont détectés automatiquement (PDC en premier).</td><td><code>dc01.corp.acme.local</code>, et non <code>10.0.0.10</code></td></tr><tr><td><strong>Nom d’utilisateur du domaine</strong></td><td>Le compte de service, au format UPN, NetBIOS ou nom simple</td><td><code>svc-s1-identity@acme.local</code>, <code>ACME\svc-s1-identity</code>, ou <code>svc-s1-identity</code>; pas <code>ACME.LOCAL\svc-s1-identity</code></td></tr><tr><td><strong>Mot de passe du domaine</strong></td><td>Saisissez-le avec soin : un mot de passe erroné <strong>verrouille le compte</strong> après plusieurs tentatives</td><td></td></tr><tr><td><strong>Planification de l’actualisation</strong> (jour, heure, fuseau horaire)</td><td>Actualisation des données AD, à planifier en heures creuses. Cela ne déclenche pas l’évaluation ISPM, qui reste fixée au samedi à 04:00 UTC.</td><td>Dimanche · 02:00 · Europe/Paris</td></tr></tbody></table>

### Protocoles et options

<table data-search="false"><thead><tr><th width="140">Option</th><th width="160">Choix</th><th>Prérequis et conséquences</th></tr></thead><tbody><tr><td rowspan="2"><strong>Méthode LDAP</strong></td><td><strong>LDAPS (636)</strong>, recommandé</td><td>Chiffre le trafic entre le connecteur et les DC. Nécessite un <strong>certificat serveur valide sur les DC</strong> (AD CS ou un certificat « Kerberos / Domain Controller Authentication ») et le port 636 ouvert. Vérifiez : <code>ldp.exe</code>, connexion SSL à <code>dc01.corp.acme.local:636</code>.</td></tr><tr><td><strong>LDAP (389)</strong></td><td>Canal non chiffré, réservé aux DC sans certificat ou au dépannage. L’erreur « LDAPS connection failed » vous invite à réessayer en LDAP. Ports fixes, non configurables.</td></tr><tr><td rowspan="2"><strong>Méthode WinRM</strong></td><td><strong>HTTPS (5986)</strong>, recommandé</td><td>Nécessite un écouteur HTTPS sur <strong>chaque DC</strong>, avec un certificat dont le Subject est le FQDN du DC (le certificat LDAPS fonctionne) et le port 5986 ouvert : <code>winrm quickconfig -transport:https</code>.</td></tr><tr><td><strong>HTTP (5985)</strong></td><td>Si les DC n’ont pas de certificat. L’authentification reste Kerberos, mais <code>AllowUnencrypted=true</code> est requis à la fois côté client et côté service. <strong>Sans WinRM sur tous les DC</strong>, Threat Detection échoue et certaines expositions deviennent <em>Ignorées</em>.</td></tr><tr><td><strong>Référence LDAP</strong></td><td>Coché si la forêt comporte des sous-domaines</td><td>Suit les renvois vers les sous-domaines : les stratégies ISIDP et IDR s’appliquent alors aussi aux domaines enfants, qui deviennent visibles dans la Configuration des protocoles. Le compte doit pouvoir interroger ces sous-domaines. Si vous l’activez ensuite, exécutez <em>Actualiser les données AD</em>.</td></tr><tr><td><strong>Synchronisation AD</strong></td><td>Coché</td><td>Synchronise les attributs des utilisateurs et des groupes. Requis pour Threat Detection, CCP, l’analyse des comptes compromis et l’inventaire des actifs. La première synchronisation peut prendre du temps.</td></tr><tr><td><strong>Threat Detection</strong></td><td>Coché (requiert AD Sync)</td><td>Menaces ISPM en temps réel : password spray, verrouillages et réinitialisations massifs, etc. S’appuie sur une connexion LDAP persistante au PDC et sur WinRM. La désactivation supprime les objets synchronisés.</td></tr><tr><td><strong>Accès via une relation d’approbation</strong></td><td>Uniquement pour une autre forêt approuvée</td><td>Pour évaluer un domaine dans une autre forêt en utilisant le compte de la forêt principale. Deux champs supplémentaires : <em>Nom de domaine de la relation d’approbation</em> et <em>Contrôleur de domaine de la relation d’approbation</em> (FQDN, pas d’IP). <strong>Ne peut pas être modifié</strong> ensuite : supprimer et recréer.</td></tr></tbody></table>

<details>

<summary>Exemple d’accès via une relation d’approbation</summary>

Le `filiale.local` relations d’approbation de forêt `acme.local`. Saisissez Nom de domaine = `filiale.local`, Nom d’utilisateur = `svc-s1-identity@acme.local`, Accès via une relation d’approbation = coché, Nom de domaine de la relation d’approbation = `acme.local`, Contrôleur de domaine de la relation d’approbation = `dc01.acme.local`. Le connecteur doit résoudre et atteindre les `filiale.local` DC.

</details>

### Leurres

IDR utilise ces leurres.

<table data-search="false"><thead><tr><th>Champ</th><th>Conseil</th><th>Exemple</th></tr></thead><tbody><tr><td>Pays pour le générateur de noms</td><td>Pays cohérent avec vos utilisateurs</td><td>France</td></tr><tr><td>Préfixe de service (SPN)</td><td>Le préfixe de vos vrais comptes de service, s’il y en a</td><td><code>svc</code></td></tr><tr><td>Format du nom</td><td>Même format que vos vrais noms d’utilisateur. Variables : <code>%FN%</code> (prénom), <code>%LN%</code> (nom), <code>%FNI%</code> et <code>%LNI%</code> (initiales), <code>%#n%</code> (n chiffres aléatoires).</td><td><code>%FNI%.%LN%</code> → <code>j.dupont</code></td></tr><tr><td>Format du nom d’hôte</td><td>Calqué sur la dénomination de vos postes de travail et de vos DC</td><td>Personnalisé : <code>PC-</code> + chiffres</td></tr><tr><td>Format de l’adresse IP</td><td>Plage ou CIDR de <strong>plus de 250 adresses</strong>, <strong>jamais utilisé en production</strong> (sinon faux positifs)</td><td><code>10.250.0.0/24</code></td></tr></tbody></table>

{% hint style="warning" %}
Les leurres ne peuvent plus être modifiés lorsqu’une stratégie de protection des identités active couvre le domaine.
{% endhint %}

### Après validation

* L’état du domaine passe à **Activé**. Il revient à *Désactivé* si le connecteur tombe en panne ou si le mot de passe du compte change.
* La console exécute l’apprentissage AD, la synchronisation, puis l’évaluation ISPM (environ 30 min). Plusieurs domaines ajoutés en même temps sont traités les uns après les autres.
* Des stratégies par défaut sont créées, **inactives**.
* Chaque domaine ne peut être déclaré **qu’une seule fois par organisation**. Après en avoir supprimé un, attendez 120 s avant de le recréer. Après avoir ajouté un DC, cliquez sur **Actualiser les données AD**, sinon des faux positifs DCSync apparaissent.

Si le domaine ne peut pas être enregistré, voir [Dépannage](#troubleshooting).

## Examiner la posture AD (ISPM)

`Politiques et paramètres` > `Identity Security` > `Paramètres de posture Identity`

Rien d’autre à faire : l’évaluation démarre dès que le domaine est enregistré (environ 30 min), puis s’exécute chaque samedi à 04:00 UTC.

1. Pour une analyse immédiate : **Analyser maintenant**.
2. Pour consulter les résultats : `Mauvaises configurations` > `Identité`. Traitez d’abord les expositions Critiques et Élevées (cliquez sur la mauvaise configuration, puis `Actions` > `Corriger` > `Télécharger le script`).

## Protéger les contrôleurs de domaine (ISIDP)

`Politiques et paramètres` > `Identity Security` > `Stratégies Identity` (`Stratégie du fournisseur d’identité` / `Stratégie d’accès conditionnel` onglets)

Deux stratégies par défaut ont été créées lors de l’enregistrement du domaine, **inactives et en lecture seule**. Dupliquez-les :

1. **Stratégie d’accès conditionnel**: dupliquer `Default_policy_account_ca`, ajoutez une **Basée sur les attaques** règle couvrant toutes les attaques avec l’action **Audit** , puis activez-la.
2. **Stratégie du fournisseur d’identité**: dupliquer `Default_policy_account_idp` et vérifiez ce qui suit :
   * Tous les domaines sont sélectionnés et **Appliquer aux serveurs Windows** est coché.
   * La validation PAC reste activée, sauf si une solution PAM ou JIT est en place. Mode d’apprentissage : activé, 4 jours.
   * Protocoles Kerberos, LDAP, SAMR et LSARPC cochés. Module complémentaire : *Épingler la version* à N-1.
   * Recommandé : *Configuration d'identifiants compromis* activé (bases de données de fuites, aucune atténuation au départ).
   * La stratégie CA de l'étape 1 est sélectionnée.
3. `Actions` > `Activer la stratégie`. Pour appliquer immédiatement : barre latérale `Sentinelles` > `Points de terminaison`, sélectionnez les contrôleurs de domaine, puis `Actions` > `Actions de l'agent` > `Appliquer les modifications de la stratégie d'identité`.

<figure><img src="https://1428753877-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaDGGQ49Oui29Ft0kJjSm%2Fuploads%2Fgit-blob-9a8a118214ab166837d7191294e7b3f153795fc2%2Fs1-identity-security-identity-provider-policy.png?alt=media" alt=""><figcaption><p>Stratégie du fournisseur d'identité : détection et protocoles.</p></figcaption></figure>

{% hint style="info" %}
Après quelques jours sans faux positifs, passez les règles d'attaque de *Audit* à **Bloquer**.
{% endhint %}

## Déployez des leurres sur les points de terminaison (IDR)

`Politiques et paramètres` > `Identity Security` > `Stratégies Identity` > `Stratégie de protection de l'identité`

1. Cliquez sur **Nouvelle stratégie de protection de l'identité**, avec la réponse PowerShell AD définie sur **Alerte**.
2. Ajoutez 4 règles : Administrateurs privilégiés, Comptes de service, Contrôleurs de domaine, Administrateurs délégués. Sélectionnez les objets réels, puis cochez **Ajouter des leurres** et **Masquer les objets réels**.
3. *Créer*, puis `Actions` > `Activer la stratégie`.

Testez depuis un poste de travail du domaine : `net group "Domain Admins" /domain` devrait renvoyer un compte leurre. Avec un agent 25.2.3+, la détection apparaît comme un indicateur dans `Recherche d'événements` (requête : `indicator.name = 'IdentityDeceptivePing'`). Les autres alertes se trouvent dans `Alertes`.

## Connecter Microsoft Entra ID (facultatif)

Uniquement si le client utilise Entra ID : `Politiques et paramètres` > `Comptes cloud` > `Microsoft Azure`. Vous avez besoin d'un tenant **Administrateur global** du compte et de l'ID du tenant. Facultatif : l'ID d'objet d'un groupe « utilisateurs à risque ».

1. *Connecter le compte*: saisissez **tenant**, vérifiez **Activer la sécurité des identités**.
2. Nom de la connexion, ID du tenant et **Synchroniser les comptes d'utilisateurs Microsoft Entra ID** activé.
3. Dans Azure : *Propriétés du tenant* > *Gestion des accès pour les ressources Azure = Oui*, puis déconnectez-vous et reconnectez-vous.
4. Téléchargez le modèle Terraform et exécutez-le dans Azure Cloud Shell :

```
terraform init && terraform apply -auto-approve
```

5. Collez `application_id` et `client_secret`, puis **Tout sélectionner** et onboarding automatique, et *Terminer*.

{% hint style="warning" %}
Le secret **expire après un an**: prévoyez son renouvellement.
{% endhint %}

Les résultats apparaissent dans `Mauvaises configurations` > `Identité`.

## Vérifiez qu'une alerte est déclenchée

Depuis un poste de travail joint au domaine, avec un compte de domaine, de préférence dans un environnement pilote.

1. Pour voir les résultats immédiatement : dans la stratégie du fournisseur d'identité, **désactivez temporairement le mode d'apprentissage** (pendant l'apprentissage, seules des alertes High sont déclenchées). Puis poussez la stratégie vers les contrôleurs de domaine.
2. Exécutez les commandes :

```
net group "Domain Admins" /domain      :: ISIDP (SAMR) + IDR (leurre dans la réponse)
dsquery * -filter "(admincount=1)"      :: ISIDP (LDAP), requiert les outils AD RSAT
```

3. Vérifiez le `Alertes` barre latérale (période *Dernière heure*), **Moteur de détection** filtre :
   * `ADSecure-DC`, `-SAMR` ou `-LDAP` pour ISIDP (énumération des comptes à privilèges).
   * `ADSecure-EP` pour IDR. Avec un agent 25.2.3+, recherchez l'indicateur dans `Recherche d'événements` à la place.
4. Réactivez le mode d'apprentissage une fois le test validé.

## Vérification finale

* Le connecteur AD affiche un statut actif dans `Politiques et paramètres` > `Identity Security` > `Active Directory`.
* Les erreurs de configuration ISPM apparaissent dans la **Mauvaises configurations** barre latérale, onglet Identité.
* La stratégie d'accès conditionnel et la stratégie du fournisseur d'identité sont actives.
* La stratégie de protection de l'identité est active.
* Le `Tableaux de bord` > `Identité` le tableau de bord affiche des données, et les alertes sont visibles dans `Alertes` > `Identité`.
* Les ressources AD et Entra sont visibles dans `Inventaire` > `Identité`.

## Dépannage

<details>

<summary>Erreur d'enregistrement : échec de l'authentification</summary>

Vérifiez le compte et le mot de passe (ainsi que tout verrouillage).

</details>

<details>

<summary>Erreur d'enregistrement : échec de la connexion LDAPS</summary>

Vérifiez le certificat du contrôleur de domaine et le port 636, ou revenez à LDAP.

</details>

<details>

<summary>Erreur d'enregistrement : le compte utilisateur n'a pas les autorisations…</summary>

Vérifiez les droits dans [Créer le compte de service AD](#create-the-ad-service-account).

</details>

<details>

<summary>Erreur d'enregistrement : contrôleur de domaine hors service / indisponible / occupé</summary>

Vérifiez le DNS et les flux depuis le connecteur AD, puis réessayez.

</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.stoik.io/help/help-center-fr/mdr/deploy/sentinelone/add-on/identity-security.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.