Cette page a été traduite par l'API Cloud Translation.

Gestion des redirecteurs

Vous pouvez utiliser les méthodes de l'API Google Security Operations Forwarder Management pour effectuer les opérations suivantes de manière programmatique :

Créer et gérer des transferts
Créer et gérer des collecteurs.
Obtenez le contenu des fichiers de configuration (.conf) et d'authentification (_auth.conf) d'un transmetteur Google SecOps.

Les réexpéditeurs sont composés d'un ou 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.

Si la configuration matérielle requise est respectée, vous pouvez utiliser plusieurs collecteurs sur le même transmetteur pour ingérer des données provenant de différents mécanismes et types de journaux. Par exemple, vous pouvez installer un transmetteur 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 Google SecOps. Une fois un transmetteur créé, vous pouvez utiliser le point de terminaison "Generate Forwarder Files" (Générer des fichiers de transmetteur) pour obtenir le contenu des fichiers (sous forme de charge utile JSON) pour les fichiers de configuration (.conf) et d'authentification (_auth.conf) d'un transmetteur. Ces contenus peuvent ensuite être écrits dans leurs fichiers .conf respectifs pour être déployés avec le service Google SecOps Forwarder sur un système Windows ou Linux.

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

Créer un redirecteur et ses collecteurs

Vous devez créer un transmetteur avant de pouvoir créer l'un de ses collecteurs.

Pour créer un transmetteur et ses collecteurs :

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

Obtenir les identifiants d'authentification de l'API

Votre représentant Google Security Operations vous fournira des identifiants de compte de service Google Developer pour permettre au client de l'API de communiquer avec l'API.

Vous devez également fournir le champ d'application 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 qui lui est attribué est limité au champ d'application accordé.

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

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.auth.transport import requests
from google.oauth2 import service_account

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 the Google Developer Service Account Credential and Backstory API
# Scope.
credentials = service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE, scopes=SCOPES)

# Build a requests Session Object to make authorized OAuth requests.
http_session = requests.AuthorizedSession(credentials)

# Your endpoint GET|POST|PATCH|etc. code will vary below

# Reference List example (for US region)
url = 'https://backstory.googleapis.com/v2/lists/COLDRIVER_SHA256'

# You might need another regional endpoint for your API call; see
# https://cloud.google.com/chronicle/docs/reference/ingestion-api#regional_endpoints

# requests GET example
response = http_session.request("GET", url)

# POST example uses json
body = {
  "foo": "bar"
}
response = http_session.request("POST", url, json=body)

# PATCH example uses params and json
params = {
  "foo": "bar"
}
response = http_session.request("PATCH", url, params=params, json=body)

# For more complete examples, see:
# https://github.com/chronicle/api-samples-python/

Limites de requêtes de l'API Backstory

L'API Backstory impose des limites sur le volume de requêtes qu'un client peut envoyer à la plate-forme Google SecOps. Si vous atteignez ou dépassez la limite de requêtes, le serveur de l'API Backstory renvoie le code HTTP 429 (RESOURCE_EXHAUSTED) à l'appelant. Lorsque vous développez des applications pour l'API Backstory, Google vous recommande d'appliquer des limites de taux dans votre système pour éviter l'épuisement des ressources. Ces limites s'appliquent à toutes les API Backstory, y compris les API Search, Forwarder Management et Tooling.

Consultez la liste détaillée des quotas de l'API Backstory.

La limite suivante pour la gestion des redirecteurs est appliquée et mesurée en requêtes par seconde (RPS) :

API Backstory	Point de terminaison de l'API	Limite
Gestion des redirecteurs	Créer un redirecteur	1 RPS
	Obtenir le redirecteur	1 RPS
	Lister les redirecteurs	1 RPS
	Mettre à jour un redirecteur	1 RPS
	Supprimer le redirecteur	1 RPS
Gestion des collecteurs	Créer un collecteur	1 RPS
	Obtenir le collecteur	1 RPS
	Lister les collecteurs	1 RPS
	Mettre à jour le collecteur	1 RPS
	Supprimer un collecteur	1 RPS

Documentation de référence des méthodes de l'API Forwarder

Cette section décrit les points de terminaison permettant de créer et de gérer des redirecteurs. Pour 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 Google SecOps. Le nouveau transitaire inclura toutes les valeurs de configuration forwarder fournies dans le corps de la requête. Les valeurs de configuration pour les collecteurs doivent être spécifiées à l'aide de l'option "Créer un collecteur" après avoir utilisé l'option "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 les valeurs par défaut. Pour en savoir plus sur les champs et les valeurs du transmetteur, consultez Champs de configuration du transmetteur.

Requête

POST https://backstory.googleapis.com/v2/forwarders

Corps de la requête

{
  "display_name": string,
  "config": {
    object (ForwarderConfig)
  }
}

Paramètres corporels

Champ	Type	Obligatoire	Description
display_name	chaîne	Obligatoire	Nom du transitaire. Ce nom s'affiche dans l'interface Google SecOps.
config	object	Facultatif	Paramètres de configuration de ce redirecteur. Consultez Champs de configuration du transitaire.

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 transitaire. Pour en savoir plus sur les valeurs par défaut, consultez Champs de configuration du transitaire.

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 redirecteur. Des valeurs de configuration par défaut sont appliquées à certains paramètres lors de la création de ressources 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 transitaire.

Champs de réponse

En plus des champs spécifiés dans la requête et de ceux pour lesquels des valeurs par défaut sont appliquées, la réponse inclut les champs générés et en sortie seule suivants.

Champ	Type	Description
nom	chaîne	ID de ressource du transitaire. Le format est "forwarders/forwarderID". Par exemple : forwarders/12ab3cd4-56ef-7ghi-j89k-1l23m4nopq56
state	enum	Spécifie l'état actuel du transitaire. Les valeurs possibles sont les suivantes : ACTIF : le transitaire est autorisé à importer des données. SUSPENDED : le transitaire n'est pas autorisé à importer des données. La valeur par défaut est ACTIVE.

Champ

Type

Description

nom

chaîne

ID de ressource du transitaire. Le format est "forwarders/forwarderID". Par exemple :

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

state

enum

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

ACTIF : le transitaire est autorisé à importer des données.
SUSPENDED : le transitaire 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 transitaire.

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"
}

Lister les redirecteurs

Liste 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 réexpéditeurs.

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 un redirecteur

Vous pouvez mettre à jour un redirecteur en utilisant le 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 corporels

Champ	Type	Obligatoire	Description
display_name	chaîne	Obligatoire	Nom du transitaire. Ce nom s'affiche dans l'interface Google SecOps.
config	object	Facultatif	Paramètres de configuration de ce redirecteur. Consultez Champs de configuration du transitaire.

Exemple de requête

Voici un exemple de requête Update Forwarder 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 aboutit, Delete Forwarder renvoie une réponse vide avec un code d'état HTTP 200 (OK).

{}

Générer des fichiers de transfert

Génère et renvoie le contenu des fichiers de configuration (.conf) et d'authentification (_auth.conf) du transitaire.

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 aboutit, elle renvoie un code d'état HTTP 200 (OK). Il renvoie également le contenu d'un fichier de configuration du 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 Google SecOps.

Champs de configuration du redirecteur

Le tableau suivant liste les paramètres de configuration du redirecteur que vous pouvez spécifier à l'aide de Create Forwarder et Update 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 (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 transmetteur. Remarque : Il s'agit d'un paramètre global qui s'applique au transmetteur et à ses collecteurs, sauf s'il est remplacé au niveau du collecteur. Pour en savoir plus, consultez 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 transmetteur 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 de la fonctionnalité du serveur. Les valeurs valides sont les suivantes : ALLOW (AUTORISER) : cet état permet d'importer la ligne filtrée. BLOCK (BLOQUER) : cet état empêche l'importation de la ligne filtrée.
server_settings	object	Facultatif	Paramètres qui configurent le serveur HTTP intégré du transmetteur, qui peut être utilisé pour configurer les options d'équilibrage de charge et de haute disponibilité pour la collecte syslog sur Linux.
server_settings.state	enum	Facultatif	Spécifie l'état de la fonctionnalité du serveur. Les valeurs valides sont les suivantes : ACTIVE : dans cet état, les paramètres du serveur sont appliqués comme spécifié. SUSPENDED : dans cet état, les paramètres du serveur ne sont pas appliqués.
server_settings.graceful_timeout	integer	Facultatif	Nombre de secondes après lesquelles le redirecteur renvoie une vérification de l'état/de la disponibilité incorrecte, tout en acceptant de nouvelles connexions. Il s'agit également du temps d'attente entre la réception d'un signal d'arrêt et le début de l'arrêt du serveur lui-même. Cela permet à l'équilibreur de charge de supprimer le redirecteur du pool. La valeur par défaut est `15`.
server_settings.drain_timeout	integer	Facultatif	Nombre de secondes pendant lesquelles le redirecteur attend que les connexions actives se ferment d'elles-mêmes avant d'être fermées par le serveur. La valeur par défaut est `10`.
server_settings.http_settings.port	integer	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 1 024 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	integer	Facultatif	Nombre maximal de secondes autorisées 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	integer	Facultatif	Nombre maximal de secondes autorisées pour lire les en-têtes de requête. La valeur par défaut est `3`.
server_settings.http_settings.write_timeout	integer	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	integer	Facultatif	Nombre maximal de secondes d'attente pour la prochaine requête lorsque les connexions inactives sont activées. La valeur par défaut est `3`.
server_settings.http_settings.route_settings.available_status_code	integer	Facultatif	Code d'état renvoyé lorsqu'une vérification d'activité est reçue et que le transitaire est disponible. La valeur par défaut est `204`.
server_settings.http_settings.route_settings.ready_status_code	integer	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	integer	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 des méthodes de l'API Collector

Cette section décrit les points de terminaison permettant d'utiliser 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 :

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

Pour en savoir plus sur les points de terminaison permettant d'utiliser les réexpéditeurs, consultez la documentation de référence de l'API Forwarder.

Créer un collecteur

Crée un collecteur dans le compte Google SecOps. 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 redirecteur".

Pour certains paramètres, les valeurs de configuration manquantes ou nulles 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 corporels

Champ	Type	Obligatoire	Description
display_name	chaîne	Obligatoire	Nom du collecteur. Ce nom s'affiche dans l'interface Google SecOps.
config	object	Obligatoire	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 : ACTIVE : le collecteur est autorisé à accepter les données. SUSPENDED : le collecteur n'est pas autorisé à accepter des données.

Champ

Type

Obligatoire

Description

display_name

chaîne

Obligatoire

Nom du collecteur. Ce nom s'affiche dans l'interface Google SecOps.

config

object

Obligatoire

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 :

ACTIVE : le collecteur est autorisé à accepter les données.
SUSPENDED : le collecteur n'est pas autorisé à accepter des données.

Exemple de requête

Cet exemple montre les paires clé/valeur requises dans une requête Create Collector. Pour tous les champs non 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 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 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 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 ressources 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 de ceux pour lesquels des 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 "forwarders/{forwarderID}/collectors/{collectorID}". Par 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"
  }
}

Lister les collecteurs

Liste 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

Lorsque vous mettez à jour un collecteur avec l'API, vous pouvez choisir d'écraser l'intégralité de la configuration du collecteur ou uniquement des champs spécifiques 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 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 corporels

Champ	Type	Obligatoire	Description
displayName	chaîne	Obligatoire	Nom du collecteur. Ce nom s'affiche dans l'interface Google SecOps.
config	object	Facultatif	Paramètres de configuration de ce redirecteur. Consultez Champs de configuration du collecteur.

Exemple de requête

Voici un exemple de requête Update Collector 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 un 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, Delete Collector 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 du corps de la requête.

Champ	Type	Obligatoire	Description
log_type	chaîne	Obligatoire	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 la liste complète des types de journaux acceptés, utilisez le point de terminaison `logtypes`.
metadata.asset_namespace	object	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 transmetteur et à ses collecteurs, sauf s'il est remplacé au niveau du collecteur. Pour en savoir plus, consultez Configurer des 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 transmetteur 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 de la fonctionnalité du serveur. Les valeurs valides sont les suivantes : ALLOW (AUTORISER) : cet état permet d'importer la ligne filtrée. BLOCK (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 sur 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	integer	Facultatif	Taille maximale des fichiers mis en mémoire tampon.
max_seconds_per_batch	integer	Facultatif	Nombre de secondes entre les lots. La valeur par défaut est `10`.
max_bytes_per_batch	integer	Facultatif	Nombre d'octets en file d'attente avant l'importation groupée par le 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`, le champ `file_settings.file_path` doit être ajouté à la configuration et recevoir une valeur. Par exemple : `"file_settings": { "file_path": "/opt/chronicle/edr/output/sample.txt", }` Les types de collecteurs et leurs champs sont listés dans les lignes suivantes de ce tableau. Voici les types de collecteurs disponibles : `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 les données. Pour en savoir plus, consultez Collecter des données à partir de sujets Kafka.
kafka_settings.group_id	chaîne	Facultatif	ID de groupe.
kafka_settings.timeout	integer	Facultatif	Nombre maximal de secondes d'attente pour l'établissement d'une connexion. La valeur par défaut est `60`.
kafka_settings.brokers	chaîne	Facultatif	Chaîne répétée listant les brokers 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'en ajouter un, spécifiez tous les courtiers existants 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é du certificat. Par exemple : `/path/to/cert.key`
kafka_settings.tls_settings.minimum_tls_version	chaîne	Facultatif	Version TLS minimale.
kafka_settings.tls_settings.insecure_skip_verify	bool	Facultatif	Si la valeur est `true`, la validation du certificat 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	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	integer	Facultatif	Port de l'API REST Splunk.
splunk_settings.minimum_window_size	integer	Facultatif	Plage de temps 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	integer	Facultatif	Plage de temps 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. Par exemple : `search index=* sourcetype=dns`
splunk_settings.query_mode	chaîne	Facultatif	Mode de requête pour Splunk. Par 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 : `TCP` `UDP`
syslog_settings.address	chaîne	Facultatif	Adresse IP ou nom d'hôte cible où réside le collecteur et où il écoute les données Syslog.
syslog_settings.port	integer	Facultatif	Port cible sur lequel le collecteur réside et écoute les données syslog.
syslog_settings.buffer_size	integer	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	integer	Facultatif	Nombre de secondes d'inactivité après lesquelles 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é du certificat. Par exemple : `/path/to/cert.key`
syslog_settings.tls_settings.minimum_tls_version	chaîne	Facultatif	Version TLS minimale.
syslog_settings.tls_settings.insecure_skip_verify	bool	Facultatif	Si la valeur est `true`, la validation du certificat SSL est activée. La valeur par défaut est `false`.