[En desuso] Creación de un conector sin código heredado para Microsoft Sentinel

Haga referencia a este documento si necesita mantener o actualizar un conector de datos basado en esta versión anterior y heredada de la CCP.

La CCP proporciona a los asociados, usuarios avanzados y desarrolladores la capacidad de crear conectores personalizados, conectarlos e ingerir datos en Microsoft Sentinel. Los conectores creados a través de la CCP se pueden implementar a través de la API, una plantilla de ARM o como solución en el centro de contenido de Microsoft Sentinel.

Los conectores creados con CCP son totalmente SaaS, sin requisitos para las instalaciones de servicio, e incluyen también la supervisión del estado y el soporte técnico completo de Microsoft Sentinel.

Cree el conector de datos mediante la definición de configuraciones JSON, con la configuración de cómo se ve la página del conector de datos en Microsoft Sentinel junto con la configuración de sondeo que define cómo funciona la conexión.

Siga estos pasos para crear el conector ccp y conectarse al origen de datos desde Microsoft Sentinel:

En este artículo se describe la sintaxis que se usa en las configuraciones y procedimientos JSON de LA CCP para implementar el conector a través de la API, una plantilla de ARM o una solución de Microsoft Sentinel.

Prerrequisitos

Antes de compilar un conector, se recomienda que comprenda cómo se comporta el origen de datos y cómo deberá conectarse Microsoft Sentinel exactamente.

Por ejemplo, deberá conocer los tipos de autenticación, paginación y puntos de conexión de API que son necesarios para las conexiones exitosas.

Creación de un archivo de configuración JSON del conector

El conector CCP personalizado tiene dos secciones JSON principales necesarias para la implementación. Rellene estas áreas para definir cómo se muestra el conector en Azure Portal y cómo conecta Microsoft Sentinel al origen de datos.

• connectorUiConfig. Define los elementos visuales y el texto que se muestran en la página del conector de datos de Microsoft Sentinel. Para más información, consulte Configuración de la interfaz de usuario del conector.

• pollingConfig. Define cómo Microsoft Sentinel recopila datos de tu origen de datos. Para más información, consulte Configuración de los valores de sondeo del conector.

A continuación, si implementa el conector sin código a través de ARM, encapsulará estas secciones en la plantilla de ARM para los conectores de datos.

Revise otros conectores de datos ccp como ejemplos o descargue la plantilla de ejemplo, DataConnector_API_CCP_template.json (versión preliminar).

Configuración de la interfaz de usuario del conector

En esta sección se describen las opciones de configuración disponibles para personalizar la interfaz de usuario de la página del conector de datos.

En la imagen siguiente se muestra una página de conector de datos de ejemplo, resaltada con números que corresponden a áreas importantes de la interfaz de usuario:

1. Título. Título que se muestra para el conector de datos.
2. Logotipo. Icono que se muestra para el conector de datos. Personalizar esto solo es posible cuando se implementa como parte de una solución.
3. Status. Indica si el conector de datos está conectado o no a Microsoft Sentinel.
4. Gráficos de datos. Muestra las consultas pertinentes y la cantidad de datos ingeridos en las últimas dos semanas.
5. Pestaña Instrucciones. Incluye una sección Requisitos previos , con una lista de validaciones mínimas antes de que el usuario pueda habilitar el conector e Instrucciones, para guiar la habilitación del usuario del conector. Esta sección puede incluir texto, botones, formularios, tablas y otros widgets comunes para simplificar el proceso.
6. Pestaña Pasos siguientes. Incluye información útil para comprender cómo buscar datos en los registros de eventos, como consultas de ejemplo.

Estas son las secciones y la connectorUiConfig sintaxis necesarias para configurar la interfaz de usuario:

Es complicado juntar todas estas piezas. Utilice la herramienta de validación de la experiencia de usuario de la página del conector para probar los componentes que ha recopilado.

tipos de datos

graphQueries

Define una consulta que presenta la ingesta de datos en las últimas dos semanas en el panel Gráficos de datos .

Proporcione una consulta para todos los tipos de datos del conector de datos o una consulta diferente para cada tipo de datos.

instructionSteps

En esta sección se proporcionan parámetros que definen el conjunto de instrucciones que aparecen en la página del conector de datos de Microsoft Sentinel.

instrucciones

Muestra un grupo de instrucciones, con varias opciones usadas como parámetros y la capacidad de anidar más pasos de instrucción en grupos.

APIKey

Es posible que quiera crear una plantilla de archivo de configuración JSON, con parámetros de marcadores de posición, reutilizar en varios conectores o incluso crear un conector con datos que no tenga actualmente.

Para crear parámetros de marcador de posición, defina una matriz adicional denominada userRequestPlaceHoldersInput en la sección Instrucciones del archivo de configuración JSON de CCP , con la sintaxis siguiente:

