Personnaliser les déploiements de référentiels (préversion publique)

  • Article

Il existe deux méthodes principales pour personnaliser le déploiement de votre contenu de référentiel sur des espaces de travail Microsoft Sentinel. Chaque méthode utilise des fichiers et une syntaxe différents. Tenez donc compte de ces exemples pour commencer.

  • Modifiez le workflow GitHub ou le pipeline DevOps pour personnaliser des options de déploiement telles que le déclencheur de déploiement de votre connexion, le chemin d’accès de déploiement ou l’utilisation de déploiements intelligents.

  • Utilisez le fichier de configuration nouvellement introduit pour contrôler l’ordre de priorité de vos déploiements de contenu, choisissez d’exclure des fichiers de contenu spécifiques de ces déploiements ou de mapper des fichiers de paramètres à des fichiers de contenu spécifiques.

Important

La fonctionnalité Référentiels de Microsoft Sentinel est actuellement en PRÉVERSION. Consultez l’Avenant aux conditions d’utilisation pour les préversions de Microsoft Azure pour connaître les conditions juridiques supplémentaires s’appliquant aux fonctionnalités Azure sont en version bêta, en préversion ou non encore en disponibilité générale.

Prérequis et étendue

Microsoft Sentinel prend actuellement en charge les connexions aux référentiels GitHub et Azure DevOps. Avant de connecter votre espace de travail Microsoft Sentinel à un référentiel de contrôle de code source, assurez-vous que vous disposez de ce qui suit :

  • Rôle Propriétaire dans le groupe de ressources auquel appartient votre espace de travail Microsoft Sentinel ou combinaison des rôles Administrateur de l’accès utilisateur et Contributeur Sentinel pour créer la connexion
  • Accès collaborateur à votre référentiel GitHub ou accès administrateur de projet à votre référentiel Azure DevOps
  • Actions activées pour GitHub et Pipelines activés pour Azure DevOps
  • Vérifier que les fichiers de contenu personnalisé que vous souhaitez déployer sur vos espaces de travail se trouvent dans des modèles Azure Resource Manager (ARM) pertinents

Pour plus d’informations, consultez Valider votre contenu.

Personnaliser le workflow ou le pipeline

Le workflow par défaut déploie uniquement le contenu qui a été modifié depuis le dernier déploiement en fonction des commits dans le dépôt. Toutefois, vous pouvez avoir besoin d’autres personnalisations, telles celles nécessaires pour configurer différents déclencheurs de déploiement ou pour déployer du contenu exclusivement à partir d’un dossier racine spécifique.

Sélectionnez l’un des onglets suivants en fonction de votre type de connexion :

