API Forwarder Management

Vous pouvez utiliser l'API Google Security Operations Forwarder Management pour effectuer les opérations suivantes par programmation:

  • Créer et gérer des transferts.
  • Créer et gérer des collecteurs
  • Récupérez le contenu des fichiers de configuration (.conf) et d'authentification (_auth.conf) d'un redirecteur Google Security Operations.

Les redirecteurs sont composés d'un ou de plusieurs collecteurs. Configuration de chaque collecteur spécifie son mécanisme d'ingestion (par exemple, File, Kafka, PCAP, Splunk ou Syslog) et son type de journal.

En supposant que la configuration matérielle requise soit respectée, 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 forwarder avec deux collecteurs syslog qui écoutent respectivement les données PAN_FIREWALL et CISCO_ASA_FIREWALL sur des ports distincts.

L'API vous permet de créer des transferts et leurs collecteurs dans votre instance Google Security Operations. Une fois qu'un redirecteur est créé, vous pouvez utiliser le point de terminaison Générer des fichiers de redirecteur pour obtenir le contenu des fichiers (sous forme de charge utile JSON) des fichiers de configuration (.conf) et d'authentification (_auth.conf) d'un redirecteur. Ces contenus peuvent ensuite être écrits dans leurs fichiers .conf respectifs pour être déployés avec la suite Google Security Operations Service de transfert sur un système Windows ou Linux.

Pour des exemples Python utilisant l'API Forwarder Management, consultez le dépôt GitHub.

Créer un redirecteur et ses collecteurs

Un redirecteur doit être créé avant que l'un de ses collecteurs puisse être créé.

Pour créer un redirecteur et son ou ses collecteurs, procédez comme suit :

  1. Créez un redirecteur.
  2. Créez un collecteur pour le redirecteur.
  3. (Facultatif) Répétez l'étape 2 pour ajouter d'autres collecteurs.

S'authentifier avec l'API Google Security Operations [:#verify]

Cette API Google Security Operations 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.

  • Interface directe avec le système OAuth 2.0 via HTTP

Consultez la documentation de référence sur la bibliothèque d'authentification Google en Python.

Les bibliothèques d'authentification Google sont 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 Google Security Operations vous fournira un Google Developer Compte de service : identifiant permettant au client API de communiquer avec l'API.

Vous devez également fournir le champ d'application d'autorisation 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 délivré à l'application est limité au champ d'application accordé.

Utilisez le champ d'application suivant pour initialiser votre client API Google:

https://www.googleapis.com/auth/chronicle-backstory

Exemple Python

L'exemple Python suivant montre comment utiliser les identifiants OAuth2. et 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 Google Security Operations 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 envoyées à un client donné vers la plate-forme Google Security Operations. Si vous atteignez ou dépassez la valeur limite de requêtes, le serveur de l'API Chronicle renvoie le code HTTP 429 (RESOURCE_EXHAUSTED) à l'appelant. Lorsque vous développez des applications pour l'API Chronicle, Google recommande d'appliquer des limites de débit dans votre système pour éviter que l'épuisement. 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 se mesure en requêtes par seconde (RPS):

API Chronicle Point de terminaison de l'API Limite
Gestion des redirecteurs Créer un redirecteur 1 RPS
Get Forwarder 1 RPS
Répertorier les administrateurs de redirection 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 en savoir plus sur les points de terminaison permettant de créer et de gérer les collecteurs, consultez la documentation de référence de l'API Collector.

Créer un redirecteur

Crée un forwarder dans l'instance Google SecOps. Le nouveau redirecteur inclura toutes les valeurs de configuration du redirecteur fournies dans le corps de la requête. Les valeurs de configuration des collecteurs doivent être spécifiées à l'aide de "Create Collector" (Créer un collecteur) après avoir utilisé Create Forwarder.

Pour certains paramètres, les valeurs de configuration manquantes ou n'ayant aucune valeur 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 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 de corps
Champ Type Obligatoire Description
display_name chaîne Obligatoire Nom du redirecteur. Ce nom est affiché dans de commande.
config objet Facultatif Paramètres de configuration de ce redirecteur. Consultez la section Champs de configuration du redirecteur.
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 a une valeur par défaut, le champ est appliquée lors de la création du redirecteur. Pour en savoir plus sur les valeurs par défaut, consultez la section Champs de configuration du transpondeur.

POST https://backstory.googleapis.com/v2/forwarders
{
  "display_name": "chronicle_forwarder"
}

Réponse

Si la requête aboutit, la réponse renvoie un code d'état HTTP 200 (OK).

La réponse affiche les valeurs de configuration appliquées lors de la création du à l'origine du transfert. Des valeurs de configuration par défaut sont appliquées lors de la création de la ressource si ces champs sont manquants ou n'ont pas de valeur le corps de la requête. Pour en savoir plus, consultez Champs de configuration du redirecteur.

Champs de réponse

Outre les champs spécifiés dans la demande et ceux pour lesquels valeurs par défaut sont appliquées, la réponse inclut les éléments générés et de sortie uniquement.

Champ Type Description
nom chaîne ID de ressource du redirecteur. Le format est le suivant : « forwarders/forwarderID ». Exemple:

forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56
state enum

Spécifie l'état actuel du redirecteur. Les valeurs possibles sont les suivantes :

  • ACTIVE: le redirecteur est autorisé à importer des données.
  • SUSPENDED : l'expéditeur n'est pas autorisé à importer des données.

La valeur par défaut est ACTIVE.

Exemple de réponse

Voici un exemple de 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"
}

