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

Faça referência a este documento se precisar manter ou atualizar um conector de dados com base nessa versão antiga e herdada do CCP.

O CCP fornece 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 por meio de API, um modelo do ARM ou como uma solução no hub de conteúdo do Microsoft Sentinel .

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

Crie seu conector de dados definindo configurações JSON, com configurações de como a página do conector de dados no Microsoft Sentinel é exibida junto com as configurações de sondagem que definem como a conexão funciona.

Use os seguintes passos para criar seu conector CCP e conectar-se à fonte de dados do Microsoft Sentinel:

Este artigo descreve a sintaxe usada nas configurações e procedimentos JSON do CCP para implantar seu conector por meio da API, de um modelo do ARM ou de uma solução do 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á entender 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 primárias necessárias para implantação. Preencha essas áreas para definir como o conector é exibido no portal do Azure e como ele conecta o Microsoft Sentinel à 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 por meio do ARM, encapsulará essas seções no modelo do ARM para conectores de dados.

Examine outros conectores de dados CCP como exemplos ou baixe o modelo de exemplo, DataConnector_API_CCP_template.json (versão prévia).

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 do 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 que é 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. guia de 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 as Instruções, para orientar a habilitaçã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. Aba Próximas etapas. Inclui informações úteis para entender como encontrar dados nos logs de eventos, tais como consultas de exemplo.

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

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

tipos de dados

graphQueries

Defina uma consulta que apresente a ingestão de dados nas últimas duas semanas no painel de gráficos de dados do .

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

instructionSteps

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 de parâmetros e a capacidade de aninhar mais etapas de instrução em grupos.

APIKey

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

Para criar parâmetros de espaço reservado, defina uma matriz adicional chamada userRequestPlaceHoldersInput na seção instruções do arquivo de configuração do CCP JSON 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"
}

InfoMessage

Aqui está um exemplo de uma mensagem de informação integrada:

Por outro lado, a imagem a seguir mostra uma mensagem de informações não embutida.

InstructionStepsGroup

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

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

Agente de Instalação

Alguns tipos 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 área de Descrição na interface do usuário do conector de dados.

permissões

fornecedor de recursos

sampleQueries

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ção:

{
   "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 do ARM, use o seguinte exemplo como um 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 estas etapas para renderizar e validar a experiência do usuário do conector.

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

Para obter mais informações sobre essa ferramenta de validação, consulte as instruções na seção Criar o conector em nosso guia de build no GitHub.

Definir as configurações de sondagem do conector

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

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

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

A seção pollingConfig inclui as seguintes propriedades:

Para obter mais informações, consulte 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 definido no elemento authType.

Parâmetros básicos do authType

Parâmetros authType de APIKey

Parâmetros do AuthType OAuth2

A Plataforma Codeless Connector dá suporte ao grant de código de autorização do 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 usará para solicitar um token de acesso.

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

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

Configuração de solicitação

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

Configuração de resposta

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

Exemplo de código pollingConfig

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

Implantar seu conector no Microsoft Sentinel e começar a ingerir dados

Depois de criar seu arquivo de configuração JSON , incluindo tanto a interface do usuário quanto a configuração de sondagem , implante o conector no workspace no Microsoft Sentinel.

1. Use uma das opções a seguir para implantar o conector de dados.

   Dica

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

   • Implantar usando modelo ARM
   • implantar via API

   Embrulhe suas coleções de configuração JSON em um modelo do ARM para implantar seu conector. Para garantir que o conector de dados seja implantado no workspace correto, defina o workspace no modelo do ARM ou selecione o workspace ao implantar o modelo do ARM.

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

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

   2. No portal do Azure, pesquise Implante um modelo personalizado.

   3. Na página de implantação personalizada , selecione Criar seu próprio modelo no editor>Carregar arquivo. Navegue até o modelo ARM local e salve suas alterações.

   4. Selecione sua assinatura e grupo de recursos e, em seguida, insira o workspace do Log Analytics no qual você deseja implantar seu conector personalizado.

   5. Selecione Revisar + criar para implantar 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 sua fonte de dados e começar a ingerir dados no Microsoft Sentinel. Você pode se conectar à fonte de dados por meio do portal, como com conectores de dados prontos para uso ou por meio da API.

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

   • Conectar por meio do 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 de InstructionSteps no elemento connectorUiConfig do arquivo de configuração CCP JSON. Se você tiver problemas com a conexão de 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ê consegue ver os logs da fonte de dados fluindo para seu workspace.

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 da configuração e verifique a conectividade. Para obter mais informações, confira Monitorar a integridade dos seus conectores de dados.

Desconecte seu 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 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óximas etapas

Caso ainda não tenha compartilhado seu novo conector de dados sem código com a comunidade do Microsoft Sentinel! Crie uma solução para o conector de dados e compartilhe-a no Microsoft Sentinel Marketplace.

Para obter mais informações, consulte

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