GitSync

Compatible avec :

GitSync est une intégration robuste conçue par l'équipe Google Security Operations SOAR Professional Services. Elle est conçue pour synchroniser les composants Google Security Operations SOAR avec un dépôt Git. Il utilise les opérations internes de Git pour écrire directement dans le dépôt lui-même, ce qui en fait essentiellement un service de stockage de fichiers. Il fournit des méthodes pour effectuer les opérations suivantes :

  • Migrer des composants entre des instances Google Security Operations SOAR

  • Sauvegarder les composants Google Security Operations SOAR

  • Documentation automatique

  • Crée un "magasin" pour partager des composants/connaissances

  • Contrôle des versions

L'intégration se compose de plusieurs jobs Google Security Operations SOAR : des jobs push et pull pour chaque asset compatible, et des jobs push/pull pour l'ensemble de l'instance Google Security Operations SOAR. Ces jobs n'ont pas besoin d'être exécutés périodiquement, car ils ont été conçus pour être exécutés manuellement à partir de l'IDE. Toutefois, ils peuvent être utilisés comme des jobs réguliers (par exemple, pour importer un commit quotidien). 

GitSync utilisera l'API SOAR Google Security Operations pour extraire l'asset concerné, tel qu'une intégration ou une famille visuelle, et analyser toutes les informations disponibles à partir de cet asset (ces informations seront ensuite affichées dans un fichier README.md qui est généralement affiché lors de la navigation dans le dépôt). Il écrit ensuite la définition JSON de l'élément et le fichier README rendu dans le dépôt local, puis le transfère vers le dépôt distant.

GitSync peut également être utilisé pour partager des connaissances. Grâce à cette intégration, un dépôt Git peut servir de "stockage" pour les composants tels que les playbooks ou les paramètres d'ontologie conçus auparavant. Il exploite les bonnes pratiques SOAR de Google Security Operations pour optimiser la plate-forme.

Prérequis

Transférer/Extraire un dépôt existant :

  • Méthode d'authentification auprès de Git. Les combinaisons nom d'utilisateur/mot de passe (non recommandées), les jetons d'accès (recommandés) et les clés privées SSH encodées en base64 (recommandées) sont acceptés. Lorsque vous utilisez les deux derniers, le paramètre "username" n'est pas obligatoire.

  • Utilisateur local de Google Security Operations SOAR. Permet d'importer des composants. Cet utilisateur doit disposer de l'autorisation d'écrire le module cible (par exemple, un utilisateur sans accès à l'IDE ne pourra pas extraire les intégrations).

Créer un dépôt

  • Tous les points mentionnés dans la section "Envoyer/Extraire un dépôt existant" ci-dessus.

  • Dépôt distant. Il est recommandé d'avoir au moins un fichier dans le dépôt. La plupart des services Git proposent de créer un fichier README lors de la création du dépôt.

Configurer l'intégration

Vous devez configurer l'intégration en tant qu'instance partagée. Il ne peut pas être associé à un environnement existant dans Google SecOps SOAR.

Propriétés d'intégration

Nom du paramètre

Description

URL du dépôt

URL du dépôt. Lorsque vous utilisez l'authentification par nom d'utilisateur/mot de passe, cette valeur doit commencer par "https://". Si vous utilisez l'authentification SSH, cette valeur doit commencer par "git@" ou "ssh://". (Consultez "Configurer l'URL et la branche du dépôt" ci-dessous.)

Branche

Branche du dépôt avec laquelle effectuer la synchronisation.

Mot de passe/jeton/clé SSH Git

Méthode d'authentification auprès de Git. Cette valeur peut être un mot de passe/jeton Git ou une clé privée SSH. Les clés privées doivent être encodées en base64. RSA et Ed25519 sont acceptés.

Nom d'utilisateur Git

Nom d'utilisateur Git. Cette valeur n'est pas obligatoire lorsque vous utilisez l'authentification SSH.

Auteur du commit

