Condividi tramite

Personalizzare le distribuzioni del repository (anteprima pubblica)

  • Articolo
  • Si applica a:
    Microsoft Sentinel in the Azure portal, Microsoft Sentinel in the Microsoft Defender portal

Esistono due modi principali per personalizzare la distribuzione del contenuto del repository nelle aree di lavoro di Microsoft Sentinel. Ogni metodo usa file e sintassi diversi, pertanto è consigliabile iniziare a usare questi esempi.

Metodo di personalizzazione Opzioni di distribuzione descritte
Flusso di lavoro GitHub
Pipeline DevOps		 Personalizzare il trigger di distribuzione della connessione
Personalizzare il percorso di distribuzione
Abilitazione delle distribuzioni intelligenti
File di configurazione Controllare l'ordine di priorità delle distribuzioni di contenuto
Scegliere di escludere file di contenuto specifici dalle distribuzioni
Ridimensionare le distribuzioni in aree di lavoro diverse eseguendo il mapping dei file di parametri a file di contenuto specifici

Importante

La funzionalità Repository di Microsoft Sentinel è attualmente disponibile in ANTEPRIMA. Vedere le Condizioni per l'utilizzo supplementari per le anteprime di Microsoft Azure per altre condizioni legali che si applicano a funzionalità di Azure in versione beta, in anteprima o in altro modo non ancora disponibili a livello generale.

Prerequisiti

Per personalizzare una distribuzione dei repository, è necessario che esista una connessione al repository. Per altre informazioni sulla creazione della connessione, vedere Distribuire contenuto personalizzato dal repository. Dopo aver effettuato la connessione, si applicano i prerequisiti seguenti:

  • Accesso come collaboratore al repository GitHub o accesso come amministratore del progetto all'accesso al repository Azure DevOps
  • Azioni abilitate per GitHub e pipeline abilitate per Azure DevOps
  • Assicurarsi che i file di contenuto personalizzati da distribuire nelle aree di lavoro siano in un formato supportato. Per i formati supportati, vedere Pianificare il contenuto del repository.

Per altre informazioni sui tipi di contenuto distribuibili, vedere Convalidare il contenuto.

Personalizzare il flusso di lavoro o la pipeline

Il flusso di lavoro predefinito distribuisce solo il contenuto modificato dall'ultima distribuzione, in base ai commit nel repository. Personalizzare per configurare trigger di distribuzione diversi o per distribuire il contenuto esclusivamente da una cartella radice specifica.

Selezionare una delle schede seguenti a seconda del tipo di connessione:

Per personalizzare il flusso di lavoro di distribuzione GitHub:

  1. In GitHub passare al repository e trovare il flusso di lavoro nella directory .github/workflows .

    Il file del flusso di lavoro è il file YML a partire da sentinel-deploy-xxxxx.yml. Aprire il file e il nome del flusso di lavoro viene visualizzato nella prima riga e ha la convenzione di denominazione predefinita seguente: Deploy Content to <workspace-name> [<deployment-id>].

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

  2. Selezionare il pulsante a forma di matita in alto a destra della pagina per aprire il file per la modifica e quindi modificare la distribuzione come indicato di seguito:

    • Per modificare il trigger di distribuzione, aggiornare la on sezione nel codice, che descrive l'evento che attiva l'esecuzione del flusso di lavoro.

      Per impostazione predefinita, questa configurazione è impostata su on: push, il che significa che il flusso di lavoro viene attivato in qualsiasi push nel ramo connesso, incluse entrambe le modifiche al contenuto esistente e le aggiunte di nuovo contenuto al repository. Ad esempio:

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

      Modificare queste impostazioni, ad esempio, per pianificare l'esecuzione periodica del flusso di lavoro o per combinare eventi del flusso di lavoro diversi.

      Per altre informazioni, vedere la documentazione di GitHub sulla configurazione degli eventi del flusso di lavoro.

    • Per disabilitare le distribuzioni intelligenti: il comportamento delle distribuzioni intelligenti è separato dal trigger di distribuzione descritto. Passare alla jobs sezione del flusso di lavoro. Passare al smartDeployment valore predefinito da true a false. Dopo aver eseguito il commit di questa modifica, la funzionalità di distribuzione intelligente è disattivata e tutte le distribuzioni future per questa connessione ridistribuire tutti i file di contenuto pertinenti del repository alle aree di lavoro connesse.

    • Per modificare il percorso di distribuzione:

      Nella configurazione predefinita illustrata per la on sezione, i caratteri jolly (**) nella prima riga della paths sezione indicano che l'intero ramo si trova nel percorso dei trigger di distribuzione.

      Questa configurazione predefinita indica che un flusso di lavoro di distribuzione viene attivato ogni volta che viene eseguito il push del contenuto in qualsiasi parte del ramo.

      Più avanti nel file, la jobs sezione include la configurazione predefinita seguente: directory: '${{ github.workspace }}'. Questa riga indica che l'intero ramo GitHub si trova nel percorso per la distribuzione del contenuto, senza filtrare i percorsi delle cartelle.

      Per distribuire il contenuto solo da un percorso di cartella specifico, aggiungerlo sia paths directory alla configurazione che alla configurazione. Ad esempio, per distribuire il contenuto solo da una cartella radice denominata SentinelContent, aggiornare il codice come indicato di seguito:

      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'

Per altre informazioni, vedere la documentazione di GitHub su GitHub Actions e la modifica dei flussi di lavoro di GitHub.

Importante

Sia in GitHub che in Azure DevOps assicurarsi di mantenere coerente il percorso del trigger e le directory del percorso di distribuzione.

Ridimensionare le distribuzioni con file di parametri

Invece di passare parametri come valori inline nei file di contenuto, è consigliabile usare un file di parametri Bicep o un file JSON che contiene i valori dei parametri. Eseguire quindi il mapping di tali file di parametri ai file di contenuto di Microsoft Sentinel associati per ridimensionare meglio le distribuzioni in aree di lavoro diverse.

Esistono diversi modi per eseguire il mapping dei file di parametri ai file di contenuto. Tenere presente che i file di parametri Bicep supportano solo i modelli di file Bicep, ma i file di parametri JSON supportano entrambi. La pipeline di distribuzione dei repository considera i file di parametri nell'ordine seguente:

Diagramma che mostra la precedenza dei mapping dei file di parametri.

  1. È presente un mapping in sentinel-deployment.config?
    Per altre informazioni, vedere Personalizzare la configurazione della connessione.

  2. Esiste un file di parametri mappato all'area di lavoro? Sì, i file di contenuto si trovano nella stessa directory con un file di parametri mappato all'area di lavoro corrispondente a uno dei modelli seguenti:
    .<WorkspaceID.bicepparam.parameters-WorkspaceID><
    >.json

  3. Esiste un file di parametri predefinito? Sì, i file di contenuto si trovano nella stessa directory con un file di parametri corrispondente a uno di questi modelli:
    .bicepparam
    .parameters.json

Evitare conflitti con più distribuzioni dell'area di lavoro eseguendo il mapping dei file di parametri tramite il file di configurazione o specificando l'ID dell'area di lavoro nel nome file.

Importante

Una volta determinata una corrispondenza del file di parametri in base alla precedenza del mapping, la pipeline ignora tutti i mapping rimanenti.

La modifica del file di parametri mappato elencato in sentinel-deployment.config attiva la distribuzione del file di contenuto associato. L'aggiunta o la modifica di un file di parametri mappato all'area di lavoro o di un file di parametri predefinito attiva anche una distribuzione dei file di contenuto associati insieme ai parametri appena modificati, a meno che non sia presente un mapping di parametri di precedenza superiore. Altri file di contenuto non vengono distribuiti finché la funzionalità di distribuzione intelligente è ancora abilitata nel file di definizione del flusso di lavoro o della pipeline.

Personalizzare la configurazione della connessione

Lo script di distribuzione per i repository supporta l'utilizzo di un file di configurazione della distribuzione per ogni ramo del repository a partire da luglio 2022. Il file JSON di configurazione consente di eseguire il mapping dei file di parametri ai file di contenuto pertinenti, assegnare priorità a contenuto specifico nelle distribuzioni ed escludere contenuto specifico dalle distribuzioni.

  1. Creare il file sentinel-deployment.config nella radice del repository. L'aggiunta, l'eliminazione o la modifica di questo file di configurazione attiva una distribuzione completa di tutto il contenuto nel repository in base alla configurazione aggiornata.

    Screenshot di una directory radice del repository. RepositorySampleContent viene visualizzato con il percorso del file sentinel-deployment.config.

  2. Includere il contenuto strutturato in tre sezioni facoltative, "prioritizedcontentfiles":, "excludecontentfiles":e "parameterfilemappings":. Se non sono incluse sezioni o se il file config viene omesso, il processo di distribuzione viene comunque eseguito. Le sezioni non valide o non riconosciute vengono ignorate.

Ecco un esempio dell'intero contenuto di un file sentinel-deployment.config valido. Questo esempio è disponibile anche nell'esempio di repository CICD di 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"
}

Nota

Non usare il carattere barra rovesciata "\" in uno dei percorsi di contenuto. Usare invece la barra "/".

  • Per classificare in ordine di priorità i file di contenuto:

    Man mano che aumenta la quantità di contenuto nel repository, i tempi di distribuzione possono aumentare. Aggiungere contenuto sensibile al tempo a questa sezione per classificare in ordine di priorità la distribuzione quando si verifica un trigger.

    Aggiungere nomi di percorso completi alla "prioritizedcontentfiles": sezione. La corrispondenza con caratteri jolly non è attualmente supportata.

  • Per escludere i file di contenuto, modificare la "excludecontentfiles": sezione con nomi di percorso completi dei singoli file di contenuto .json.

  • Per eseguire il mapping dei parametri:

    Lo script di distribuzione accetta tre metodi di mapping dei parametri, come descritto in Ridimensionare le distribuzioni con i file di parametri. Il mapping dei parametri tramite sentinel-deployment.config ha la precedenza più alta e garantisce che un determinato file di parametri sia mappato ai file di contenuto associati. Modificare la "parameterfilemappings": sezione con l'ID dell'area di lavoro della connessione di destinazione e i nomi completi dei singoli file di .json.

Contenuto correlato

È disponibile un repository di esempio che illustra il file di configurazione della distribuzione e tutti e tre i metodi di mapping dei parametri. Per altre informazioni, vedere l'esempio di repository CICD di Microsoft Sentinel.