"instructions": [
                {
                  "parameters": {
                    "enable": "true",
                    "userRequestPlaceHoldersInput": [
                      {
                        "displayText": "Organization Name",
                        "requestObjectKey": "apiEndpoint",
                        "placeHolderName": "{{placeHolder}}"
                      }
                    ]
                  },
                  "type": "APIKey"
                }
              ]

El userRequestPlaceHoldersInput parámetro incluye los siguientes atributos:

EtiquetaCopiable

Ejemplo:

Código de ejemplo:

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}

InfoMessage

Este es un ejemplo de un mensaje de información insertado:

En cambio, la imagen siguiente muestra un mensaje de información no en línea:

InstructionStepsGroup

Este es un ejemplo de un grupo de instrucciones expandible:

Para obtener un ejemplo detallado, consulte el código JSON de configuración para el conector dns de Windows.

Agente de Instalación

Algunos tipos InstallAgent aparecen como un botón; otros aparecerán como un vínculo. Estos son ejemplos de ambos:

metadatos

En esta sección se proporcionan metadatos en la interfaz de usuario del conector de datos en el área Descripción .

permisos

proveedor de recursos

sampleQueries

Configuración de otras opciones de vínculo

Para definir un vínculo insertado mediante Markdown, use el ejemplo siguiente. Este vínculo se proporciona en una descripción de instrucciones:

{
   "title": "",
   "description": "Make sure to configure the machine's security according to your organization's security policy\n\n\n[Learn more >](https://aka.ms/SecureCEF)"
}

Para definir un vínculo como plantilla de ARM, use el ejemplo siguiente como guía:

{
   "title": "Azure Resource Manager (ARM) template",
   "description": "1. Click the **Deploy to Azure** button below.\n\n\t[![Deploy To Azure](https://aka.ms/deploytoazurebutton)]({URL to custom ARM template})"
}

Validación de la experiencia del usuario de la página del conector de datos

Siga estos pasos para representar y validar la experiencia del usuario del conector.

1. Esta dirección URL puede acceder a la utilidad de prueba: https://aka.ms/sentineldataconnectorvalidateurl
2. Vaya a Microsoft Sentinel - Conectores de datos
3. Haga clic en el botón "importar" y seleccione un archivo JSON que solo contenga la connectorUiConfig sección del conector de datos.

Para obtener más información sobre esta herramienta de validación, consulte las instrucciones de compilación del conector en nuestra guía de compilación de GitHub.

Configuración de los valores de sondeo del conector

En esta sección se describe la configuración de cómo se sondean los datos desde el origen de datos para un conector de datos sin código.

El código siguiente muestra la sintaxis de la pollingConfig sección del archivo de configuración ccp .

"pollingConfig": {
    "auth": {
    },
    "request": {
    },
    "response": {
    },
    "paging": {
    }
 }

La pollingConfig sección incluye las siguientes propiedades:

Para obtener más información, consulte Sample pollingConfig code.

Configuración de autenticación

La auth sección de la configuración pollingConfig incluye los parámetros siguientes, según el tipo definido en el elemento authType :

Parámetros básicos de authType

Parámetros de APIKey authType

Parámetros de OAuth2 authType

Codeless Connector Platform admite la concesión de código de autorización de OAuth 2.0.

Los clientes confidenciales y públicos usan el tipo de concesión de código de autorización para intercambiar un código de autorización para un token de acceso.

Después de que el usuario vuelva al cliente a través de la dirección URL de redireccionamiento, la aplicación obtendrá el código de autorización de la dirección URL y lo usará para solicitar un token de acceso.

Este es un ejemplo de cómo podría ser una configuración de OAuth2:

