[Descontinuado] 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 monitorização de integridade e suporte completo 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, será necessário saber os tipos de autenticação, paginação e endpoints 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 de utilizador do conector.

• pollingConfig. Define como o Microsoft Sentinel coleta dados de sua fonte de dados. Para obter mais informações, consulte Definir 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.

Reveja outros conectores de dados CCP como exemplos ou baixe o exemplo de modelo, DataConnector_API_CCP_template.json (Pré-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. Logo. 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. Separador de Instruções. Inclui uma seção de Pré-requisitos , com uma lista de validações mínimas antes que o utilizador possa ativar o conector, e Instruções , para orientar o utilizador na ativação do conector. 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 sintaxe connectorUiConfig necessárias para configurar a interface do utilizador:

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 de 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 denominada userRequestPlaceHoldersInput na seção Instruções no 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 parâmetro userRequestPlaceHoldersInput inclui os seguintes atributos:

RótuloCopiável

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:

Grupo de Passos de Instrução

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 Windows DNS.

InstallAgent

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

metadados

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

Permissões

provedor de recursos

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 na página do conector de dados

Siga estes passos para apresentar e validar a experiência do utilizador do conector.

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

Para obter mais informações sobre essa ferramenta de validação, consulte as instruções Build the connector em nosso guia de construçã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 sintaxe da secção pollingConfig do ficheiro de configuração do CCP.

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

A seção pollingConfig inclui as seguintes propriedades:

Para mais informações, consulte o exemplo de código pollingConfig .

Configuração de autenticação

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

Parâmetros de autenticação básica (authType)

APIKey authType parâmetros

Parâmetros de tipo de autenticação OAuth2

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 do tipo de autenticação da sessão

Solicitar configuração

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

Configuração de resposta

A seção response 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 seção paging da configuração pollingConfig inclui os seguintes parâmetros:

Exemplo de código pollingConfig

O código a seguir mostra um exemplo da seção pollingConfig do arquivo de configuração do 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 tanto a configuração da interface do usuário quanto 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.

   Tip

   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 de 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 Implementar um modelo personalizado.

   3. Na página de 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 Revisar + criar para implementar o seu conector personalizado no Microsoft Sentinel.

   6. No Microsoft Sentinel, vá para a página Conectores de dados, procure o 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.

   • Ligar-se ao Portal do Azure
   • Conectar 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 elemento connectorUiConfig do arquivo de configuração JSON do 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 de Logs e verifique se vê os logs da fonte de dados a fluírem para o seu 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.

Use um dos seguintes métodos:

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

• API: Use a DISCONNECT API para fazer 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