Conectores push Microsoft Sentinel CCF (pré-visualização) - Guia para começar

Este guia ajuda-o a compreender, construir e implementar conectores sem código baseados em push para o Microsoft Sentinel usando o Codeless Connector Framework (CCF) Push (pré-visualização).

O que é o CCF push?

Os conectores CCF Push permitem que as suas aplicações enviem eventos de segurança diretamente para o Microsoft Sentinel em tempo real. Ao contrário dos conectores tradicionais baseados em polling, que periodicamente recolhem dados das APIs, os conectores push permitem enviar dados para o Sentinel à medida que os eventos ocorrem no seu sistema.

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

  • Fluxo de dados controlado pela aplicação: A sua aplicação controla quando e como enviar dados, permitindo estratégias inteligentes de batching e utilização otimizada da rede.
  • Ingestão em tempo real: Envie dados imediatamente assim que os eventos acontecem, sem esperar pelos intervalos de sondagem.
  • Arquitetura simplificada: Não é necessário manter os endpoints da API para o Sentinel questionar.
  • Provisionamento baseado em modelos: A implementação cria modelos ARM para DCRs, tabelas personalizadas, registo de aplicações Entra e segredos de cliente – recebe os detalhes da ligação para configurar na sua aplicação de envio.
  • Autenticação segura: Utiliza aplicações Microsoft Entra com OAuth 2.0 para submissão segura de dados.

Pré-requisitos

  • Antes de começar, deve ter acesso ao repositório Azure-Sentinel GitHub para ferramentas de empacotamento.
  • Permissões Microsoft Entra:
    • Permissão para criar um registo de aplicação no Microsoft Entra ID. Requer normalmente a função de Programador de Aplicações do Entra ID ou superior.
    • Permissão para criar uma aplicação com segredos. Se não concederes esta permissão, o conector falha por razões de segurança.
    • O publicador deve ter o papel adequado para recuperar tokens da aplicação Microsoft Entra. Estes tokens são necessários para autenticar pedidos para o Data Collection Endpoint (DCE), que é o endpoint onde o conector acaba por enviar os seus dados. Se o fornecedor não conseguir recuperar tokens, os dados não podem ser enviados para o DCE.
  • Permissões do Microsoft Azure:
    • Permissão para atribuir a função de Editor de Métricas de Monitorização na regra de recolha de dados (DCR). Normalmente, requer a função Proprietário do Azure RBAC ou a função Administrador de Acesso de Utilizador.

Como funciona o CCF push

O modelo de empurrar vs modelo de puxar

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

Conectores de extração CCF - Baseados em pesquisa:

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

  • O Microsoft Sentinel inicia ligações à API da sua fonte de dados num horário configurado.
  • Os dados chegam em intervalos regulares de sondagem, como a cada cinco minutos.
  • Deve manter um endpoint API acessível publicamente.
  • A infraestrutura de sondagens do Sentinel gere o processo de recolha de dados.

Conectores CCF push - Orientados por eventos:

No modelo push, a sua aplicação envia dados diretamente para o Microsoft Sentinel:

  • A sua aplicação inicia a submissão de dados quando ocorrem eventos.
  • Os dados chegam quase em tempo real à medida que os eventos são gerados.
  • Não precisas de manter um endpoint API.
  • A sua aplicação controla o processamento em lotes, a temporalização e a otimização do fluxo de dados.

O fluxo de dados push

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

  1. Implementa o conetor no Microsoft Sentinel.

  2. O Azure cria automaticamente os seguintes recursos:

    • Aplicação Microsoft Entra com credenciais
    • Regra de Recolha de Dados (DCR) - define como processar os seus dados
    • Data Collection Endpoint (DCE) - a URL para onde envia dados
    • Tabela de registos personalizada - onde os seus dados são armazenados
    • Atribuições de funções - permissões para a aplicação Entra

  3. Recebe os seguintes detalhes de ligação:

    • ID do inquilino
    • ID da Aplicação (Cliente)
    • Segredo do Cliente
    • URI DCE (URL de destino)
    • ID Imutável DCR
    • Nome do Stream

  4. A sua candidatura envia os seguintes dados:

    • Recebe um token OAuth 2.0 usando as credenciais da aplicação Entra geradas pelo CCF. Para mais informações, consulte OAuth 2.0 fluxo de credenciais do cliente
    • Formata eventos como JSON correspondendo ao esquema da sua tabela
    • Envia dados para o endpoint DCE usando POSTs

  5. O Azure processa e armazena dados:

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

Artefactos de empurrar CCF

Uma solução de conector CCF Push consiste em quatro componentes principais:

  • Definição de tabela personalizada
  • Regra de recolha de dados (DCR)
  • Definição de conector (UI)
  • Configuração do Conector Push

Definição de tabela personalizada

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

Requisitos principais:

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

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 recolha de dados (DCR)

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

O que faz:

  • Especifica o nome do fluxo de entrada (o que a tua aplicação usa ao enviar dados)
  • Define transformações KQL opcionais para moldar e enriquecer dados
  • Dados de roteamento para a tabela de destinos
  • Ligações para o Endpoint de Recolha de Dados (DCE)

Componentes-chave:

  • streamDeclarations: Define a estrutura dos dados recebidos (deve corresponder ao que a sua aplicação envia)
  • destinations: Para onde vão os dados (o seu espaço de trabalho de Log Analytics)
  • dataFlows: O processo de transformação do fluxo de entrada para a tabela de saída
  • dataCollectionEndpointId: Ligações 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 stream deve começar com o prefixo Custom-.
  • O transformKql pode ser simplesmente "source" para pass-through, ou incluir lógica KQL para transformação de dados.
  • outputStream deve corresponder ao nome da sua tabela com o prefixo Custom- e o sufixo _CL.

Definição de conector (UI)

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

A definição do conector inclui:

  • Título, descrição e marca do conector
  • Pré-requisitos e permissões necessárias, como acesso ao espaço de trabalho e permissões Entra
  • Passos de instrução para implementação
  • Controlos de interface para mostrar detalhes de ligação aos utilizadores

Elementos-chave da interface:

  • DeployPushConnectorButton: Desencadeia a implementação automatizada de recursos
  • CopyableLabel: Mostra detalhes de ligação após a implementação (usa fillWith parâmetro)
  • Markdown: Fornece instruções formatadas e contexto
  • IsConnectedQuery: Valida a conectividade do conector com base em dados recentes

Exemplo de estrutura (abreviada para maior 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

  • O id in connectorUiConfig deve ser único 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 automaticamente preenchidos após a implementação.
  • Valores fixos, como o nome do fluxo, usam o value parâmetro em vez de fillWith.

Configuração do conector push

A configuração do conector push é a instância do conector de dados que liga a definição do conector aos recursos implementados.

A configuração do conector de pressão

  • Liga a definição do conector (UI) à aplicação DCR e Entra implementada
  • Armazena detalhes de autenticação (ID da aplicação, ID do principal do serviço)
  • Regista configuração DCR (endpoint, ID imutável, nome do fluxo)
  • Permite à interface recuperar e mostrar detalhes de ligação aos utilizadores

Propriedades principais:

  • connectorDefinitionName: Deve corresponder a na id definição do seu conector
  • dcrConfig: Contém endpoint DCR, ID de regra e nome do fluxo
  • auth: Contém o ID da aplicação Entra e o ID do principal do serviço
  • kind: Deve ser "Push" para os 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

  • A connectorDefinitionName deve corresponder exatamente à definição de id do conector.
  • O streamName deve corresponder ao fluxo declarado no seu DCR.
  • Este recurso é criado automaticamente durante a implementação quando os utilizadores selecionam o botão DeployPushConnector .

Construir o seu primeiro conector push

Neste exemplo, constróis um conector push simples que envia alertas de segurança da tua aplicação para o Sentinel.

Objetivo: Envie alertas de segurança da sua aplicação para a Sentinel em tempo real

A sua candidatura envia a estrutura do evento:

{
  "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 push

  1. Clone o Repositório Azure-Sentinel

    Faz um fork e depois clona o repositório oficial de Azure-Sentinel para a tua máquina local. Este repositório contém as ferramentas de empacotamento e fornece a estrutura padrão da solução.

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

    2. Navegar até ao diretório de 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 irá criar a sua solução de conectores

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

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

    A sua estrutura de pastas é a seguinte:

    Azure-Sentinel/
     └── Soluções/
        └── Contoso-Alertas-Segurança/
            ├── Data/
            └── Conectores de Dados/
                └── ContosoSecurityAlerts_ccf/

  3. Defina a Sua Tabela

    Na pasta ContosoSecurityAlerts_ccf, crie um ficheiro chamado table.json com a definição da sua 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 ficheiro chamado DCR.json que defina o fluxo de entrada e encaminhe os dados para a 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 ficheiro chamado connectorDefinition.json que defina como os utilizadores 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 ficheiro chamado dataConnector.json que ligue a definição do conector aos recursos implementados:

    {
  "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 Ficheiros de Metadados de Solução

    1. Solution_ContosoSecurityAlerts.json Na pasta Data, crie Solution_ContosoSecurityAlerts.json com os detalhes da sua 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 críticos do campo:

      • BasePath: Atualize o seu caminho local real para o repositório Azure-Sentinel
      • Metadata: Referência SolutionMetadata.json obrigatória (criada no Passo 6B)
      • Version: Versionamento semântico, por exemplo, 3.0.0
      • TemplateSpec: Sempre true para soluções Content Hub
      • Is1Pconnector: Defina como false para conectores parceiros/personalizados

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

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

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

      Precisa do ficheiro SolutionMetadata.json para a embalagem do Content Hub:

      • A ferramenta de empacotamento espera este ficheiro na raiz da solução
      • Contém metadados do marketplace para a distribuição do Content Hub

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

      Version Data Modificada (DD-MM-YYYY) História da Mudança
      3.0.0 DD-MM-YYYY Exemplo de solução

    Lista de verificação de validação

    Antes de avançar para o próximo passo, verifique:

    • O nome da pasta não tem espaços, por exemplo ContosoSecurityAlerts
    • Name O campo em Solution_ContosoSecurityAlerts.json corresponde exatamente ao nome da pasta
    • SolutionMetadata.json existe na raiz da solução (não na pasta Data)
    • BasePath aponta para o seu percurso exato do repositório local do Azure-Sentinel
    • Metadata Referências de campo "SolutionMetadata.json"
    • publisherId e offerId coincidem entre ambos os ficheiros

  8. Verifique a estrutura da sua solução

    Confirme se a estrutura da sua pasta corresponde ao layout exigido com todos os ficheiros no lugar:

    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. Empacota a tua solução

    Use a ferramenta de empacotamento createSolutionV3.ps1 para gerar o modelo de implementação 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 opera automaticamente:

    • Valida a tua estrutura de Dados/pastas
    • Artefatos de ligação de processos

    Resultados esperados:

    O script de empacotamento mostra uma validação de arm-ttk falhada (Azure Resource Manager Template Toolkit). Esta falha é esperada e normal para conectores CCF Push:

    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 processo de embalagem teve sucesso se conseguires ver as três mensagens de validação JSON que confirmam ficheiros válidos. Podes ignorar a arm-ttk falha dos conectores CCF Push.

    Para mais informações, consulte a documentação doAzure-Sentinel Solutions Tools.

  10. Implementar o pacote de soluções

    Implemente o modelo ARM gerado (Pacote/mainTemplate.json) para a sua subscrição Azure.

    1. No portal do Azure, procure por Implementar um modelo personalizado
    2. Selecione Criar o seu próprio modelo no editor
    3. Selecione Carregar ficheiro e selecione Package/mainTemplate.json da sua pasta de saída
    4. Selecione Guardar
    5. Preencha os parâmetros de implementação:
      • Subscrição: A sua subscrição Azure
      • Grupo de Recursos: O grupo de recursos que contém o seu espaço de trabalho Sentinela
      • Região: Mesma região do teu espaço de trabalho Sentinela
      • Espaço de Trabalho: Nome do seu espaço de trabalho Log Analytics
    6. Selecione Revisar + criar, depois Criar

    Esta implementação disponibiliza o conector na sua galeria de conectores de dados Microsoft Sentinel.

    Para passos detalhados, veja [Quickstart: Criar e implementar templates ARM usando o portal Azure](/azure/azure-resource-manager/templates/ quickstart-create-templates-use-the-portal).

  11. Ativar o conector de dados

    Após implementar o pacote de solução, permita ao conector que disponibilize recursos e gere credenciais.

    1. No portal Azure, navegue até ao seu espaço de trabalho Microsoft Sentinel
    2. Vá a Configuração>Conectores de Dados
    3. Procure e selecione Alertas de Segurança Contoso (Push)
    4. Selecione Abrir página do conector
    5. Selecione o botão Implantar Conector de Alertas de Segurança Contoso
    6. Esperar que a implementação seja concluída (cria tabela personalizada, DCR, DCE, aplicação Entra com credenciais)
    7. Copie os detalhes da ligação que aparecem:
      • ID do inquilino
      • ID da Aplicação (Cliente)
      • Segredo do Cliente
      • URI de Endpoint de Recolha de Dados
      • ID imutável da Regra de Recolha de Dados
      • Nome do Fluxo: Custom-ContosoSecurityAlerts

  12. Configure a sua aplicação

    Atualize o código da sua candidatura com as credenciais e detalhes de recursos do Passo 10. O código utiliza o fluxo de credenciais do cliente OAuth 2.0 para autenticação com o Azure Monitor.

    Atenção

    Proteja as suas credenciais: Nunca codifique as credenciais (ID do Inquilino, ID da Aplicação, Secret do Cliente) diretamente no código da sua aplicação nem as coloque no controlo de versão. Utilize soluções seguras de armazenamento de credenciais, tais como:

    • Azure Key Vault para aplicações de produção
    • Variáveis de ambiente ou ficheiros de configuração (excluídos do controlo de versão)
    • Identidades geridas, quando aplicável
    • Ferramentas de gestão de segredos que encriptam credenciais em repouso

    Código de Aplicação de Exemplo em Python:

    O exemplo seguinte utiliza valores provisórios como <Your-Tenant-ID>. 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 os seus dados

    Depois de enviar alertas, consulta no Sentinel. Espere 5-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 compreende os conectores CCF Push, siga os seguintes passos:

  1. Desenhe o seu esquema de dados - Identifique os eventos que quer enviar e os seus campos.
  2. Criar artefactos de conector - Construir os quatro ficheiros JSON (tabela, DCR, definição de conector, conector de dados).
  3. Organizar a estrutura da solução - Configurar Pastas de Dados/ e Conectores de Dados/ com a nomenclatura correta.
  4. Empacota a tua solução - Usa createSolutionV3.ps1 para gerar templates de implementação.
  5. Implementar e testar - Implemente para o seu espaço de trabalho Sentinel e valide o fluxo de dados.
  6. Integre com a sua aplicação - Adicione código para enviar eventos em tempo real.
  7. Crie alertas e livros de exercícios – Use os seus dados para monitorização de segurança.

Recursos adicionais

Documentação CCF

Azure Monitor e recolha de dados

Autenticação e segurança

Microsoft Sentinel

Obter ajuda

  • Para parceiros ISV que desenvolvem integrações, contacte: azuresentinelpartner@microsoft.com
  • Para questões técnicas, use o Microsoft Q&A com a etiqueta 'azure-sentinel'.
  • Last updated on