Configuration du client de streaming d'événements

La configuration sur le client de diffusion d’événements est actuellement disponible uniquement via REST APIv2. Pour savoir comment configurer l’accès à l’API, consultez : Déploiement client de streaming d’événements .

Cette page fournit des références pour chaque point de terminaison de l'API.

Pour en savoir plus :

• Configuration du proxy pour Docker
• Red Hat et configuration de Podman
• Exemples de formats
• Accès à l'API du client de streaming d'événements

Pour visualiser une configuration étape par étape, reportez-vous au document Déploiement du client de streaming d'événements.

Définition de la norme des points finaux de l'API

Pour chaque objet, il existe cinq points d'extrémité standard :

• GET {object endpoint}: Liste de tous les objets avec leur configuration, la pagination est disponible pour les longues listes.
• POST {object endpoint}: Créer un objet New
• GET {object endpoint}/{id}: Récupérer la définition d'un seul objet
• PATCH {object endpoint}/{id}: Mise à jour de la définition d'un seul objet, il est possible de ne modifier qu'un seul des paramètres.
• DELETE {object endpoint}/{id}: Supprimer un seul objet, ce qui n'est possible que si l'objet n'est pas référencé dans une autre configuration.

Voici un exemple de format :

Chaque objet est identifié par son attribut id. Cette adresse id n'est lue qu'après la création et est unique par type d'objet.

Exemple de création

POST peut être facilement utilisé pour créer un objet New. Utilisez le bouton "Try it out" et personnalisez le json pour définir les paramètres.

Dans l'exemple suivant, un client New est créé en définissant uniquement son nom :

Dans la réponse, les paramètres non définis ont une valeur par défaut. Si id n'est pas défini lors de la création, un New est automatiquement généré :

Lire l'exemple

Les deux points de terminaison GET peuvent être utilisés pour lire la configuration existante. La "liste" renverra tous les objets, tandis que l'ajout du point de terminaison /{id} permet de lire un seul objet.

Exemple de lecture pour l'objet précédemment créé :

Exemple d'édition partielle

PATCH peut être utilisé pour modifier un objet.

Dans l'exemple suivant, nous n'activerons que le client :

La réponse renvoie la configuration complète, ce qui permet de contrôler l'état de tous les paramètres :

Supprimer l'exemple

Le point d'arrivée DELETE est utilisé pour supprimer tout objet non référencé.

Exemple :

Configuration du client

Définition de l'objet client

{
  "id": "0198",
  "name": "Client-1",
  "description": "Primary streaming client for production environment",
  "enabled": true,
  "create_by": "esc",
  "create_time": "2025-08-27T13:59:51.83Z",
  "modify_by": "esc",
  "modify_time": "2025-08-27T13:59:51.83Z"
}

• id: UUID de l'objet, peut être défini au moment de la création mais n'est lu qu'après la création.
• namenom de l'objet
• descriptiondescription de l'objet
• enabled: définit si le client est désactivé ou activé. Un client désactivé peut être installé mais ne recevra aucun journal.
• create_bycompte d'administrateur utilisé pour la création d'objets (en lecture seule)
• create_timeheure de création (en lecture seule)
• modify_bycompte d'administrateur utilisé pour la dernière modification (en lecture seule)
• modify_timeheure de la dernière modification (en lecture seule)

Points d'extrémité de l'API de l'objet client

Génération d'un jeton client

/api/v2/streamingclient/clients/{id}/token permet à un administrateur d'inscrire un client de streaming d'événements en renvoyant un jwtToken. Ce jeton est demandé lors de l'exécution du programme d'installation.

Exemple :

Configuration du format

L'objet « Format » sert à définir les champs à inclure dans le message envoyé via Syslog.

Pour en savoir plus : Exemples de formats de clients pour la diffusion en continu d'événements

Définition de l'objet format

