API Forwarder Management

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

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

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

Si les exigences matérielles sont remplies, vous pouvez utiliser de nombreux collecteurs sur le même forwarder 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 un forwarder créé, vous pouvez utiliser le point de terminaison "Generate Forwarder Files" (Générer des fichiers de forwarder) pour obtenir le contenu des fichiers de configuration (.conf) et d'authentification (_auth.conf) d'un forwarder (en tant que charge utile JSON). Ces contenus peuvent ensuite être écrits dans leurs fichiers .conf respectifs pour être déployés avec le service de transfert des opérations de sécurité Google sur un système Windows ou Linux.

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

Créer un redirecteur et ses collecteurs

Vous devez créer un forwarder avant de pouvoir créer ses collecteurs.

Pour créer un forwarder et ses collecteurs :

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

S'authentifier avec l'API Google Security Operations

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 de l'API Google pour votre langage informatique.

• Interfaçage direct avec le système OAuth 2.0 à l'aide de HTTP.

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

Les bibliothèques Google Authentication sont un sous-ensemble des bibliothèques clientes des API Google. Consultez les autres implémentations de langues.

Obtenir des identifiants d'authentification de l'API

Votre représentant Google Security Operations vous fournira des identifiants de compte de service de développeur Google pour permettre au client de l'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 d'API Google:

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 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 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 des requêtes de l'API Chronicle

L'API Chronicle applique des limites au volume de requêtes qu'un client peut envoyer à la plate-forme Google Security Operations. Si vous atteignez ou dépassez la 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 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 de recherche, de gestion des transferts et d'outils.

Consultez la liste détaillée des limites de requêtes de l'API Chronicle.

La limite suivante pour l'API Chronicle Forwarder Management est appliquée et est mesurée en requêtes par seconde (RPS):

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

Cette section décrit les points de terminaison permettant de créer et de gérer des transferts. 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 transpondeur

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

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 du transpondeur, consultez la section Champs de configuration du transpondeur.

Requête

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

Corps de la requête

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

Paramètres du corps

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, cette valeur est appliquée lors de la création du transpondeur. 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 indique les valeurs de configuration appliquées lors de la création du transpondeur. 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 s'ils ont une valeur nulle dans le corps de la requête. Pour en savoir plus, consultez la section Champs de configuration du transpondeur.

Champs de réponse

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

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 transmettant.

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 administrateurs de redirection

Répertorie tous les transferts 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 transferts.

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 transfert à 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 de correctif:

?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

Exemple de requête

Il s'agit d'un exemple de requête Update Forwarder dans laquelle la requête spécifie de nouvelles valeurs pour displayName et ajoute une étiquette 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 transpondeur

Supprime un expéditeur.

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 forwarder.

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 transfert, y compris les données de configuration des collecteurs du transfert, ainsi que le contenu du fichier d'authentification (_auth.conf) utilisé par le transfert pour s'authentifier auprès de l'instance Google SecOps.

Champs de configuration du transfert

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 forwarder", 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.

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

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:

• 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. Les valeurs de configuration des collecteurs doivent être spécifiées à l'aide de "Créer un collecteur" après avoir utilisé "Créer un forwarder".

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 la section 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

Exemple de requête

Cet exemple montre les paires clé-valeur requises dans une requête "Create Collector" (Créer un collecteur). 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 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 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 à certains paramètres lors de la création de ressources si ces champs sont manquants ou s'ils ont une valeur nulle dans le corps de la requête. Pour en savoir plus, consultez la section Champs de configuration du collecteur.

Champs de réponse

En plus des champs spécifiés dans la requête et des champs pour lesquels des valeurs par défaut sont appliquées, la réponse inclut les champs suivants:

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

Liste 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 d'écraser l'intégralité de la configuration du collecteur ou d'écraser 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 d'URL updateMask dans la requête de correction. 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

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 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 aboutit, Delete Collector 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.