Non obligatoire. Permet de spécifier l'auteur du commit. Cette valeur doit être au format suivant : nom d'utilisateur.

Google Security Operations SOAR Vérifier le protocole SSL

Vérifier le protocole SSL pour l'API Google Security Operations SOAR

Vérifier le protocole SSL Git

Valider le protocole SSL avec le service Git cible

Configurer l'URL et la branche du dépôt

Dans ce guide, nous allons vous montrer comment obtenir les bonnes valeurs dans Bitbucket (notez que le processus est le même dans GitHub).


  1. Localisez le dépôt dans Bitbucket.

    gitsync1

  2. Cliquez sur le bouton "Cloner" en haut à droite (Code dans GitHub).

    • Authentification SSH : l'URL du dépôt est git@bitbucket.org:siemplifyproserv/connectors.git

      gitsync2

  3. Authentification par nom d'utilisateur/mot de passe ou par jeton : l'URL du dépôt est https://bitbucket.org/siemplifyproserv/connectors.git . (Le nom d'utilisateur peut être ignoré)

    gitsync3

  4. Vérifiez la branche actuelle (master dans l'image ci-dessous).

    gitsync4

Exemple d'utilisation

Chaque job dans GitSync contient les paramètres suivants :


Nom

Description

Spécifiques à la tâche : nom du connecteur, identifiant d'intégration, liste d'autorisation des playbooks, etc.

Ces paramètres permettent de spécifier ce qui est transféré ou extrait du dépôt. Dans GitSync, les composants sont désignés par leurs identifiants. Ces valeurs sont sensibles à la casse.

URL et branche du dépôt

Ajout de la prise en charge de plusieurs dépôts avec les mêmes identifiants. Une fois ces paramètres définis, le dépôt configuré dans l'instance d'intégration sera ignoré. 

Message de validation

Lorsque vous transférez des composants au dépôt, un message est requis pour le commit. Vous pouvez y indiquer la raison de l'envoi, en précisant ce qui a été corrigé, modifié ou ajouté à l'asset.

Module complémentaire Readme

Ajoute la possibilité d'étendre la documentation des composants lorsqu'ils sont transférés. Vous pouvez utiliser les valeurs suivantes :

  • Syntaxe Markdown : compatible avec les fichiers README des fournisseurs Git tels que GitHub et Bitbucket

  • Jinja : pour afficher des informations sur le composant. Consultez des exemples dans les constantes du gestionnaire d'intégration.

Le modèle est ajouté à la fin de la documentation et enregistré dans le fichier de métadonnées GitSync.json à la racine du dépôt.


Récupérer des composants

Dans cet exemple, nous allons extraire un connecteur avec les mappages et les familles visuelles appropriés.

  1. Tout d'abord, assurez-vous que le composant se trouve dans le dépôt configuré. Il vous suffit de parcourir les répertoires du dépôt et de copier l'identifiant de l'élément (il s'agit généralement du nom du répertoire ou du titre du fichier README).
    gitsync5

    Exemple tiré d'un dépôt dans Bitbucket, dans le répertoire "Connectors". Notez que les répertoires sont les noms d'intégration et qu'ils contiennent les identifiants réels des connecteurs.

  2. Trouvez le job adapté dans l'IDE SOAR Google Security Operations. Dans cet exemple, nous allons utiliser le job Pull Connector.

    • Remarque : Lorsque vous retirez un connecteur, vérifiez que l'intégration du connecteur est également installée.

  3. Cliquez sur l'onglet "Test" et configurez les paramètres. Comme nous utilisons un seul dépôt et qu'il est déjà configuré dans l'instance d'intégration, nous allons laisser les paramètres "URL du dépôt" et "Branche" vides, et définir les autres paramètres sur les valeurs dont nous avons besoin.

  4. Exécuter la tâche.

  5. Consultez la sortie de débogage pour obtenir le journal de l'opération. Si tout se passe bien, le journal l'indiquera.

  6. Accédez à Google Security Operations SOAR > Connecteurs, puis configurez le connecteur.


 Envoyer des composants

