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, creare e distribuire connettori senza codice basati su push per Microsoft Sentinel usando il Codeless Connector Framework Push (anteprima).
Che cos'è il CCF push?
I connettori push CCF consentono alle applicazioni di inviare eventi di sicurezza direttamente a Microsoft Sentinel in tempo reale. A differenza dei connettori tradizionali basati sul polling che recuperano periodicamente i dati dalle API, i connettori push consentono di eseguire il push dei dati in Sentinel man mano che si verificano eventi nel sistema.
Il CCF Push offre diversi vantaggi principali:
- Flusso di dati controllato dall'applicazione: L'applicazione controlla quando e come inviare dati, abilitando strategie di batch intelligenti e utilizzo ottimizzato della rete.
- Inserimento in tempo reale: Inviare i dati immediatamente quando si verificano eventi, senza attendere intervalli di polling.
- Architettura semplificata: Non è necessario mantenere gli endpoint API per il polling di Sentinel.
- Provisioning basato su modello: La distribuzione crea modelli ARM per Data Collection Rules (DCR), tabelle personalizzate, registrazione dell'applicazione Entra e segreti client: riceverai i dettagli di connessione da configurare nell'applicazione di invio.
- Autenticazione sicura: Usa le applicazioni Microsoft Entra con OAuth 2.0 per l'invio sicuro dei dati.
Prerequisiti
- Prima di iniziare, è necessario avere accesso al repository GitHub Azure-Sentinel per gli strumenti di creazione di pacchetti.
- Autorizzazioni di Microsoft Entra:
- Autorizzazione per creare una registrazione dell'app in Microsoft Entra ID. In genere richiede il ruolo Sviluppatore applicazioni di Entra ID o superiore.
- Autorizzazione per creare un'applicazione con segreti. Se non si concede questa autorizzazione, il connettore non riesce a causa di motivi di sicurezza.
- Il pubblicatore 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 (DCE), ovvero l'endpoint in cui il connettore esegue il push dei dati. Se il provider non riesce a recuperare i token, i dati non possono essere inviati al controller di dominio.
- Autorizzazioni di Microsoft Azure:
- Autorizzazione per assegnare il ruolo di Publisher delle metriche di monitoraggio per la regola di raccolta dati (DCR). In genere richiede il ruolo Proprietario di Azure RBAC o Amministratore accesso utenti.
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 appropriato per lo scenario in uso.
Connettori pull CCF - Basati su polling:
Nel modello di pull, Microsoft Sentinel esegue periodicamente il polling dell'API per recuperare i dati:
- Microsoft Sentinel avvia le connessioni all'API dell'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 dati.
Connettori push CCF - Guidata dagli 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:
Distribuisci il connettore in Microsoft Sentinel.
Azure crea automaticamente le risorse seguenti:
- Applicazione Microsoft Entra con credenziali
- Regola di raccolta dati (DCR) - Definisce come elaborare i dati
- Endpoint raccolta dati (DCE) - URL in cui si inviano dati
- Tabella di log personalizzata in cui vengono archiviati i dati
- Assegnazioni di ruolo : autorizzazioni per l'app Entra
Vengono visualizzati i dettagli di connessione seguenti:
- ID del locatario
- ID client dell'applicazione
- Segreto del cliente
- URI DCE (endpoint URL)
- 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 da CCF. Per altre informazioni, vedere Flusso di credenziali client OAuth 2.0
- Formatta gli eventi come JSON corrispondenti allo schema della tabella
- Invia dati all'endpoint DCE
Azure elabora e archivia i dati:
- Le Regole di Raccolta Dati trasformano 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 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 versioni successive. - Per altre informazioni, vedere Creare una tabella personalizzata nei log di Monitoraggio di Azure.
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 Monitoraggio di Azure inserisce ed elabora i dati. Per altre informazioni, vedere Regole di raccolta dati in Monitoraggio di Azure.
Risultato:
- Specifica il nome del flusso di input (usato dall'app durante l'invio di dati)
- Definisce le trasformazioni KQL facoltative per modellare e arricchire i dati
- Indirizza 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 ciò che l'app invia) -
destinations: posizione dei 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 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
- Il nome del flusso deve iniziare con
Custom-il prefisso . -
transformKqlpuò essere utilizzato semplicemente per il pass-through, oppure 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 di Microsoft Sentinel. Per ulteriori informazioni, vedere Riferimento API per le Definizioni del 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 Entra
- Istruzioni per il processo di distribuzione
- Controlli dell'interfaccia utente per la visualizzazione dei dettagli della 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 deve 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
valueflusso, usano ilfillWithparametro anziché .
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 all'app Entra implementata
- Archivia i dettagli di autenticazione (ID app, ID entità servizio)
- Configurazione delle registrazioni DCR (endpoint, ID immutabile, nome del flusso)
- Consente all'interfaccia utente di recuperare e visualizzare i dettagli della connessione agli utenti
Proprietà chiave:
-
connectorDefinitionName: deve corrispondere aidnella definizione del connettore -
dcrConfig: contiene l'endpoint DCR, l'ID regola e il nome del flusso -
auth: contiene l'ID applicazione Entra e l'ID principale del 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
- Il
connectorDefinitionNamedeve corrispondere esattamente allaiddefinizione del connettore. - Deve
streamNamecorrispondere al flusso dichiarato nel tuo 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 a Sentinel in tempo reale
L'applicazione invia la struttura di eventi:
{
"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
Effettua un fork e poi clona il repository ufficiale di Azure-Sentinel sul tuo computer locale. Questo repository contiene gli strumenti di creazione pacchetti e fornisce la struttura della soluzione standard.
Clonare il repository
git clone https://github.com/<YOUR_FORK>/Azure-Sentinel.gitAccedere alla cartella Soluzioni
cd Azure-Sentinel/Solutions
La struttura del repository include:
- Strumenti/Creare-Azure-Sentinel-Solution/V3/
- Contiene lo script di creazione di pacchetti createSolutionV3.ps1
- Soluzioni/ Dove si creerà la soluzione del connettore
Creare la struttura di cartelle della soluzione Creare una nuova directory della soluzione all'interno della cartella Soluzioni/seguendo la convenzione di denominazione standard. Creare directory delle soluzioni (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/
├── Dati/
└_* Connettori dati/
└──ContosoSecurityAlerts_ccf/Definisci la tua 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 file di 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 critici per i campi:
-
BasePath: eseguire l'aggiornamento al percorso locale effettivo del repository Azure-Sentinel -
Metadata: deve fare riferimentoSolutionMetadata.json(creato nel passaggio 6B) -
Version: versionamento semantico, ad esempio3.0.0 -
TemplateSpec: sempretrueper le soluzioni per Hub dei contenuti -
Is1Pconnector: impostato sufalseper i connettori partner/connettori personalizzati
-
Creare SolutionMetadata.json nella radice della soluzione
Nella cartella ContosoSecurityAlerts, creare la cartella SolutionMetadata.json nella directory radice della soluzione (stesso livello della cartella 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" } }È necessario il file SolutionMetadata.json per il packaging di Content Hub.
- Lo strumento di creazione pacchetti prevede questo file nella radice della soluzione
- Contiene i metadati del marketplace per la distribuzione del Content Hub
Creare ReleaseNotes.md nella radice della soluzione
Versione Data di modifica (DD-MM-YYYY) Cronologia modifiche 3.0.0 DD-MM-YYYY Soluzione di esempio
Elenco di controllo per la 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 del repository Azure-Sentinel locale effettivo -
Metadatai campi fanno riferimento a "SolutionMetadata.json" -
publisherIdeofferIdcorrispondono in entrambi i file
Verificare la struttura della soluzione
Verificare che la struttura di cartelle corrisponda al layout richiesto con tutti i file sul posto:
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 6Imballare la tua soluzione
Usare lo script di packaging createSolutionV3.ps1 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 eseguito 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 non riuscita (Azure Resource Manager Template Toolkit). 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 è riuscita 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 ulteriori informazioni, consultare la documentazione degli strumenti delle soluzioni Azure-Sentinel.
Distribuire il pacchetto della soluzione
Distribuire il modello di Resource Manager generato (Package/mainTemplate.json) nella sottoscrizione di Azure.
- Nel portale di Azure cercare Distribuire un modello personalizzato
- Selezionare Compila un modello personalizzato nell'editor
- Selezionare Carica file e selezionare
Package/mainTemplate.jsondalla cartella di output - Seleziona Salva
- Compilare i parametri di distribuzione:
- Sottoscrizione: Sottoscrizione di Azure
- Gruppo di risorse: Gruppo di risorse contenente l'area di lavoro di Sentinel
- Regione: Stessa area dell'area di lavoro di Sentinel
- Workspace: Nome dell'area di lavoro Log Analytics
- Selezionare Rivedi e crea e quindi Crea
Questa distribuzione rende il connettore disponibile nella raccolta di connettori dati di 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 effettuare il provisioning delle risorse e generare le credenziali.
- Nel portale di Azure passare all'area di lavoro di Microsoft Sentinel
- Passare a Configurazione>Connettori dati
- Cercare e selezionare Contoso Security Alerts (Push)
- Selezionare Apri la pagina del 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, applicazione Entra con credenziali)
- Copiare i dettagli della connessione visualizzati:
- ID del locatario
- ID client dell'applicazione
- Segreto del cliente
- URI dell'endpoint di raccolta dati
- ID non modificabile della regola di raccolta dati
- Nome flusso:
Custom-ContosoSecurityAlerts
Configurare l'applicazione
Aggiorna il codice dell'applicazione con le credenziali e i dettagli della risorsa dal Passo 10. Il codice usa il flusso di credenziali client OAuth 2.0 per l'autenticazione con Monitoraggio di Azure.
Attenzione
Proteggi le credenziali: non hardcodare mai le credenziali (tenant ID, application ID, client secret) direttamente nel codice dell'applicazione o committarle nel controllo del codice sorgente. Usare soluzioni di archiviazione delle credenziali sicure, ad esempio:
- Azure Key Vault per le 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 crittografano le credenziali a riposo
Codice applicazione di esempio Python:
L'esempio seguente usa 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 l'invio di avvisi, eseguire una query in Sentinel. Attendere 5-10 minuti per il primo 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
Contenuti correlati
Ora che si conoscono i connettori push CCF, seguire questa procedura:
- Progettare lo schema dei dati : identificare gli eventi da inviare e i relativi campi.
- Creare gli artefatti del connettore - Generare i quattro file JSON (tabella, DCR, definizione del connettore, connettore dei dati).
- Organizzare la struttura della soluzione : configurare le cartelle Data/ e Data Connectors/con la denominazione corretta.
-
Creare un pacchetto della soluzione : usare
createSolutionV3.ps1per generare modelli di distribuzione. - Distribuire e testare : eseguire la distribuzione nell'area di lavoro di 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 di CCF
- Creare un connettore senza codice (CCF Pull) - Connettori basati sul polling.
- Informazioni di riferimento sulle API delle definizioni del 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.
Monitoraggio di Azure e raccolta dati
- API di inserimento log di Monitoraggio di Azure - API core per l'invio di dati.
- Regole di raccolta dati in Monitoraggio di Azure - Informazioni sui DCR.
- Struttura di una regola di raccolta dati : dettagli della struttura DCR.
- Endpoint per la raccolta dati in Monitoraggio di Azure - Configurazione DCE.
- Esercitazione: Inviare dati ai log di Monitoraggio di Azure con l'API di inserimento log - Esercitazione dettagliata.
- Creare una tabella personalizzata - Guida alla creazione di tabelle personalizzate.
Autenticazione e sicurezza
- Flusso di credenziali client OAuth 2.0 : funzionamento dell'autenticazione da app a servizio.
- Token di accesso di Microsoft Identity Platform - Informazioni sui token OAuth.
- Registrare un'applicazione in Microsoft Entra ID - Come registrare un'applicazione in Microsoft Entra ID.
- Procedure consigliate per la registrazione dell'applicazione Azure AD - Entra app security.
- Assegnare ruoli di Azure usando i modelli di Azure Resource Manager (ARM): assegnare ruoli usando i modelli.
- Raccomandazioni sulla sicurezza dei modelli ARM - Messa in sicurezza dei modelli di distribuzione.
- Limiti del servizio Monitoraggio di Azure : limiti di frequenza e quote.
Microsoft Sentinel
- Informazioni sulle soluzioni di Microsoft Sentinel : creazione di pacchetti di connettori come soluzioni.
- Monitorare l'integrità dei connettori dati - Monitoraggio dello stato di integrità
- Riferimento ARM per i connettori dati - Riferimento completo API.
Come ottenere assistenza
- Per i partner ISV che creano integrazioni, contattare: azuresentinelpartner@microsoft.com
- Per domande tecniche, usare Microsoft Q&A con il tag "azure-sentinel".