API Forwarder Management
L'API Chronicle Forwarder Management vous permet d'effectuer les opérations suivantes de manière automatisée:
- Créer et gérer des redirecteurs.
- Créez et gérez des collecteurs.
- Obtenez le contenu des fichiers de configuration (
.conf) et d'authentification (_auth.conf) d'un redirecteur Chronicle.
Les redirecteurs sont composés d'un ou de plusieurs collecteurs. La configuration de chaque collecteur spécifie son mécanisme d'ingestion (par exemple, Fichier, Kafka, PCAP, Splunk ou Syslog) et son type de journal.
En supposant que les exigences matérielles sont remplies, vous pouvez utiliser plusieurs collecteurs sur le même redirecteur pour ingérer des données provenant de divers mécanismes et types de journaux. Par exemple, vous pouvez installer un redirecteur avec deux collecteurs syslog qui écoutent les données PAN_FIREWALL et CISCO_ASA_FIREWALL sur des ports distincts, respectivement.
L'API vous permet de créer des redirecteurs et leurs collecteurs dans votre instance Chronicle. Une fois qu'un redirecteur est créé, vous pouvez utiliser le point de terminaison "Generate Forwarder Files" (Générer des fichiers de redirecteur) pour obtenir le contenu des fichiers de configuration (.conf) et d'authentification (_auth.conf) d'un redirecteur (sous forme de charge utile JSON). Ces contenus peuvent ensuite être écrits dans leurs fichiers .conf respectifs en vue d'un déploiement avec le service de transfert Chronicle sur un système Windows ou Linux.
Pour obtenir des exemples Python utilisant l'API Forwarder Management, consultez le dépôt GitHub.
Créer un redirecteur et son ou ses collecteurs
Un redirecteur doit être créé avant que l'un de ses collecteurs ne puisse être créé.
Pour créer un redirecteur et son ou ses collecteurs :
- Créez un redirecteur.
- Créez un collecteur pour le redirecteur.
- (Facultatif) Répétez l'étape 2 pour ajouter d'autres collecteurs.
S'authentifier avec l'API Chronicle
Cette API Chronicle utilise le protocole OAuth 2.0 pour l'authentification et l'autorisation. Votre application peut effectuer ces tâches à l'aide de l'une des implémentations suivantes:
Utiliser la bibliothèque cliente des API Google pour le langage de votre ordinateur
Interagir directement avec le système OAuth 2.0 à l'aide du protocole HTTP
Consultez la documentation de référence sur la bibliothèque d'authentification Google en Python.
Les bibliothèques d'authentification Google constituent un sous-ensemble des bibliothèques clientes des API Google. Consultez les autres implémentations de langages.
Obtenir des identifiants d'authentification pour l'API
Votre représentant Chronicle vous fournira des identifiants de compte de service Google Developers pour permettre au client API de communiquer avec l'API.
Vous devez également indiquer l'habilitation de l'authentification lors de l'initialisation de votre client API. OAuth 2.0 utilise un champ d'application pour limiter l'accès d'une application à un compte. Lorsqu'une application demande un champ d'application, le jeton d'accès émis pour l'application est limité au champ d'application accordé.
Initialisez le client API Google à l'aide du champ d'application suivant:
https://www.googleapis.com/auth/chronicle-backstory
Exemple Python
L'exemple Python suivant montre comment utiliser les identifiants OAuth2 et le client HTTP à l'aide de google.oauth2 et googleapiclient.
# Imports required for the sample - Google Auth and API Client Library Imports.
# Get these packages from https://pypi.org/project/google-api-python-client/ or run $ pip
# install google-api-python-client from your terminal
from google.oauth2 import service_account
from googleapiclient import _auth
SCOPES = ['https://www.googleapis.com/auth/chronicle-backstory']
# The apikeys-demo.json file contains the customer's OAuth 2 credentials.
# SERVICE_ACCOUNT_FILE is the full path to the apikeys-demo.json file
# ToDo: Replace this with the full path to your OAuth2 credentials
SERVICE_ACCOUNT_FILE = '/customer-keys/apikeys-demo.json'
# Create a credential using Google Developer Service Account Credential and Chronicle API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)
# Build an HTTP client to make authorized OAuth requests.
http_client = _auth.authorized_http(credentials)
# <your code continues here>
Limites des requêtes de l'API Chronicle
L'API Chronicle impose des limites au volume de requêtes pouvant être effectuées par n'importe quel client sur la plate-forme Chronicle. Si vous atteignez ou dépassez la limite de requête, le serveur d'API Chronicle renvoie le code HTTP 429 (RESOURCE_EXHAUSTED) à l'appelant. Lorsque vous développez des applications pour l'API Chronicle, Chronicle vous recommande d'appliquer des limites de débit dans votre système pour éviter l'épuisement des ressources. Ces limites s'appliquent à toutes les API Chronicle, y compris les API Search, Forwarder Management et Tooling.
La limite suivante est appliquée pour l'API Chronicle Forwarder Management et est mesurée en requêtes par seconde (RPS):
| API Chronicle | Point de terminaison de l'API | Limite |
| Gestion du système de transfert | Créer un redirecteur | 1 RPS |
| Obtenir le redirecteur | 1 RPS | |
| Répertorier les redirecteurs | 1 RPS | |
| Mettre à jour le redirecteur | 1 RPS | |
| Supprimer le redirecteur | 1 RPS | |
| Gestion des collecteurs | Créer un collecteur | 1 RPS |
| Obtenir le collecteur | 1 RPS | |
| Répertorier les collecteurs | 1 RPS | |
| Mettre à jour le collecteur | 1 RPS | |
| Supprimer le collecteur | 1 RPS |
Documentation de référence de l'API Forwarder
Cette section décrit les points de terminaison pour la création et la gestion des redirecteurs. Pour connaître les points de terminaison permettant de créer et de gérer des collecteurs, consultez la documentation de référence de l'API Collector.
Créer un redirecteur
Crée un redirecteur dans l'instance Chronicle. Le nouveau redirecteur inclura toutes les valeurs de configuration du redirecteur fournies dans le corps de la requête. Les valeurs de configuration des collectors doivent être spécifiées via Create Collector après avoir utilisé Create Forwarder.
Pour certains paramètres, les valeurs de configuration manquantes ou ayant une valeur nulle dans le corps de la requête sont définies sur les valeurs par défaut. Pour plus d'informations sur les champs et les valeurs du redirecteur, consultez la section Champs de configuration du redirecteur.
Requête
POST https://backstory.googleapis.com/v2/forwarders
Corps de la requête
{
"display_name": string,
"config": {
object (ForwarderConfig)
}
}
Paramètres du corps
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| display_name | chaîne | Requis | Nom du redirecteur. Ce nom est affiché dans l'interface Chronicle. |
| config | objet | Facultatif | Paramètres de configuration de ce redirecteur. Consultez la section Champs de configuration du système de transfert. |
Exemple de requête
Cet exemple montre les paires clé/valeur requises dans une requête Create Forwarder. Si un champ n'est pas spécifié dans la requête et qu'il possède une valeur par défaut, celle-ci est appliquée lors de la création du redirecteur. Pour en savoir plus sur les valeurs par défaut, consultez Champs de configuration du système de transfert.
POST https://backstory.googleapis.com/v2/forwarders
{
"display_name": "chronicle_forwarder"
}
Réponse
Si la requête aboutit, la réponse renvoie le code d'état HTTP 200 (OK).
La réponse affiche les valeurs de configuration appliquées lors de la création du redirecteur. Des valeurs de configuration par défaut sont appliquées à certains paramètres lors de la création de la ressource si ces champs sont manquants ou ont une valeur nulle dans le corps de la requête. Pour en savoir plus, consultez Champs de configuration du système de transfert.
Champs de réponse
Outre les champs spécifiés dans la requête et les champs auxquels les valeurs par défaut sont appliquées, la réponse inclut les champs suivants, générés et uniquement en sortie.
| Champ | Type | Description |
|---|---|---|
| name | chaîne | ID de ressource du redirecteur. Le format est "forwarders/forwarderID". Par exemple: forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56 |
| state | enum | Spécifie l'état actuel du redirecteur. Les valeurs possibles sont les suivantes :
La valeur par défaut est ACTIVE. |
Exemple de réponse
Voici un exemple de la réponse renvoyée pour l'exemple de requête ci-dessus.
{
"name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
"displayName": "chronicle_forwarder",
"config": {
"uploadCompression": "false",
"serverSettings": {
"gracefulTimeout": 15,
"drainTimeout": 10,
"httpSettings": {
"port": "8080",
"host": "0.0.0.0",
"readTimeout": "3",
"readHeaderTimeout": "3",
"writeTimeout": "3",
"idleTimeout": "3"
"routeSettings": {
"availableStatusCode": "204",
"readyStatusCode": "204",
"unreadyStatusCode": "503"
},
},
},
},
"state": "ACTIVE"
}
Obtenir le redirecteur
Renvoie un redirecteur.
Requête
GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}
Corps de la requête
N'incluez pas de corps de requête.
Exemple de requête
GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56
Exemple de réponse
{
"name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
"displayName": "chronicle_forwarder",
"config": {
"uploadCompression": "false",
"serverSettings": {
"gracefulTimeout": 15,
"drainTimeout": 10,
"httpSettings": {
"port": "8080",
"host": "0.0.0.0",
"readTimeout": "3",
"readHeaderTimeout": "3",
"writeTimeout": "3",
"idleTimeout": "3"
"routeSettings": {
"availableStatusCode": "204",
"readyStatusCode": "204",
"unreadyStatusCode": "503"
},
},
},
},
"state": "ACTIVE"
}
Répertorier les redirecteurs
Répertorie tous les redirecteurs d'une instance Chronicle.
Requête
GET https://backstory.googleapis.com/v2/forwarders
Exemple de requête
GET https://backstory.googleapis.com/v2/forwarders
Réponse
Renvoie une liste de redirecteurs.
Exemple de réponse
{
"forwarders": [
{
"name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56",
"displayName": "chronicle_forwarder_1",
"config": {
"uploadCompression": "false",
"serverSettings": {
"gracefulTimeout": 15,
...
},
},
"state": "ACTIVE"
},
{
"name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde57",
"displayName": "chronicle_forwarder_2",
"config": {
"uploadCompression": "false",
"serverSettings": {
"gracefulTimeout": 15,
...
},
},
"state": "ACTIVE"
}
]
}
Mettre à jour le redirecteur
Vous pouvez mettre à jour un redirecteur à l'aide du paramètre de requête d'URL updateMask pour spécifier les champs à mettre à jour.
Par exemple, pour mettre à jour le nom à afficher, vous devez utiliser le paramètre de requête updateMask comme suit dans la requête patch:
?updateMask=displayName
Le corps de la requête ne doit contenir que les champs que vous souhaitez mettre à jour (à leur emplacement exact).
Requête
PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}?updateMask=<field_1,field_2>
Corps de la requête
{
"display_name": string,
"config": {
object (ForwarderConfig)
},
}
Paramètres du corps
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| display_name | chaîne | Requis | Nom du redirecteur. Ce nom est affiché dans l'interface Chronicle. |
| config | objet | Facultatif | Paramètres de configuration de ce redirecteur. Consultez la section Champs de configuration du système de transfert. |
Exemple de requête
Il s'agit d'un exemple de requête de transfert de mise à jour dans laquelle la requête spécifie de nouvelles valeurs pour displayName et ajoute un libellé de métadonnées.
PATCH https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56?updateMask=displayName,config.metadata.labels
{
"display_name": "UpdatedForwarder",
"config": {
"metadata": {
"labels": [
{
"key": "office",
"value": "corporate",
}
]
}
}
}
Exemple de réponse
Voici un exemple de la réponse renvoyée pour l'exemple de requête ci-dessus.
{
"name": "forwarders/{forwarderUUID}",
"displayName": "UpdatedForwarder",
"config": {
"uploadCompression": "false",
"metadata": {
"labels": [
{
"key": "office",
"value": "corporate"
}
]
}
},
"state": "ACTIVE"
}
Supprimer le redirecteur
Supprime un redirecteur.
Requête
DELETE https://backstory.googleapis.com/v2/forwarders/{forwarderID}
Corps de la requête
N'incluez pas de corps de requête.
Exemple de requête
DELETE https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56
Exemple de réponse
Si l'opération réussit, Delete Forwarder renvoie une réponse vide avec le code d'état HTTP 200 (OK).
{}
Générer des fichiers de redirecteur
Génère et renvoie le contenu des fichiers de configuration (.conf) et d'authentification (_auth.conf) du redirecteur.
Requête
GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}:generateForwarderFiles
Corps de la requête
N'incluez pas de corps de requête.
Exemple de requête
GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56:generateForwarderFiles
Exemple de réponse
Si l'opération réussit, il renvoie le code d'état HTTP 200 (OK). Il renvoie également le contenu d'un fichier de configuration de redirecteur, y compris les données de configuration des collecteurs du redirecteur, ainsi que le contenu du fichier d'authentification (_auth.conf) utilisé par le redirecteur pour s'authentifier auprès de l'instance Chronicle.
Champs de configuration du système de transfert
Le tableau suivant répertorie les paramètres de configuration du redirecteur que vous pouvez spécifier à l'aide des méthodes Create Forwarder et Update Forwarder. Si vous ne spécifiez pas de valeur pour un paramètre lorsque vous utilisez "Créer un système de transfert", la valeur par défaut du paramètre (indiquée ci-dessous) est appliquée.
Les champs suivants peuvent être fournis dans l'objet config du corps de la requête.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| upload_compression | bool | Facultatif | Si la valeur est true, les lots de données sont compressés avant l'importation.La valeur par défaut est false. |
| metadata.asset_namespace | chaîne | Facultatif | Espace de noms permettant d'identifier les journaux de ce redirecteur. Remarque:Il s'agit d'un paramètre global qui s'applique au redirecteur et à ses collecteurs, sauf s'il est remplacé au niveau du collecteur. Pour en savoir plus, consultez la section Configurer des espaces de noms. |
| metadata.labels | liste | Facultatif | Liste de paires clé/valeur arbitraires pouvant être spécifiées dans la configuration du redirecteur. Remarque:Il s'agit d'un paramètre global qui s'applique au redirecteur et à ses collecteurs, sauf s'il est remplacé au niveau du collecteur. |
| metadata.labels.key | chaîne | Facultatif | Clé d'un champ dans la liste des libellés de métadonnées. |
| metadata.labels.value | chaîne | Facultatif | Valeur d'un champ dans la liste des libellés de métadonnées. |
| regex_filters.description | chaîne | Facultatif | Décrit ce qui est filtré et pourquoi. |
| regex_filters.regexp | chaîne | Facultatif | Expression régulière utilisée pour établir une correspondance avec chaque ligne entrante. |
| regex_filters.behavior | enum | Facultatif | Spécifie l'état du fonctionnement du serveur. Les valeurs possibles sont les suivantes:
|
| server_settings | objet | Facultatif | Paramètres qui configurent le serveur HTTP intégré du redirecteur, qui permet de configurer les options d'équilibrage de charge et de haute disponibilité pour la collecte syslog sous Linux. |
| server_settings.state | enum | Facultatif | Spécifie l'état du fonctionnement du serveur. Les valeurs possibles sont les suivantes:
|
| server_settings.graceful_timeout | entier | Facultatif | Nombre de secondes après lesquelles le redirecteur renvoie une vérification d'aptitude/d'état insatisfaisante et accepte toujours de nouvelles connexions. C'est également le temps d'attente entre la réception d'un signal d'arrêt et le début réel de l'arrêt du serveur lui-même. Cela laisse à l'équilibreur de charge le temps de supprimer le redirecteur du pool. La valeur par défaut est 15. |
| server_settings.drain_timeout | entier | Facultatif | Nombre de secondes au terme desquelles le redirecteur attend que les connexions actives se ferment automatiquement avant d'être fermées par le serveur. La valeur par défaut est 10. |
| server_settings.http_settings.port | entier | Facultatif | Numéro de port sur lequel le serveur HTTP écoute les vérifications d'état provenant de l'équilibreur de charge. Doit être compris entre 1024 et 65 535. La valeur par défaut est 8080. |
| server_settings.http_settings.host | chaîne | Facultatif | Adresse IP, ou nom d'hôte pouvant être résolu en adresses IP, que le serveur doit écouter. La valeur par défaut est 0.0.0.0 (système local). |
| server_settings.http_settings.read_timeout | entier | Facultatif | Nombre maximal de secondes autorisées pour lire des requêtes entières, y compris l'en-tête et le corps. La valeur par défaut est 3. |
| server_settings.http_settings.read_header_timeout | entier | Facultatif | Nombre maximal de secondes autorisées pour lire les en-têtes de requêtes. La valeur par défaut est 3. |
| server_settings.http_settings.write_timeout | entier | Facultatif | Nombre maximal de secondes autorisées pour l'envoi d'une réponse. La valeur par défaut est 3. |
| server_settings.http_settings.idle_timeout | entier | Facultatif | Nombre maximal de secondes d'attente pour la requête suivante lorsque les connexions inactives sont activées. La valeur par défaut est 3. |
| server_settings.http_settings.route_settings.available_status_code | entier | Facultatif | Code d'état renvoyé lorsqu'une vérification d'activité est reçue et que le redirecteur est disponible. La valeur par défaut est 204. |
| server_settings.http_settings.route_settings.ready_status_code | entier | Facultatif | Code d'état renvoyé lorsque le redirecteur est prêt à accepter le trafic. La valeur par défaut est 204. |
| server_settings.http_settings.route_settings.unready_status_code | entier | Facultatif | Code d'état renvoyé lorsque le redirecteur n'est pas prêt à accepter le trafic. La valeur par défaut est 503. |
Documentation de référence de l'API Collector
Cette section décrit les points de terminaison permettant d'utiliser les collecteurs.
Lors de la création et de la mise à jour de collecteurs, notez que chaque configuration de collecteur peut spécifier des paramètres d'ingestion pour un, mais pas plusieurs des collecteurs suivants:
- Données du fichier journal
- Sujets Kafka
- Données de paquets (pcap)
- Données Splunk
- Données Syslog
Pour connaître les points de terminaison permettant d'utiliser des redirecteurs, consultez la documentation de référence de l'API Forwarder.
Créer un collecteur
Crée un collecteur dans le compte Chronicle. Les valeurs de configuration des collecteurs doivent être spécifiées à l'aide de l'option "Créer un collecteur" après avoir utilisé l'option "Créer un système de transfert".
Pour certains paramètres, les valeurs de configuration manquantes ou ayant une valeur nulle dans le corps de la requête sont définies sur les valeurs par défaut. Pour en savoir plus sur les champs et les valeurs de configuration du collecteur, consultez Champs de configuration du collecteur.
Requête
POST https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors
Corps de la requête
{
"display_name": string,
"config": {
object (CollectorConfig)
}
"state": enum
}
Paramètres du corps
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| display_name | chaîne | Requis | Nom du collecteur. Ce nom est affiché dans l'interface Chronicle. |
| config | objet | Requis | Paramètres de configuration de ce collecteur. Consultez Champs de configuration du collecteur. |
| state | enum | Facultatif | Spécifie l'état actuel du collecteur. Les valeurs possibles sont les suivantes :
|
Exemple de requête
Cet exemple montre les paires clé/valeur requises dans une requête de création d'un collecteur. Pour tous les champs non fournis, les valeurs par défaut sont appliquées lors de la création du collecteur.
Dans cet exemple, le type de collecteur est file. La configuration du collecteur inclut donc file_settings pour indiquer le type de collecteur et ses paramètres. Si le type de collecteur est syslog, la configuration du collecteur inclut syslog_settings. Pour en savoir plus, consultez la section Champs de configuration du collecteur.
POST https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors
{
"display_name": "abc_collector",
"config" {
"log_type": "CS_EDR"
"file_settings": {
"file_path": "/opt/chronicle/edr/output/sample.txt",
}
}
}
Réponse
Si la requête aboutit, la réponse renvoie le code d'état HTTP 200 (OK).
La réponse affiche les valeurs de configuration appliquées lors de la création du collecteur. Des valeurs de configuration par défaut sont appliquées à certains paramètres lors de la création de la ressource si ces champs sont manquants ou ont une valeur nulle dans le corps de la requête. Pour en savoir plus, consultez Champs de configuration du collecteur.
Champs de réponse
En plus des champs spécifiés dans la requête et des champs auxquels les valeurs par défaut sont appliquées, la réponse comprend les champs suivants:
| Champ | Type | Description |
|---|---|---|
| name | chaîne | ID de ressource du collecteur. Le format est "forwarders/{forwarderID}/collectors/{collectorID}". Exemple:forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56 |
Exemple de réponse
Voici un exemple de la réponse renvoyée pour l'exemple de requête ci-dessus.
{
"name": "forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56/collectors/
98ab7cd6-54ef-3abc-d21e-1f23a4bcde56",
"displayName": "abc_collector",
"config": {
"logType": "tomcat",
"maxSecondsPerBatch": "10",
"maxBytesPerBatch": "1048576"
}
}
Obtenir le collecteur
Renvoie un collecteur.
Requête
GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}
Corps de la requête
N'incluez pas de corps de requête.
Exemple de requête
GET
https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56
Exemple de réponse
{
"name": "?",
"displayName": "abc_collector",
"config": {
"logType": "tomcat",
"maxSecondsPerBatch": "10",
"maxBytesPerBatch": "1048576"
}
}
Répertorier les collecteurs
Répertorie les collecteurs existants pour le redirecteur spécifié.
Requête
GET https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors
Exemple de requête
GET https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors
Réponse
Renvoie plusieurs collecteurs.
Exemple de réponse
{
"collectors": [
{
"name": "?",
"displayName": "abc_collector_1",
"config": {
"logType": "tomcat",
"maxSecondsPerBatch": "10",
"maxBytesPerBatch": "1048576"
}
},
{
"name": "?",
"displayName": "abc_collector_2",
"config": {
"logType": "tomcat",
"maxSecondsPerBatch": "10",
"maxBytesPerBatch": "1048576"
}
}
]
}
Mettre à jour le collecteur
Lors de la mise à jour d'un collecteur avec l'API, vous pouvez choisir d'écraser l'ensemble de la configuration du collecteur ou de n'écraser que des champs spécifiques de la configuration. Il est généralement préférable d'écraser des champs spécifiques afin d'éviter d'écraser accidentellement toutes vos données. Pour écraser des champs spécifiques, fournissez un masque FieldMask à votre requête de mise à jour.
Pour fournir un paramètre FieldMask afin de mettre à jour le nom à afficher d'un collecteur, indiquez le paramètre de requête d'URL updateMask dans la requête patch. Exemple :
?updateMask=displayName
Le corps de la requête ne doit contenir que les champs que vous souhaitez mettre à jour (à leur emplacement exact).
Requête
PATCH https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}?updateMask=<field_1,field_2>
Corps de la requête
{
"display_name": string,
"config": {
object (CollectorConfig)
},
}
Paramètres du corps
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| displayName | chaîne | Requis | Nom du collecteur. Ce nom est affiché dans l'interface Chronicle. |
| config | objet | Facultatif | Paramètres de configuration de ce redirecteur. Consultez Champs de configuration du collecteur. |
Exemple de requête
Il s'agit d'un exemple de requête du collecteur de mise à jour dans laquelle la requête spécifie de nouvelles valeurs pour displayName, logType, assetnamespace et protocole.
PATCH https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56?updateMask=displayName,config.logType,config.metadata.assetNamespace,config.syslogSettings.protocol
{
"display_name": "UpdatedCollector"
"config": {
"metadata": {
"asset_namespace": "COLLECTOR",
},
"log_type": "CISCO_ASA_FIREWALL",
"syslog_settings": {
"protocol": "TCP",
}
}
}
Exemple de réponse
Voici un exemple de la réponse renvoyée pour l'exemple de requête ci-dessus.
{
"name": "forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56",
"displayName": "UpdatedCollector",
"config": {
"logType": "CISCO_ASA_FIREWALL",
"metadata": {
"assetNamespace": "COLLECTOR"
},
"maxSecondsPerBatch": 10,
"maxBytesPerBatch": "1048576",
"syslogSettings": {
"protocol": "TCP",
"address": "0.0.0.0",
"port": 10514,
}
},
"state": "ACTIVE"
}
Supprimer le collecteur
Supprime un collecteur.
Requête
DELETE https://backstory.googleapis.com/v2/forwarders/{forwarderID}/collectors/{collectorID}
Corps de la requête
N'incluez pas de corps de requête.
Exemple de requête
DELETE https://backstory.googleapis.com/v2/forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56
Exemple de réponse
Si l'opération réussit, l'outil Supprimer le collecteur renvoie une réponse vide avec le code d'état HTTP 200 (OK).
{}
Champs de configuration du collecteur
Les champs suivants peuvent être fournis dans l'objet config du corps de la requête.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| log_type | chaîne | Requis | Un type de journal compatible (qui peut être ingéré par Chronicle) Pour obtenir la liste des types de journaux compatibles pour lesquels Chronicle dispose d'un analyseur, consultez la colonne Libellé d'ingestion de la page Analyseurs par défaut compatibles. Pour obtenir la liste complète des types de journaux compatibles, utilisez le point de terminaison logtypes.
|
| metadata.asset_namespace | objet | Facultatif | Espace de noms permettant d'identifier les journaux de ce collecteur. Remarque:Il s'agit d'un paramètre global qui s'applique au redirecteur et à ses collecteurs, sauf s'il est remplacé au niveau du collecteur. Pour en savoir plus, consultez la section Configurer des espaces de noms. |
| metadata.labels | liste | Facultatif | Une liste de paires clé/valeur arbitraires pouvant être spécifiées dans la configuration du collecteur. Remarque:Il s'agit d'un paramètre global qui s'applique au redirecteur et à ses collecteurs, sauf s'il est remplacé au niveau du collecteur. |
| metadata.labels.key | chaîne | Facultatif | Clé d'un champ dans la liste des libellés de métadonnées. |
| metadata.labels.value | chaîne | Facultatif | Valeur d'un champ dans la liste des libellés de métadonnées. |
| regex_filters.description | chaîne | Facultatif | Décrit ce qui est filtré et pourquoi. |
| regex_filters.regexp | chaîne | Facultatif | Expression régulière utilisée pour établir une correspondance avec chaque ligne entrante. |
| regex_filters.behavior | enum | Facultatif | Spécifie l'état du fonctionnement du serveur. Les valeurs possibles sont les suivantes:
|
| disk_buffer.state | enum | Facultatif | Spécifie l'état de mise en mémoire tampon du disque pour le collecteur. Les valeurs possibles sont les suivantes :
|
| disk_buffer.directory_path | chaîne | Facultatif | Chemin d'accès au répertoire pour les fichiers écrits. |
| disk_buffer.max_file_buffer_bytes | entier | Facultatif | Taille maximale du fichier mis en mémoire tampon. |
| max_seconds_per_batch | entier | Facultatif | Nombre de secondes entre les lots. La valeur par défaut est 10. |
| max_bytes_per_batch | entier | Facultatif | Nombre d'octets mis en file d'attente avant l'importation groupée du redirecteur. La valeur par défaut est 1048576. |
| <type_collect>_settings.<champs> | Requis | Spécifie un type de collecteur et ses paramètres. Chaque collecteur doit spécifier un type de collecteur et ses champs. Par exemple, pour utiliser le type de collecteur file, vous devez ajouter le champ file_settings.file_path à la configuration et lui attribuer une valeur. Par exemple:"file_settings": {Les types de collecteurs et leurs champs sont répertoriés dans les lignes suivantes de ce tableau. Les types de collecteurs disponibles sont les suivants:
|
|
| file_settings.file_path | chaîne | Facultatif | Chemin d'accès au fichier à surveiller. |
| kafka_settings.authentication.username | chaîne | Facultatif | Nom d'utilisateur d'une identité utilisée pour l'authentification. |
| kafka_settings.authentication.password | chaîne | Facultatif | Mot de passe du compte identifié par le nom d'utilisateur. |
| kafka_settings.topic | chaîne | Facultatif | Sujet Kafka à partir duquel ingérer les données. Pour en savoir plus, consultez Collecter des données à partir de sujets Kafka. |
| kafka_settings.group_id | chaîne | Facultatif | Un ID de groupe. |
| kafka_settings.timeout | entier | Facultatif | Nombre maximal de secondes pendant lesquelles un utilisateur attend la fin d'une connexion. La valeur par défaut est 60. |
| kafka_settings.brokers | chaîne | Facultatif | Chaîne répétée listant les courtiers Kafka. Par exemple: "broker-1:9092", "broker-2:9093" Remarque:Toutes les valeurs sont remplacées lors d'une opération de mise à jour. Par conséquent, pour mettre à jour une liste de courtiers afin d'ajouter un nouveau courtier, spécifiez tous les courtiers existants ainsi que le nouveau courtier. |
| kafka_settings.tls_settings.certificate | chaîne | Facultatif | Chemin d'accès et nom de fichier du certificat. Exemple:/path/to/cert.pem |
| kafka_settings.tls_settings.certificate_key | chaîne | Facultatif | Nom du chemin d'accès et de la clé de certificat. Exemple:/path/to/cert.key |
| kafka_settings.tls_settings.minimum_tls_version | chaîne | Facultatif | Version minimale de TLS. |
| kafka_settings.tls_settings.insecure_skip_verify | bool | Facultatif | Si la valeur est true, la validation de la certification SSL est activée.La valeur par défaut est false. |
| pcap_settings.network_interface | chaîne | Facultatif | Interface à écouter pour les données PCAP. |
| pcap_settings.bpf | chaîne | Facultatif | Le filtre de paquets Berkeley (BPF) pour pcap. |
| splunk_settings.authentication.username | chaîne | Facultatif | Nom d'utilisateur d'une identité utilisée pour l'authentification. |
| splunk_settings.authentication.password | chaîne | Facultatif | Mot de passe du compte identifié par le nom d'utilisateur. |
| splunk_settings.host | chaîne | Facultatif | Hôte ou adresse IP de l'API REST Splunk. |
| splunk_settings.port | entier | Facultatif | Port de l'API REST Splunk. |
| splunk_settings.minimum_window_size | entier | Facultatif | Période minimale en secondes pour une recherche Splunk donnée. Pour en savoir plus, consultez Collecter des données Splunk. La valeur par défaut est 10. |
| splunk_settings.maximum_window_size | entier | Facultatif | Période maximale en secondes pour une recherche Splunk donnée. Pour en savoir plus, consultez Collecter des données Splunk. La valeur par défaut est 30. |
| splunk_settings.query_string | chaîne | Facultatif | Requête utilisée pour filtrer les enregistrements dans Splunk. Exemple: search index=* sourcetype=dns |
| splunk_settings.query_mode | chaîne | Facultatif | Mode de requête pour Splunk. Exemple: realtime |
| splunk_settings.cert_ignored | bool | Facultatif | Si la valeur est true, le certificat est ignoré. |
| syslog_settings.protocol | enum | Facultatif | Spécifie le protocole que le collecteur utilisera pour écouter les données syslog. Les valeurs possibles sont les suivantes :
|
| syslog_settings.address | chaîne | Facultatif | Adresse IP ou nom d'hôte cible où réside et écoute les données syslog. |
| syslog_settings.port | entier | Facultatif | Port cible sur lequel réside le collecteur et écoute les données syslog. |
| syslog_settings.buffer_size | entier | Facultatif | Taille du tampon du socket TCP, en octets. La valeur par défaut pour TCP est 65536.La valeur par défaut pour UDP est 8192. |
| syslog_settings.connecton_timeout | entier | Facultatif | Nombre de secondes d'inactivité au terme duquel la connexion TCP est interrompue. La valeur par défaut est 60. |
| syslog_settings.tls_settings.certificate | chaîne | Facultatif | Chemin d'accès et nom de fichier du certificat. Exemple:/path/to/cert.pem |
| syslog_settings.tls_settings.certificate_key | chaîne | Facultatif | Nom du chemin d'accès et de la clé de certificat. Exemple:/path/to/cert.key |
| syslog_settings.tls_settings.minimum_tls_version | chaîne | Facultatif | Version minimale de TLS. |
| syslog_settings.tls_settings.insecure_skip_verify | bool | Facultatif | Si la valeur est true, la validation de la certification SSL est activée.La valeur par défaut est false. |