Options de transfert de liste

Répertorie tous les redirecteurs d'une instance Google SecOps.

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 transfert

Vous pouvez mettre à jour un redirecteur à l'aide du paramètre de requête d'URL updateMask afin de 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 de corps
Champ Type Obligatoire Description
display_name chaîne Obligatoire Nom du redirecteur. Ce nom est affiché dans de commande.
config objet Facultatif Paramètres de configuration de ce redirecteur. Consultez la section Champs de configuration du redirecteur.
Exemple de requête

Voici un exemple de requête du redirecteur 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 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 un 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, le code d'état HTTP 200 (OK) est renvoyé. Il renvoie également le contenu d'un fichier de configuration du redirecteur, y compris le les données de configuration des collecteurs du redirecteur, ainsi que le contenu le fichier d'authentification (_auth.conf) utilisé par le redirecteur pour s'authentifier auprès de l'instance Google SecOps.

Champs de configuration du redirecteur

Le tableau suivant répertorie les paramètres de configuration du forwarder que vous pouvez spécifier à l'aide de "Créer un forwarder" et "Mettre à jour le forwarder". Si vous ne spécifiez pas de valeur pour un paramètre lorsque vous utilisez Créer un redirecteur, la valeur par défaut du paramètre (affichée ci-dessous) s'applique.

Les champs suivants peuvent être fournis dans l'objet config de la requête. .

Champ Type Obligatoire Description
upload_compression Valeur booléenne 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 général qui s'applique à la le redirecteur et les collecteurs du redirecteur, à moins que le paramètre au niveau du collecteur. Pour en savoir plus, consultez la section Configurer les espaces de noms.
metadata.labels liste Facultatif Liste de paires clé/valeur arbitraires pouvant être spécifiées dans le la configuration du redirecteur.

Remarque:Il s'agit d'un paramètre général qui s'applique à la le redirecteur et les collecteurs du redirecteur, à moins que le paramètre au niveau du collecteur.
metadata.labels.key chaîne Facultatif Clé d'un champ dans la liste des étiquettes 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 des fonctionnalités du serveur. Valeurs valides sont:

  • ALLOW: cet état permet d'importer la ligne filtrée.
  • BLOQUER: cet état empêche l'importation de la ligne filtrée.
server_settings objet Facultatif les paramètres qui configurent le serveur HTTP intégré du redirecteur, qui peut être utilisé pour 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 des fonctionnalités du serveur. Valeurs valides sont:

  • ACTIVE: dans cet état, les paramètres du serveur sont appliqués comme indiqué.
  • SUSPENDED Dans cet état, les paramètres du serveur ne sont pas appliqués.