Pour personnaliser votre flux de travail de déploiement GitHub :

  1. Dans GitHub, accédez à votre référentiel et recherchez votre flux de travail dans le répertoire .github/workflows.

    Le fichier de flux de travail est le fichier YML commençant par sentinel-deploy-xxxxx.yml. Ouvrez ce fichier. Le nom du flux de travail figure sur la première ligne et respecte la convention d’affectation de noms par défaut suivante : Deploy Content to <workspace-name> [<deployment-id>].

    Par exemple : name: Deploy Content to repositories-demo [xxxxx-dk5d-3s94-4829-9xvnc7391v83a]

  2. Sélectionnez le bouton crayon en haut à droite de la page pour ouvrir le fichier à modifier, puis modifiez le déploiement comme suit :

    • Pour modifier le déclencheur de déploiement, mettez à jour la section on dans le code, qui décrit l’événement déclenchant l’exécution du flux de travail.

      Par défaut, cette configuration est définie sur on: push, ce qui signifie que le flux de travail est déclenché lors de tout envoi (push) à la branche connectée, y compris les modifications de contenu et les ajouts de nouveau contenu au référentiel. Par exemple :

      on:
    push:
        branches: [ main ]
        paths:
        - `**`
        - `!.github/workflows/**` # this filter prevents other workflow changes from triggering this workflow
        - `.github/workflows/sentinel-deploy-<deployment-id>.yml`

      Vous pouvez modifier ces paramètres, par exemple, pour planifier l’exécution périodique du flux de travail ou pour combiner différents événements de flux de travail.

      Pour plus d’informations, consultez la documentation GitHub sur la configuration des événements de flux de travail.

    • Pour désactiver les déploiements intelligents : le comportement des déploiements intelligents est distinct du déclencheur de déploiement décrit. Accédez à la section jobs de votre flux de travail. Modifiez la valeur par défaut de smartDeployment en remplaçant true par false. Une fois cette modification commitée, la fonctionnalité de déploiement intelligent est désactivée et tous les futurs déploiements pour cette connexion redéploient tous les fichiers de contenu pertinents du dépôt sur les espaces de travail connectés.

    • Pour modifier le chemin d’accès du déploiement :

      Dans la configuration par défaut présentée pour la section on, les caractères génériques (**) dans la première ligne de la section paths indiquent que la branche entière se trouve dans le chemin d’accès pour les déclencheurs de déploiement.

      Cette configuration par défaut signifie qu’un flux de travail de déploiement est déclenché à chaque envoi (push) de contenu à une partie quelconque de la branche.

      Plus loin dans le fichier, la section jobs contient la configuration par défaut suivante : directory: '${{ github.workspace }}'. Cette ligne indique que la branche GitHub entière se trouve dans le chemin d’accès pour le déploiement de contenu, sans filtrage des chemins d’accès de dossiers.

      Pour déployer du contenu uniquement à partir d’un chemin d’accès de dossier spécifique, ajoutez-le à la configuration de paths et de directory. Par exemple, pour déployer du contenu uniquement à partir d’un dossier racine nommé SentinelContent, mettez à jour votre code comme suit :

      paths:
- `SentinelContent/**`
- `!.github/workflows/**` # this filter prevents other workflow changes from triggering this workflow
- `.github/workflows/sentinel-deploy-<deployment-id>.yml`

...
    directory: '${{ github.workspace }}/SentinelContent'

Pour plus d’informations, consultez la documentation GitHub sur GitHub Actions et la modification de flux de travail GitHub.

Important

Dans GitHub et Azure DevOps, veillez à ce que les répertoires des chemins de déclenchement et de déploiement soient cohérents.

Mettre à l’échelle vos déploiements avec des fichiers de paramètres

Au lieu de passer des paramètres en tant que valeurs incluse dans vos fichiers de contenu, pensez à utiliser un fichier JSON qui contient les valeurs des paramètres. Mappez ensuite ces fichiers JSON de paramètres à leurs fichiers de contenu Sentinel associés pour mieux mettre à l’échelle vos déploiements sur différents espaces de travail. Il existe plusieurs façons de mapper des fichiers de paramètres à des fichiers Sentinel, et le pipeline de déploiement des dépôts les considère dans l’ordre suivant :

A diagram showing the precedence of parameter file mappings.

  1. Existe-t-il un mappage dans le sentinel-deployment.config ? Pour plus d’informations, consultez Personnaliser votre configuration de connexion.
  2. Existe-t-il un fichier de paramètres mappé à l’espace de travail ? Oui, il s’agit d’un fichier de paramètres dans le même répertoire que les fichiers de contenu qui se termine par .parameters-<WorkspaceID>.json
  3. Existe-t-il un fichier de paramètres par défaut ? Oui, tout fichier de paramètres dans le même répertoire que les fichiers de contenu qui se termine par .parameters.json

Il est recommandé de mapper vos fichiers de paramètres via le fichier de configuration ou en spécifiant l’identifiant de l’espace de travail dans le nom de fichier pour éviter les conflits dans les scénarios avec plusieurs déploiements.

Important

Une fois qu’une correspondance de fichier de paramètres est déterminée en fonction de la priorité de mappage ci-dessus, le pipeline ignore tous les mappages restants.

La modification du fichier de paramètres mappé répertorié dans sentinel-deployment.config déclenche le déploiement de son fichier de contenu apparié. L’ajout ou la modification d’un fichier .parameters-<WorkspaceID>.json ou .parameters.json déclenche également un déploiement des fichiers de contenu appariés avec les paramètres nouvellement modifiés, sauf si des mappages de paramètres de priorité plus élevés sont en place. Les autres fichiers de contenu ne sont pas déployés tant que la fonctionnalité de déploiement intelligent est toujours activée dans le fichier de définition de workflow/pipeline.

Personnaliser votre configuration de connexion

Le script de déploiement pour les référentiels prend en charge l’utilisation d’un fichier de configuration de déploiement pour chaque branche de référentiel à compter de juillet 2022. Le fichier JSON de configuration vous permet de mapper des fichiers de paramètres aux fichiers de contenu pertinents, de hiérarchiser le contenu spécifique dans les déploiements et d’exclure du contenu spécifique des déploiements.

  1. Créez le fichier sentinel-deployment.config à la racine de votre référentiel. L’ajout, la suppression ou la modification de ce fichier de configuration entraîne un déploiement complet de tout le contenu du référentiel en fonction de la configuration mise à jour.

    Screenshot of a repository root directory. The RepositoriesSampleContent is shown with the location of the sentinel-deployment.config file.

  2. Inclure du contenu structuré JSON dans trois sections facultatives, "prioritizedcontentfiles":, "excludecontentfiles": et "parameterfilemappings":. Si aucune section n’est incluse ou si le fichier .config n’est pas omis, le processus de déploiement s’exécute toujours. Les sections non valides ou non reconnues sont ignorées.

Voici un exemple de contenu entier d’un fichier sentinel-deployment.config valide. Cet exemple se trouve également dans l’exemple de référentiels Sentinel CICD.

{
  "prioritizedcontentfiles": [
    "parsers/Sample/ASimAuthenticationAWSCloudTrail.json",
    "workbooks/sample/TrendMicroDeepSecurityAttackActivity_ARM.json",
    "Playbooks/PaloAlto-PAN-OS/PaloAltoCustomConnector/azuredeploy.json"
  ], 
  "excludecontentfiles": [
     "Detections/Sample/PaloAlto-PortScanning.json",
     "parameters"
  ],
  "parameterfilemappings": {
    "879001c8-2181-4374-be7d-72e5dc69bd2b": {
      "Playbooks/PaloAlto-PAN-OS/Playbooks/PaloAlto-PAN-OS-BlockIP/azuredeploy.json": "parameters/samples/parameter-file-1.json"
    },
    "9af71571-7181-4cef-992e-ef3f61506b4e": {
      "Playbooks/Enrich-SentinelIncident-GreyNoiseCommunity-IP/azuredeploy.json": "path/to/any-parameter-file.json"
    }
  },
  "DummySection": "This shouldn't impact deployment"
}

Notes

N’utilisez pas la barre oblique inverse « \ » dans l’un des chemins de contenu. Utilisez plutôt la barre oblique « / ».

  • Pour hiérarchiser les fichiers de contenu :

    À mesure que la quantité de contenu de votre référentiel augmente, les temps de déploiement peuvent augmenter. Ajoutez du contenu respectant le temps à cette section pour hiérarchiser son déploiement lorsqu’un déclencheur se produit.

    Ajoutez des noms de chemin d’accès complets à la "prioritizedcontentfiles": section. La mise en correspondance de caractères génériques n’est pas prise en charge pour le moment.

  • Pour exclure des fichiers de contenu, modifiez la section "excludecontentfiles": avec les noms de chemin d’accès complets des fichiers de contenu .json individuels.

  • Pour mapper les paramètres :

    Le script de déploiement accepte trois méthodes de mappage des paramètres, comme décrit dans Mettre à l’échelle vos déploiements avec des fichiers de paramètres. Le mappage des paramètres via sentinel-deployment.config a la priorité la plus élevée et garantit qu’un fichier de paramètres donné est mappé à ses fichiers de contenu associés. Modifiez simplement la section "parameterfilemappings": avec l’ID d’espace de travail de votre connexion cible et les noms de chemin d’accès complets des fichiers .json individuels.

Étapes suivantes

Un exemple de dépôt est disponible pour démontrer le fichier de configuration de déploiement et les trois méthodes de mappage de paramètres. Pour plus d’informations, consultez l’exemple de référentiels CICD Sentinel.

Pour plus d’informations sur les modèles ARM, consultez ces ressources :