Microsoft Sentinel CCF-pushconnectors (preview) - Introductiehandleiding

Deze handleiding helpt u bij het begrijpen, bouwen en implementeren van op push gebaseerde codeloze connectors voor Microsoft Sentinel met behulp van de CCF-push (Codeless Connector Framework) (preview).

Wat is CCF-push?

MET CCF Push-connectors kunnen uw toepassingen beveiligingsgebeurtenissen rechtstreeks naar Microsoft Sentinel verzenden in realtime. In tegenstelling tot traditionele op polling gebaseerde connectors die periodiek gegevens ophalen uit API's, kunt u met pushconnectors gegevens naar Sentinel pushen wanneer er gebeurtenissen plaatsvinden in uw systeem.

CCF Push biedt verschillende belangrijke voordelen:

  • Toepassingsgestuurde gegevensstroom: Uw toepassing bepaalt wanneer en hoe u gegevens verzendt, waardoor intelligente batchverwerkingsstrategieën en geoptimaliseerd netwerkgebruik mogelijk zijn.
  • Realtime invoer: Gegevens onmiddellijk verzenden zodra gebeurtenissen plaatsvinden, zonder te wachten op polling-interval.
  • Vereenvoudigde architectuur: U hoeft GEEN API-eindpunten te onderhouden voor Sentinel om te peilen.
  • Inrichting op basis van sjablonen: Implementatie maakt ARM-sjablonen voor DCR's, aangepaste tabellen, Entra-toepassingsregistratie en clientgeheimen. U ontvangt de verbindingsgegevens die u in uw verzendende toepassing wilt configureren.
  • Veilige verificatie: Maakt gebruik van Microsoft Entra-toepassingen met OAuth 2.0 voor het veilig verzenden van gegevens.

Prerequisites

  • Voordat u begint, moet u toegang hebben tot de Azure-Sentinel GitHub-opslagplaats voor verpakkingshulpprogramma's.
  • Microsoft Entra-machtigingen:
    • Machtiging voor het maken van een app-registratie in Microsoft Entra-id. Vereist doorgaans de rol Toepassingsontwikkelaar van Entra ID of hoger.
    • Machtiging voor het maken van een toepassing met geheimen. Als u deze machtiging niet verleent, mislukt de connector vanwege beveiligingsredenen.
    • De uitgever moet de juiste rol hebben om tokens op te halen uit de Microsoft Entra-toepassing. Deze tokens zijn vereist voor het verifiëren van aanvragen bij het EINDPUNT voor gegevensverzameling (DCE), het eindpunt waar de connector uiteindelijk de gegevens pusht. Als de provider geen tokens kan ophalen, kunnen gegevens niet naar de DCE worden verzonden.
  • Microsoft Azure-machtigingen:
    • Toestemming om de rol Monitoring Metrics Publisher toe te wijzen op de gegevensverzamelingsregel (DCR). Vereist doorgaans de rol Eigenaar in Azure RBAC of de rol Beheerder van gebruikerstoegang.

Hoe CCF-push werkt

Het pushmodel versus het pull-model

Inzicht in het verschil tussen push- en pullgegevensopnamemodellen helpt u bij het kiezen van het juiste connectortype voor uw scenario.

CCF-pull-connectors - op polling gebaseerd:

In het pull-model peilt Microsoft Sentinel periodiek uw API om gegevens op te halen:

  • Microsoft Sentinel initieert verbindingen met uw gegevensbron-API volgens een geconfigureerd schema.
  • Gegevens komen binnen op regelmatige polling-intervallen, zoals elke vijf minuten.
  • U moet een openbaar toegankelijk API-eindpunt onderhouden.
  • De polling-infrastructuur van Sentinel beheert het proces voor het verzamelen van gegevens.

CCF-pushaansluitingen - Gebeurtenisgestuurd:

In het pushmodel verzendt uw toepassing gegevens rechtstreeks naar Microsoft Sentinel:

  • Uw toepassing initieert het verzenden van gegevens wanneer er gebeurtenissen plaatsvinden.
  • Gegevens komen bijna in realtime binnen wanneer gebeurtenissen worden gegenereerd.
  • U hoeft geen API-eindpunt te onderhouden.
  • Uw toepassing bepaalt batchverwerking, timing en optimalisatie van gegevensstromen.