"pollingConfig": {
    "auth": {
        "authType": "OAuth2",
        "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent",
        "redirectionEndpoint": "https://portal.azure.com/TokenAuthorize",
        "tokenEndpoint": "https://oauth2.googleapis.com/token",
        "authorizationEndpointQueryParameters": {},
        "tokenEndpointHeaders": {
            "Accept": "application/json"
        },
        "TokenEndpointQueryParameters": {},
        "isClientSecretInHeader": false,
        "scope": "https://www.googleapis.com/auth/admin.reports.audit.readonly",
        "grantType": "authorization_code",
        "contentType": "application/x-www-form-urlencoded",
        "FlowName": "AuthCode"
    },

Parámetros de authType de sesión

Configuración de la solicitud

La request sección de la configuración pollingConfig incluye los parámetros siguientes:

Configuración de respuesta

La response sección de la configuración pollingConfig incluye los parámetros siguientes:

En el código siguiente se muestra un ejemplo del valor eventsJsonPaths para un mensaje de nivel superior:

"eventsJsonPaths": [
              "$"
            ]

Configuración de paginación

La paging sección de la configuración pollingConfig incluye los parámetros siguientes:

Código pollingConfig de ejemplo

El código siguiente muestra un ejemplo de la pollingConfig sección del archivo de configuración ccp :

"pollingConfig": {
    "auth": {
        "authType": "APIKey",
        "APIKeyIdentifier": "token",
        "APIKeyName": "Authorization"
     },
     "request": {
        "apiEndpoint": "https://api.github.com/../{{placeHolder1}}/audit-log",
        "rateLimitQPS": 50,
        "queryWindowInMin": 15,
        "httpMethod": "Get",
        "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
        "retryCount": 2,
        "timeoutInSeconds": 60,
        "headers": {
           "Accept": "application/json",
           "User-Agent": "Scuba"
        },
        "queryParameters": {
           "phrase": "created:{_QueryWindowStartTime}..{_QueryWindowEndTime}"
        }
     },
     "paging": {
        "pagingType": "LinkHeader",
        "pageSizeParaName": "per_page"
     },
     "response": {
        "eventsJsonPaths": [
          "$"
        ]
     }
}

Implementación del conector en Microsoft Sentinel e inicio de la ingesta de datos

Después de crear el archivo de configuración JSON, incluida la interfaz de usuario y la configuración de sondeo , implemente el conector en el área de trabajo de Microsoft Sentinel.

1. Use una de las siguientes opciones para implementar el conector de datos.

   Sugerencia

   La ventaja de implementar mediante una plantilla de Azure Resource Manager (ARM) es que varios valores están integrados en la plantilla y no es necesario definirlos manualmente en una llamada API.

   • Implementación mediante una plantilla de ARM
   • Implementación mediante API

   Envuelve tus colecciones de configuración JSON en una plantilla ARM para desplegar tu conector. Para asegurarse de que el conector de datos se implementa en el área de trabajo correcta, asegúrese de definir el área de trabajo en la plantilla de ARM o seleccione el área de trabajo al implementar la plantilla de ARM.

   1. Prepare un archivo JSON de plantilla de ARM para el conector. Por ejemplo, consulte los siguientes archivos JSON de plantilla de ARM:

      • Conector de datos en la solución Slack
      • Conector de datos en la solución de GitHub

   2. En Azure Portal, busque Implementación de una plantilla personalizada.

   3. En la página Implementación personalizada, seleccione Crear su propia plantilla en el editor>Cargar archivo. Vaya a y seleccione la plantilla de ARM local y, a continuación, guarde los cambios.

   4. Seleccione su suscripción y grupo de recursos, y a continuación, ingrese el espacio de trabajo de Log Analytics donde desea implementar su conector personalizado.

   5. Seleccione Revisar y crear para implementar el conector personalizado en Microsoft Sentinel.

   6. En Microsoft Sentinel, vaya a la página Conectores de datos y busque el nuevo conector. Configúrelo para empezar a ingerir datos.

   Para más información, consulte Implementación de una plantilla local en la documentación de Azure Resource Manager.

2. Configure el conector de datos para conectar el origen de datos y comenzar a ingerir datos en Microsoft Sentinel. Puede conectarse al origen de datos mediante el portal, como con los conectores de datos predefinidos, o mediante la API.

   Cuando se usa Azure Portal para conectarse, los datos de usuario se envían automáticamente. Al conectarse a través de la API, deberá enviar los parámetros de autenticación pertinentes en la llamada API.

   • Conexión mediante Azure Portal
   • Conexión a través de la API

   En la página del conector de datos de Microsoft Sentinel, siga las instrucciones que ha proporcionado para conectarse al conector de datos.

   La página del conector de datos de Microsoft Sentinel está controlada por la configuración de InstructionSteps en el elemento connectorUiConfig del archivo CCP de configuración JSON. Si tiene problemas con la conexión de la interfaz de usuario, asegúrese de que tiene la configuración correcta para el tipo de autenticación.

3. En Microsoft Sentinel, vaya a la página Registros y compruebe que los registros de su origen de datos están fluyendo hacia su área de trabajo.

Si no ve los datos que fluyen a Microsoft Sentinel, compruebe la documentación del origen de datos y los recursos de solución de problemas, compruebe los detalles de configuración y compruebe la conectividad. Para más información, consulte Supervisión del estado de los conectores de datos.

Desconectar el conector

Si ya no necesita los datos del conector, desconecte el conector para detener el flujo de datos.

Use uno de los métodos siguientes:

• Azure Portal: en la página del conector de datos de Microsoft Sentinel, seleccione Desconectar.

• API: use la API DISCONNECT para enviar una llamada PUT con un cuerpo vacío a la siguiente dirección URL:

  https://management.azure.com /subscriptions/{{SUB}}/resourceGroups/{{RG}}/providers/Microsoft.OperationalInsights/workspaces/{{WS-NAME}}/providers/Microsoft.SecurityInsights/dataConnectors/{{Connector_Id}}/disconnect?api-version=2021-03-01-preview
  

Pasos siguientes

Si aún no lo ha hecho, comparta el nuevo conector de datos sin código con la comunidad de Microsoft Sentinel. Cree una solución para el conector de datos y compártala en Marketplace de Microsoft Sentinel.

Para obtener más información, consulta

• Acerca de las soluciones de Microsoft Sentinel
• Referencia de la plantilla de ARM del conector de datos