{
  "id": "019adf54-4d79-77e4-a224-8d9a941e1dad",
  "name": "Format 1 CEF",
  "description": "Transaction Event Format 1",
  "type": "CEF",
  "definition": {
    "remove_empty_fields": true,
    "customize": true,
    "custom_fields": [
      {
        "name": "date",
        "source": "date",
        "default": ""
      },
      {
        "name": "time",
        "source": "time",
        "default": ""
      },
      {
        "name": "time-taken",
        "source": "time-taken",
        "default": ""
      },
      {
        "name": "cs-bytes",
        "source": "cs-bytes",
        "default": ""
      },
      {
        "name": "sc-bytes",
        "source": "sc-bytes",
        "default": ""
      },
      {
        "name": "bytes",
        "source": "bytes",
        "default": ""
      },
      {
        "name": "c-ip",
        "source": "c-ip",
        "default": ""
      },
      {
        "name": "s-ip",
        "source": "s-ip",
        "default": ""
      },
      {
        "name": "cs-username",
        "source": "cs-username",
        "default": ""
      },
      {
        "name": "cs-method",
        "source": "cs-method",
        "default": ""
      },
      {
        "name": "cs-uri-scheme",
        "source": "cs-uri-scheme",
        "default": ""
      },
      {
        "name": "cs-uri-query",
        "source": "cs-uri-query",
        "default": ""
      },
      {
        "name": "cs-user-agent",
        "source": "cs-user-agent",
        "default": ""
      },
      {
        "name": "cs-content-type",
        "source": "cs-content-type",
        "default": ""
      },
      {
        "name": "sc-status",
        "source": "sc-status",
        "default": ""
      },
      {
        "name": "sc-content-type",
        "source": "sc-content-type",
        "default": ""
      },
      {
        "name": "cs-dns",
        "source": "cs-dns",
        "default": ""
      },
      {
        "name": "cs-host",
        "source": "cs-host",
        "default": ""
      },
      {
        "name": "cs-uri",
        "source": "cs-uri",
        "default": ""
      },
      {
        "name": "cs-uri-port",
        "source": "cs-uri-port",
        "default": ""
      },
      {
        "name": "cs-referer",
        "source": "cs-referer",
        "default": ""
      },
      {
        "name": "x-cs-session-id",
        "source": "x-cs-session-id",
        "default": ""
      },
      {
        "name": "x-cs-access-method",
        "source": "x-cs-access-method",
        "default": ""
      },
      {
        "name": "x-cs-app",
        "source": "x-cs-app",
        "default": ""
      },
      {
        "name": "x-s-country",
        "source": "x-s-country",
        "default": ""
      },
      {
        "name": "x-s-latitude",
        "source": "x-s-latitude",
        "default": ""
      },
      {
        "name": "x-s-longitude",
        "source": "x-s-longitude",
        "default": ""
      },
      {
        "name": "x-s-location",
        "source": "x-s-location",
        "default": ""
      },
      {
        "name": "x-s-region",
        "source": "x-s-region",
        "default": ""
      },
      {
        "name": "x-s-zipcode",
        "source": "x-s-zipcode",
        "default": ""
      },
      {
        "name": "x-c-country",
        "source": "x-c-country",
        "default": ""
      },
      {
        "name": "x-c-latitude",
        "source": "x-c-latitude",
        "default": ""
      },
      {
        "name": "x-c-longitude",
        "source": "x-c-longitude",
        "default": ""
      },
      {
        "name": "x-c-location",
        "source": "x-c-location",
        "default": ""
      },
      {
        "name": "x-c-region",
        "source": "x-c-region",
        "default": ""
      },
      {
        "name": "x-c-zipcode",
        "source": "x-c-zipcode",
        "default": ""
      },
      {
        "name": "x-c-os",
        "source": "x-c-os",
        "default": ""
      },
      {
        "name": "x-c-browser",
        "source": "x-c-browser",
        "default": ""
      },
      {
        "name": "x-c-browser-version",
        "source": "x-c-browser-version",
        "default": ""
      },
      {
        "name": "x-c-device",
        "source": "x-c-device",
        "default": ""
      },
      {
        "name": "x-cs-site",
        "source": "x-cs-site",
        "default": ""
      },
      {
        "name": "x-cs-timestamp",
        "source": "x-cs-timestamp",
        "default": ""
      },
      {
        "name": "x-cs-page-id",
        "source": "x-cs-page-id",
        "default": ""
      },
      {
        "name": "x-cs-userip",
        "source": "x-cs-userip",
        "default": ""
      },
      {
        "name": "x-cs-traffic-type",
        "source": "x-cs-traffic-type",
        "default": ""
      },
      {
        "name": "x-cs-tunnel-id",
        "source": "x-cs-tunnel-id",
        "default": ""
      },
      {
        "name": "x-category",
        "source": "x-category",
        "default": ""
      },
      {
        "name": "x-other-category",
        "source": "x-other-category",
        "default": ""
      },
      {
        "name": "x-type",
        "source": "x-type",
        "default": ""
      },
      {
        "name": "x-server-ssl-err",
        "source": "x-server-ssl-err",
        "default": ""
      },
      {
        "name": "x-client-ssl-err",
        "source": "x-client-ssl-err",
        "default": ""
      },
      {
        "name": "x-transaction-id",
        "source": "x-transaction-id",
        "default": ""
      },
      {
        "name": "x-request-id",
        "source": "x-request-id",
        "default": ""
      },
      {
        "name": "x-cs-sni",
        "source": "x-cs-sni",
        "default": ""
      },
      {
        "name": "x-cs-domain-fronted-sni",
        "source": "x-cs-domain-fronted-sni",
        "default": ""
      },
      {
        "name": "x-category-id",
        "source": "x-category-id",
        "default": ""
      },
      {
        "name": "x-other-category-id",
        "source": "x-other-category-id",
        "default": ""
      },
      {
        "name": "x-sr-headers-name",
        "source": "x-sr-headers-name",
        "default": ""
      },
      {
        "name": "x-sr-headers-value",
        "source": "x-sr-headers-value",
        "default": ""
      }
    ],
    "header": [
      {
        "name": "device_vendor",
        "source": "vendor_field",
        "default": "Updated Vendor"
      },
      {
        "name": "device_product",
        "source": "product_field",
        "default": "WebTX"
      },
      {
        "name": "device_version",
        "source": "version_field",
        "default": "2.0"
      },
      {
        "name": "signature_id",
        "source": "signature_id_field",
        "default": "unknown_signature"
      },
      {
        "name": "name",
        "source": "name_field",
        "default": "unknown_name"
      },
      {
        "name": "severity",
        "source": "severity_field",
        "default": "medium"
      }
    ],
    "syslog_header": "<%priority%>%timestamp% netskope"
  },
  "create_by": "esc",
  "create_time": "2025-12-02T13:50:35.385Z",
  "modify_by": "esc",
  "modify_time": "2025-12-02T14:00:03.728Z"
}

• id: UUID de l'objet, peut être défini au moment de la création mais n'est lu qu'après la création.
• namenom de l'objet
• descriptiondescription de l'objet
• type: Formatez le type parmi les valeurs suivantes : JSON, CEF, ELFF
• definitionConfiguration de la liste des champs et de leur contenu
  • remove_empty_fields: si un champ n'a pas de valeur, cette option supprimera la clé (prise en charge pour JSON et CEF)
  • customize: activer la configuration custom_fields pour personnaliser le contenu envoyé au SIEM. Veuillez noter customize = true est désormais obligatoire.
  • custom_fieldsListe ordonnée de champs permettant la sélection, le renommage et la valeur par défaut des champs.
    • namenom du champ visible dans le SIEM
    • source: Nom du champ source Netskope, cette valeur peut être vide pour créer des champs statiques (même valeur pour tous les événements, définie par default valeur) ou doit être l’un des champs Transaction Events pris en charge.
    • default: si le champ source a une valeur vide (ou si la configuration source est vide), Event Streaming Client le remplacera par cette définition.
  • header: configuration de l'en-tête (uniquement pour le format CEF )
    • name: nom du champ CEF
    • source: Nom du champ source Netskope, cette valeur peut être vide pour créer des champs statiques (même valeur pour tous les événements, définie par default valeur) ou doit être l’un des champs Transaction Events pris en charge.
    • default: si le champ source a une valeur vide (ou si la configuration source est vide), Event Streaming Client le remplacera par cette définition.
  • syslog_header: configuration de l'en-tête ajouté au début de chaque événement syslog conformément à la RFC 3164. La chaîne peut inclure des variables encadrées par %, les variables suivantes sont prises en charge :
    • %timestamp%: heure système hôte au format UTC/GMT (RFC 3164) Mmm dd

hh:mm:ss. Il s'agit de l'heure de l'hôte et non de l'heure de l'événement.

• %hostname%Nom d'hôte du système
  • %priority%Priorité de l'événement : priorité de l'événement
  • %pid%service en cours d'exécution PID
• create_bycompte d'administrateur utilisé pour la création d'objets (en lecture seule)
• create_timeheure de création (en lecture seule)
• modify_bycompte d'administrateur utilisé pour la dernière modification (en lecture seule)
• modify_timeheure de la dernière modification (en lecture seule)

Points finaux de l'API pour les objets de format

Seuls les points de terminaison standard sont disponibles pour l'objet Format :

Configuration de la destination

Définition de l'objet de destination

Exemple avec deux cibles vers le même serveur syslog :

{
    "id": "0198eb",
    "name": "Syslog1",
    "description": "Primary SIEM destination for production logs",
    "enabled": true,
    "type": "syslog_tcp",
    "format": "0198f093",
    "targets": [
      {
        "client": "0198ec",
        "ip": "syslog1.domain.local",
        "port": 514,
        "enabled": true
      },
      {
        "client": "0198f5410",
        "ip": "syslog1.domain.local",
        "port": 514,
        "enabled": true
      }
    ],
    "create_by": "esc",
    "create_time": "2025-08-27T11:44:40.557Z",
    "modify_by": "esc",
    "modify_time": "2025-09-01T12:45:13.966Z"
  }

L'objet « Format » sert à définir les champs à inclure dans le message envoyé via Syslog.

• id: UUID de l'objet, peut être défini au moment de la création mais n'est lu qu'après la création.
• namenom de l'objet
• descriptiondescription de l'objet
• enabled: définit si la destination est désactivée ou activée. Une destination désactivée n'enverra aucun événement. Une seule destination peut être activée par locataire.
• type: soit syslog_udp soit syslog_tcp. Nous recommandons vivement syslog_tcp pour éviter la perte d’événements.
• format: l'identifiant de l'objet de format précédemment configuré
• targets: tableau référençant un client de streaming et une destination syslog. Créez un enregistrement pour chaque définition de client à syslog (le même identifiant de client peut être utilisé plusieurs fois, la même destination de serveur syslog peut être utilisée plusieurs fois).
  • client: l'identifiant de l'objet client précédemment configuré
  • ip: IP ou FQDN du serveur syslog
  • port: Port TCP/UDP du serveur syslog
  • enabledStatut de la cible : statut de la cible. Une cible désactivée ne recevra aucun événement
• create_bycompte d'administrateur utilisé pour la création d'objets (en lecture seule)
• create_timeheure de création (en lecture seule)
• modify_bycompte d'administrateur utilisé pour la dernière modification (en lecture seule)
• modify_timeheure de la dernière modification (en lecture seule)

Points finaux de l'API de l'objet de destination

Seuls les points de terminaison standard sont disponibles pour l'objet Destination :

Configuration de la diffusion du journal

Il existe actuellement trois points de terminaison pour la configuration de la diffusion des journaux. Les points de terminaison sont not et respectent la structure d'API définie dans la section « Définition standard des points de terminaison API ».

Créer un flux pour le client de diffusion d'événements

Exemple de JSON pour la création d'un flux :

{
  "streamType": "transaction",
  "name": "Transaction Stream",
  "provider": "streamingclient",
  "credential": {
    "streamingclient": {
      "client-destination": "019914ea"
    }
  },
  "compressionType": "zstd"
}

Configuration du flux de lecture

Modifier la configuration du flux

Supprimer un flux

Configuration du proxy HTTP

Si Event Streaming Client nécessite un proxy HTTP pour télécharger les mises à jour (docker pull), il doit être configuré au niveau systemd en suivant la configuration Proxy pour Docker.

Si le client de streaming d'événements nécessite un proxy HTTP pour se connecter au plan de gestion pour la configuration et les événements, il doit être configuré avec le script d'installation, comme indiqué dans Déploiement du client de streaming d'événements.