De pushgegevensstroom

De CCF-pushgegevensstroom bestaat uit vijf hoofdstappen:

  1. U implementeert de connector in Microsoft Sentinel.

  2. Azure maakt automatisch de volgende resources:

    • Microsoft Entra-toepassing met inloggegevens
    • DcR (Data Collection Rule) - definieert hoe uw gegevens moeten worden verwerkt
    • Eindpunt voor gegevensverzameling (DCE) - de URL waar u gegevens verzendt
    • Aangepaste logboektabel - waar uw gegevens worden opgeslagen
    • Roltoewijzingen - machtigingen voor de Entra-app

  3. U ontvangt de volgende verbindingsgegevens:

    • Tenant-id
    • Applicatie-id (client)
    • Clientgeheim
    • DCE-URI (eindpunt-URL)
    • Onveranderbare DCR-ID
    • Naam van stream

  4. Uw toepassing verzendt de volgende gegevens:

    • Hiermee haalt u een OAuth 2.0-token op met behulp van de door CCF gegenereerde Entra-app-referenties. Zie de OAuth 2.0-clientreferentiestroom voor meer informatie
    • Hiermee worden gebeurtenissen opgemaakt als JSON die overeenkomt met uw tabelschema
    • POST-gegevens naar het DCE-eindpunt

  5. Azure verwerkt en slaat gegevens op:

    • DCR's transformeren de gegevens (optionele KQL-transformaties)
    • Gegevens worden geschreven naar de aangepaste tabel in Log Analytics
    • De gegevens zijn beschikbaar voor query's, analyses en waarschuwingen in Sentinel

CCF-pushartefacten

Een CCF Push-connectoroplossing bestaat uit vier hoofdonderdelen:

  • Aangepaste tabeldefinitie
  • Regel voor gegevensverzameling (DCR)
  • Definitie van connector (UI)
  • Configuratie van pushconnector

Aangepaste tabeldefinitie

Wat het is: Het schema waarmee de structuur van uw gegevens in Log Analytics wordt gedefinieerd.

Belangrijke vereisten:

  • De tabelnaam moet eindigen op _CL (aangepast logboekachtervoegsel).
  • Moet een TimeGenerated kolom (datum/tijd-type) bevatten.
  • Kolomtypen: tekenreeks, int, long, real, bool, datetime, dynamic, guid.
  • Api-versie 2025-07-01 of hoger gebruiken.
  • Zie Een aangepaste tabel maken in Azure Monitor-logboeken voor meer informatie.

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

Regel voor gegevensverzameling (DCR)

Wat het is: Definieert hoe Azure Monitor uw gegevens opneemt en verwerkt. Zie Regels voor gegevensverzameling in Azure Monitor voor meer informatie.

Wat het doet:

  • Hiermee geeft u de naam van de invoerstroom op (wat uw app gebruikt bij het verzenden van gegevens)
  • Definieert optionele KQL-transformaties om gegevens vorm te geven en te verrijken
  • Routeert gegevens naar de doeltabel.
  • Koppelingen naar het eindpunt voor gegevensverzameling (DCE)

Belangrijkste onderdelen:

  • streamDeclarations: Definieert de structuur van binnenkomende gegevens (moet overeenkomen met wat uw app verzendt)
  • destinations: Waar de gegevens naartoe gaan (uw Log Analytics-werkruimte)
  • dataFlows: De transformatiepijplijn van invoerstroom naar uitvoertabel
  • dataCollectionEndpointId: Koppelingen naar dce voor gegevensopname

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'))]"
  }
}

Important

  • Streamnaam moet beginnen met Custom- voorvoegsel.
  • Dit transformKql kan eenvoudigweg "source" voor passthrough zijn of KQL-logica voor gegevenstransformatie bevatten.
  • outputStream moet overeenkomen met de tabelnaam met Custom- voor- en _CL achtervoegsel.

Definitie van connector (UI)

De definitie van de connector bepaalt hoe de connector wordt weergegeven in de Microsoft Sentinel-gegevensconnector-galerij. Voor meer informatie, zie Data Connector Definitions API-referentie.

De definitie van de connector bevat:

  • Titel, beschrijving en huisstijl van de connector
  • Vereiste vereisten en machtigingen, zoals toegang tot werkruimten en Entra-machtigingen
  • Instructies voor implementatie
  • Ui-besturingselementen voor het weergeven van verbindingsgegevens voor gebruikers

Belangrijkste elementen van de gebruikersinterface:

  • DeployPushConnectorButton: Hiermee wordt de geautomatiseerde implementatie van resources geactiveerd
  • CopyableLabel: Geeft de verbindingsgegevens weer na de implementatie (gebruikt fillWith parameter)
  • Markdown: Biedt opgemaakte instructies en context
  • IsConnectedQuery: De connectorconnectiviteit valideren op basis van recente gegevens

Voorbeeldstructuur (afgekort voor duidelijkheid):

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

Important

  • De id in connectorUiConfig moeten uniek zijn en overeenkomen met verwijzingen in de configuratie van de gegevensconnector.
  • Gebruiken IsConnectedQuery voor productieconnectors (valideert recente gegevens) of hasDataConnectors voor eenvoudigere validatie.
  • De parameters in fillWith worden automatisch ingevuld na de implementatie.
  • Vaste waarden, zoals streamnaam, gebruiken de value parameter in plaats van fillWith.

Configuratie van pushconnector

De configuratie van de pushconnector is het exemplaar van de gegevensconnector waarmee de definitie van de connector wordt gekoppeld aan geïmplementeerde resources.

De configuratie van de pushconnector

  • Koppelt de definitie van de connector (UI) aan de geïmplementeerde DCR- en Entra-app
  • Slaat verificatiegegevens op (app-id, service-principal-id)
  • Registreert DCR-configuratie (eindpunt, onveranderbare id, stroomnaam)
  • Hiermee kan de gebruikersinterface verbindingsgegevens ophalen en weergeven voor gebruikers

Belangrijkste eigenschappen:

  • connectorDefinitionName: moet overeenkomen met de definitie van de id connector
  • dcrConfig: Bevat DCR-eindpunt, regel-id en stroomnaam
  • auth: Bevat de Entra-toepassings-id en service-principal-id
  • kind: Moet 'Push' zijn voor push-connectors

Voorbeeld:

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

Important

  • De connectorDefinitionName moet exact overeenkomen met de id definitie van de connector.
  • De streamName stroom moet overeenkomen met de stream die is gedeclareerd in uw DCR.
  • Deze resource wordt automatisch gemaakt tijdens de implementatie wanneer gebruikers de knop DeployPushConnector selecteren.

Uw eerste pushconnector bouwen

In dit voorbeeld bouwt u een eenvoudige pushconnector waarmee beveiligingswaarschuwingen van uw toepassing naar Sentinel worden verzonden.

Doel: Beveiligingswaarschuwingen van uw toepassing in realtime verzenden naar Sentinel

Uw toepassing verzendt de gebeurtenisstructuur:

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

Stapsgewijze handleiding voor het maken van de pushconnector

  1. De Azure-Sentinel-opslagplaats klonen

    Fork en kloon vervolgens de officiële Azure-Sentinel-opslagplaats naar uw lokale machine. Deze opslagplaats bevat de verpakkingshulpprogramma's en biedt de standaardoplossingsstructuur.

    1. De opslagplaats klonen
      git clone https://github.com/<YOUR_FORK>/Azure-Sentinel.git

    2. Navigeer naar de directory Oplossingen cd Azure-Sentinel/Solutions
      De structuur van de opslagplaats bevat:

    • Tools/Create-Azure-Sentinel-Solution/V3/
    • Bevat het createSolutionV3.ps1 verpakkingsscript
    • Oplossingen/ Waar u uw connectoroplossing maakt

  2. Maak de structuur van uw oplossingsmap maak een nieuwe oplossingsmap in de map Oplossingen/map volgens de standaardnaamconventie. Oplossingsmappen maken (van Azure-Sentinel/Solutions/)

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

    De mapstructuur ziet er als volgt uit:

    Azure-Sentinel/
     └.* Oplossingen/
        └.* ContosoSecurityAlerts/
            ├── Gegevens/
            └-gegevensconnectors/
                └ContosoSecurityAlerts_ccf/

  3. De tabel definiëren

    Maak in de map ContosoSecurityAlerts_ccf een bestand met de naam table.json met de definitie van de aangepaste tabel:

    {
  "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. De DCR maken

    Maak in de map ContosoSecurityAlerts_ccf een bestand met de naam DCR.json waarmee de invoerstroom wordt gedefinieerd en gegevens naar de tabel worden gerouteerd:

    {
  "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. De definitie van de connector maken

    Maak in de map ContosoSecurityAlerts_ccf een bestand met de naam connectorDefinition.json waarmee wordt gedefinieerd hoe gebruikers communiceren met de connector in 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. De configuratie van de gegevensconnector maken

    Maak in de map ContosoSecurityAlerts_ccf een bestand met de naam dataConnector.json waarmee de connectordefinitie wordt gekoppeld aan de geïmplementeerde resources:

    {
  "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. Metagegevensbestanden voor oplossingen maken

    1. Solution_ContosoSecurityAlerts.json Maak Solution_ContosoSecurityAlerts.json met de details van uw oplossing in de map Gegevens:

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

      Important

      Vereisten voor kritieke velden:

      • BasePath: Werk het werkelijke lokale pad naar de Azure-Sentinel-opslagplaats bij
      • Metadata: Moet verwijzen SolutionMetadata.json (gemaakt in stap 6B)
      • Version: Semantische versiebeheer, bijvoorbeeld 3.0.0
      • TemplateSpec: Altijd true voor Content Hub-oplossingen
      • Is1Pconnector: Ingesteld op false voor partner-/aangepaste connectors

    2. SolutionMetadata.json maken in de hoofdmap van de oplossing

      Maak in de map ContosoSecurityAlerts SolutionMetadata.json in de hoofdmap van de oplossing (hetzelfde niveau als de map Gegevens):

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

      U hebt het SolutionMetadata.json-bestand nodig voor content hub-pakketten:

      • Het verpakkingshulpprogramma verwacht dit bestand in de hoofdmap van de oplossing
      • Het bevat marketplace-metagegevens voor Content Hub-distributie

    3. ReleaseNotes.md maken in de hoofdmap van de oplossing

      Versie Datum gewijzigd (DD-MM-YYYY) Wijzigingsgeschiedenis
      3.0.0 DD-MM-YYYY Voorbeeldoplossing

    Controlelijst voor validatie

    Controleer het volgende voordat u doorgaat met de volgende stap:

    • Mapnaam heeft geen spaties, bijvoorbeeld ContosoSecurityAlerts
    • Name veld in Solution_ContosoSecurityAlerts.json komt exact overeen met de mapnaam
    • SolutionMetadata.json bestaat in de hoofdmap van de oplossing (niet in de map Gegevens)
    • BasePath verwijst naar het werkelijke pad naar de lokale Azure-Sentinel-repository
    • Metadata veldverwijzingen "SolutionMetadata.json"
    • publisherId en offerId komen overeen in beide bestanden

  8. Uw oplossingsstructuur controleren

    Controleer of de mapstructuur overeenkomt met de vereiste indeling met alle bestanden:

    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. Uw oplossing verpakken

    Gebruik het createSolutionV3.ps1 verpakkingshulpprogramma om de ARM-implementatiesjabloon te genereren.

    # 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

    Het script werkt automatisch:

    • Valideert uw gegevens-/mapstructuur
    • Connectorartefacten verwerkt

    Verwachte uitvoer:

    In het verpakkingsscript wordt een mislukte arm-ttk-validatie (Azure Resource Manager Template Toolkit) weergegeven. Deze fout wordt verwacht en is normaal bij CCF-pushconnectors.

    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!

    De verpakking is voltooid als u de drie JSON-validatieberichten ziet die geldige bestanden bevestigen. U kunt de arm-ttk fout voor CCF Push-connectors negeren.

    Zie de Azure-Sentinel Solutions Tools documentatie voor meer informatie.

  10. Het oplossingspakket implementeren

    Implementeer de gegenereerde ARM-sjabloon (Pakket/mainTemplate.json) in uw Azure-abonnement.

    1. Zoek in Azure Portal naar Een aangepaste sjabloon implementeren
    2. Selecteer Uw eigen sjabloon maken in de editor
    3. Selecteer Bestand laden en selecteer Package/mainTemplate.json uit de uitvoermap.
    4. Selecteer Opslaan
    5. Vul de implementatieparameters in:
      • Abonnement: Uw Azure-abonnement
      • Resourcegroep: De resourcegroep met uw Sentinel-werkruimte
      • Regio: Dezelfde regio als uw Sentinel-werkruimte
      • Werkruimte: De naam van uw Log Analytics-werkruimte
    6. Selecteer Beoordelen en maken en vervolgens Maken

    Met deze implementatie is de connector beschikbaar in de Microsoft Sentinel-gegevensconnectorsgalerie.

    Zie [Quickstart: ARM-sjablonen maken en implementeren met behulp van Azure Portal](/azure/azure-resource-manager/templates/ quickstart-create-templates-use-the-portal) voor gedetailleerde stappen.

  11. De gegevensconnector inschakelen

    Nadat u het oplossingspakket hebt geïmplementeerd, schakelt u de connector in om resources in te richten en referenties te genereren.

    1. Navigeer in Azure Portal naar uw Microsoft Sentinel-werkruimte
    2. Ga naar Configuratie>Dataverbinders
    3. Beveiligingswaarschuwingen van Contoso zoeken en selecteren (push)
    4. De pagina Connector openen selecteren
    5. Selecteer de knop Contoso Security Alerts Connector implementeren
    6. Wacht tot de implementatie is voltooid (maakt een aangepaste tabel, DCR, DCE en Entra-toepassing met referenties aan)
    7. Kopieer de verbindingsgegevens die worden weergegeven:
      • Tenant-id
      • Applicatie-id (client)
      • Clientgeheim
      • Eindpunt-URI voor gegevensverzameling
      • Onveranderbare ID voor regel voor gegevensverzameling
      • Streamnaam: Custom-ContosoSecurityAlerts

  12. Uw toepassing configureren

    Werk uw toepassingscode bij met de referenties en resourcegegevens uit stap 10. De code maakt gebruik van de OAuth 2.0-clientreferentiestroom voor verificatie met Azure Monitor.

    Waarschuwing

    Bescherm uw referenties: codeer nooit referenties (tenant-id, toepassings-id, clientgeheim) rechtstreeks in uw toepassingscode of voer ze door naar broncodebeheer. Veilige opslagoplossingen voor referenties gebruiken, zoals:

    • Azure Key Vault voor productietoepassingen
    • Omgevingsvariabelen of configuratiebestanden (uitgesloten van broncodebeheer)
    • Beheerde identiteiten indien van toepassing
    • Tools voor geheimenbeheer die inloggegevens in rust versleutelen

    Python-voorbeeldtoepassingscode:

    In het volgende voorbeeld worden tijdelijke aanduidingen gebruikt, zoals <uw tenant-id>. Vervang deze waarden door beveiligde verwijzingen naar uw werkelijke referenties.

    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. Query's uitvoeren op uw gegevens

    Nadat u waarschuwingen hebt verzonden, voert u een query uit in Sentinel. Reken op 5-10 minuten voor de eerste opname.

    // 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

Verwante onderwerpen

Nu u de CCF Push connectors begrijpt, voert u de volgende stappen uit:

  1. Ontwerp uw gegevensschema - Identificeer de gebeurtenissen die u wilt verzenden en de bijbehorende velden.
  2. Connectorartefacten maken : bouw de vier JSON-bestanden (tabel, DCR, connectordefinitie, gegevensconnector).
  3. Oplossingsstructuur organiseren - Gegevens- en Gegevensconnectors/-mappen instellen met de juiste naamgeving.
  4. Uw oplossing verpakken : gebruik createSolutionV3.ps1 deze om implementatiesjablonen te genereren.
  5. Implementeren en testen : implementeren in uw Sentinel-werkruimte en gegevensstroom valideren.
  6. Integreren met uw toepassing : voeg code toe om gebeurtenissen in realtime te verzenden.
  7. Waarschuwingen en werkmappen maken : gebruik uw gegevens voor beveiligingsbewaking.

Aanvullende bronnen

CCF-documentatie

Azure Monitor en gegevensverzameling

Verificatie en beveiliging

Microsoft Sentinel

Hulp krijgen

  • Voor ISV-partners die integraties bouwen, neemt u contact op met: azuresentinelpartner@microsoft.com
  • Gebruik Microsoft Q&A met de tag 'azure-sentinel' voor technische vragen.
  • Last updated on