server_settings.graceful_timeout entier Facultatif Nombre de secondes au terme desquelles le redirecteur renvoie une erreur de préparation/vérification de l'état et accepte toujours les nouvelles connexions. C'est ainsi que le temps d'attente entre la réception d'un signal et l'arrêt effectif l'arrêt du serveur lui-même. Cela permet à la charge pour retirer 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 une conversion les connexions se ferment d'elles-mêmes avant d'être fermées 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 de l'état 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 L'adresse IP, ou nom d'hôte, qui peut être résolu en adresses IP, que le serveur doit écouter.

La valeur par défaut est 0.0.0.0 (le système local).
server_settings.http_settings.read_timeout entier Facultatif Nombre maximal de secondes autorisé pour lire l'intégralité des requêtes, 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 envoyer une réponse.

La valeur par défaut est 3.
server_settings.http_settings.idle_timeout entier Facultatif Nombre maximal de secondes d'attente de la requête suivante en cas d'inactivité 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é lors de la réception d'une vérification d'activité et 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 du 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 du trafic.

La valeur par défaut est 503.

Documentation de référence de l'API de collecteur

Cette section décrit les points de terminaison à utiliser avec les collecteurs.

Lorsque vous créez et mettez à jour des collecteurs, notez que chaque configuration de collecteur peut spécifier des paramètres d'ingestion pour un seul des éléments suivants, mais pas pour plusieurs:

  • Données des fichiers journaux
  • Sujets Kafka
  • Données de paquets (pcap)
  • Données Splunk
  • Données Syslog

Pour connaître les points de terminaison à utiliser avec les transferts, consultez la documentation de référence de l'API Forwarder.

Créer un collecteur

crée un collecteur dans le compte Google SecOps ; Configuration les valeurs des collecteurs doivent être spécifiées avec "Create Collector" (Créer un collecteur) après avoir utilisé Créer un redirecteur

Pour certains paramètres, les valeurs de configuration manquantes ou nulles dans le corps de la requête sont définies sur des 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 de corps
Champ Type Obligatoire Description
display_name chaîne Obligatoire Nom du collecteur. Ce nom s'affiche dans l'interface Google SecOps.
config objet Obligatoire Paramètres de configuration de ce collecteur. Consultez la section Champs de configuration du collecteur.
state enum Facultatif

Spécifie l'état actuel du collecteur. Les valeurs possibles sont les suivantes :

  • ACTIVE : le collecteur est autorisé à accepter les données.
  • SUSPENDED : le collecteur n'est pas autorisé à accepter les données.
Exemple de requête

Cet exemple montre les paires clé/valeur requises dans une requête Create Collector. Pour tous les champs qui ne sont pas fournis, des 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 file_settings pour indiquer le type de collecteur et ses paramètres. Si le type de collecteur est syslog, alors la configuration du collecteur inclut syslog_settings Pour en savoir plus, consultez 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 un code d'état HTTP 200 (OK).

La réponse indique les valeurs de configuration appliquées lors de la création du collecteur. Des valeurs de configuration par défaut sont appliquées lors de la création de la ressource si ces champs sont manquants ou n'ont pas de valeur le corps de la requête. Pour en savoir plus, consultez Champs de configuration du collecteur.

Champs de réponse

Outre les champs spécifiés dans la demande et ceux pour lesquels valeurs par défaut sont appliquées, la réponse inclut les champs suivants:

Champ Type Description
nom chaîne ID de ressource du collecteur. Le format est le suivant : &quot;forwarders/{forwarderID}/collectors/{collectorID}&quot;. Pour exemple:

forwarders/12ab3cd4-56ef-7abc-d89e-1f23a4bcde56/collectors/98ab7cd6-54ef-3abc-d21e-1f23a4bcde56
Exemple de réponse

Voici un exemple de 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 forwarder 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

Lorsque vous mettez à jour un collecteur avec l'API, vous pouvez choisir pour écraser l'intégralité de la configuration du collecteur de la configuration du collecteur. Il est généralement préférable d'écraser des champs spécifiques, afin d'éviter d'écraser accidentellement l'ensemble de vos données. Pour écraser des champs spécifiques, fournissez un FieldMask à votre requête de mise à jour.

Pour fournir un FieldMask afin de mettre à jour le nom à afficher d'un collecteur, Fournissez 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 (dans 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 de corps
Champ Type Obligatoire Description
displayName chaîne Obligatoire Nom du collecteur. Ce nom s'affiche dans l'interface Google SecOps.
config objet Facultatif Paramètres de configuration de ce redirecteur. Consultez la section Champs de configuration du collecteur.
Exemple de requête

Voici 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 "protocol".

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 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 un code d'état HTTP 200 (OK).

{}

Champs de configuration du collecteur

Les champs suivants peuvent être fournis dans l'objet config de la requête. .

Champ Type Obligatoire Description
log_type chaîne Obligatoire Un type de journal compatible (pouvant être ingéré par Google SecOps) Pour obtenir la liste des types de journaux compatibles pour lesquels Google SecOps dispose d'un analyseur, consultez la colonne "Libellé d'ingestion" sur la page Analyseurs par défaut compatibles. Pour obtenir un 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 général qui s'applique à la le redirecteur et les collecteurs du redirecteur, à moins que le paramètre au niveau du collecteur. Pour en savoir plus, consultez la section Configurer les espaces de noms.
metadata.labels liste Facultatif 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 transmettant et aux collecteurs du transmettant, sauf s'il est remplacé au niveau du collecteur.
metadata.labels.key chaîne Facultatif Clé d'un champ dans la liste des étiquettes 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 des fonctionnalités du serveur. Valeurs valides sont:

  • ALLOW: cet état permet d'importer la ligne filtrée.
  • BLOQUER: cet état empêche l'importation de la ligne filtrée.
disk_buffer.state enum Facultatif

Spécifie l'état de la mise en mémoire tampon du disque pour le collecteur. Les valeurs possibles sont les suivantes :

  • ACTIVE: la mise en mémoire tampon est activée.
  • SUSPENDED: la mise en mémoire tampon est désactivée.
disk_buffer.directory_path chaîne Facultatif Chemin d'accès au répertoire des 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.
<collector_type>_settings.<fields> Obligatoire 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": {
  "file_path": "/opt/chronicle/edr/output/sample.txt",
}


Les types de collecteurs et leurs champs sont répertoriés dans les lignes suivantes de cette table. Les types de collecteurs disponibles sont les suivants:
  • file
  • kafka
  • pcap
  • splunk
  • syslog
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 des 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 numéro doit attendre une connexion à terminé.

La valeur par défaut est 60.
kafka_settings.brokers chaîne Facultatif Chaîne répétée répertoriant les courtiers Kafka. 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 et le nouveau courtier.
kafka_settings.tls_settings.certificate chaîne Facultatif Chemin d'accès et nom de fichier du certificat. Par exemple :

/path/to/cert.pem
kafka_settings.tls_settings.certificate_key chaîne Facultatif Chemin d'accès et nom de fichier de la clé de certificat. Exemple:

/path/to/cert.key
kafka_settings.tls_settings.minimum_tls_version chaîne Facultatif Version minimale du 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 permettant d'écouter les données PCAP.
pcap_settings.bpf chaîne Facultatif Filtre de paquet de 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 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 utilisé par le collecteur pour écouter les données syslog. Les valeurs possibles sont les suivantes :

  • TCP
  • UDP
syslog_settings.address chaîne Facultatif Adresse IP ou nom d'hôte cible où se trouve le collecteur et où il écoute les données syslog.
syslog_settings.port entier Facultatif Port cible sur lequel le collecteur réside et écoute le journal syslog données.
syslog_settings.buffer_size entier Facultatif Taille en octets du tampon du socket TCP.

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é après lequel 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. Par exemple :

/path/to/cert.pem
syslog_settings.tls_settings.certificate_key chaîne Facultatif Chemin d'accès et nom de fichier de la clé de certificat. Exemple:

/path/to/cert.key
syslog_settings.tls_settings.minimum_tls_version chaîne Facultatif Version minimale du TLS.
syslog_settings.tls_settings.insecure_skip_verify Valeur booléenne Facultatif Si la valeur est true, la validation de la certification SSL est activée.

La valeur par défaut est false.