Gestire il contenuto come codice con i repository Microsoft Sentinel

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

Microsoft Sentinel repository consentono di distribuire e gestire contenuto Sentinel personalizzato da un repository di controllo del codice sorgente esterno per l'integrazione continua/recapito continuo (CI/CD). Questa automazione elimina la necessità di processi manuali per aggiornare e distribuire il contenuto personalizzato nelle aree di lavoro. Un sottoinsieme dei contenuti come codice è costituito dai rilevamenti come codice (DaC). Microsoft Sentinel Repository implementa anche DaC.

Per altre informazioni sul contenuto Sentinel, vedere Informazioni sul contenuto e sulle soluzioni Microsoft Sentinel.

Funzionamento dei repository Microsoft Sentinel

È possibile distribuire questi tipi di contenuto personalizzati di Microsoft Sentinel da un repository esterno di controllo del codice sorgente che si connette a Microsoft Sentinel:

  • Regole di analisi
  • Regole di automazione
  • Regole di rilevamento personalizzate (anteprima)
  • Query di ricerca
  • Parser
  • Playbook
  • Cartelle di lavoro

Gli aggiornamenti apportati al contenuto nei repository di Microsoft Sentinel vengono sincronizzati nell'area di lavoro di Microsoft Sentinel e sovrascrivono tutte le modifiche apportate a tale contenuto tramite il portale di Microsoft Sentinel. I repository Microsoft Sentinel diventano l'unica fonte di verità per il contenuto personalizzato nelle aree di lavoro connesse.

Pianificare la connessione al repository

Microsoft Sentinel repository richiedono un'attenta pianificazione per assicurarsi di disporre delle autorizzazioni appropriate dall'area di lavoro al repository (repository) che si vuole connettere.

  • Sono supportate solo le connessioni a GitHub e Azure repository DevOps.
  • È necessario l'accesso dei collaboratori al repository GitHub o all'amministratore del progetto al repository Azure DevOps.
  • L'applicazione Microsoft Sentinel richiede l'autorizzazione per il repository.
  • Le azioni devono essere abilitate per GitHub.
  • Le pipeline devono essere abilitate per Azure DevOps.
  • Una connessione DevOps Azure deve trovarsi nello stesso tenant dell'area di lavoro Microsoft Sentinel.

La creazione di una connessione a un repository richiede un ruolo proprietario nel gruppo di risorse che contiene l'area di lavoro Microsoft Sentinel.

Se trovi contenuto in un repository pubblico di cui non sei collaboratore, per prima cosa importa, crea un fork o clona il contenuto in un repository di cui sei collaboratore. Connettere quindi il repository all'area di lavoro Microsoft Sentinel. Per altre informazioni, vedere Distribuire contenuto personalizzato dal repository.

Numero massimo di connessioni e distribuzioni

  • Ogni area di lavoro Microsoft Sentinel è attualmente limitata a cinque connessioni al repository.
  • Ogni gruppo di risorse di Azure può contenere al massimo 800 distribuzioni nella cronologia delle distribuzioni. Se si dispone di un volume elevato di distribuzioni di modelli in uno o più gruppi di risorse, è possibile che venga visualizzato l'errore Deployment QuotaExceeded . Per altre informazioni, vedere DeploymentQuotaExceeded nella documentazione dei modelli di Azure Resource Manager.

Pianificare il contenuto del repository

Microsoft Sentinel repository supportano la distribuzione del contenuto archiviato come file Bicep o modelli di Azure Resource Manager (ARM). È consigliabile usare Bicep, che è più intuitivo e semplifica la descrizione delle risorse Azure e del contenuto Microsoft Sentinel.

Il modello per ogni tipo di contenuto ha una struttura e un nome di parametro specifici, come illustrato nel riferimento al modello di risorse Sentinel. Per alcuni esempi di ciascun tipo di contenuto, consulta il RepositoriesSampleContent repository.

È stato fornito un repository di esempio con i modelli per ognuno dei tipi di contenuto elencati. Il repo mostra anche come usare le funzionalità avanzate delle connessioni del repository. Per ulteriori informazioni, vedi esempio di repository CI/CD di Microsoft Sentinel.

Screenshot di una connessione al repository riuscita. Viene visualizzato RepositoriesSampleContent. Questo screenshot è successivo all'importazione dell'esempio dal repository SentinelCICD in un repository GitHub privato nell'organizzazione FourthCoffee.

Anche se è possibile creare modelli da zero, spesso è più semplice iniziare dai file YAML del repository GitHub pubblico Sentinel o dal contenuto predefinito Microsoft Sentinel. Questa tabella illustra come convertire un modello ARM da utilizzare con i Repository di Microsoft Sentinel.

Tipo di contenuto Converti da YAML pubblico di Sentinel Esportare da Sentinel Informazioni di riferimento sul modello Modelli di esempio
Regole di analisi Script di PowerShell Esportare la funzionalità o lo script di PowerShell Riferimenti Modelli ARM
Regole di automazione N/D Esportare la funzionalità o gli script di PowerShell Riferimenti N/D
Query di ricerca Script di PowerShell Comandi di interfaccia della riga di comando di Azure Riferimenti Contenuto di esempio
Parser Script di PowerShell ASIM Comandi di interfaccia della riga di comando di Azure Riferimenti Modelli
Playbook N/D Utilità PowerShell Riferimenti N/D
Cartelle di lavoro N/D Esportazione di cartelle di lavoro come modelli ARM Riferimenti N/D

Importante

Considerazioni su Bicep:

  • Per usare i file Bicep, la connessione ai repository deve essere aggiornata se la connessione è stata creata prima del 1° novembre 2024. Per eseguire l'aggiornamento, è necessario rimuovere e ricreare le connessioni dei repository.
  • I file Bicep non supportano la id proprietà . Quando si decompila ARM JSON in Bicep, verificare di non includere questa proprietà. Ad esempio, i modelli di regola analitica esportati da Microsoft Sentinel hanno la id proprietà che deve essere rimossa.
  • Modificare lo schema JSON arm in versione 2019-04-01 per ottenere risultati ottimali durante la decompilazione.

Le regole di analisi distribuite usando la funzionalità Microsoft Sentinel repository possono usare query tra aree di lavoro solo se l'area di lavoro di destinazione si trova nello stesso gruppo di risorse dell'area di lavoro connessa al repository.

Per informazioni sulla creazione di contenuto personalizzato da zero, vedere il wiki Microsoft Sentinel GitHub pertinente per ogni tipo di contenuto.

Distribuire regole di rilevamento personalizzate come codice (anteprima)

Importante

Il supporto delle regole di rilevamento personalizzate nei repository Microsoft Sentinel è attualmente in anteprima. Vedi le Condizioni supplementari d'uso per le anteprime di Microsoft Azure per conoscere le condizioni legali applicabili alle funzionalità di Azure che sono in beta, in anteprima o non ancora rilasciate nella disponibilità generale.

È possibile gestire le regole di rilevamento personalizzate come codice nel repository usando l'estensione MICROSOFT SECURITY BICEP. Le regole di rilevamento personalizzate usano un'estensione BICEP e un provider di risorse diversi rispetto ad altri tipi di contenuto Microsoft Sentinel.

Prerequisiti per le regole di rilevamento personalizzate

Oltre ai prerequisiti di connessione al repository standard, le regole di rilevamento personalizzate richiedono:

  • Una licenza Microsoft 365 E5 (o una licenza equivalente che include Microsoft Defender XDR).
  • Aree di lavoro di Microsoft Sentinel connesse al portale Microsoft Defender.

Configurare l'estensione MICROSOFT SECURITY BICEP

Le regole di rilevamento personalizzate richiedono l'estensione MICROSOFT SECURITY BICEP. Creare un file bicepconfig.json nella radice del repository:

{
  "extensions": {
    "MicrosoftSecurity": "br:mcr.microsoft.com/bicep/extensions/microsoftsecurity:v1.0.1"
  }
}

Questa configurazione è necessaria sia per la sincronizzazione basata su repository che per la distribuzione BICEP diretta.

Crea un file BICEP per una regola di rilevamento personalizzata

Definire una regola di rilevamento personalizzata usando il Microsoft.Security/detectionRules tipo di risorsa. Creare un .bicep file (ad esempio, detectionRule.bicep) con la struttura seguente:

extension MicrosoftSecurity

resource detectionRule 'Microsoft.Security/detectionRules@2026-06-01-preview' = {
  id: 'custom-rule-id'
  displayName: 'Custom Rule Display Name'
  status: 'enabled'
  queryCondition: {
    queryText: 'DeviceProcessEvents | take 10 | project DeviceId, Timestamp, FileName'
  }
  schedule: {
    frequency: 'PT1H'
  }
  detectionAction: {
    alertTemplate: {
      title: '<ruleTitle>'
      description: 'Custom detection rule'
      severity: 'medium'
      tactics: [
        {
          tactic: 'Execution'
          techniques: [
            {
              technique: 'T1059'
            }
          ]
        }
      ]
      entityMappings: {
        hosts: [
          {
            id: 'h'
            deviceIdColumn: 'DeviceId'
          }
        ]
      }
    }
  }
}

Le regole vengono identificate in modo univoco dal relativo ID, che deve essere specificato nel modello.

Distribuire regole di rilevamento personalizzate

È possibile distribuire regole di rilevamento personalizzate usando uno dei metodi seguenti.

Metodo di distribuzione Description Chi esegue la distribuzione
Repository di Microsoft Sentinel (sincronizzazione) Sincronizzazione automatica dal repository GitHub o Azure DevOps a Microsoft Sentinel. Sentinel esegue automaticamente la distribuzione in ogni commit.
Interfaccia della riga di comando di BICEP (diretta) Eseguire la distribuzione usando az deployment group create da interfaccia della riga di comando di Azure. La distribuzione viene eseguita manualmente o da una pipeline personalizzata.

