Partager via

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

  • Article
  • S’applique à:
    Microsoft Sentinel in the Azure portal, Microsoft Sentinel in the Microsoft Defender portal

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.

Méthode de personnalisation Options de déploiement couvertes
Workflow GitHub
Pipeline DevOps		 Personnaliser le déclencheur de déploiement de votre connexion
Personnaliser le chemin d’accès de votre déploiement
Activation des déploiements intelligents
Fichiers de configuration Contrôler l’ordre de priorité des déploiements de votre contenu
Choisir d’exclure des fichiers de contenu spécifiques des déploiements
Mettre à l’échelle des déploiements sur différents espaces de travail en mappant des fichiers de paramètres à des fichiers spécifiques de contenu

Important

La fonctionnalité Référentiels de Microsoft Sentinel est actuellement en PRÉVERSION. Voir les Avenant aux conditions d’utilisation supplémentaires pour les préversions de Microsoft Azure pour découvrir plus de conditions juridiques applicables aux fonctionnalités Azure qui sont en version bêta, en préversion ou qui n’ont pas encore été mises en disponibilité générale.

Prérequis

Si vous souhaitez personnaliser un déploiement de référentiels, une connexion de référentiel doit exister. Pour découvrir plus d’informations sur la création de la connexion, consultez Déployer du contenu personnalisé à partir de votre référentiel. Une fois la connexion effectuée, les conditions préalables suivantes s’appliquent :

  • 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érifiez que les fichiers de contenu personnalisé que vous souhaitez déployer sur vos espaces de travail sont dans un format pris en charge. Pour découvrir les formats pris en charge, consultez Planifier le contenu de votre référentiel.

Si vous souhaitez découvrir plus d’informations sur les types de contenu déployable, 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. Personnalisez pour configurer différents déclencheurs de déploiement ou déployez 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`

      Modifiez ces paramètres, par exemple, pour planifier l’exécution périodique du workflow ou pour combiner différents événements de workflow.

      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 inline dans vos fichiers de contenu, envisagez d’utiliser un fichier de paramètres Bicep ou un fichier JSON qui contient les valeurs des paramètres. Mappez ensuite ces fichiers de paramètres à leurs fichiers de contenu Microsoft 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 de contenu. N’oubliez pas que les fichiers de paramètres Bicep ne prennent en charge que les modèles de fichier Bicep et que les fichiers de paramètres JSON prennent en charge les deux. Le pipeline de déploiement de référentiels tient compte des fichiers de paramètres dans l’ordre suivant :

Diagramme montrant la priorité des mappages de fichiers de paramètres.

  1. Existe-t-il un mappage dans sentinel-deployment.config ?
    Pour découvrir plus d’informations, consultez Personnaliser votre configuration de connexion.

  2. Existe-t-il un fichier de paramètres mappé à l’espace de travail ? Oui. Les fichiers de contenu se trouvent dans le même répertoire avec un fichier de paramètres mappé à un espace de travail correspondant à l’un de ces modèles :
    .<WorkspaceID>.bicepparam
    .parameters-<WorkspaceID>.json

  3. Existe-t-il un fichier de paramètres par défaut ? Oui. Les fichiers de contenu se trouvent dans le même répertoire avec un fichier de paramètres correspondant à l’un de ces modèles :
    .bicepparam
    .parameters.json

Évitez les conflits avec plusieurs déploiements d’espace de travail en mappant vos fichiers de paramètres via le fichier config ou en spécifiant l’ID de l’espace de travail dans le nom de fichier.

Important

Une fois qu’une correspondance de fichier de paramètres est déterminée en fonction de la priorité de mappage, 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 associé. L’ajout ou la modification d’un fichier de paramètres par défaut ou d’un fichier de paramètres mappé à un espace de travail déclenche également un déploiement des fichiers de contenu associés, ainsi que les paramètres nouvellement modifiés, sauf si un mappage de paramètres de priorité plus élevés est 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 déclenche un déploiement complet de tout le contenu du référentiel en fonction de la configuration mise à jour.

    Capture d’écran d’un répertoire racine du référentiel. Le référentielSampleContent s’affiche avec l’emplacement du fichier sentinel-deployment.config.

  2. Incluez votre contenu structuré 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 CICD Microsoft Sentinel.

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

Remarque

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

Contenu connexe

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 découvrir plus d’informations, consultez l’exemple de référentiels CICD Microsoft Sentinel.