[Preterido] Criar um conector sem código herdado para o Microsoft Sentinel

Consulte este documento se precisar manter ou atualizar um conector de dados com base nessa versão mais antiga e herdada da CCP.

A CCP oferece aos parceiros, usuários avançados e desenvolvedores a capacidade de criar conectores personalizados, conectá-los e ingerir dados ao Microsoft Sentinel. Os conectores criados por meio do CCP podem ser implantados via API, um modelo ARM ou como uma solução no hub de conteúdo do Microsoft Sentinel.

Os conectores criados usando CCP são totalmente SaaS, sem quaisquer requisitos para instalações de serviço, e também incluem monitoramento de integridade e suporte total do Microsoft Sentinel.

Crie seu conector de dados definindo configurações JSON, com configurações para a aparência da página do conector de dados no Microsoft Sentinel, juntamente com configurações de sondagem que definem como a conexão funciona.

Use as seguintes etapas para criar seu conector CCP e conectar-se à sua fonte de dados a partir do Microsoft Sentinel:

Este artigo descreve a sintaxe usada nas configurações JSON CCP e procedimentos para implantar seu conector via API, um modelo ARM ou uma solução Microsoft Sentinel.

Pré-requisitos

Antes de criar um conector, recomendamos que você entenda como sua fonte de dados se comporta e exatamente como o Microsoft Sentinel precisará se conectar.

Por exemplo, você precisará saber os tipos de autenticação, paginação e pontos de extremidade de API necessários para conexões bem-sucedidas.

Criar um arquivo de configuração JSON do conector

Seu conector CCP personalizado tem duas seções JSON principais necessárias para implantação. Preencha essas áreas para definir como seu conector é exibido no portal do Azure e como ele conecta o Microsoft Sentinel à sua fonte de dados.

• connectorUiConfig. Define os elementos visuais e o texto exibidos na página do conector de dados no Microsoft Sentinel. Para obter mais informações, consulte Configurar a interface do usuário do conector.

• pollingConfig. Define como o Microsoft Sentinel coleta dados de sua fonte de dados. Para obter mais informações, consulte Configurar as configurações de sondagem do conector.

Em seguida, se você implantar seu conector sem código via ARM, encapsulará essas seções no modelo ARM para conectores de dados.

Analise outros conectores de dados CCP como exemplos ou baixe o modelo de exemplo, DataConnector_API_CCP_template.json (Visualização).

Configurar a interface do usuário do conector

Esta seção descreve as opções de configuração disponíveis para personalizar a interface do usuário da página do conector de dados.

A imagem a seguir mostra uma página de conector de dados de exemplo, realçada com números que correspondem a áreas notáveis da interface do usuário:

1. Título. O título exibido para o conector de dados.
2. Logótipo. O ícone exibido para o conector de dados. Personalizar isso só é possível ao implantar como parte de uma solução.
3. Estado. Indica se o conector de dados está ou não conectado ao Microsoft Sentinel.
4. Gráficos de dados. Exibe consultas relevantes e a quantidade de dados ingeridos nas últimas duas semanas.
5. Guia Instruções. Inclui uma seção de Pré-requisitos , com uma lista de validações mínimas antes que o usuário possa habilitar o conector, e Instruções, para orientar a ativação do conector pelo usuário. Esta seção pode incluir texto, botões, formulários, tabelas e outros widgets comuns para simplificar o processo.
6. Guia Próximas etapas. Inclui informações úteis para entender como localizar dados nos logs de eventos, como consultas de exemplo.

Aqui estão as seções e a connectorUiConfig sintaxe necessárias para configurar a interface do usuário:

Juntar todas estas peças é complicado. Use a ferramenta de validação da experiência do usuário da página do conector para testar os componentes que você montou.

Tipos de dados

graphQueries

Define uma consulta que apresenta a ingestão de dados nas últimas duas semanas no painel Gráficos de dados.

Forneça uma consulta para todos os tipos de dados do conector de dados ou uma consulta diferente para cada tipo de dados.

instruçãoPassos

Esta seção fornece parâmetros que definem o conjunto de instruções que aparecem na página do conector de dados no Microsoft Sentinel.

instruções

Exibe um grupo de instruções, com várias opções como parâmetros e a capacidade de aninhar mais instructionSteps em grupos.

APIKey

Você pode querer criar um modelo de arquivo de configuração JSON, com parâmetros de espaços reservados, para reutilizar em vários conectores ou até mesmo para criar um conector com dados que você não tem no momento.

Para criar parâmetros de espaço reservado, defina uma matriz adicional nomeada userRequestPlaceHoldersInput na seção Instruções do arquivo de configuração JSON do CCP, usando a seguinte sintaxe:

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

O userRequestPlaceHoldersInput parâmetro inclui os seguintes atributos:

CopyableLabel

Exemplo:

Código de exemplo:

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

Mensagem de Informação

Eis um exemplo de uma mensagem informativa embutida:

Por outro lado, a imagem a seguir mostra uma mensagem informativa não embutida:

InstruçãoPassosGrupo

Aqui está um exemplo de um grupo de instruções expansível:

Para obter um exemplo detalhado, consulte a configuração JSON para o conector DNS do Windows.

InstallAgent

Alguns tipos de InstallAgent aparecem como um botão, outros aparecerão como um link. Aqui estão exemplos de ambos:

do IdP

Esta seção fornece metadados na interface do usuário do conector de dados na área Descrição .

permissões

resourceProvider

exemploConsultas

Configurar outras opções de link

Para definir um link embutido usando markdown, use o exemplo a seguir. Aqui um link é fornecido em uma descrição de instruções:

{
   "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 um link como um modelo ARM, use o seguinte exemplo como guia:

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

Validar a experiência do usuário da página do conector de dados

Siga estas etapas para renderizar e validar a experiência do usuário do conector.

1. O utilitário de teste pode ser acessado por este URL - https://aka.ms/sentineldataconnectorvalidateurl
2. Ir para Microsoft Sentinel -> Conectores de dados
3. Clique no botão "importar" e selecione um arquivo json que contenha apenas a connectorUiConfig seção do seu conector de dados.

Para obter mais informações sobre essa ferramenta de validação, consulte as instruções Construir o conector em nosso guia de compilação do GitHub.

Definir as configurações de sondagem do conector

Esta seção descreve a configuração de como os dados são pesquisados de sua fonte de dados para um conector de dados sem código.

O código a seguir mostra a pollingConfig sintaxe da seção do arquivo de configuração do CCP.

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

A pollingConfig seção inclui as seguintes propriedades:

Para obter mais informações, consulte Exemplo de código pollingConfig.

Configuração de autenticação

A auth seção da configuração pollingConfig inclui os seguintes parâmetros, dependendo do tipo definido no elemento authType:

Parâmetros básicos authType

APIKey authType parâmetros

Parâmetros OAuth2 authType

A Codeless Connector Platform suporta concessão de código de autorização OAuth 2.0.

O tipo de concessão de Código de Autorização é usado por clientes confidenciais e públicos para trocar um código de autorização por um token de acesso.

Depois que o usuário retornar ao cliente por meio da URL de redirecionamento, o aplicativo obterá o código de autorização da URL e o usará para solicitar um token de acesso.

Aqui está um exemplo de como uma configuração OAuth2 pode parecer:

"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 authType da sessão

Solicitar configuração

A request seção da configuração pollingConfig inclui os seguintes parâmetros:

Configuração de resposta

A response seção da configuração pollingConfig inclui os seguintes parâmetros:

O código a seguir mostra um exemplo do valor eventsJsonPaths para uma mensagem de nível superior:

"eventsJsonPaths": [
              "$"
            ]

Configuração de paginação

A paging seção da configuração pollingConfig inclui os seguintes parâmetros:

Exemplo de pollingConfig code

O código a seguir mostra um exemplo da pollingConfig seção do arquivo de configuração 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": [
          "$"
        ]
     }
}

Implante seu conector no Microsoft Sentinel e comece a ingerir dados

Depois de criar o arquivo de configuração JSON, incluindo a interface do usuário e a configuração de sondagem, implante o conector no espaço de trabalho do Microsoft Sentinel.

1. Use uma das seguintes opções para implantar seu conector de dados.

   Gorjeta

   A vantagem de implantar por meio de um modelo do Azure Resource Manager (ARM) é que vários valores são incorporados ao modelo e você não precisa defini-los manualmente em uma chamada de API.

   • Implantar via modelo ARM
   • Implantar via API

   Envolva suas coleções de configuração JSON em um modelo ARM para implantar seu conector. Para garantir que seu conector de dados seja implantado no espaço de trabalho correto, certifique-se de definir o espaço de trabalho no modelo ARM ou selecionar o espaço de trabalho ao implantar o modelo ARM.

   1. Prepare um arquivo JSON de modelo ARM para seu conector. Por exemplo, consulte os seguintes arquivos JSON de modelo ARM:

      • Conector de dados na solução Slack
      • Conector de dados na solução GitHub

   2. No portal do Azure, procure Implantar um modelo personalizado.

   3. Na página Implantação personalizada, selecione Criar seu próprio modelo no editor>Carregar arquivo. Procure e selecione seu modelo ARM local e salve as alterações.

   4. Selecione sua assinatura e grupo de recursos e insira o espaço de trabalho do Log Analytics onde você deseja implantar seu conector personalizado.

   5. Selecione Rever + criar para implementar o seu conector personalizado no Microsoft Sentinel.

   6. No Microsoft Sentinel, vá para a página Conectores de dados, procure seu novo conector. Configure-o para começar a ingerir dados.

   Para obter mais informações, consulte Implantar um modelo local na documentação do Azure Resource Manager.

2. Configure o conector de dados para conectar a fonte de dados e começar a ingerir dados no Microsoft Sentinel. Você pode se conectar à sua fonte de dados através do portal, como com conectores de dados prontos para uso, ou via API.

   Quando você usa o portal do Azure para se conectar, os dados do usuário são enviados automaticamente. Ao se conectar via API, você precisará enviar os parâmetros de autenticação relevantes na chamada de API.

   • Conecte-se por meio do portal do Azure
   • Conecte-se via API

   Na página do conector de dados do Microsoft Sentinel, siga as instruções fornecidas para se conectar ao conector de dados.

   A página do conector de dados no Microsoft Sentinel é controlada pela configuração InstructionSteps no connectorUiConfig elemento do arquivo de configuração JSON CCP. Se você tiver problemas com a conexão da interface do usuário, verifique se você tem a configuração correta para o tipo de autenticação.

3. No Microsoft Sentinel, vá para a página Logs e verifique se você vê os logs da fonte de dados fluindo para o espaço de trabalho.

Se você não vir dados fluindo para o Microsoft Sentinel, verifique a documentação da fonte de dados e os recursos de solução de problemas, verifique os detalhes de configuração e verifique a conectividade. Para obter mais informações, consulte Monitorar a integridade dos conectores de dados.

Desconecte o conector

Se você não precisar mais dos dados do conector, desconecte o conector para interromper o fluxo de dados.

Utilize um dos métodos seguintes:

• Portal do Azure: na página do conector de dados do Microsoft Sentinel, selecione Desconectar.

• API: Use a API DISCONNECT para enviar uma chamada PUT com um corpo vazio para a seguinte 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
  

Próximos passos

Se ainda não o fez, partilhe o seu novo conector de dados sem código com a comunidade Microsoft Sentinel! Crie uma solução para o seu conector de dados e partilhe-a no Microsoft Sentinel Marketplace.

Para obter mais informações, consulte,

• Acerca das soluções do Microsoft Sentinel
• Referência de modelo ARM do conector de dados