Opzione 1: Eseguire la distribuzione con repository Microsoft Sentinel

  1. Esegui il commit del file BICEP e bicepconfig.json nel tuo repository GitHub o Azure DevOps.
  2. Nel portale di Microsoft Defender, passare a Microsoft Sentinel>Gestione dei contenuti>Repository.
  3. Creare una nuova connessione al repository o modificarne una esistente.
  4. Nelle impostazioni di connessione selezionare Regole di rilevamento personalizzate in Tipi di contenuto.
  5. Salva la connessione.

Dopo l'abilitazione, Microsoft Sentinel sincronizza automaticamente le regole di rilevamento personalizzate dal repository.

Opzione 2: Distribuire direttamente con BICEP

Eseguire il comando interfaccia della riga di comando di Azure seguente:

az deployment group create \
  --resource-group <RESOURCE_GROUP> \
  --template-file detectionRule.bicep \
  --name mtp-deployment

Verificare che la distribuzione sia stata completata correttamente nel gruppo di risorse.

Convalidare la distribuzione

Dopo la distribuzione con una delle opzioni seguenti:

  1. Verificare che la regola di rilevamento venga visualizzata nell'elenco di regole di rilevamento personalizzate nel portale di Microsoft Defender.
  2. Verificare che la regola sia abilitata e stia producendo i risultati previsti.
  3. Se è stata usata la sincronizzazione del repository (opzione 1), apportare modifiche nel repository per convalidare il comportamento di sincronizzazione.

Limitazioni dell'anteprima

Durante l'anteprima:

  • La frequenza personalizzata per i dati Microsoft Sentinel non è supportata.
  • I dettagli personalizzati non sono supportati.

Migliorare le prestazioni con distribuzioni intelligenti

Consiglio

Per garantire il funzionamento delle distribuzioni intelligenti in GitHub, i flussi di lavoro devono disporre delle autorizzazioni di lettura e scrittura nel repository. Per altre informazioni, vedere Gestione delle impostazioni di GitHub Actions per un repository.

La funzionalità distribuzioni intelligenti è una funzionalità back-end che migliora le prestazioni monitorando attivamente le modifiche apportate ai file di contenuto di un repository connesso. Usa un file CSV all'interno della .sentinel cartella nel repository per controllare ogni commit. Il flusso di lavoro evita la ridistribuzione del contenuto che non è stato modificato dall'ultima distribuzione. Questo processo migliora le prestazioni di distribuzione e impedisce la manomissione del contenuto non modificato nell'area di lavoro, ad esempio la reimpostazione delle pianificazioni dinamiche delle regole di analisi.

Le distribuzioni intelligenti sono abilitate per impostazione predefinita nelle connessioni appena create. Se si preferisce che tutto il contenuto del controllo del codice sorgente venga distribuito ogni volta che viene attivata una distribuzione, indipendentemente dal fatto che tale contenuto sia stato modificato o meno, modificare il flusso di lavoro per disabilitare le distribuzioni intelligenti. Per altre informazioni, vedere Personalizzare il flusso di lavoro o la pipeline.

Prendere in considerazione le opzioni di personalizzazione della distribuzione

Quando si distribuiscono contenuti con repository Microsoft Sentinel, prendere in considerazione le opzioni di personalizzazione seguenti.

Personalizzare il flusso di lavoro o la pipeline

Personalizzare il flusso di lavoro o la pipeline in uno dei modi seguenti:

  • configurare diversi trigger di distribuzione
  • distribuire il contenuto solo da una cartella radice specifica per una determinata area di lavoro
  • Pianifica il flusso di lavoro per l'esecuzione periodica
  • combinare diversi eventi del flusso di lavoro
  • disattiva le distribuzioni intelligenti

Queste personalizzazioni sono definite in un file .yml specifico del flusso di lavoro o della pipeline. Per altre informazioni su come implementare, vedere Personalizzare le distribuzioni del repository

Personalizzare la distribuzione

Dopo l'attivazione del flusso di lavoro o della pipeline, la distribuzione supporta gli scenari seguenti:

  • assegnare priorità al contenuto da distribuire prima del resto del contenuto del repository
  • escludere il contenuto dalla distribuzione
  • specificare i file di parametri del modello ARM

Queste opzioni sono disponibili tramite una funzionalità dello script di distribuzione di PowerShell chiamato dal flusso di lavoro o dalla pipeline. Per altre informazioni su come implementare queste personalizzazioni, vedere Personalizzare le distribuzioni del repository.

Gestire i repository di Microsoft Sentinel tramite l'API

Per informazioni sulla gestione dei repository Microsoft Sentinel tramite l'API, vedere le azioni Controllo del codice sorgente e Controlli del codice sorgente nell'API REST Microsoft Sentinel.

Importante

A partire da giugno 2026, le versioni precedenti delle API usate da Microsoft Sentinel repository non saranno più supportate. Se si usano le API per creare e gestire le connessioni al repository, passare all'API versione 2025-09-01, 2025-06-01 o 2025-07-01-preview prima del 15 giugno 2026 per evitare interruzioni del servizio. Le connessioni al repository esistenti non sono interessate.

Passaggi successivi

Ottenere altri esempi e istruzioni dettagliate sulla distribuzione di repository Microsoft Sentinel.

  • Last updated on