Conectores por push do Microsoft Sentinel CCF (prévia) – Guia de primeiros passos

Este guia ajuda você a entender, compilar e implantar conectores sem código baseados em push para o Microsoft Sentinel usando o Push do CCF (Codeless Connector Framework) (versão prévia).

O que é o push do CCF?

Os conectores ccf push permitem que seus aplicativos enviem eventos de segurança diretamente para o Microsoft Sentinel em tempo real. Ao contrário dos conectores tradicionais baseados em sondagem que buscam periodicamente dados de APIs, os conectores por push permitem enviar dados por push para o Sentinel à medida que os eventos ocorrem em seu sistema.

O CCF Push oferece vários benefícios principais:

  • Fluxo de dados controlado pelo aplicativo: Seu aplicativo controla quando e como enviar dados, habilitando estratégias inteligentes de envio em lotes e uso otimizado de rede.
  • Ingestão em tempo real: Envie dados imediatamente à medida que os eventos ocorrem, sem aguardar intervalos de sondagem.
  • Arquitetura simplificada: não é necessário manter pontos de extremidade de API para o Sentinel sondar.
  • Provisionamento baseado em modelo: a implantação cria modelos ARM para DCRs, tabelas personalizadas, registro de aplicativo do Entra e segredos do cliente. Você recebe os detalhes da conexão a serem configurados em seu aplicativo de envio.
  • Autenticação segura: Usa aplicativos do Microsoft Entra com o OAuth 2.0 para envio seguro de dados.

Pré-requisitos

  • Antes de começar, você deve ter acesso ao repositório github Azure-Sentinel para ferramentas de empacotamento.
  • Permissões do Microsoft Entra:
    • Permissão para criar um registro de app no Microsoft Entra ID. Normalmente, requer a função de Desenvolvedor de Aplicativos do Entra ID ou superior.
    • Permissão para criar um aplicativo com segredos. Se você não conceder essa permissão, o conector falhará devido a motivos de segurança.
    • O publicador deve ter a função apropriada para recuperar tokens do aplicativo Microsoft Entra. Esses tokens são necessários para autenticar solicitações para o Ponto de Extremidade de Coleta de Dados (DCE), que é o ponto de extremidade em que o conector finalmente envia seus dados. Se o provedor não puder recuperar tokens, os dados não poderão ser enviados para o DCE.
  • Permissões do Microsoft Azure:
    • Permissão para atribuir a função de Editor de métricas de monitoramento na regra de coleta de dados (DCR). Normalmente, requer a função Proprietário do RBAC do Azure ou a função Administrador de Acesso de Usuário.

Como funciona o push do CCF

O modelo push versus o modelo pull

Entender a diferença entre modelos de ingestão de dados por push e pull ajuda você a escolher o tipo de conector certo para seu cenário.

Conectores de pull do CCF – baseados em sondagem:

No modelo de pull, o Microsoft Sentinel pesquisa periodicamente sua API para recuperar dados:

  • O Microsoft Sentinel inicia conexões com sua API de fonte de dados em um agendamento configurado.
  • Os dados chegam a intervalos de sondagem regulares, como a cada cinco minutos.
  • Você deve manter um ponto de extremidade de API acessível publicamente.
  • A infraestrutura de sondagem do Sentinel gerencia o processo de coleta de dados.

Conectores por push do CCF – controlados por eventos:

No modelo de push, seu aplicativo envia dados diretamente para o Microsoft Sentinel:

  • Seu aplicativo inicia o envio de dados quando ocorrem eventos.
  • Os dados chegam quase em tempo real à medida que os eventos são gerados.
  • Você não precisa manter um endpoint de API.
  • Seu aplicativo controla o envio em lote, o tempo e a otimização do fluxo de dados.

O fluxo de dados push

O fluxo de dados por push do CCF consiste em cinco etapas principais:

  1. Implante o conector no Microsoft Sentinel.

  2. O Azure cria automaticamente os seguintes recursos:

    • Aplicação Microsoft Entra com credenciais
    • DCR (Regra de Coleta de Dados) – define como processar seus dados
    • Ponto de Extremidade de Coleta de Dados (DCE) – URL para o qual você envia dados
    • Tabela de log personalizada – em que seus dados são armazenados
    • Atribuições de função – permissões para o aplicativo Entra

  3. Você recebe os seguintes detalhes de conexão:

    • ID do locatário
    • ID do aplicativo (cliente)
    • Segredo do Cliente
    • URI do DCE (URL do ponto de extremidade)
    • ID Imutável do DCR
    • Nome do Stream

  4. Seu aplicativo envia os seguintes dados:

    • Obtém um token OAuth 2.0 usando as credenciais do aplicativo Entra geradas pelo CCF. Para obter mais informações, consulte o fluxo de credenciais de cliente do OAuth 2.0
    • Formata eventos como JSON que correspondem ao esquema de tabela
    • Envia dados para o endpoint DCE

  5. O Azure processa e armazena dados:

    • DCRs transforma os dados (transformações opcionais de KQL)
    • Os dados são gravados na tabela personalizada no Log Analytics
    • Os dados estão disponíveis para consultas, análises e alertas no Sentinel

Artefatos de push do CCF

Uma solução de conector CCF Push é composta por quatro componentes principais:

  • Definição de tabela personalizada
  • Regra de coleta de dados (DCR)
  • Definição do conector (interface do usuário)
  • Configuração do conector por push