Dans cet exemple, nous allons transférer un playbook et un bloc vers le dépôt.

  1. Identifiez les playbooks que vous souhaitez transférer. Nous allons ajouter un nouveau bloc appelé "Échec de connexion" et un playbook mis à jour appelé "Activité malveillante".

    gitsync7

  2. Trouvez le job adapté dans l'IDE SOAR Google Security Operations. Dans cet exemple, nous allons utiliser le job "Push Playbook".

  3. Cliquez sur l'onglet "Test" et configurez les paramètres.

  4. Comme les deux se trouvent dans le même dossier (par défaut), vous pouvez également utiliser la liste d'autorisation des dossiers.

  5. Exécuter la tâche.

  6. Consultez la sortie de débogage pour obtenir le journal de l'opération. Si tout se passe bien, le journal l'indiquera.

  7. Vérifiez que le dépôt contient les dernières versions des playbooks.


Créer un dépôt

Pour créer un dépôt, une seule chose est importante : inclure un seul fichier dans le dépôt avant de le configurer avec GitSync. Vous pouvez le faire rapidement en incluant un fichier README à la racine du dépôt lors de sa création.
Bitbucket

gitsync8

GitHub

gitsync9

Limites et problèmes connus

  • Une fois le dépôt configuré pour la première fois, il utilise une structure de répertoire prédéfinie pour savoir où se trouve chaque élément. Si vous ne respectez pas la structure du répertoire avec un commit personnalisé ou des modifications apportées au dépôt, l'intégration ne fonctionnera pas correctement. Vous trouverez le schéma de la structure du répertoire du dépôt à la fin de ce document.

  • Soyez prudent lorsque vous utilisez cette intégration avec des dépôts publics. Les composants SOAR Google Security Operations utilisent des paramètres contenant des ID d'application, des ID client, des noms d'utilisateur et d'autres informations sensibles. GitSync ne peut pas déterminer si un paramètre est sensible ou non. Par conséquent, tous les paramètres qui ne sont pas de type "Password" seront importés dans le dépôt. De plus, lorsque vous transférez une instance SOAR Google Security Operations (tâche "Transférer l'environnement"), vous avez la possibilité d'enregistrer les mots de passe. Cette option indique à GitSync d'essayer d'exporter tous les paramètres de mot de passe à partir de la configuration de l'intégration. Ne définissez pas cette valeur sur "true" si le dépôt est public, car toutes les identifiants seront divulgués en ligne.

  • Lorsque vous extrayez une instance SOAR Google Security Operations (job "Pull Environment"), l'installation de toutes les intégrations peut prendre plus de cinq minutes. Le job échouera alors en raison d'un délai d'inactivité. Nous vous recommandons d'installer manuellement toutes les intégrations commerciales depuis la place de marché Google Security Operations au préalable pour éviter tout problème. Toutefois, il est également possible de relancer le job s'il échoue avec un délai d'expiration.

  • Les intégrations commerciales et personnalisées sont traitées différemment. L'intégration personnalisée sera envoyée sous la forme d'un fichier ZIP complet de l'intégration, pour une opération d'importation/exportation. Les intégrations commerciales ne seront envoyées qu'avec le code personnalisé. Une fois extraite, GitSync installe la dernière version de l'intégration depuis Google SecOps Marketplace et enregistre le code personnalisé dans l'intégration officielle.

  • Lorsque vous récupérez des mappages, ils n'apparaissent pas dans le tableau Paramètres > Ontologie > État de l'ontologie tant que les événements n'ont pas été ingérés dans Google Security Operations SOAR, car ils ne sont pas encore indexés.

  • Le dépôt local est enregistré dans /opt/siemplify/siemplify_server/GitSyncFiles/{RepoName}. Étant donné que l'intégration écrit des objets Git et non des fichiers, ce dossier ne représente pas le dépôt et est écrasé par toute modification apportée à chaque fois qu'un job est exécuté. Il est conseillé d'utiliser un autre clone du dépôt, et non celui créé par GitSync.

  • Les playbooks dont les autorisations sont limitées (par exemple, les autorisations par défaut définies sur Peut afficher) nécessitent une configuration d'autorisation spécifique sur le système source pour que la synchronisation via GitSync réussisse. Pour en savoir plus, consultez Utiliser les autorisations de playbook.

  • Google SecOps est compatible avec GitSync pour sauvegarder les composants SOAR. Toutefois,Google SecOps n'est pas compatible avec l'utilisation de GitSync pour *distribuer* les composants SOAR entre les systèmes. Cela peut entraîner des résultats inattendus, car les objets de base de données peuvent ne pas être uniques.


Utiliser les autorisations de playbook

Lorsque vous utilisez GitSync pour synchroniser des playbooks avec des autorisations restreintes (par exemple, des autorisations par défaut définies sur Peut afficher ou d'autres paramètres non définis par défaut), vous pouvez rencontrer une erreur sur le système de destination s'il n'est pas autorisé à modifier le playbook. Cela se produit, car GitSync utilise une clé API système interne avec le rôle SOC Administrator pour effectuer des actions. Pour que la synchronisation des playbooks avec des autorisations restreintes réussisse, accordez les autorisations Peut modifier du rôle SOC Administrator sur le système source pour ces playbooks.

Activer GitSync pour extraire les playbooks avec des autorisations limitées

  1. Sur le système source :
    1. Accédez au playbook que vous souhaitez synchroniser avec GitSync.
    2. Ouvrez les paramètres d'autorisation du playbook.
    3. Assurez-vous que le rôle SOC Administrator est ajouté à la liste des entités disposant de l'autorisation Peut modifier.
  2. Après avoir ajusté les autorisations sur le système source, exécutez l'action Push Playbook (Envoyer le playbook) dans GitSync pour mettre à jour le dépôt Git avec le playbook et ses autorisations.
  3. Sur le système de destination, exécutez l'action Pull Playbook dans GitSync.

Créer des clés SSH à utiliser avec GitSync

  1. Commencez par générer une paire de clés. Lorsque vous êtes invité à saisir une phrase secrète, appuyez sur Entrée : ssh-keygen -b 2048 -t rsa -f ./id_rsa

    Deux fichiers seront créés : id_rsa (clé privée) et id_rsa.pub (clé publique). Conservez la clé privée dans un endroit sûr.

  2. Définissez la clé publique dans le dépôt. Par exemple, dans Bitbucket, saisissez les paramètres du dépôt et cliquez sur "Access Keys" (Clés d'accès). Cliquez sur "Ajouter une clé" et collez le contenu de id_rsa.pub dans le paramètre "Clé".

  3. Avant de pouvoir ajouter la clé privée à la configuration de l'intégration, elle doit être encodée en base64.

    Utilisez ces commandes pour encoder le fichier :

    • Linux :
      cat id_rsa | base64 -w 0
    • Windows :

      Ouvrez PowerShell à l'emplacement de id_rsa et collez (sur une seule ligne) :

      Write-Output [System.Text.Encoding]::ASCII.GetString([convert]::ToBase64String(([IO.File]::ReadAllBytes((Join-Path (pwd) 'id_rsa')))))
  4. Copiez la valeur imprimée dans la propriété d'intégration "Mot de passe/Jeton/Clé SSH", puis testez la connectivité de l'intégration.

Structure des répertoires du dépôt GitSync

Voici la structure de répertoire attendue dans le dépôt distant.

* Il s'agit d'un résultat de la commande "tree" pour un exemple de dépôt. Les commentaires sont en rouge.


gitsync10

gitsync11

Vous avez encore besoin d'aide ? Obtenez des réponses de membres de la communauté et de professionnels Google SecOps.