Les points de terminaison Netskope dataexport, également appelés points de terminaison iterator, offrent un moyen simplifié de consommer les informations du journal du locataire. Cet article décrit les meilleures pratiques pour la consommation de ces données. Netskope recommande de s'appuyer sur les clients existants pour l'intégration SIEM lorsque cela est possible en utilisant les solutions suivantes :
- Netskope Cloud Exchange: Module Log Shipper : /en/Netskope-Cloud Exchange.html
- Module complémentaire technique Netskope Splunk : https://apps.splunk.com/app/3808/
- Source de données WebTx pour Sumo Logic Netskope : https://help.sumologic.com/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/netskope-webtx-source/
Si les clients susmentionnés ne suffisent pas, Netskope fournit également un SDK python.
- Kit de développement logiciel (SDK) Python pour les points de terminaison d'exportation de données : https://pypi.org/project/netskopesdk/
Comment fonctionnent les points de terminaison des itérateurs ?
Grâce à l'utilisation d'un index, la plateforme Netskope suit la consommation des journaux par le biais d'un site opérationnel simplifié workflow qui reproduit ce que l'on voit souvent dans les forums en ligne. Lorsqu'un consommateur demande une page de données à partir du point final, Netskope fournit les données demandées en écrivant un index relatif aux données fournies. Lorsque le consommateur a terminé le traitement de la page de données demandée, il demande simplement la page de données suivante.
Chaque point d'accès stocke sa propre valeur d'index, qui est fournie par le consommateur lors d'une requête. Cela permet de paralléliser facilement les appels d'API sur plusieurs points d'extrémité simultanément.
Note
L'utilisation simultanée par plusieurs consommateurs du même point final et du même index n'est pas prise en charge et pourrait entraîner l'apparition de données manquantes sur le consommateur.
Structure d'interrogation de l'itérateur
La structure d'interrogation des points d'extrémité est très facile à construire.
https://<tenant-URL>/api/v2/<endpoint>/?operation=<operation>&index=<index>
Opérations supportées sur les itérateurs
epoch timestamp: Si un horodatage est fourni, cela indique au point d'accès Netskope de commencer à consommer les journaux par lots d'une heure à partir de cet horodatage. Vous devrez utiliser l'opération suivante pour récupérer d'autres journaux.next: La valeur de l'opération suivante demande la page de données suivante au point d'extrémité Netskope.resend: Si le consommateur n'est pas en mesure de traiter la page de données fournie, l'opération de réexpédition permet de relancer la dernière page de données demandée.
Les opérations epoch timestamp et next mettent toutes deux à jour l'index stocké dans Netskope, tandis que l'opération resend demande la page précédente sans mettre à jour l'index.
Index de l'itérateur
L'index de l'itérateur est une chaîne de caractères fournie par le consommateur et utilisée par Netskope pour stocker les valeurs de la page. Cet index doit être unique pour le consommateur afin d'éviter les problèmes de consommation de données. Le consommateur peut utiliser la même valeur d'index sur plusieurs points d'extrémité sans problème.
La chaîne d'index est utilisée lorsque plusieurs systèmes extraient des journaux. Par exemple, vous utilisez demo comme index et extrayez les enregistrements 1 à 1000. La prochaine fois que demo extraira les journaux, il extraira les journaux 1001 à 2000 (si l'extraction se fait par lots de 1000).
Si vous laissez ce champ vide et que deux systèmes extraient des journaux, le premier système extraira les journaux 1 à 1000, puis lorsque le deuxième système extraira les journaux, il extraira les journaux 1001 à 2000. Ce n'est pas optimal.
Si le système 1 (demo1) et le système 2 (demo2) tirent des journaux en même temps, chacun obtiendra 1-1000 s'il utilise des chaînes d'indexation uniques.
Le fait de ne pas utiliser d'index a des chances d'être "réutilisé". Si vous définissez votre propre index, vous pouvez garantir que vous êtes le seul à posséder cette valeur d'index et vous ne perdrez pas d'enregistrements.
Taille de la page
Les points d'extrémité de Netskope Iterator fournissent 10 000 pages d'enregistrement par appel d'API.
Temps d'attente
Chaque requête d'itérateur fournira des indications en secondes sur le temps d'attente. Cette valeur est calculée en fonction de la quantité de données renvoyées lors de votre appel à l'API.
{
"ok": 1,
"result": [
{
}
],
"wait_time": 5
Limites de taux
Il est recommandé d'utiliser les en-têtes de réponse pour gérer les limites de débit afin d'éviter les messages d'erreur 429.
- RateLimit-Limite : Les limites de débit sont appliquées par le point d'extrémité, et cette valeur indique le nombre autorisé par seconde.
- RateLimit-Remaining : Nombre de requêtes prises en charge avant que l'intervalle ne se réinitialise et ne génère un message d'erreur 429.
- RateLimit-Reset : Le temps avant que les limites de débit soient réinitialisées, cette valeur est exprimée en secondes.
HTTP/1.1 200 OK .... RateLimit-Limit: 4 RateLimit-Remaining: 1 RateLimit-Reset: 1 ...
Si un taux est dépassé, les en-têtes seront étendus et les données utiles mentionneront la raison pour laquelle la requête a renvoyé une réponse d'erreur 429.
- Réessayer après : Il s'agit du temps d'attente recommandé avant de réessayer votre requête. Cette valeur est exprimée en secondes.
HTTP/1.1 429 Too Many Requests
...
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
RateLimit-Limit: 4
...
{
"message":"API rate limit exceeded"
}
Exemple
Exemple de workflow utilisant le point d'arrivée de l'itérateur en commençant par l'enregistrement le plus ancien de Netskope.
- Créez votre requête en utilisant la valeur d'index
operation=next.https://<tenant-URL>/api/v2/events/dataexport/events/alert?operation=next&index=demo
- Examinez l’attribut
wait_timedans la réponse JSON."wait_time": 5
- Demander la page de données suivante au point d'extrémité.
https://<tenant-URL>/api/v2/events/dataexport/events/alert?operation=next&index=demo
- Répétez les étapes 2 et 3.
Codes de réponse d'erreur
| Code d'erreur | Action de l'utilisateur requise | Notes |
|---|---|---|
| 403 | Oui | Vérifiez que le jeton API V2 est associé à un point de terminaison valide et qu'il n'a pas expiré. Une nouvelle tentative ne résoudra le problème qu'après la résolution du problème de jeton en suivant les instructions. |
| 409 | Non | La demande ne peut pas être traitée pour le moment. Les points d'extrémité de la V2 de l'API DataExport ne prennent pas en charge le téléchargement simultané du même type d'événement avec le même index d'itérateur et le client doit s'assurer que la logique d'extraction des événements est monotâche. |
| 429 | Non | Trop de demandes pour le même locataire accédant au même point final. Le client est censé respecter la limite de débit pour éviter une erreur 429 et, dans le cadre de l'en-tête de réponse, il porte le temps de réinitialisation dans l'en-tête ratelimit-reset. Le client est censé dormir/attendre (ratelimit-reset) pour éviter le 429. La limite de débit actuelle est de 4 requêtes / seconde / point final. |
| 5xx | Non | Netskope a un problème temporaire de serveur pour l'une de ces raisons :
|
Utilisation de l'API de l'itérateur de statut de client
Le site Netskope Client signale périodiquement l'état du client au backend Netskope afin d'avoir une visibilité dans l'interface utilisateur du locataire sur les différents aspects des clients. Par exemple, l'état des actions initiées par l'utilisateur (activer/désactiver), l'état de l'installation/de la mise à niveau, l'état actuel du tunnel (haut/bas), etc. Les utilisateurs peuvent consulter les journaux d'état du client sur la page périphérique de l'interface utilisateur du locataire.
Grâce à l'utilisation d'un itérateur d'état du client, la plateforme Netskope suit la consommation des journaux par le biais d'un outil opérationnel simplifié workflow. Lorsqu'un consommateur demande une page d'événements d'état du client à partir du point final, Netskope fournit les événements demandés et écrit un index avec le filigrane des événements fournis. Lorsque le consommateur a terminé le traitement de la page d'événements demandée, il demande simplement la page suivante.
Le service d'itérateur de statut de client fournit une API de flux et ces API de gestion :
- API de création d'itérateur : Permet de créer un itérateur New. Appelez cette API avant d'envoyer des demandes de journaux d'événements.
- Vérifier le statut de l'itérateur API : Permet de vérifier si la création d'un itérateur est terminée.
- API Supprimer l'itérateur : Permet de supprimer un itérateur existant. En général, cette fonction est utilisée lorsque vous devez renommer un itérateur d'un certain type d'événement.
- API de recherche d'événements : Vous permet de demander des journaux d'événements à partir d'un itérateur. La réponse sera renvoyée au format CSV.
Workflow
Vous trouverez ci-dessous des exemples d'utilisation des API New pour demander des informations sur le statut du client :
- Utilisez l'API Create Iterator pour créer un itérateur pour les événements de statut de client.
POST https://my_test_tenant/api/v2/dataexport/iterator/my_test_index?eventtype=clientstatus
- Utilisez l'API Check Iterator status pour vérifier l'état de création de l'itérateur jusqu'à ce que l'état de l'itérateur soit prêt.
GET https://my_test_tenant/api/v2/dataexport/iterator/my_test_index?
- Utilisez l'API Event Fetch pour demander des événements à l'itérateur.
Get https://my_test_tenant/api/v2/dataexport/iterator/my_test_index/events?operation=next
- Examinez l'attribut wait_time dans l'en-tête de la réponse et attendez suffisamment de temps en conséquence, comme "wait_time" : 1
- Utilisez l'API Iterator Events Request pour demander des événements à l'itérateur.
Get https://my_test_tenant/api/v2/dataexport/iterator/my_test_index/events?operation=next
- Répétez les étapes 4 et 5.
Limites de l'API
- Nous n'autorisons qu'un seul itérateur de statut de client par locataire.
- Les demandes simultanées de création ou de suppression d'un itérateur ne sont pas prises en charge et peuvent entraîner l'échec de la demande.
- Le service itérateur est conçu pour diffuser les journaux d'événements récents à grande vitesse. Vous ne pouvez demander que les journaux d'événements qui ne datent pas de plus d'un certain temps ; les événements plus anciens sont automatiquement abandonnés s'ils ne sont pas demandés à temps. La durée de conservation des itérateurs de statut de client est de 7 jours.
- Les demandes simultanées de récupération d'événements sur le même itérateur ne sont pas prises en charge et entraîneront l'échec de la demande.
- Le fait que plusieurs consommateurs demandent simultanément des journaux d'événements au même itérateur n'est pas pris en charge et pourrait entraîner l'apparition de données manquantes sur le consommateur.