Definição de tabela personalizada

O que é: O esquema que define a estrutura de seus dados no Log Analytics.

Principais requisitos:

  • O nome da tabela deve terminar com _CL (sufixo de log personalizado).
  • Deve incluir uma TimeGenerated coluna (tipo datetime).
  • Tipos de coluna: cadeia de caracteres, int, long, real, bool, datetime, dinâmico, guid.
  • Use a versão 2025-07-01 da API ou posterior.
  • Para obter mais informações, consulte Criar uma tabela personalizada nos Logs do Azure Monitor.

Example:

{
  "name": "ContosoSecurityAlerts_CL",
  "type": "Microsoft.OperationalInsights/workspaces/tables",
  "apiVersion": "2025-07-01",
  "properties": {
     "schema": {
        "name": "ContosoSecurityAlerts_CL",
        "columns": [
          {
             "name": "TimeGenerated",
             "type": "datetime"
          },
          {
             "name": "EventSeverity",
             "type": "string"
          },
          {
             "name": "EventType",
             "type": "string"
          },
          {
             "name": "UserName",
             "type": "string"
          },
          {
             "name": "SourceIP",
             "type": "string"
          },
          {
             "name": "DeviceId",
             "type": "string"
          },
          {
             "name": "AlertMessage",
             "type": "string"
          }
        ]
     }
  }
}

Regra de coleta de dados (DCR)

O que é: Define como o Azure Monitor ingere e processa seus dados. Para obter mais informações, consulte as regras de coleta de dados no Azure Monitor.

O que faz:

  • Especifica o nome do fluxo de entrada (o que seu aplicativo usa ao enviar dados)
  • Define transformações opcionais de KQL para formatar e enriquecer dados
  • Roteia dados para a tabela de destino
  • Links para o Ponto de Extremidade de Coleta de Dados (DCE)

Principais componentes:

  • streamDeclarations: define a estrutura dos dados de entrada (deve corresponder ao que seu aplicativo envia)
  • destinations: para onde os dados vão (seu workspace do Log Analytics)
  • dataFlows: O pipeline de transformação do fluxo de entrada à tabela de saída
  • dataCollectionEndpointId: links para o DCE para ingestão de dados

Example:

{
  "name": "ContosoSecurityAlertsPushDCR",
  "apiVersion": "2021-09-01-preview",
  "type": "Microsoft.Insights/dataCollectionRules",
  "location": "[parameters('workspace-location')]",
  "properties": {
     "streamDeclarations": {
        "Custom-ContosoSecurityAlerts": {
          "columns": [
             {
                "name": "EventSeverity",
                "type": "string"
             },
             {
                "name": "EventType",
                "type": "string"
             },
             {
                "name": "UserName",
                "type": "string"
             },
             {
                "name": "SourceIP",
                "type": "string"
             },
             {
                "name": "DeviceId",
                "type": "string"
             },
             {
                "name": "AlertMessage",
                "type": "string"
             }
          ]
        }
     },
     "destinations": {
        "logAnalytics": [
          {
             "workspaceResourceId": "[variables('workspaceResourceId')]",
             "name": "clv2ws1"
          }
        ]
     },
     "dataFlows": [
        {
          "streams": [
             "Custom-ContosoSecurityAlerts"
          ],
          "destinations": [
             "clv2ws1"
          ],
          "transformKql": "source | extend TimeGenerated = now()",
          "outputStream": "Custom-ContosoSecurityAlerts_CL"
        }
     ],
     "dataCollectionEndpointId": "[concat('/subscriptions/',parameters('subscription'),'/resourceGroups/',parameters('resourceGroupName'),'/providers/Microsoft.Insights/dataCollectionEndpoints/',parameters('workspace'))]"
  }
}

Importante

  • O nome do fluxo deve começar com o prefixo Custom-.
  • O transformKql pode ser simplesmente "source" para passagem ou incluir lógica KQL para transformação de dados.
  • outputStream deve corresponder ao nome da tabela com o prefixo Custom- e o sufixo _CL.

Definição do conector (interface do usuário)

A definição do conector controla como o conector aparece na galeria de conectores de dados do Microsoft Sentinel. Para obter mais informações, consulte a referência da API de Definições do Conector de Dados.

A definição do conector inclui:

  • Título, descrição e marca do conector
  • Pré-requisitos e permissões necessários, como acesso ao workspace e permissões do Entra
  • Etapas de instrução para implantação
  • Controles de interface do usuário para exibir detalhes da conexão aos usuários

Principais elementos da interface do usuário:

  • DeployPushConnectorButton: dispara a implantação automatizada de recursos
  • CopyableLabel: exibe os detalhes da conexão após a implantação (usa fillWith o parâmetro)
  • Markdown: fornece instruções formatadas e contexto
  • IsConnectedQuery: valida a conectividade do conector com base em dados recentes

Estrutura de exemplo (abreviada para clareza):

{
    "name": "ContosoSecurityAlertsPush",
    "apiVersion": "2022-09-01-preview",
    "type": "Microsoft.SecurityInsights/dataConnectorDefinitions",
    "location": "[parameters('workspace-location')]",
    "kind": "Customizable",
    "properties": {
        "connectorUiConfig": {
            "id": "ContosoSecurityAlertsPush",
            "title": "Contoso Security Alerts (Push)",
            "publisher": "Contoso Corporation",
            "descriptionMarkdown": "The [Contoso Security Alerts](https://www.contoso.com/) connector provides the capability to push real-time security alerts from your Contoso application directly into Microsoft Sentinel using the Codeless Connector Framework (CCF) Push pattern. This connector ingests alert severity, event types, user information, and network details into a custom Log Analytics table for analysis, alerting, and visualization.",
            "graphQueries": [
                {
                    "metricName": "Security Alerts",
                    "legend": "ContosoSecurityAlerts_CL",
                    "baseQuery": "ContosoSecurityAlerts_CL"
                }
            ],
            "sampleQueries": [
                {
                    "description": "All security alerts",
                    "query": "ContosoSecurityAlerts_CL\n | sort by TimeGenerated desc"
                },
                {
                    "description": "Critical and High severity alerts",
                    "query": "ContosoSecurityAlerts_CL\n | where EventSeverity in ('Critical', 'High')\n | sort by TimeGenerated desc"
                }
            ],
            "dataTypes": [
                {
                    "name": "ContosoSecurityAlerts_CL",
                    "lastDataReceivedQuery": "ContosoSecurityAlerts_CL\n| summarize Time = max(TimeGenerated)\n| where isnotempty(Time)"
                }
            ],
            "connectivityCriteria": [
                {
                    "type": "IsConnectedQuery",
                    "value": [
                        "ContosoSecurityAlerts_CL\n| summarize LastLogReceived = max(TimeGenerated)\n| project IsConnected = LastLogReceived > ago(7d)"
                    ]
                }
            ],
            "availability": {
                "status": 1
            },
            "permissions": {
                "resourceProvider": [
                    {
                        "provider": "Microsoft.OperationalInsights/workspaces",
                        "permissionsDisplayText": "read and write permissions are required.",
                        "providerDisplayName": "Workspace",
                        "scope": "Workspace",
                        "requiredPermissions": {
                            "write": true,
                            "read": true,
                            "delete": true
                        }
                    }
                ],
                "customs": [
                    {
                        "name": "Microsoft Entra",
                        "description": "Permission to create an app registration in Microsoft Entra ID. Typically requires Entra ID Application Developer role or higher."
                    },
                    {
                        "name": "Microsoft Azure",
                        "description": "Permission to assign Monitoring Metrics Publisher role on data collection rule (DCR). Typically requires Azure RBAC Owner or User Access Administrator role."
                    }
                ]
            },
            "instructionSteps": [
                {
                    "title": "1. Create ARM Resources and Provide the Required Permissions",
                    "description": "This connector enables your Contoso application to push security alerts directly to Microsoft Sentinel via the Azure Monitor Ingestion API.",
                    "instructions": [
                        {
                            "type": "Markdown",
                            "parameters": {
                                "content": "#### Automated Configuration and Secure Data Ingestion with Entra Application \nClicking on \"Deploy\" will trigger the creation of a Log Analytics table and a Data Collection Rule (DCR). \nIt will then create an Entra application, link the DCR to it, and set the entered secret in the application. This setup enables data to be sent securely to the DCR using an Entra token."
                            }
                        },
                        {
                            "type": "DeployPushConnectorButton",
                            "parameters": {
                                "label": "Deploy Contoso Push connector resources",
                                "applicationDisplayName": "Contoso Security Alerts Push Connector Application"
                            }
                        }
                    ]
                },
                {
                    "title": "2. Configure Your Contoso Application",
                    "description": "Use the following parameters to configure your Contoso application to push security alerts to the workspace.",
                    "instructions": [
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Tenant ID (Directory ID)",
                                "fillWith": [
                                    "TenantId"
                                ]
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Entra App Registration Application ID",
                                "fillWith": [
                                    "ApplicationId"
                                ],
                                "placeholder": "Deploy push connector to get the App Registration Application ID"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Entra App Registration Secret",
                                "fillWith": [
                                    "ApplicationSecret"
                                ],
                                "placeholder": "Deploy push connector to get the App Registration Secret"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Data Collection Endpoint Uri",
                                "fillWith": [
                                    "DataCollectionEndpoint"
                                ],
                                "placeholder": "Deploy push connector to get the Data Collection Endpoint Uri"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Data Collection Rule Immutable ID",
                                "fillWith": [
                                    "DataCollectionRuleId"
                                ],
                                "placeholder": "Deploy push connector to get the Data Collection Rule Immutable ID"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Stream Name",
                                "value": "Custom-ContosoSecurityAlerts"
                            }
                        },
                        {
                            "type": "Markdown",
                            "parameters": {
                                "content": "#### Configure Contoso Application\nUpdate your Contoso application configuration with the above credentials to enable security alert push to Microsoft Sentinel.\n\nExample configuration:\njson\n{\n \"azure\": {\n \"tenant_id\": \"<Tenant ID>\",\n \"client_id\": \"<Application ID>\",\n \"client_secret\": \"<Application Secret>\",\n \"dce_endpoint\": \"<Data Collection Endpoint Uri>\",\n \"dcr_immutable_id\": \"<Data Collection Rule Immutable ID>\",\n \"stream_name\": \"Custom-ContosoSecurityAlerts\"\n }\n}\n"
                            }
                        }
                    ]
                }
            ]
        }
    }
}

Importante

  • A id em connectorUiConfig deve ser exclusiva e corresponder às referências na configuração do conector de dados.
  • Use IsConnectedQuery para conectores de produção (valida dados recentes) ou hasDataConnectors para validação mais simples.
  • Os fillWith parâmetros em CopyableLabel são preenchidos automaticamente após a implantação.
  • Valores fixos, como o nome do fluxo, usam o value parâmetro em vez de fillWith.

Configuração do conector de push

A configuração do conector push é a instância do conector push que vincula a definição do conector aos recursos implantados.

A configuração do conector de push

  • Vincula a definição do conector (UI) ao DCR e ao aplicativo Entra implantados
  • Armazena detalhes de autenticação (ID do aplicativo, ID da entidade de serviço)
  • Registra a configuração de DCR (ponto de extremidade, ID imutável, nome do fluxo)
  • Permite que a IU recupere e exiba informações de conexão aos usuários

Propriedades principais

  • connectorDefinitionName: deve corresponder ao id na definição do conector
  • dcrConfig: Contém o ponto de extremidade DCR, a ID da regra e o nome da transmissão
  • auth: contém a ID do aplicativo Entra e a ID da entidade de serviço
  • kind: deve ser "Push" para conectores push

Exemplo:

{
  "name": "ContosoSecurityAlertsPushDCR",
  "apiVersion": "2021-09-01-preview",
  "type": "Microsoft.Insights/dataCollectionRules",
  "location": "[parameters('workspace-location')]",
  "properties": {
    "streamDeclarations": {
      "Custom-ContosoSecurityAlerts": {
        "columns": [
          {
            "name": "EventSeverity",
            "type": "string"
          },
          {
            "name": "EventType",
            "type": "string"
          },
          {
            "name": "UserName",
            "type": "string"
          },
          {
            "name": "SourceIP",
            "type": "string"
          },
          {
            "name": "DeviceId",
            "type": "string"
          },
          {
            "name": "AlertMessage",
            "type": "string"
          }
        ]
      }
    },
    "destinations": {
      "logAnalytics": [
        {
          "workspaceResourceId": "[variables('workspaceResourceId')]",
          "name": "clv2ws1"
        }
      ]
    },
    "dataFlows": [
      {
        "streams": [
          "Custom-ContosoSecurityAlerts"
        ],
        "destinations": [
          "clv2ws1"
        ],
        "transformKql": "source | extend TimeGenerated = now()",
        "outputStream": "Custom-ContosoSecurityAlerts_CL"
      }
    ],
    "dataCollectionEndpointId": "[concat('/subscriptions/',parameters('subscription'),'/resourceGroups/',parameters('resourceGroupName'),'/providers/Microsoft.Insights/dataCollectionEndpoints/',parameters('workspace'))]"
  }
}

Importante

  • O connectorDefinitionName deve corresponder exatamente à definição do id.
  • A transmissão do streamName deve corresponder à transmissão declarada em seu DCR.
  • Esse recurso é criado automaticamente durante a implantação quando os usuários selecionam o botão DeployPushConnector .

Compilando seu primeiro conector push

Neste exemplo, você cria um conector push simples que envia alertas de segurança do aplicativo para o Sentinel.

Objetivo: Enviar alertas de segurança do aplicativo para o Sentinel em tempo real

Seu aplicativo envia a estrutura de eventos:

{
  "TimeGenerated": "2025-11-21T10:30:00Z",
  "EventSeverity": "Medium",
  "EventType": "LoginAlert",
  "UserName": "alice@contoso.com",
  "SourceIP": "192.168.1.100",
  "DeviceId": "device-12345",
  "AlertMessage": "Multiple failed login attempts detected"
}

Guia passo-a-passo para criar o conector de push

  1. Clonar o repositório Azure-Sentinel

    Primeiro faça um fork e depois clone o repositório oficial do Azure-Sentinel para o seu computador local. Esse repositório contém as ferramentas de empacotamento e fornece a estrutura de solução padrão.

    1. Clonar o repositório
      git clone https://github.com/<YOUR_FORK>/Azure-Sentinel.git

    2. Navegue até o diretório Soluções cd Azure-Sentinel/Solutions
      A estrutura do repositório inclui:

    • Tools/Create-Azure-Sentinel-Solution/V3/
    • Contém o script de empacotamento createSolutionV3.ps1
    • Soluções/ Onde você criará sua solução de conectores

  2. Crie sua estrutura de pastas de solução Crie um novo diretório de solução dentro da pasta Soluções/ seguindo a convenção de nomenclatura padrão. Criar diretórios de solução (do Azure-Sentinel/Solutions/)

    mkdir ContosoSecurityAlerts
cd ContosoSecurityAlerts
mkdir Data
mkdir "Data Connectors"
mkdir "Data Connectors/ContosoSecurityAlerts_ccf"

    Sua estrutura de pastas tem a seguinte aparência:

    Azure-Sentinel/
     └── Soluções/
        └── ContosoSecurityAlerts/
            ├── Dados/
            └── Conectores de Dados/
                └── ContosoSecurityAlerts_ccf/

  3. Defina sua tabela

    Na pasta ContosoSecurityAlerts_ccf, crie um arquivo chamado table.json com sua definição de tabela personalizada:

    {
  "name": "ContosoSecurityAlerts_CL",
  "type": "Microsoft.OperationalInsights/workspaces/tables",
  "apiVersion": "2025-07-01",
  "properties": {
    "schema": {
      "name": "ContosoSecurityAlerts_CL",
      "columns": [
        {
          "name": "TimeGenerated",
          "type": "datetime"
        },
        {
          "name": "EventSeverity",
          "type": "string"
        },
        {
          "name": "EventType",
          "type": "string"
        },
        {
          "name": "UserName",
          "type": "string"
        },
        {
          "name": "SourceIP",
          "type": "string"
        },
        {
          "name": "DeviceId",
          "type": "string"
        },
        {
          "name": "AlertMessage",
          "type": "string"
        }
      ]
    }
  }
}

  4. Criar o DCR

    Na pasta ContosoSecurityAlerts_ccf, crie um arquivo chamado DCR.json que defina o fluxo de entrada e encaminhe dados para sua tabela:

    {
  "name": "ContosoSecurityAlertsPushDCR",
  "apiVersion": "2021-09-01-preview",
  "type": "Microsoft.Insights/dataCollectionRules",
  "location": "[parameters('workspace-location')]",
  "properties": {
    "streamDeclarations": {
      "Custom-ContosoSecurityAlerts": {
        "columns": [
          {
            "name": "EventSeverity",
            "type": "string"
          },
          {
            "name": "EventType",
            "type": "string"
          },
          {
            "name": "UserName",
            "type": "string"
          },
          {
            "name": "SourceIP",
            "type": "string"
          },
          {
            "name": "DeviceId",
            "type": "string"
          },
          {
            "name": "AlertMessage",
            "type": "string"
          }
        ]
      }
    },
    "destinations": {
      "logAnalytics": [
        {
          "workspaceResourceId": "[variables('workspaceResourceId')]",
          "name": "clv2ws1"
        }
      ]
    },
    "dataFlows": [
      {
        "streams": [
          "Custom-ContosoSecurityAlerts"
        ],
        "destinations": [
          "clv2ws1"
        ],
        "transformKql": "source | extend TimeGenerated = now()",
        "outputStream": "Custom-ContosoSecurityAlerts_CL"
      }
    ],
    "dataCollectionEndpointId": "[concat('/subscriptions/',parameters('subscription'),'/resourceGroups/',parameters('resourceGroupName'),'/providers/Microsoft.Insights/    dataCollectionEndpoints/',parameters('workspace'))]"
  }
}

  5. Criar a definição do conector

    Na pasta ContosoSecurityAlerts_ccf, crie um arquivo chamado connectorDefinition.json que define como os usuários interagem com o conector no Sentinel:

    {
    "name": "ContosoSecurityAlertsPush",
    "apiVersion": "2022-09-01-preview",
    "type": "Microsoft.SecurityInsights/dataConnectorDefinitions",
    "location": "[parameters('workspace-location')]",
    "kind": "Customizable",
    "properties": {
        "connectorUiConfig": {
            "id": "ContosoSecurityAlertsPush",
            "title": "Contoso Security Alerts (Push)",
            "publisher": "Contoso Corporation",
            "descriptionMarkdown": "The [Contoso Security Alerts](https://www.contoso.com/) connector provides the capability to push real-time security alerts from your   Contoso application directly into Microsoft Sentinel using the Codeless Connector Framework (CCF) Push pattern. This connector ingests alert severity, event  types, user information, and network details into a custom Log Analytics table for analysis, alerting, and visualization.",
            "graphQueries": [
                {
                    "metricName": "Security Alerts",
                    "legend": "ContosoSecurityAlerts_CL",
                    "baseQuery": "ContosoSecurityAlerts_CL"
                }
            ],
            "sampleQueries": [
                {
                    "description": "All security alerts",
                    "query": "ContosoSecurityAlerts_CL\n | sort by TimeGenerated desc"
                },
                {
                    "description": "Critical and High severity alerts",
                    "query": "ContosoSecurityAlerts_CL\n | where EventSeverity in ('Critical', 'High')\n | sort by TimeGenerated desc"
                }
            ],
            "dataTypes": [
                {
                    "name": "ContosoSecurityAlerts_CL",
                    "lastDataReceivedQuery": "ContosoSecurityAlerts_CL\n| summarize Time = max(TimeGenerated)\n| where isnotempty(Time)"
                }
            ],
            "connectivityCriteria": [
                {
                    "type": "IsConnectedQuery",
                    "value": [
                        "ContosoSecurityAlerts_CL\n| summarize LastLogReceived = max(TimeGenerated)\n| project IsConnected = LastLogReceived > ago(7d)"
                    ]
                }
            ],
            "availability": {
                "status": 1
            },
            "permissions": {
                "resourceProvider": [
                    {
                        "provider": "Microsoft.OperationalInsights/workspaces",
                        "permissionsDisplayText": "read and write permissions are required.",
                        "providerDisplayName": "Workspace",
                        "scope": "Workspace",
                        "requiredPermissions": {
                            "write": true,
                            "read": true,
                            "delete": true
                        }
                    }
                ],
                "customs": [
                    {
                        "name": "Microsoft Entra",
                        "description": "Permission to create an app registration in Microsoft Entra ID. Typically requires Entra ID Application Developer role or higher."
                    },
                    {
                        "name": "Microsoft Azure",
                        "description": "Permission to assign Monitoring Metrics Publisher role on data collection rule (DCR). Typically requires Azure RBAC Owner or User   Access Administrator role."
                    }
                ]
            },
            "instructionSteps": [
                {
                    "title": "1. Create ARM Resources and Provide the Required Permissions",
                    "description": "This connector enables your Contoso application to push security alerts directly to Microsoft Sentinel via the Azure Monitor Ingestion  API.",
                    "instructions": [
                        {
                            "type": "Markdown",
                            "parameters": {
                                "content": "#### Automated Configuration and Secure Data Ingestion with Entra Application \nClicking on \"Deploy\" will trigger the creation    of a Log Analytics table and a Data Collection Rule (DCR). \nIt will then create an Entra application, link the DCR to it, and set the     entered secret in the application. This setup enables data to be sent securely to the DCR using an Entra token."
                            }
                        },
                        {
                            "type": "DeployPushConnectorButton",
                            "parameters": {
                                "label": "Deploy Contoso Push connector resources",
                                "applicationDisplayName": "Contoso Security Alerts Push Connector Application"
                            }
                        }
                    ]
                },
                {
                    "title": "2. Configure Your Contoso Application",
                    "description": "Use the following parameters to configure your Contoso application to push security alerts to the workspace.",
                    "instructions": [
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Tenant ID (Directory ID)",
                                "fillWith": [
                                    "TenantId"
                                ]
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Entra App Registration Application ID",
                                "fillWith": [
                                    "ApplicationId"
                                ],
                                "placeholder": "Deploy push connector to get the App Registration Application ID"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Entra App Registration Secret",
                                "fillWith": [
                                    "ApplicationSecret"
                                ],
                                "placeholder": "Deploy push connector to get the App Registration Secret"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Data Collection Endpoint Uri",
                                "fillWith": [
                                    "DataCollectionEndpoint"
                                ],
                                "placeholder": "Deploy push connector to get the Data Collection Endpoint Uri"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Data Collection Rule Immutable ID",
                                "fillWith": [
                                    "DataCollectionRuleId"
                                ],
                                "placeholder": "Deploy push connector to get the Data Collection Rule Immutable ID"
                            }
                        },
                        {
                            "type": "CopyableLabel",
                            "parameters": {
                                "label": "Stream Name",
                                "value": "Custom-ContosoSecurityAlerts"
                            }
                        },
                        {
                            "type": "Markdown",
                            "parameters": {
                                "content": "#### Configure Contoso Application\nUpdate your Contoso application configuration with the above credentials to enable security     alert push to Microsoft Sentinel.\n\nExample configuration:\njson\n{\n \"azure\": {\n \"tenant_id\": \"<Tenant ID>\",\n \"client_id\":  \"<Application ID>\",\n \"client_secret\": \"<Application Secret>\",\n \"dce_endpoint\": \"<Data Collection Endpoint Uri>\",\n   \"dcr_immutable_id\": \"<Data Collection Rule Immutable ID>\",\n \"stream_name\": \"Custom-ContosoSecurityAlerts\"\n }\n}\n"
                            }
                        }
                    ]
                }
            ]
        }
    }
}

  6. Criar a configuração do Conector de Dados

    Na pasta ContosoSecurityAlerts_ccf, crie um arquivo chamado dataConnector.json que vincule a definição do conector aos recursos implantados:

    {
  "name": "ContosoSecurityAlertsPushConnectorPolling",
  "apiVersion": "2024-09-01",
  "type": "Microsoft.SecurityInsights/dataConnectors",
  "kind": "Push",
  "properties": {
    "connectorDefinitionName": "ContosoSecurityAlertsPush",
    "dcrConfig": {
      "streamName": "Custom-ContosoSecurityAlerts",
      "dataCollectionEndpoint": "[[parameters('dcrConfig').dataCollectionEndpoint]",
      "dataCollectionRuleImmutableId": "[[parameters('dcrConfig').dataCollectionRuleImmutableId]"
    },
    "auth": {
      "type": "Push",
      "AppId": "[[parameters('auth').appId]",
      "ServicePrincipalId": "[[parameters('auth').servicePrincipalId]"
    },
    "request": {
      "RetryCount": 1
    },
    "response": {
      "eventsJsonPaths": [
        "$"
      ]
    }
  }
}

  7. Criar arquivos de metadados da solução

    1. Solution_ContosoSecurityAlerts.json na pasta Dados, crie Solution_ContosoSecurityAlerts.json com os detalhes da solução:

      {
     "Name": "ContosoSecurityAlerts",
     "Author": "Contoso Corporation - support@contoso.com",
     "Logo": "<svg width=\"75px\" height=\"75px\" viewBox=\"0 0 75 75\" xmlns=\"http://www.w3.org/2000/svg\"><rect width=\"75\" height=\"75\" fill=\"#FF6B35\"/><text   x=\"37.   5\" y=\"45\" font-family=\"Arial\" font-size=\"18\" fill=\"white\" text-anchor=\"middle\" font-weight=\"bold\">CONTOSO</text></svg>",
     "Description": "The Contoso Security Alerts solution provides real-time security alert ingestion from your Contoso application into Microsoft Sentinel using the       Codeless Connector Framework (CCF) Push pattern. Your application pushes alert severity, event types, user information, and network details directly to Azure   Monitor     for analysis, alerting, and visualization.",
     "Data Connectors": [
          "Data Connectors/ContosoSecurityAlerts_ccf/connectorDefinition.json"
     ],
     "BasePath": "C:\\GitHub\\Azure-Sentinel\\Solutions\\ContosoSecurityAlerts",
     "Version": "1.0.0",
     "Metadata": "SolutionMetadata.json",
     "TemplateSpec": true,
     "Is1PConnector": false
}

      Importante

      Requisitos de campo críticos:

      • BasePath: Atualize o caminho local real para o repositório Azure-Sentinel
      • Metadata: deve referenciar SolutionMetadata.json (criado na Etapa 6B)
      • Version: controle de versão semântico, por exemplo, 3.0.0
      • TemplateSpec: Sempre true para soluções do Content Hub
      • Is1Pconnector: Definido para conectores parceiros/personalizados false

    2. Criar SolutionMetadata.json na raiz da solução

      Na pasta ContosoSecurityAlerts, crie SolutionMetadata.json no diretório raiz da solução (mesmo nível da pasta Dados):

      {
  "publisherId": "contoso",
  "offerId": "contoso-security-alerts",
  "firstPublishDate": "2025-01-01",
  "lastPublishDate": "2025-01-01",
  "providers": [
     "Contoso"
  ],
  "categories": {
     "domains": [
        "Security - Threat Protection",
        "Security - Cloud Security"
     ]
  },
  "support": {
     "name": "Contoso Corporation",
     "tier": "Partner",
     "link": "https://www.contoso.com/support"
  }
}

      Você precisa do arquivo SolutionMetadata.json para empacotamento do Hub de Conteúdo:

      • A ferramenta de empacotamento espera esse arquivo na raiz da solução
      • Ele contém metadados do marketplace para distribuição do Hub de Conteúdo

    3. Criar ReleaseNotes.md na raiz da solução

      Version Data modificada (DD-MM-YYYY) Histórico de alterações
      3.0.0 DD-MM-YYYY Solução de exemplo

    Lista de verificação de validação

    Antes de prosseguir para a próxima etapa, verifique:

    • O nome da pasta não tem espaços, por exemplo ContosoSecurityAlerts
    • Name campo no Solution_ContosoSecurityAlerts.json corresponde exatamente ao nome da pasta
    • SolutionMetadata.json existe na raiz da solução (não na pasta Dados)
    • BasePath aponta para o caminho real do repositório de Azure-Sentinel local
    • Metadata referências de campo "SolutionMetadata.json"
    • publisherId e offerId correspondem entre ambos os arquivos

  8. Verificar sua estrutura de solução

    Confirme se a estrutura da pasta corresponde ao layout necessário com todos os arquivos em vigor:

    Azure-Sentinel/
└── Solutions/
     └── ContosoSecurityAlerts/                         Folder name (no spaces)
          ├── Data/
          │   └── Solution_ContosoSecurityAlerts.json    From Step 7A
          ├── SolutionMetadata.json                      From Step 7B (at root)
          ├── ReleaseNotes.md                            From Step 7C
          └── Data Connectors/
                └── ContosoSecurityAlerts_ccf/
                     ├── table.json                         From Step 3
                     ├── DCR.json                           From Step 4
                     ├── connectorDefinition.json           From Step 5
                     └── dataConnector.json                 From Step 6

  9. Empacotar sua solução

    Use a ferramenta de empacotamento createSolutionV3.ps1 para gerar o modelo de implantação do ARM.

    # Navigate to the packaging tools directory (from Azure-Sentinel repository root)
cd Tools/Create-Azure-Sentinel-Solution/V3

# Run the packaging tool
# When prompted for "Enter solution data folder path:", provide:
# <REPO_ROOT>Solutions/ContosoSecurityAlerts/Data (Note! This path is absolute)
.\createSolutionV3.ps1

    O script automaticamente:

    • Valida sua estrutura de dados/pastas
    • Processa artefatos do conector

    Saída esperada:

    O script de empacotamento mostra uma falha na validação do arm-ttk (Kit de Ferramentas de Modelo do Azure Resource Manager). Essa falha é esperada e normal para conectores push do CCF:

    Failed arm-ttk (Test-AzTemplate): Package
Failed arm-ttk (Test-AzTemplate) on solutions: Package
************Validating if Package Json files are valid or not***************
File Solutions\ContosoSecurityAlerts\Package\createUiDefinition.json is a valid Json file!
File Solutions\ContosoSecurityAlerts\Package\mainTemplate.json is a valid Json file!
File Solutions\ContosoSecurityAlerts\Package\testParameters.json is a valid Json file!

    O empacotamento terá sido bem-sucedido se você vir as três mensagens de validação JSON confirmando arquivos válidos. Você pode ignorar o erro arm-ttk nos conectores push do CCF.

    Para obter mais informações, consulte a documentação das ferramentas de soluções do Azure-Sentinel.

  10. Implantar o pacote de solução

    Implante o modelo ARM gerado (Package/mainTemplate.json) em sua assinatura do Azure.

    1. No portal do Azure, procure implantar um modelo personalizado
    2. Selecione Criar seu próprio modelo no editor
    3. Selecione Carregar arquivo e selecione Package/mainTemplate.json na pasta de saída
    4. Selecione Salvar
    5. Preencha os parâmetros de implantação:
      • Assinatura: Sua assinatura do Azure
      • Grupo de Recursos: O grupo de recursos que contém o workspace do Sentinel
      • Região: Mesma região do workspace do Sentinel
      • Espaço: Seu nome do workspace do Log Analytics
    6. Selecione Examinar + criar e, em seguida, Criar

    Essa implantação disponibiliza o conector em sua galeria de conectores de dados do Microsoft Sentinel.

    Para obter etapas detalhadas, consulte [Início Rápido: Criar e implantar modelos do ARM usando o portal do Azure](/azure/azure-resource-manager/templates/ quickstart-create-templates-use-the-portal).

  11. Habilitar o conector de dados

    Depois de implantar o pacote de solução, habilite o conector para provisionar recursos e gerar credenciais.

    1. No portal do Azure, navegue até o workspace do Microsoft Sentinel
    2. Ir para configuração>conectores de dados
    3. Pesquise e selecione Contoso Security Alerts (Push)
    4. Selecione Abrir página do conector
    5. Selecione o botão Implantar Alertas de Segurança da Contoso
    6. Aguarde a conclusão da implantação (cria tabela personalizada, DCR, DCE, aplicativo Entra com credenciais)
    7. Copie os detalhes da conexão que aparecem:
      • ID do locatário
      • ID do aplicativo (cliente)
      • Segredo do Cliente
      • URI do ponto de extremidade de coleta de dados
      • ID imutável da política de coleção de dados
      • Nome do fluxo: Custom-ContosoSecurityAlerts

  12. Configurar seu aplicativo

    Atualize o código do aplicativo com as credenciais e os detalhes do recurso da Etapa 10. O código usa o fluxo de credenciais do cliente OAuth 2.0 para autenticar com o Azure Monitor.

    Cuidado

    Proteja suas credenciais: nunca codifique as credenciais (ID do Locatário, ID do Aplicativo, Segredo do Cliente) diretamente no código do aplicativo ou confirme-as no controle do código-fonte. Use soluções de armazenamento de credenciais seguras, como:

    • Azure Key Vault para aplicativos de produção
    • Variáveis de ambiente ou arquivos de configuração (excluídos do controle do código-fonte)
    • Identidades gerenciadas quando aplicável
    • Ferramentas de gerenciamento de segredos que criptografam credenciais em repouso

    Código do aplicativo de exemplo do Python:

    O exemplo a seguir usa valores de espaço reservado, como <Sua ID de Inquilino>. Substitua esses valores por referências seguras às suas credenciais reais.

    import requests
import json
from datetime import datetime, timezone

# Connection details from Step 11

tenant_id = "<Your-Tenant-ID>"
app_id = "<Your-Application-ID>"
app_secret = "<Your-Client-Secret>"
dce_uri = "<Your-DCE-URI>"
dcr_immutable_id = "<Your-DCR-Immutable-ID>"
stream_name = "Custom-ContosoSecurityAlerts"


**Get OAuth token**

token_url = f"https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token"
token_data = {
     "client_id": app_id,
     "scope": "https://monitor.azure.com//.default",
     "client_secret": app_secret,
     "grant_type": "client_credentials"
}
token_response = requests.post(token_url, data=token_data)
access_token = token_response.json()["access_token"]


# Create event matching your table schema

event = [{
     "TimeGenerated": datetime.now(timezone.utc).isoformat(),
     "EventSeverity": "Medium",
     "EventType": "LoginAlert",
     "UserName": "alice@contoso.com",
     "SourceIP": "192.168.1.100",
     "DeviceId": "device-12345",
     "AlertMessage": "Multiple failed login attempts detected"
}]


# Send to Sentinel

headers = {
     "Authorization": f"Bearer {access_token}",
     "Content-Type": "application/json"
}
upload_url = f"{dce_uri}/dataCollectionRules/{dcr_immutable_id}/streams/{stream_name}?api-version=2023-01-01"
response = requests.post(upload_url, headers=headers, json=event)

print(f"Status: {response.status_code}")
print("Security alert sent to Sentinel!")

  13. Consultar seus dados

    Depois de enviar alertas, consulte no Sentinel. Permita de 5 a 10 minutos para a primeira ingestão.

    // View all recent alerts
ContosoSecurityAlerts_CL
| where TimeGenerated > ago(1h)
| order by TimeGenerated desc

// High severity alerts
ContosoSecurityAlerts_CL
| where EventSeverity == "High"
| project TimeGenerated, EventType, UserName, SourceIP, AlertMessage

// Alert summary by severity
ContosoSecurityAlerts_CL
| where TimeGenerated > ago(7d)
| summarize Count=count() by EventSeverity

Conteúdo relacionado

Agora que você entende os conectores do CCF Push, execute as seguintes etapas:

  1. Projetar seu esquema de dados – identifique os eventos que você deseja enviar e seus campos.
  2. Criar artefatos do conector – crie os quatro arquivos JSON (tabela, DCR, definição do conector, conector de dados).
  3. Organizar a estrutura da solução – criar pastas Data/ e Data Connectors/ com nomenclatura adequada.
  4. Empacotar sua solução – Use createSolutionV3.ps1 para gerar modelos de implantação.
  5. Implantar e testar – implantar no workspace do Sentinel e validar o fluxo de dados.
  6. Integrar com seu aplicativo – Adicionar código para enviar eventos em tempo real.
  7. Criar alertas e pastas de trabalho – use seus dados para monitoramento de segurança.

Recursos adicionais

Documentação do CCF

Azure Monitor e coleta de dados

Autenticação e segurança

Microsoft Sentinel

Obter ajuda

  • Para os parceiros ISV que criam integrações, entre em contato: azuresentinelpartner@microsoft.com
  • Para perguntas técnicas, use o Microsoft Q&A com a tag 'azure-sentinel'.
  • Last updated on