@cccsaurora/howler-ui 2.14.0-dev.263 → 2.14.0-dev.264

package/components/routes/help/markdown/fr/authentication.md

@@ -0,0 +1,259 @@
+<!-- docs/ingestion/authentication.fr.md -->
+
+# Authentification de Howler
+
+L'API de Howler prend en charge un certain nombre d'approches d'authentification lors de l'accès à l'API. Ce document présente les
+différentes approches et explique comment utiliser chacune d'entre elles.
+
+## Types d'authentification
+
+Il existe quatre méthodes d'authentification que l'on peut utiliser pour se connecter à l'API howler:
+
+1. Nom d'utilisateur et mot de passe
+2. Nom d'utilisateur et clé API
+3. Nom d'utilisateur et clé d'application (après connexion)
+4. Jeton d'accès OAuth
+
+Nous allons maintenant présenter les cas d'utilisation de chaque type d'authentification.
+
+### Authentification par nom d'utilisateur/mot de passe
+
+L'authentification par nom d'utilisateur et mot de passe est la méthode d'authentification la plus simple et la moins sûre. Il est peu probable qu'elle soit activée
+dans un environnement de production, elle permet aux utilisateurs de se connecter facilement à l'API Howler et d'effectuer des modifications en tant qu'utilisateur donné,
+sans avoir à se soucier de créer des clés API ou d'utiliser un fournisseur OAuth comme Keycloak ou Azure. Les utilisateurs peuvent se connecter
+en utilisant l'authentification par nom d'utilisateur et mot de passe de l'une des deux manières suivantes :
+
+#### Appel direct au point de terminaison requis (mot de passe)
+
+C'est de loin la méthode la plus simple. Il suffit d'ajouter un en-tête d'autorisation de base à la requête HTTP que vous souhaitez effectuer, et tout est pris en charge.
+que vous voulez faire, et tout est pris en charge:
+
+```bash
+echo -n "user:user" | base64 -w0
+# -> dXNlcjp1c2Vy
+```
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Basic dXNlcjp1c2Vy
+```
+
+#### Échange contre un jeton d'application (mot de passe)
+
+Il s'agit d'une approche un peu plus complexe, mais qui présente l'avantage de ne pas exposer le nom d'utilisateur et le mot de passe à chaque demande.
+à chaque requête. Vous pouvez utiliser le point de terminaison `v1/auth/login` pour échanger votre nom d'utilisateur et votre mot de passe contre un jeton d'application. Le jeton
+fonctionne de la même manière qu'un jeton d'accès OAuth - vous le fournissez à chaque requête ultérieure, et il vous authentifie jusqu'à ce que le jeton expire.
+jusqu'à ce que le jeton expire.
+
+```http
+POST $CURRENT_URL/api/v1/auth/login/
+Content-Type: application/json
+
+{
+  "user": "user",
+  "password": "user"
+}
+```
+
+Le résultat sera quelque chose comme:
+
+```json
+{
+  "api_error_message": "",
+  "api_response": {
+    "app_token": "user:5791a142067745c3af51d6596da7da8f86357a9fa92ad78d1ce118ea7d89d34e",
+    "provider": null,
+    "refresh_token": null
+  },
+  "api_server_version": "0.0.0.dev0",
+  "api_status_code": 200
+}
+```
+
+Utilisation de ce jeton dans un autre appel d'API:
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Bearer user:5791a142067745c3af51d6596da7da8f86357a9fa92ad78d1ce118ea7d89d34e
+```
+
+### Authentification par nom d'utilisateur/clé API
+
+L'authentification par nom d'utilisateur et clé API fonctionne en grande partie de la même manière que l'authentification par nom d'utilisateur/mot de passe du point de vue du client.
+Du côté du serveur, cependant, les clés API présentent plusieurs avantages essentiels. Tout d'abord, elles peuvent être facilement révoquées par l'utilisateur.
+Deuxièmement, leurs privilèges peuvent être limités, n'autorisant qu'un sous-ensemble de permissions.
+
+Il existe deux méthodes d'authentification, reflétant le nom d'utilisateur et le mot de passe:
+
+#### Appel direct au point de terminaison requis (clé API)
+
+Il suffit d'ajouter un en-tête d'autorisation de base contenant le nom d'utilisateur et la clé API à la requête HTTP que vous souhaitez effectuer, et
+tout est pris en charge:
+
+```bash
+# note the format is <username>:<apikeyname>:<secret>
+echo -n "user:devkey:user" | base64 -w0
+# -> dXNlcjpkZXZrZXk6dXNlcg==
+```
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Basic dXNlcjpkZXZrZXk6dXNlcg==
+```
+
+#### Échange contre un jeton d'application (clé API)
+
+Vous pouvez également utiliser le point de terminaison `v1/auth/login` pour échanger votre nom d'utilisateur et votre clé API contre un jeton d'application. Le jeton
+fonctionne de la même manière qu'un jeton d'accès OAuth - vous le fournissez à chaque demande ultérieure, et il vous authentifie jusqu'à ce que le jeton expire.
+
+```http
+POST $CURRENT_URL/api/v1/auth/login/
+Content-Type: application/json
+
+{
+  "user": "user",
+  "apikey": "devkey:user"
+}
+```
+
+Le résultat sera quelque chose comme:
+
+```json
+{
+  "api_error_message": "",
+  "api_response": {
+    "app_token": "user:f220eb76ff8404abfece8c0c2f3368c7d89618c776bedcd3a506843dc4a952e4",
+    "provider": null,
+    "refresh_token": null
+  },
+  "api_server_version": "0.0.0.dev0",
+  "api_status_code": 200
+}
+```
+
+Utilisation de ce jeton dans un autre appel d'API:
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Bearer user:f220eb76ff8404abfece8c0c2f3368c7d89618c776bedcd3a506843dc4a952e4
+```
+
+Notez que lorsque vous vous connectez à l'aide d'une clé d'api, les autorisations de la clé d'api continuent de s'appliquer. Ainsi, si vous essayez d'accéder à
+à un point d'accès qui requiert l'autorisation "write" avec une clé API qui n'a que l'autorisation "read", cela provoquera une erreur 403
+Forbidden (Interdit).
+
+### Authentification par jeton d'accès
+
+En plus des méthodes d'authentification fournies en interne par Howler, vous pouvez également vous authentifier avec un fournisseur OAuth externe comme Azure ou Keycloak.
+Pour ce faire, vous devez obtenir un jeton d'accès auprès de l'un de ces fournisseurs.
+Pour obtenir un jeton d'accès, il y a généralement deux flux - On-Behalf-Of, ou le flux de connexion de l'utilisateur (voir [ici](https://www.rfc-editor.org/rfc/rfc6749#section-4.1) pour un récapitulatif
+de cela). Dans le cas de Howler, le point de terminaison `v1/auth/login` est utilisé pour les étapes D & E du flux de connexion de l'utilisateur, et
+il renvoie ce qui suit:
+
+```json
+{
+  "api_response": {
+    "app_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyIn0",
+    "provider": "keycloak",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWZyZXNoIn0"
+  }
+}
+```
+
+Dans ce cas, le `app_token` est le Web Token JSON que l'application utilise comme jeton d'accès. De la même manière, le
+`refresh_token` est un autre JWT qui est utilisé pour rafraîchir le jeton d'accès si nécessaire. Enfin, le champ `provider` (fournisseur)
+indique à quel fournisseur correspond ce jeton d'accès.
+
+Une fois que vous avez ce jeton d'accès, vous pouvez simplement le transmettre dans l'en-tête Authorization :
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyIn0
+```
+
+Howler détectera automatiquement qu'il s'agit d'un JWT et le traitera comme tel. Si le jeton est valide, l'utilisateur sera
+authentifié.
+
+Afin de rafraîchir un jeton d'accès expiré, vous pouvez utiliser l'appel API suivant:
+
+```http
+POST $CURRENT_URL/api/v1/auth/login/
+Content-Type: application/json
+
+{
+  "oauth_provider": "keycloak",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWZyZXNoIn0"
+}
+```
+
+Et vous obtiendrez quelque chose comme ceci en retour:
+
+```json
+{
+  "api_response": {
+    "app_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyMiJ9",
+    "provider": "keycloak",
+    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZWZyZXNodG9rZW4yIn0"
+  }
+}
+```
+
+## Impersonation
+
+Le dernier élément important du flux d'authentification est la fonctionnalité d'usurpation d'identité. Pour qu'un compte de service
+ou un autre utilisateur puisse se faire passer pour vous (c'est-à-dire créer des alertes en votre nom), Howler permet aux utilisateurs de fournir une deuxième clé API
+afin de s'authentifier en tant qu'autre utilisateur.
+
+Avant d'utiliser la clé API d'un autre utilisateur pour vous authentifier en tant que lui, il est important que la clé API que vous utilisez ait été
+marquée comme valide pour l'usurpation d'identité - vérifiez auprès de l'utilisateur qui l'a fournie. Si c'est le cas, vous pouvez l'utiliser en formulant votre requête
+comme suit:
+
+```bash
+# Your credentials
+echo -n "admin:devkey:admin" | base64 -w0
+# -> YWRtaW46ZGV2a2V5OmFkbWlu
+
+# Their credentials
+echo -n "user:impersonate_admin:user" | base64 -w0
+# -> dXNlcjppbXBlcnNvbmF0ZV9hZG1pbjp1c2Vy
+```
+
+```alert
+Toute forme d'authentification peut être utilisée par l'usurpateur, mais les clés API validées sont la seule méthode d'authentification autorisée pour la personne dont vous usurpez l'identité.
+```
+
+```http
+GET $CURRENT_URL/api/v1/user/whoami
+Authorization: Basic YWRtaW46ZGV2a2V5OmFkbWlu
+X-Impersonating: Basic dXNlcjppbXBlcnNvbmF0ZV9hZG1pbjp1c2Vy
+```
+
+Si la configuration est correcte, le résultat sera le suivant:
+
+```json
+{
+  "api_error_message": "",
+  "api_response": {
+    "avatar": null,
+    "classification": "TLP:W",
+    "email": "user@howler.cyber.gc.ca",
+    "groups": ["USERS"],
+    "is_active": true,
+    "is_admin": false,
+    "name": "User",
+    "roles": ["user"],
+    "username": "user"
+  },
+  "api_server_version": "0.0.0.dev0",
+  "api_status_code": 200
+}
+```
+
+Notez que le serveur a renvoyé cette requête comme si vous étiez `user`, PAS `admin`. Il est cependant clairement indiqué dans les logs que c'est vous qui faites la requête:
+
+```log
+22/12/05 14:15:02 INFO howler.api.security | Authenticating user for path /api/v1/user/whoami/
+22/12/05 14:15:03 WARNING howler.api.security | admin is impersonating user
+22/12/05 14:15:03 INFO howler.api.security | Logged in as user from 127.0.0.1
+22/12/05 14:15:03 INFO howler.api | GET /api/v1/user/whoami/ - 200
+```

package/components/routes/help/markdown/fr/bundles.md

@@ -0,0 +1,70 @@
+<!-- docs/ingestion/bundles.fr.md -->
+
+# Les groupes des hits Howler
+
+Les groupes des hits peuvent être utilisés pour regrouper facilement un grand nombre d'alertes similaires, ce qui permet aux analystes de les traiter comme un seul incident. Prenons l'exemple d'un ordinateur qui effectue à plusieurs reprises un appel réseau vers `baddomain.ru` - bien qu'une alerte puisse être générée pour chaque cas où cet ordinateur accède à ce domaine, il est logique que les analystes traitent toutes ces alertes comme un seul et même cas.
+
+## Création de groupes via le client Howler
+
+Il y a plusieurs façons de créer un groupe via le client Howler:
+
+```python
+from howler_client import get_client
+
+howler = get_client("https://howler.dev.analysis.cyber.gc.ca")
+
+"""Création simultanée d'un groupe howler et de hits"""
+howler.bundle.create(
+    # Le premier argument est le hit de l'offre groupée
+    {
+        "howler.analytic": "example-test",
+        "howler.score": 0
+    },
+    # Le deuxième argument est un hit ou une liste de hits à inclure dans l'offre groupée.
+    [
+        {
+            "howler.analytic": "example-test",
+            "howler.score": 0
+        },
+        {
+            "howler.analytic": "example-test",
+            "howler.score": 0
+        }
+    ]
+)
+
+"""Création d'un groupe howler à partir de hits existants"""
+howler.bundle.create(
+    {
+        "howler.analytic": "example-test",
+        "howler.score": 0,
+        "howler.hits": ["YcUsL8QsjmwwIdstieROk", "6s7MztwuSvz6tM0PgGJhvz"]
+    },
+    # Noter: Dans les prochaines versions, vous n'aurez plus besoin d'inclure cet argument.
+    []
+)
+
+
+"""Création à partir d'une carte"""
+bundle_hit = {
+    "score": 0,
+    "bundle": True
+}
+
+map = {
+    "score": ["howler.score"],
+    "bundle": ["howler.is_bundle"]
+}
+
+howler.bundle.create_from_map("example-test", bundle_hit, map, [{"score": 0}])
+```
+
+## Visualiser les groupes sur l'interface utilisateur de Howler
+
+Afin de visualiser les groupes créés sur l'interface utilisateur de Howler, vous pouvez utiliser la requête `howler.is_bundle:true`. Cela fournira une liste de groupes créés que vous pourrez consulter.
+
+En cliquant sur un groupe, vous ouvrirez une interface de recherche légèrement différente de l'interface normale. Dans ce cas, nous filtrons automatiquement les résultats de la recherche pour n'inclure que les résultats inclus dans le groupe. Pour que cela soit évident, l'en-tête représentant le groupe apparaît au-dessus de la barre de recherche.
+
+Vous pouvez continuer à filtrer les résultats en utilisant les mêmes requêtes que d'habitude et à les visualiser comme d'habitude. Lors du triage d'un groupe, son évaluation s'appliquera à tous les hits du groupe, **sauf ceux qui ont déjà été triés**. En d'autres termes, si le groupe est ouvert, tous les hits ouverts seront évalués lorsque vous l'évaluerez.
+
+Les groupes disposent également d'un onglet **Résumé** qui n'est pas disponible pour les hits ordinaires. Cet onglet vous aidera à regrouper les données relatives à tous les résultats du groupe. Il suffit d'ouvrir l'onglet et de cliquer sur "Créer un sommaire". Notez que cette opération peut prendre un certain temps, car un grand nombre de requêtes sont exécutées pour agréger les données.

package/components/routes/help/markdown/fr/client.md

@@ -0,0 +1,209 @@
+# Documentation du client Howler
+
+Cette documentation explique comment interagir avec l'API howler en utilisant le client howler dans les environnements de développement Java et Python. Nous décrirons le processus de base de la création d'un nouveau hit dans chaque environnement ainsi que la recherche dans howler des hits correspondant à votre requête.
+
+## Mise en route
+
+### Installation
+
+Afin d'utiliser le client howler, vous devez le lister comme une dépendance dans votre projet.
+
+#### **Python**
+
+Il suffit de l'installer à l'aide de pip:
+
+```bash
+pip install howler-client
+```
+
+Vous pouvez également l'ajouter à votre requirements.txt, ou à tout autre système de gestion des dépendances que vous utilisez.
+
+### Authentification
+
+Comme indiqué dans la [Documentation sur l'authentification](/help/auth), les utilisateurs peuvent s'authentifier de différentes manières. Pour interfacer avec le client howler, cependant, le flux suggéré est d'utiliser une clé API. Avant de commencer, générons une clé.
+
+1. Ouvrez l'interface utilisateur Howler avec laquelle vous souhaitez vous interfacer.
+2. Connectez-vous, puis cliquez sur votre profil en haut à droite.
+3. Dans le menu utilisateur, cliquez sur Paramètres.
+4. Sous Sécurité de l'utilisateur, appuyez sur l'icône (+) sur la ligne Clés API.
+5. Nommez votre clé et donnez-lui les autorisations nécessaires.
+6. Appuyez sur Create (Créer) et copiez la chaîne fournie dans un endroit sûr. \*\*Vous ne reverrez plus cette chaîne.
+
+Cette clé API sera fournie à votre code par la suite.
+
+## Client Python
+
+Pour se connecter à howler en utilisant le client python, il y a un processus assez simple à suivre:
+
+```python
+from howler_client import get_client
+
+USERNAME = 'user' # Obtenez-le à partir de la page des paramètres de l'utilisateur de l'interface utilisateur de Howler.
+APIKEY = 'apikey_name:apikey_data'
+
+apikey = (USERNAME, APIKEY)
+
+howler = get_client("$CURRENT_URL", apikey=apikey)
+```
+
+Voilà, c'est fait ! Vous pouvez maintenant utiliser l'objet `howler` pour interagir avec le serveur. A quoi cela ressemble-t-il en réalité?
+
+### Créer des hits en Python
+
+Pour le client python, vous pouvez créer des hits en utilisant les fonctions `howler.hit.create` ou `howler.hit.create_from_map`.
+
+#### `create`
+
+Cette fonction prend un seul argument - soit un hit unique, soit une liste de hits, conforme au [Howler Schema] (/help/hit?tab=schema). Voici un exemple simple :
+
+```python
+# Quelques données bidons au format Howler Schema
+exemple_hit = {
+  "howler" : {
+    "analytic" : "exemple",
+    "score" : 10.0
+  },
+  "event" : {
+    "reason" : "Exemple hit"
+  }
+}
+
+howler.hit.create(example_hit)
+```
+
+Vous pouvez également ingérer des données dans un format plat :
+
+```python
+example_hit = {
+  "howler.analytic": "example",
+  "howler.score": 10.0,
+  "event.reason": "Example hit"
+}
+
+howler.hit.create(example_hit)
+```
+
+#### `create_from_map`
+
+This function takes in three arguments:
+
+- `tool name`: Le nom de l'outil d'analyse qui crée le hit
+- `map`: Une correspondance entre les données brutes que vous avez et le schéma howler
+  - Le format est un dictionnaire où les clés sont le chemin aplati des données brutes, et les valeurs sont une liste de chemins aplatis pour les champs de Howler dans lesquels les données seront copiées.
+- `documents`: Les données brutes que vous voulez ajouter à Howler.
+
+Voici un exemple simple:
+
+```python
+# La correspondance entre nos données et le schéma de Howler
+hwl_map = {
+  "file.sha256": ["file.hash.sha256", "howler.hash"],
+  "file.name": ["file.name"],
+  "src_ip": ["source.ip", "related.ip"],
+  "dest_ip": ["destination.ip", "related.ip"],
+  "time.created": ["event.start"],
+}
+
+# Quelques fausses données dans un format personnalisé que nous voulons ajouter à howler
+example_hit = {
+  "src_ip": "0.0.0.0",
+  "dest_ip": "8.8.8.8",
+  "file": {
+    "name": "hello.exe",
+    "sha256": sha256(str("hello.exe").encode()).hexdigest()
+  },
+  "time": {
+    "created": datetime.now().isoformat()
+  },
+}
+
+# Notez que le troisième argument est de type liste!
+howler.hit.create_from_map("example_ingestor", hwl_map, [example_hit])
+```
+
+### Interroger les hits en Python
+
+L'interrogation des hits avec le client python howler se fait en utilisant la fonction `howler.search.hit`. Elle possède un certain nombre d'arguments obligatoires et optionnels:
+
+- Obligatoire:
+  - `query`: requête lucene (chaîne)
+- Facultatif: `filters`: requête lucene (chaîne):
+  - `filters`: Requêtes lucene additionnelles utilisées pour filtrer les données (liste de chaînes)
+  - `fl`: Liste des champs à retourner (chaîne de champs séparés par des virgules)
+  - `offset`: Offset auquel les éléments de la requête doivent commencer (entier)
+  - `rows`: Nombre d'enregistrements à retourner (entier)
+  - `sort`: Champ utilisé pour le tri avec direction (chaîne: ex. 'id desc')
+  - `timeout`: Nombre maximum de millisecondes d'exécution de la requête (entier)
+  - `use_archive`: Interroge également l'archive
+  - `track_total_hits`: Nombre de hits à suivre (par défaut: 10k)
+
+Voici quelques exemples de requêtes:
+
+```python
+# Rechercher tous les hits créés par assemblyline, afficher les 50 premiers et ne renvoyer que leurs identifiants.
+howler.search.hit("howler.analytic:assemblyline", fl="howler.id", rows=50)
+
+# Recherche de toutes les occurrences résolues créées au cours des cinq derniers jours, avec indication de leur identifiant et de l'analyste qui les a créées. N'en afficher que dix, décalés de 40
+howler.search.hit("howler.status:resolved", filters=['event.created:[now-5d TO now]'] fl="howler.id,howler.analytic", rows=10, offset=40)
+
+# Recherche de tous les résultats, délai d'attente si la requête prend plus de 100 ms
+howler.search.hit("howler.id:*", track_total_hits=100000000, timeout=100, use_archive=True)
+```
+
+### Mise à jour des résultats
+
+Afin de mettre à jour les hits, il existe un certain nombre de fonctions supportées :
+
+- `howler.hit.update(...)`
+- `howler.hit.update_by_query(...)`
+- `howler.hit.overwrite(...)`
+
+#### `update()`
+
+Si vous souhaitez mettre à jour un hit de manière transactionnelle, vous pouvez utiliser le code suivant:
+
+```python
+hit_to_update = client.search.hit("howler.id:*", rows=1, sort="event.created desc")["items"][0]
+
+result = client.hit.update(hit_to_update["howler"]["id"], [(UPDATE_SET, "howler.score", hit_to_update["howler"]["score"] + 100)])
+```
+
+Les opérations suivantes peuvent être exécutées pour mettre à jour un résultat.
+
+**Opérations de liste:**
+
+- `UPDATE_APPEND` : Utilisé pour ajouter une valeur à une liste donnée
+- `UPDATE_APPEND_IF_MISSING` : Utilisé pour ajouter une valeur à une liste donnée si la valeur n'est pas déjà dans la liste.
+- `UPDATE_REMOVE` : Supprime une valeur donnée d'une liste
+
+**Opérations numériques:**
+
+- `UPDATE_DEC` : Diminue une valeur numérique de la quantité spécifiée.
+- `UPDATE_INC` : Incrémente une valeur numérique de la quantité spécifiée.
+- `UPDATE_MAX` : Fixe une valeur numérique au maximum de la valeur existante et de la valeur spécifiée.
+- `UPDATE_MIN` : Fixe une valeur numérique au minimum de la valeur existante et de la valeur spécifiée.
+
+**Opérations polyvalentes:**
+
+- `UPDATE_SET` : Fixe la valeur d'un champ à la valeur donnée.
+- `UPDATE_DELETE` : Supprime la valeur d'un champ donné
+
+#### `update_by_query()`
+
+Cette fonction vous permet de mettre à jour un grand nombre d'occurrences à l'aide d'une requête :
+
+```python
+client.hit.update_by_query(f'howler.analytic : "Exemple d\'analytic"', [(UPDATE_INC, "howler.score", 100)])
+```
+
+Les mêmes opérations que dans `update()` peuvent être utilisées.
+
+### `overwrite()`
+
+Cette fonction vous permet d'écraser directement un hit avec un objet hit partiel. C'est la plus facile à utiliser, mais elle perd une partie de la validation et du traitement supplémentaire des fonctions de mise à jour.
+
+```python
+hit_to_update = client.search.hit("howler.id:*", rows=1, sort="event.created desc")["items"][0]
+
+result = client.hit.overwrite(hit_to_update["howler"]["id"], {"source.ip" : "127.0.0.1", “destination.ip” : "8.8.8.8"})
+```

package/components/routes/help/markdown/fr/links.md

@@ -0,0 +1,37 @@
+# Liens du hit
+
+Afin de faciliter l'ajout d'outils supplémentaires que l'on peut utiliser pour suivre un hit, Howler permet aux utilisateurs de spécifier un ensemble de liens, ainsi qu'un titre et une icône à afficher. Cette documentation vous expliquera comment utiliser ces liens.
+
+## Specification
+
+Afin d'ajouter des liens, vous pouvez utiliser le champ `howler.links`. Ce champ contient une liste d'objets avec trois clés :
+
+```python
+hit = {
+  "howler.links": [
+    {
+      "title": "Titre du lien avec image interne",
+      "href": "https://example.com",
+      # Notez qu'il s'agit d'une autre application, et non d'un lien vers une image.
+      "icon": "superset",
+    },
+    {
+      "title": "Titre du lien avec image externe",
+      "href": "https://www.britannica.com/animal/goose-bird",
+      # Notez qu'il s'agit d'un lien vers une image. Nous ne fournissons pas d'hébergement, vous devrez donc l'héberger ailleurs !
+      "icon": "https://cdn.britannica.com/76/76076-050-39DDCBA1/goose-Canada-North-America.jpg",
+    },
+  ]
+}
+```
+
+Notez que l'icône peut être soit :
+
+1. Un nom identifiant une application liée (à partir du sélecteur d'applications), afin d'utiliser son icône.
+2. Une URL externe
+
+Si vous souhaitez utiliser une application liée, les valeurs suivantes sont actuellement prises en charge :
+
+$APP_LIST
+
+L'utilisation de l'une de ces valeurs entraîne automatiquement l'utilisation de l'icône correspondante. Inutile d'héberger la vôtre !