Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Questa guida consente di comprendere, compilare e distribuire connettori senza codice basati su push per Microsoft Sentinel usando codeless Connector Framework (CCF) Push (anteprima).
Che cos'è il push CCF?
I connettori push CCF consentono alle applicazioni di inviare eventi di sicurezza direttamente a Microsoft Sentinel in tempo reale. A differenza dei tradizionali connettori basati sul polling che recuperano periodicamente dati dalle API, i connettori push consentono di eseguire il push dei dati in Sentinel man mano che si verificano eventi nel sistema.
Il push CCF offre diversi vantaggi principali:
- Flusso di dati controllato dall'applicazione: L'applicazione controlla quando e come inviare dati, abilitando strategie intelligenti di invio in batch e ottimizzato l'utilizzo della rete.
- Inserimento in tempo reale: Inviare i dati immediatamente quando si verificano eventi, senza attendere gli intervalli di polling.
- Architettura semplificata: Non è necessario gestire gli endpoint API per Sentinel eseguire il polling.
- Provisioning basato su modello: La distribuzione crea modelli arm per dcr, tabelle personalizzate, registrazione dell'applicazione Entra e segreti client: vengono visualizzati i dettagli di connessione da configurare nell'applicazione di invio.
- Autenticazione sicura: Usa Microsoft Entra applicazioni con OAuth 2.0 per l'invio sicuro dei dati.
Prerequisiti
- Prima di iniziare, è necessario avere accesso al repository GitHub Azure-Sentinel per creare pacchetti di strumenti.
- Microsoft Entra autorizzazioni:
- Autorizzazione per creare una registrazione dell'app in Microsoft Entra ID. In genere richiede Entra ruolo sviluppatore di applicazioni ID o superiore.
- Autorizzazione per creare un'applicazione con segreti. Se non si concede questa autorizzazione, il connettore ha esito negativo per motivi di sicurezza.
- Il server di pubblicazione deve avere il ruolo appropriato per recuperare i token dall'applicazione Microsoft Entra. Questi token sono necessari per autenticare le richieste all'endpoint di raccolta dati, ovvero l'endpoint in cui il connettore esegue il push dei dati. Se il provider non è in grado di recuperare i token, i dati non possono essere inviati al controller di dominio.
- Autorizzazioni di Microsoft Azure:
- Autorizzazione per l'assegnazione del ruolo server di pubblicazione metriche di monitoraggio per la regola di raccolta dati . In genere richiede Azure ruolo Proprietario controllo degli accessi in base al ruolo o Amministratore accesso utente.
Funzionamento del push CCF
Modello push e modello pull
Comprendere la differenza tra i modelli di inserimento dati push e pull consente di scegliere il tipo di connettore corretto per lo scenario.
Connettori pull CCF - Basati sul polling:
Nel modello pull Microsoft Sentinel esegue periodicamente il polling dell'API per recuperare i dati:
- Microsoft Sentinel avvia le connessioni all'API origine dati in base a una pianificazione configurata.
- I dati arrivano a intervalli di polling regolari, ad esempio ogni cinque minuti.
- È necessario mantenere un endpoint API accessibile pubblicamente.
- L'infrastruttura di polling di Sentinel gestisce il processo di raccolta dei dati.
Connettori push CCF - Basati su eventi:
Nel modello push l'applicazione invia i dati direttamente a Microsoft Sentinel:
- L'applicazione avvia l'invio dei dati quando si verificano eventi.
- I dati arrivano quasi in tempo reale man mano che vengono generati eventi.
- Non è necessario gestire un endpoint API.
- L'applicazione controlla l'invio in batch, la tempistica e l'ottimizzazione del flusso di dati.
Flusso di dati push
Il flusso di dati push CCF è costituito da cinque passaggi principali:
Il connettore viene distribuito in Microsoft Sentinel.
Azure crea automaticamente le risorse seguenti:
- Microsoft Entra'applicazione con credenziali
- Data Collection Rule (DCR) - definisce come elaborare i dati
- Data Collection Endpoint (DCE) - URL in cui si inviano dati
- Tabella di log personalizzata- dove vengono archiviati i dati
- Assegnazioni di ruolo : autorizzazioni per l'app Entra
Vengono visualizzati i dettagli di connessione seguenti:
- ID del Tenant
- ID applicazione (client)
- Segreto client
- URI DCE (URL endpoint)
- ID non modificabile DCR
- nome Stream
L'applicazione invia i dati seguenti:
- Ottiene un token OAuth 2.0 usando le credenziali dell'app Entra generate dal CCF. Per altre informazioni, vedere Flusso delle credenziali client OAuth 2.0
- Formatta gli eventi come JSON corrispondenti al proprio schema di tabella
- Dati POST per l'endpoint DCE
Azure elabora e archivia i dati:
- DcR trasforma i dati (trasformazioni KQL facoltative)
- I dati sono scritti nella tabella personalizzata in Log Analytics
- I dati sono disponibili per query, analisi e avvisi in Sentinel
Elementi push CCF
Una soluzione del connettore push CCF è costituita da quattro componenti principali:
- Definizione di tabella personalizzata
- Regola di raccolta dati (DCR)
- Definizione del connettore (UI)
- Configurazione del connettore push
Definizione di tabella personalizzata
Che cos'è: Schema che definisce la struttura dei dati in Log Analytics.
Requisiti chiave:
- Il nome della tabella deve terminare con
_CL(suffisso di log personalizzato). - Deve includere una
TimeGeneratedcolonna (tipo datetime). - Tipi di colonna: string, int, long, real, bool, datetime, dynamic, guid.
- Usare la versione
2025-07-01dell'API o versione successiva. - Per altre informazioni, vedere Creare una tabella personalizzata in Azure Monitorare i log.
Esempio:
{
"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"
}
]
}
}
}
Regola di raccolta dati (DCR)
Che cos'è: Definisce il modo in cui Azure Monitor inserisce ed elabora i dati. Per altre informazioni, vedere Regole di raccolta dati in Monitoraggio Azure.
Operazioni eseguite:
- Specifica il nome del flusso di input (uso dell'app durante l'invio dei dati)
- Definisce trasformazioni KQL facoltative per modellare e arricchire i dati
- Instrada i dati alla tabella di destinazione
- Collegamenti all'endpoint di raccolta dati (DCE)
Componenti chiave:
-
streamDeclarations: definisce la struttura dei dati in ingresso (deve corrispondere a quanto inviato dall'app) -
destinations: dove vanno i dati (area di lavoro Log Analytics) -
dataFlows: pipeline di trasformazione dal flusso di input alla tabella di output -
dataCollectionEndpointId: collegamenti a DCE per l'inserimento di dati
Esempio:
{
"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
- Stream nome deve iniziare con
Custom-il prefisso. - Può
transformKqlessere semplicemente"source"per il pass-through o includere la logica KQL per la trasformazione dei dati. -
outputStreamdeve corrispondere al nome della tabella conCustom-prefisso e_CLsuffisso.
Definizione del connettore (UI)
La definizione del connettore controlla la modalità di visualizzazione del connettore nella raccolta di connettori dati Microsoft Sentinel. Per altre informazioni, vedere Informazioni di riferimento sull'API Definizioni connettore dati.
La definizione del connettore include:
- Titolo, descrizione e personalizzazione del connettore
- Prerequisiti e autorizzazioni necessari, ad esempio l'accesso all'area di lavoro e le autorizzazioni di Entra
- Passaggi delle istruzioni per la distribuzione
- Controlli dell'interfaccia utente per la visualizzazione dei dettagli di connessione agli utenti
Elementi chiave dell'interfaccia utente:
-
DeployPushConnectorButton: attiva la distribuzione automatica delle risorse -
CopyableLabel: visualizza i dettagli della connessione dopo la distribuzione (usa ilfillWithparametro ) -
Markdown: fornisce istruzioni formattate e contesto -
IsConnectedQuery: convalida la connettività del connettore in base ai dati recenti
Struttura di esempio (abbreviata per chiarezza):
{
"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
- L'oggetto
idinconnectorUiConfigdeve essere univoco e corrispondere ai riferimenti nella configurazione del connettore dati. - Usare
IsConnectedQueryper i connettori di produzione (convalida i dati recenti) ohasDataConnectorsper una convalida più semplice. - I
fillWithparametri inCopyableLabelvengono popolati automaticamente dopo la distribuzione. - I valori fissi, ad esempio il nome del flusso, usano il
valueparametro anzichéfillWith.
Configurazione del connettore push
La configurazione del connettore push è l'istanza del connettore dati che collega la definizione del connettore alle risorse distribuite.
Configurazione del connettore push
- Collega la definizione del connettore (UI) all'app DCR e Entra distribuita
- Archivia i dettagli di autenticazione (ID app, ID entità servizio)
- Registra la configurazione DCR (endpoint, ID non modificabile, nome del flusso)
- Consente all'interfaccia utente di recuperare e visualizzare i dettagli della connessione agli utenti
Proprietà chiave:
-
connectorDefinitionName: deve corrispondere a nella definizione delidconnettore -
dcrConfig: contiene l'endpoint DCR, l'ID regola e il nome del flusso -
auth: contiene l'ID applicazione Entra e l'ID entità servizio -
kind: deve essere "Push" per i connettori push
Esempio:
{
"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
- Deve
connectorDefinitionNamecorrispondere esattamente all'oggetto della definizione delidconnettore. - Deve
streamNamecorrispondere al flusso dichiarato nel DCR. - Questa risorsa viene creata automaticamente durante la distribuzione quando gli utenti selezionano il pulsante DeployPushConnector .
Creazione del primo connettore push
In questo esempio viene creato un semplice connettore push che invia avvisi di sicurezza dall'applicazione a Sentinel.
Obiettivo: Inviare avvisi di sicurezza dall'applicazione per Sentinel in tempo reale
L'applicazione invia la struttura dell'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"
}
Guida dettagliata alla creazione del connettore push
Clonare il repository Azure-Sentinel
Clonare quindi il repository Azure-Sentinel ufficiale nel computer locale. Questo repository contiene gli strumenti di creazione dei pacchetti e fornisce la struttura della soluzione standard.
Clonare il repository
git clone https://github.com/<YOUR_FORK>/Azure-Sentinel.gitPassare alla directory Soluzioni
cd Azure-Sentinel/Solutions
La struttura del repository include:
- Strumenti/Create-Azure-Sentinel-Solution/V3/
- Contiene lo script di creazione di pacchetti createSolutionV3.ps1
- Soluzioni/ Dove si creerà la soluzione del connettore
Create Your Solution Folder Structure Creare una nuova directory della soluzione all'interno della cartella Solutions/ seguendo la convenzione di denominazione standard. Creare directory della soluzione (da Azure-Sentinel/Solutions/)
mkdir ContosoSecurityAlerts cd ContosoSecurityAlerts mkdir Data mkdir "Data Connectors" mkdir "Data Connectors/ContosoSecurityAlerts_ccf"La struttura di cartelle è simile alla seguente:
Azure-Sentinel/
└-- Soluzioni/
└-, ContosoSecurityAlerts/
├✔mente Dati/
└-, Connettori dati/
└-, ContosoSecurityAlerts_ccf/Definire la tabella
Nella cartella ContosoSecurityAlerts_ccf creare un file denominato table.json con la definizione di tabella personalizzata:
{ "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" } ] } } }Creare il DCR
Nella cartella ContosoSecurityAlerts_ccf creare un file denominato DCR.json che definisce il flusso di input e instrada i dati alla tabella:
{ "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'))]" } }Creare la definizione del connettore
Nella cartella ContosoSecurityAlerts_ccf creare un file denominato connectorDefinition.json che definisce il modo in cui gli utenti interagiscono con il connettore 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" } } ] } ] } } }Creare la configurazione del connettore dati
Nella cartella ContosoSecurityAlerts_ccf creare un file denominato dataConnector.json che collega la definizione del connettore alle risorse distribuite:
{ "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": [ "$" ] } } }Creare Files metadati della soluzione
Solution_ContosoSecurityAlerts.json Nella cartella Dati creare
Solution_ContosoSecurityAlerts.jsoncon i dettagli della soluzione:{ "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
Requisiti di campo critici:
-
BasePath: eseguire l'aggiornamento al percorso locale effettivo del repository Azure-Sentinel -
Metadata: deve fare riferimentoSolutionMetadata.json(creato nel passaggio 6B) -
Version: controllo delle versioni semantico, ad esempio3.0.0 -
TemplateSpec: sempretrueper le soluzioni dell'hub contenuti -
Is1Pconnector: impostare sufalseper i connettori partner/personalizzati
-
Creare SolutionMetadata.json nella radice della soluzione
Nella cartella ContosoSecurityAlerts creare SolutionMetadata.json nella directory radice della soluzione (stesso livello della cartella Dati):
{ "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" } }È necessario il file SolutionMetadata.json per la creazione di pacchetti dell'hub contenuto:
- Lo strumento di creazione pacchetti prevede che questo file sia nella radice della soluzione
- Contiene i metadati del marketplace per la distribuzione dell'hub contenuti
Creare ReleaseNotes.md nella radice della soluzione
Versione Data modifica (DD-MM-AAAA) Cronologia modifiche 3.0.0 DD-MM-AAAA Soluzione di esempio
Elenco di controllo di convalida
Prima di procedere al passaggio successivo, verificare:
- Il nome della cartella non ha spazi, ad esempio
ContosoSecurityAlerts -
Namecampo in Solution_ContosoSecurityAlerts.json corrisponde esattamente al nome della cartella -
SolutionMetadata.jsonesiste nella radice della soluzione (non nella cartella Dati) -
BasePathpunta al percorso effettivo del repository Azure-Sentinel locale -
Metadatariferimenti ai campi "SolutionMetadata.json" -
publisherIdeofferIdcorrispondono tra entrambi i file
Verificare la struttura della soluzione
Verificare che la struttura di cartelle corrisponda al layout richiesto con tutti i file inseriti:
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 6Creare un pacchetto della soluzione
Usare lo strumento createSolutionV3.ps1 creazione di pacchetti per generare il modello di distribuzione 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.ps1Lo script viene automaticamente:
- Convalida la struttura di dati/cartelle
- Elabora gli artefatti del connettore
Output previsto:
Lo script di creazione del pacchetto mostra una convalida arm-ttk (Azure Resource Manager Template Toolkit) non riuscita. Questo errore è previsto e normale per i connettori push CCF:
Failed arm-ttk (Test-AzTemplate): Package Failed arm-ttk (Test-AzTemplate) on solutions: Package ************Validating if Package Json files are valid or not*************** File Solutions\ContosoSecurityAlerts\Package\createUiDefinition.json is a valid Json file! File Solutions\ContosoSecurityAlerts\Package\mainTemplate.json is a valid Json file! File Solutions\ContosoSecurityAlerts\Package\testParameters.json is a valid Json file!La creazione del pacchetto ha avuto esito positivo se vengono visualizzati i tre messaggi di convalida JSON che confermano i file validi. È possibile ignorare l'errore
arm-ttkper i connettori push CCF.Per altre informazioni, vedere la documentazione Azure-Sentinel Solutions Tools.For more information, see the Azure-Sentinel Solutions Tools documentation.
Distribuire il pacchetto della soluzione
Distribuire il modello arm generato (pacchetto/mainTemplate.json) nella sottoscrizione Azure.
- Nel portale di Azure cercare Deploy a custom template (Distribuisci un modello personalizzato)
- Selezionare Crea un modello personalizzato nell'editor
- Selezionare Carica file e selezionare
Package/mainTemplate.jsondalla cartella di output - Selezionare Salva
- Compilare i parametri di distribuzione:
- Sottoscrizione: Sottoscrizione Azure
- Gruppo di risorse: Gruppo di risorse contenente l'area di lavoro Sentinel
- Regione: Stessa area dell'area di lavoro Sentinel
- Workspace: Nome dell'area di lavoro Log Analytics
- Selezionare Rivedi e crea, quindi Crea
Questa distribuzione rende il connettore disponibile nella raccolta di connettori dati Microsoft Sentinel.
Per i passaggi dettagliati, vedere [Guida introduttiva: Creare e distribuire modelli di Resource Manager usando il portale di Azure](/azure/azure-resource-manager/templates/quickstart-create-templates-use-the-portal).
Abilitare il connettore dati
Dopo aver distribuito il pacchetto della soluzione, abilitare il connettore per il provisioning delle risorse e la generazione delle credenziali.
- Nella portale di Azure passare all'area di lavoro Microsoft Sentinel
- Passare aConnettori dati diconfigurazione>
- Cercare e selezionare Avvisi di sicurezza contoso (push)
- Selezionare la pagina Apri connettore
- Selezionare il pulsante Deploy Contoso Security Alerts connector (Distribuisci connettore avvisi di sicurezza contoso )
- Attendere il completamento della distribuzione (crea una tabella personalizzata, DCR, DCE, Entra'applicazione con credenziali)
- Copiare i dettagli della connessione visualizzati:
- ID del Tenant
- ID applicazione (client)
- Segreto client
- URI endpoint raccolta dati
- ID non modificabile della regola di raccolta dati
- Stream Nome:
Custom-ContosoSecurityAlerts
Configurare l'applicazione
Aggiornare il codice dell'applicazione con le credenziali e i dettagli delle risorse del passaggio 10. Il codice usa il flusso di credenziali client OAuth 2.0 per eseguire l'autenticazione con Azure Monitor.
Attenzione
Proteggere le credenziali: non eseguire mai il hardcode delle credenziali (ID tenant, ID applicazione, segreto client) direttamente nel codice dell'applicazione o eseguirne il commit nel controllo del codice sorgente. Usare soluzioni di archiviazione delle credenziali sicure, ad esempio:
- Azure Key Vault per applicazioni di produzione
- Variabili di ambiente o file di configurazione (esclusi dal controllo del codice sorgente)
- Identità gestite, se applicabile
- Strumenti di gestione dei segreti che crittografa le credenziali inattivi
Codice applicazione di esempio Python:
Nell'esempio seguente vengono usati valori segnaposto come <Your-Tenant-ID>. Sostituire questi valori con riferimenti sicuri alle credenziali effettive.
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!")Eseguire query sui dati
Dopo aver inviato gli avvisi, eseguire query in Sentinel. Attendere 5-10 minuti per la prima inserimento.
// 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
Passaggi successivi
Dopo aver compreso i connettori push CCF, seguire questa procedura:
- Progettare lo schema dei dati : identificare gli eventi da inviare e i relativi campi.
- Creare artefatti del connettore: compilare i quattro file JSON (tabella, DCR, definizione del connettore, connettore dati).
- Organizzare la struttura della soluzione : configurare i connettori di dati e i connettori dati/cartelle con la denominazione corretta.
-
Creare un pacchetto della soluzione : usare
createSolutionV3.ps1per generare modelli di distribuzione. - Distribuire e testare: distribuire nell'area di lavoro Sentinel e convalidare il flusso di dati.
- Integrazione con l'applicazione : aggiungere codice per inviare eventi in tempo reale.
- Creare avvisi e cartelle di lavoro : usare i dati per il monitoraggio della sicurezza.
Risorse aggiuntive
Documentazione CCF
- Creare un connettore senza codice (pull CCF) - Connettori basati sul polling.
- Informazioni di riferimento sulle API Definizioni connettore dati - Guida alla configurazione dell'interfaccia utente.
- Informazioni di riferimento sulle regole di connessione del connettore dati : regole di connessione per i connettori di polling.
Azure Monitoraggio e raccolta dati
- Azure Monitorare l'API di inserimento log - API core per l'invio di dati.
- Regole di raccolta dati in Monitoraggio Azure - Informazioni sui controller di dominio.
- Struttura di una regola di raccolta dati - Dettagli della struttura DCR.
- Endpoint di raccolta dati in Azure Monitoraggio - Configurazione DCE.
- Esercitazione: Inviare dati a Azure Monitorare i log con l'API di inserimento log - Esercitazione dettagliata.
- Creare una tabella personalizzata - Guida alla creazione di tabelle personalizzate.
Autenticazione e sicurezza
- Flusso delle credenziali client di OAuth 2.0 : funzionamento dell'autenticazione da app a servizio.
- Microsoft Identity Platform token di accesso: informazioni sui token OAuth.
- Registrare un'applicazione in Microsoft Entra ID: come registrare un'applicazione in Microsoft Entra ID.
- Procedure consigliate per Azure registrazione dell'applicazione AD: Entra la sicurezza delle app.
- Assegnare ruoli Azure usando modelli di Azure Resource Manager (ARM): assegnare ruoli usando i modelli.
- Raccomandazioni sulla sicurezza dei modelli di Resource Manager : protezione dei modelli di distribuzione.
- Azure Monitorare i limiti del servizio - Limiti di frequenza e quote.
Microsoft Sentinel
- Informazioni sulle soluzioni Microsoft Sentinel: creazione di pacchetti di connettori come soluzioni.
- Monitorare l'integrità dei connettori dati - Monitoraggio dell'integrità.
- Informazioni di riferimento sul modello arm per i connettori dati - Informazioni di riferimento complete sulle API.
Visualizzazione della Guida
- Per i partner ISV che creano integrazioni, contattare: azuresentinelpartner@microsoft.com
- Per domande tecniche, usare Microsoft Q&A con il tag "azure-sentinel".