Condividi tramite

Personalizzare le distribuzioni del repository (anteprima pubblica)

  • Articolo

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.

  • Modificare il flusso di lavoro GitHub o la pipeline DevOps per personalizzare le opzioni di distribuzione, ad esempio il trigger di distribuzione della connessione, il percorso di distribuzione o l'utilizzo di distribuzioni intelligenti.

  • Usare il file di configurazione appena introdotto per controllare l'ordine di priorità delle distribuzioni di contenuto, scegliere di escludere file di contenuto specifici da tali distribuzioni o eseguire 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 applicabili alle funzionalità di Azure disponibili in versione beta, in anteprima o non ancora rilasciate nella disponibilità generale.

Prerequisiti e ambito

Microsoft Sentinel supporta attualmente le connessioni ai repository GitHub e Azure DevOps. Prima di connettere l'area di lavoro di Microsoft Sentinel al repository del controllo del codice sorgente, assicurarsi di disporre di:

  • Ruolo Proprietario nel gruppo di risorse che contiene l'area di lavoro di Microsoft Sentinel o una combinazione di ruoli Accesso utenti Amministrazione istrator e Collaboratore sentinel per creare la connessione
  • Accesso collaboratore al repository GitHub o all'accesso di Project Amministrazione istrator al repository Di 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 si trovino nei modelli di Azure Resource Manager (ARM) pertinenti

Per altre informazioni, 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. Ma potrebbero essere necessarie altre personalizzazioni, ad esempio 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`

      È possibile modificare queste impostazioni, ad esempio, pianificare l'esecuzione periodica del flusso di lavoro o 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 JSON che contiene i valori dei parametri. Eseguire quindi il mapping dei file JSON dei parametri ai file di contenuto sentinel associati per ridimensionare meglio le distribuzioni in aree di lavoro diverse. Esistono diversi modi per eseguire il mapping dei file dei parametri ai file di Sentinel e la pipeline di distribuzione dei repository li considera nell'ordine seguente:

A diagram showing the precedence of parameter file mappings.

  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ì, si tratta di un file di parametri nella stessa directory dei file di contenuto che termina con .parameters-WorkspaceID<>.json
  3. Esiste un file di parametri predefinito? Sì, qualsiasi file di parametro nella stessa directory dei file di contenuto che termina con .parameters.json

È consigliabile eseguire il mapping dei file di parametri tramite il file di configurazione o specificando l'ID dell'area di lavoro nel nome del file per evitare conflitti negli scenari con più distribuzioni.

Importante

Una volta determinata una corrispondenza del file di parametri in base alla precedenza di mapping precedente, la pipeline ignorerà eventuali 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 con estensione parameters-WorkspaceID<>.json o .parameters.json attiva anche una distribuzione dei file di contenuto associati insieme ai parametri appena modificati, a meno che non siano presenti mapping di parametri di precedenza più elevati. 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 causerà una distribuzione completa di tutto il contenuto nel repository in base alla configurazione aggiornata.

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

  2. Includere contenuto strutturato JSON 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 Sentinel.

{
  "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"
}

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. È sufficiente modificare la "parameterfilemappings": sezione con l'ID dell'area di lavoro della connessione di destinazione e i nomi completi dei singoli file di .json.

Passaggi successivi

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

Per altre informazioni sui modelli di Resource Manager, prendere in considerazione queste risorse: