Compartir vía

Personalización de implementaciones de repositorios (versión preliminar pública)

  • Artículo

Hay dos formas principales de personalizar la implementación del contenido de repositorios en áreas de trabajo de Microsoft Sentinel. En cada método se usan archivos y sintaxis diferentes, por lo que debe tener en cuenta estos ejemplos al empezar.

  • Modifique el flujo de trabajo de GitHub o la canalización de DevOps para personalizar las opciones de implementación, como el desencadenador de implementación de la conexión, la ruta de acceso de implementación o el uso de implementaciones inteligentes.

  • Use el archivo de configuración recién introducido para controlar el orden priorizado de las implementaciones de contenido, excluir archivos de contenido específicos de esas implementaciones o asignar archivos de parámetros a archivos de contenido específicos.

Importante

La característica Repositorios de Microsoft Sentinel se encuentra actualmente en VERSIÓN PRELIMINAR. Consulte Términos de uso complementarios para las Versiones preliminares de Microsoft Azure para conocer los términos legales adicionales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

Requisitos previos y ámbito

Microsoft Sentinel admite actualmente conexiones a repositorios de GitHub y Azure DevOps. Antes de conectar el área de trabajo de Microsoft Sentinel a su repositorio de control de código fuente, asegúrese de que tiene lo siguiente:

  • El rol Propietario en el grupo de recursos que contiene el área de trabajo de Microsoft Sentinel o una combinación de los roles Administrador de acceso de usuario y Colaborador de Sentinel para crear la conexión
  • Acceso de colaborador al repositorio de GitHub o acceso de administrador de proyectos al repositorio de Azure DevOps
  • Acciones habilitadas para GitHub y la oferta Pipelines habilitada para Azure DevOps.
  • Asegúrese de que los archivos de contenido personalizado que quiera implementar en sus áreas de trabajo se encuentren en las plantillas de Azure Resource Manager (ARM) pertinentes

Para obtener más información, consulte Validación del contenido.

Personalización del flujo de trabajo o la canalización

El flujo de trabajo predeterminado solo implementa el contenido modificado desde la última implementación, en función de las confirmaciones en el repositorio. Pero es posible que necesites otras personalizaciones, como configurar diferentes activadores de implementación o implementar contenido exclusivamente desde una carpeta raíz específica.

Seleccione una de las pestañas siguientes según su tipo de conexión:

Para personalizar el flujo de trabajo de implementación de GitHub:

  1. En GitHub, vaya a su repositorio y busque el flujo de trabajo en el directorio .github/workflows.

    El archivo del flujo de trabajo es el archivo YML que empieza por sentinel-deploy-xxxxx.yml. Abra ese archivo; el nombre del flujo de trabajo se muestra en la primera línea y tiene la siguiente convención de nomenclatura predeterminada: Deploy Content to <workspace-name> [<deployment-id>].

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

  2. Seleccione el botón de lápiz situado en la parte superior derecha de la página para abrir el archivo para su edición y, después, modifique la implementación de la siguiente manera:

    • Para modificar el desencadenador de implementación, actualice la sección on del código, la cual describe el evento que desencadena la ejecución del flujo de trabajo.

      De forma predeterminada, esta configuración está establecida en on: push, lo que significa que el flujo de trabajo se desencadena con cualquier inserción en la rama conectada, incluidas las modificaciones en el contenido existente y las adiciones de contenido nuevo al repositorio. Por ejemplo:

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

      Es posible que quiera cambiar esta configuración, por ejemplo, para programar el flujo de trabajo para que se ejecute periódicamente o para combinar diferentes eventos de flujo de trabajo.

      Para obtener más información, vea la documentación de GitHub sobre cómo configurar eventos de flujo de trabajo.

    • Para deshabilitar las implementaciones inteligentes: el comportamiento de las implementaciones inteligentes es independiente del desencadenador de implementación descrito. Desplácese hasta la sección jobs del flujo de trabajo. Cambie el valor predeterminado de smartDeployment de true a false. Una vez confirmado este cambio, la funcionalidad de implementación inteligente está desactivada y todas las implementaciones futuras para esta conexión vuelven a implementar todos los archivos de contenido pertinentes del repositorio en las áreas de trabajo conectadas.

    • Para modificar la ruta de acceso de la implementación:

      En la configuración predeterminada que se muestra para la sección on, los caracteres comodín (**) de la primera línea de la sección paths indican que toda la rama está en la ruta de acceso de los desencadenadores de implementación.

      Esta configuración predeterminada significa que un flujo de trabajo de implementación se desencadena cada vez que se inserta contenido en cualquier parte de la rama.

      Más adelante en el archivo, la sección jobs incluye la siguiente configuración predeterminada: directory: '${{ github.workspace }}'. Esta línea indica que toda la rama de GitHub está en la ruta de acceso de la implementación de contenido, y no se está filtrando ninguna ruta de acceso de carpeta.

      Para implementar contenido únicamente desde una ruta de acceso de carpeta específica, agréguela a la configuración de paths y de directory. Por ejemplo, para implementar contenido únicamente desde una carpeta raíz denominada SentinelContent, actualice el código de la siguiente manera:

      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 obtener más información, consulte la documentación de GitHub sobre Acciones de GitHub y sobre la edición de flujos de trabajo de GitHub.

Importante

Tanto en GitHub como en Azure DevOps, asegúrese de que los directorios de las rutas de acceso del desencadenador y de implementación sean coherentes.

Escalado de las implementaciones con archivos de parámetros

En lugar de pasar parámetros como valores en línea en tus archivos de contenido, considera usar un archivo JSON que contenga los valores de los parámetros. Puedes asignar esos archivos JSON de parámetros a sus archivos de contenido de Sentinel asociados para escalar mejor las implementaciones entre diferentes áreas de trabajo. Hay varias maneras de asignar archivos de parámetros a archivos de Sentinel y la canalización de implementación del repositorio las tiene en cuenta en el orden siguiente:

A diagram showing the precedence of parameter file mappings.

  1. ¿Hay una asignación en el archivo sentinel-deployment.config? Para obtener más información, consulte Personalización de la configuración de conexión.
  2. ¿Hay un archivo de parámetros asignado al área de trabajo? Sí es un archivo de parámetros en el mismo directorio que los archivos de contenido que termina con .parameters-<WorkspaceID>.json
  3. ¿Hay un archivo de parámetros predeterminado? Sí, cualquier archivo de parámetros en el mismo directorio que los archivos de contenido que termina con .parameters.json

Se recomienda asignar los archivos de parámetros mediante el archivo de configuración o especificando el identificador del área de trabajo en el nombre de archivo para evitar conflictos en escenarios con varias implementaciones.

Importante

Una vez que se determina una coincidencia del archivo de parámetros en función de la precedencia de asignación anterior, la canalización omitirá las asignaciones restantes.

La modificación del archivo de parámetros asignado que se muestra en sentinel-deployment.config desencadena la implementación de su archivo de contenido emparejado. Agregar o modificar un archivo .parameters-<WorkspaceID>.json o .parameters.json también desencadena una implementación de los archivos de contenido emparejado junto con los parámetros recién modificados, a menos que haya una asignación de parámetros de prioridad más alta. No se implementarán otros archivos de contenido siempre que la característica de implementaciones inteligentes siga habilitada en el archivo de definición de flujo de trabajo o canalización.

Personalización de la configuración de conexión

El script de implementación para repositorios admite el uso de un archivo de configuración de implementación para cada rama de repositorio a partir de julio de 2022. El archivo JSON de configuración le ayuda a asignar archivos de parámetros a los archivos de contenido pertinentes, además de priorizar y excluir contenido específico en las implementaciones.

  1. Cree el archivo sentinel-deployment.config en la raíz del repositorio. El hecho de agregar, eliminar o modificar este archivo de configuración provocará una implementación completa de todo el contenido del repositorio según la configuración actualizada.

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

  2. Incluya contenido estructurado JSON en tres secciones opcionales, "prioritizedcontentfiles":, "excludecontentfiles": y "parameterfilemappings":. Si no se incluyen secciones o se omite el archivo .config, el proceso de implementación se sigue ejecutando. Se omiten las secciones no válidas o no reconocidas.

Este es un ejemplo de todo el contenido de un archivo sentinel-deployment.config válido. Este ejemplo también se puede encontrar en el ejemplo de repositorios CI/CD de 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

No use el carácter de barra diagonal inversa "\" en ninguna de las rutas de acceso de contenido. Use la barra diagonal "/".

  • Para priorizar los archivos de contenido:

    A medida que crezca la cantidad de contenido del repositorio, los tiempos de implementación pueden aumentar. Agregue contenido urgente a esta sección para priorizar su implementación cuando se produzca un desencadenador.

    Agregue nombres de ruta de acceso completos a la sección "prioritizedcontentfiles":. La coincidencia de caracteres comodín no se admite en este momento.

  • Para excluir archivos de contenido, modifique la sección "excludecontentfiles": con los nombres de ruta de acceso completos de los archivos de contenido .json individuales.

  • Para asignar parámetros:

    El script de implementación acepta tres métodos de parámetros de asignación como se describe en Escalar las implementaciones con archivos de parámetros. La asignación de parámetros a través de sentinel-deployment.config tienen la prioridad más alta y garantizan que un archivo de parámetros determinado se asigne a sus archivos de contenido asociados. Solo tiene que modificar la sección "parameterfilemappings": con el identificador del área de trabajo de la conexión de destino y los nombres de ruta de acceso completos de los archivos .json individuales.

Pasos siguientes

Hay disponible un repositorio de ejemplo que muestra el archivo de configuración de implementación y los tres métodos de asignación de parámetros. Para más información, consulte Ejemplo de repositorios CI/CD de Sentinel.

Tenga en cuenta estos recursos para obtener más información sobre las plantillas de ARM: