Personalizar implementações de repositórios (Pré-visualização Pública)

  • Aplica-se a: Microsoft Sentinel in the Microsoft Defender portal, Microsoft Sentinel in the Azure portal

Existem duas formas principais de personalizar a implementação do conteúdo do seu repositório para Microsoft Sentinel áreas de trabalho. Cada método utiliza diferentes ficheiros e sintaxe, por isso, considere estes exemplos para começar.

Método de personalização Opções de implementação abrangidas
Fluxo de trabalho do GitHub
Pipeline de DevOps		 Personalizar o acionador de implementação da ligação
Personalizar o caminho de implementação
Ativação de implementações inteligentes
Arquivos de configuração Controlar a ordem priorizada das implementações de conteúdos
Optar por excluir ficheiros de conteúdo específicos de implementações
Dimensionar implementações em diferentes áreas de trabalho ao mapear ficheiros de parâmetros para ficheiros de conteúdo específicos

Importante

A funcionalidade Repositórios Microsoft Sentinel está atualmente em PRÉ-VISUALIZAÇÃO. Consulte os Termos de Utilização Suplementares para Pré-visualizações do Microsoft Azure para obter mais termos legais aplicáveis às funcionalidades Azure que estão em versão beta, pré-visualização ou que ainda não foram lançadas para disponibilidade geral.

Pré-requisitos

Para personalizar uma implementação de repositórios, tem de existir uma ligação de repositório. Para obter mais informações sobre como criar a ligação, veja Implementar conteúdo personalizado a partir do seu repositório. Após a ligação ser estabelecida, aplicam-se os seguintes pré-requisitos:

  • Acesso de colaborador ao repositório do GitHub ou ao acesso do Administrador de Projetos ao seu repositório do Azure DevOps
  • Ações ativadas para o GitHub e Pipelines ativadas para Azure DevOps
  • Certifique-se de que os ficheiros de conteúdo personalizados que pretende implementar nas áreas de trabalho estão num formato suportado. Para obter os formatos suportados, veja Planear o conteúdo do repositório.

Para obter mais informações sobre tipos de conteúdo implementáveis, veja Planear o conteúdo do repositório.

Personalizar o fluxo de trabalho ou pipeline

O fluxo de trabalho predefinido só implementa conteúdo modificado desde a última implementação, com base em consolidações no repositório. Personalize para configurar diferentes acionadores de implementação ou para implementar conteúdo exclusivamente a partir de uma pasta raiz específica.

Selecione um dos seguintes separadores consoante o seu tipo de ligação:

Para personalizar o fluxo de trabalho de implementação do GitHub:

  1. No GitHub, aceda ao seu repositório e localize o fluxo de trabalho no diretório .github/workflows .

    O ficheiro de fluxo de trabalho é o ficheiro YML que começa com sentinel-deploy-xxxxx.yml. Abra esse ficheiro e o nome do fluxo de trabalho é apresentado na primeira linha e tem a seguinte convenção de nomenclatura predefinida: Deploy Content to <workspace-name> [<deployment-id>].

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

  2. Selecione o botão de lápis no canto superior direito da página para abrir o ficheiro para edição e, em seguida, modifique a implementação da seguinte forma:

    • Para modificar o acionador de implementação, atualize a on secção no código, que descreve o evento que aciona a execução do fluxo de trabalho.

      Por predefinição, esta configuração está definida como on: push, o que significa que o fluxo de trabalho é acionado em qualquer push para o ramo ligado, incluindo modificações ao conteúdo existente e adições de novos conteúdos ao repositório. Por exemplo:

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

      Altere estas definições, por exemplo, para agendar a execução periódica do fluxo de trabalho ou para combinar diferentes eventos de fluxo de trabalho.

      Para obter mais informações, veja a documentação do GitHub sobre como configurar eventos de fluxo de trabalho.

    • Para desativar implementações inteligentes: o comportamento das implementações inteligentes é separado do acionador de implementação discutido. Navegue para a jobs secção do fluxo de trabalho. Mude o smartDeployment valor predefinido de true para false. Assim que esta alteração for consolidada, a funcionalidade de implementação inteligente é desativada e todas as implementações futuras para esta ligação implementam novamente todos os ficheiros de conteúdo relevantes do repositório para as áreas de trabalho ligadas.

    • Para modificar o caminho de implementação:

      Na configuração predefinida apresentada para a on secção, os carateres universais (**) na primeira linha da paths secção indicam que todo o ramo está no caminho para os acionadores de implementação.

      Esta configuração predefinida significa que um fluxo de trabalho de implementação é acionado sempre que esse conteúdo é emitido para qualquer parte do ramo.

      Posteriormente no ficheiro, a jobs secção inclui a seguinte configuração predefinida: directory: '${{ github.workspace }}'. Esta linha indica que todo o ramo do GitHub está no caminho para a implementação de conteúdos, sem filtrar por caminhos de pastas.

      Para implementar conteúdo apenas a partir de um caminho de pasta específico, adicione-o pathsdirectory à configuração e . Por exemplo, para implementar conteúdo apenas a partir de uma pasta raiz chamada SentinelContent, atualize o código da seguinte forma:

      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'

Para obter mais informações, veja a documentação do GitHub sobre GitHub Actions e editar fluxos de trabalho do GitHub.

Importante

No GitHub e no Azure DevOps, certifique-se de que mantém o caminho do acionador e os diretórios do caminho de implementação consistentes.

Dimensionar as implementações com ficheiros de parâmetros

Em vez de transmitir parâmetros como valores inline nos seus ficheiros de conteúdo, considere utilizar um ficheiro de parâmetro bicep ou um ficheiro JSON que contenha os valores dos parâmetros. Em seguida, mapeie esses ficheiros de parâmetros para os ficheiros de conteúdo Microsoft Sentinel associados para dimensionar melhor as suas implementações em diferentes áreas de trabalho.

Existem várias formas de mapear ficheiros de parâmetros para os ficheiros de conteúdo. Tenha em atenção que os ficheiros de parâmetros bicep só suportam modelos de ficheiro Bicep, mas os ficheiros de parâmetros JSON suportam ambos. O pipeline de implementação de repositórios considera os ficheiros de parâmetros pela seguinte ordem:

Um diagrama a mostrar a precedência dos mapeamentos de ficheiros de parâmetros.

  1. Existe um mapeamento no sentinel-deployment.config?
    Para obter mais informações, veja Personalizar a configuração da ligação.

  2. Existe um ficheiro de parâmetros mapeado pela área de trabalho? Sim, os ficheiros de conteúdo estão no mesmo diretório com um ficheiro de parâmetros mapeado pela área de trabalho que corresponde a um destes padrões:
    .<WorkspaceID.bicepparam.parameters-WorkspaceID>
    <>.json

  3. Existe um ficheiro de parâmetros predefinido? Sim, os ficheiros de conteúdo estão no mesmo diretório com um ficheiro de parâmetro que corresponde a um destes padrões:
    .bicepparam
    .parameters.json

Evite conflitos com múltiplas implementações de áreas de trabalho ao mapear os ficheiros de parâmetros através do ficheiro de configuração ou ao especificar o ID da área de trabalho no nome do ficheiro.

Importante

Assim que uma correspondência de ficheiro de parâmetros for determinada com base na precedência de mapeamento, o pipeline ignora os mapeamentos restantes.

Modificar o ficheiro de parâmetro mapeado listado no sentinel-deployment.config aciona a implementação do respetivo ficheiro de conteúdo emparelhado. Adicionar ou modificar um ficheiro de parâmetros mapeado por área de trabalho ou um ficheiro de parâmetros predefinido também aciona uma implementação dos ficheiros de conteúdo emparelhado juntamente com os parâmetros recentemente modificados, a menos que esteja em vigor um mapeamento de parâmetros de precedência superior. Outros ficheiros de conteúdo não são implementados desde que a funcionalidade de implementações inteligentes ainda esteja ativada no ficheiro de definição de fluxo de trabalho/pipeline.

Personalizar a configuração da ligação

O script de implementação para repositórios suporta a utilização de um ficheiro de configuração de implementação para cada ramo de repositório a partir de julho de 2022. O ficheiro JSON de configuração ajuda-o a mapear ficheiros de parâmetros para ficheiros de conteúdo relevantes, a atribuir prioridades a conteúdos específicos em implementações e a excluir conteúdos específicos de implementações.

  1. Crie o ficheiro sentinel-deployment.config na raiz do seu repositório. Adicionar, eliminar ou modificar este ficheiro de configuração aciona uma implementação completa de todo o conteúdo no repositório de acordo com a configuração atualizada.

    Captura de ecrã a mostrar um diretório de raiz do repositório. O RepositoriesSampleContent é apresentado com a localização do ficheiro sentinel-deployment.config.

  2. Inclua o conteúdo estruturado em três secções opcionais, "prioritizedcontentfiles":, "excludecontentfiles":e "parameterfilemappings":. Se não estiverem incluídas secções ou o ficheiro .config for omitido, o processo de implementação continuará a ser executado. As secções inválidas ou não reconhecidas são ignoradas.

Eis um exemplo de todo o conteúdo de um ficheiro desentinel-deployment.config válido. Este exemplo também pode ser encontrado no Microsoft Sentinel exemplo de repositórios CICD.

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

Observação

Não utilize o caráter "\" da barra invertida em nenhum dos caminhos de conteúdo. Em alternativa, utilize a barra "/".

  • Para atribuir prioridades a ficheiros de conteúdo:

    À medida que a quantidade de conteúdo no seu repositório aumenta, os tempos de implementação podem aumentar. Adicione conteúdo sensível ao tempo a esta secção para priorizar a implementação quando ocorre um acionador.

    Adicione nomes de caminho completos à "prioritizedcontentfiles": secção. A correspondência de carateres universais não é suportada neste momento.

  • Para excluir ficheiros de conteúdo, modifique a "excludecontentfiles": secção com nomes de caminho completos de ficheiros de conteúdo .json individuais.

  • Para mapear parâmetros:

    O script de implementação aceita três métodos de parâmetros de mapeamento, conforme descrito em Dimensionar as implementações com ficheiros de parâmetros. Os parâmetros de mapeamento através do sentinel-deployment.config têm a precedência mais elevada e garantem que um determinado ficheiro de parâmetro é mapeado para os respetivos ficheiros de conteúdo associados. Modifique a secção com o "parameterfilemappings": ID da área de trabalho da ligação de destino e os nomes de caminho completo de ficheiros de .json individuais.

Conteúdo relacionado

Está disponível um repositório de exemplo que demonstra o ficheiro de configuração de implementação e os três métodos de mapeamento de parâmetros. Para obter mais informações, veja Microsoft Sentinel exemplo de repositórios CICD.

  • Last updated on