本指南將協助您了解、建置並部署使用無程式碼連接器框架 (CCF) 推送的 Microsoft Sentinel 推送式無程式碼連接器 (預覽)。
CCF 推送是什麼?
CCF Push 連接器讓你的應用程式能即時直接將安全事件傳送給 Microsoft Sentinel。 與傳統會定期從 API 擷取資料的輪詢連接器不同,推送連接器允許你在系統事件發生時立即將資料推送至 Sentinel。
CCF Push 提供多項主要優勢:
- 應用控制的資料流: 您的應用程式控制何時以及如何傳送資料,實現智慧批次策略與優化網路使用。
- 即時攝取: 事件發生時立即傳送資料,無需等待輪詢間隔。
- 簡化架構: 不需要維護 API 端點讓 Sentinel 進行輪詢。
- 基於範本的配置: 部署會建立 ARM 範本,用於 DCR、自訂資料表、Entra 應用程式註冊和用戶端秘密——你會收到連線細節,以便在發送應用程式中設定。
- 安全認證: 使用 Microsoft Entra 應用程式搭配 OAuth 2.0 進行安全資料提交。
先決條件
Important
目前部署 CCF Push 連接器需要在 Azure 入口網站中使用 Microsoft Sentinel 體驗介面。 從 Microsoft Defender 入口網站執行的受控部署,在建立連接器所需的身分識別資源時可能會失敗。 若發生這種情況,請在 Azure 入口網站安裝並連接 Microsoft Sentinel 的連接器,然後使用 Microsoft Defender 入口網站進行持續的 Microsoft Sentinel 操作。
- 在開始之前,你必須能存取 Azure-Sentinel GitHub 的封裝工具倉庫。
- Microsoft Entra 權限:
- 允許在 Microsoft Entra ID 中建立應用程式註冊。 通常需要 Entra ID 應用程式開發人員或更高階的職位。
- 允許建立帶有秘密的應用程式。 如果你不授予這個權限,連接器會因安全原因失效。
- 發佈者必須具備從 Microsoft Entra 應用程式中取得權杖的適當角色。 這些憑證是驗證向資料收集端點(Data Collection Endpoint,DCE)請求的必要條件,DCE 是連接器最終推送資料的端點。 如果提供者無法取得憑證,資料就無法傳送到 DCE。
- Microsoft Azure permissions:
- 在收集規則 (DCR) 上指派監視計量發行者角色的權限。 通常需要 Azure RBAC 擁有者或使用者存取管理員角色。
CCF 推送的運作方式
推式模型與拉式模型
了解推送與拉取資料擷取模型的差異,有助於你為情境選擇合適的連接器類型。
CCF 插拔式連接器 - 輪詢機制:
在拉取模型中,Microsoft Sentinel 會定期輪詢你的 API 以取得資料:
- Microsoft Sentinel 會依照設定的排程啟動連接你的資料來源 API。
- 資料會在定期輪詢間隔內抵達,例如每五分鐘一次。
- 你必須維護一個公開可存取的 API 端點。
- Sentinel 的輪詢基礎設施負責管理資料收集流程。
CCF「推式連接器」 - 「事件驅動」:
在推送模式中,你的應用程式會直接將資料傳送給 Microsoft Sentinel:
- 當事件發生時,您的應用程式會啟動資料提交。
- 隨著事件產生,資料幾乎即時抵達。
- 你不需要維護 API 端點。
- 你的應用程式控制批次處理、時間安排和資料流優化。
資料推送流程
CCF 推送資料流程包含五個主要步驟:
你在 Microsoft Sentinel 中部署連接器。
Azure 會自動建立以下資源:
- Microsoft Entra 應用程式與憑證
- 資料收集規則(DCR)-定義如何處理您的資料
- 資料收集端點(Data Collection Endpoint,DCE)-你用來傳送資料的網址
- 自訂日誌表——資料存放的地方
- 角色指派 - Entra 應用程式的權限
您將收到以下連結資訊:
- 租戶識別碼
- 應用程式(用戶端)ID
- 用戶端密碼
- DCE URI(端點 URL)
- DCR 不可變識別碼
- 串流名稱
您的申請會傳送以下資料:
- 使用 CCF 產生的 Entra 應用程式憑證取得 OAuth 2.0 令牌。 更多資訊請參閱 OAuth 2.0 用戶端憑證流程
- 將事件格式化為符合你的表格結構的 JSON
- 將資料以 POST 方法傳送至 DCE 端點
Azure 處理並儲存資料:
- DCR 會轉換資料(可選的 KQL 轉換)
- 資料會寫入Log Analytics的自訂資料表
- 這些資料可在 Sentinel 查詢、分析及警示中使用
CCF 推送成品
CCF Push 連接器解決方案包含四個主要組件:
- 自訂資料表定義
- 資料收集規則 (DCR)
- 連接器定義(UI)
- 推送連接器設定
自訂資料表定義
內容簡介: 定義你在 Log Analytics 中資料結構的架構。
主要需求:
- 表格名稱必須以
_CL(custom log suffix)結尾。 - 必須包含一個
TimeGenerated欄位(datetime 類型)。 - 欄位類型:字串、int、long、real、bool、datetime、dynamic、guid。
- 使用 API 版本
2025-07-01或更高版本。 - 欲了解更多資訊,請參閱在 Azure 監視器 Logs 建立自訂資料表。
Example:
{
"name": "ContosoSecurityAlerts_CL",
"type": "Microsoft.OperationalInsights/workspaces/tables",
"apiVersion": "2025-07-01",
"properties": {
"schema": {
"name": "ContosoSecurityAlerts_CL",
"columns": [
{
"name": "TimeGenerated",
"type": "datetime"
},
{
"name": "EventSeverity",
"type": "string"
},
{
"name": "EventType",
"type": "string"
},
{
"name": "UserName",
"type": "string"
},
{
"name": "SourceIP",
"type": "string"
},
{
"name": "DeviceId",
"type": "string"
},
{
"name": "AlertMessage",
"type": "string"
}
]
}
}
}
資料收集規則 (DCR)
內容簡介: 定義 Azure 監視器 如何擷取和處理你的資料。 如需詳細資訊,請參閱 Azure 監視器中的數據收集規則。
它的用途:
- 指定輸入串流名稱(你的應用程式傳送資料時使用的名稱)
- 定義可選的 KQL 轉換以塑造並豐富資料
- 將資料導向至目的資料表
- 資料收集端點(DCE)的連結
關鍵組件:
-
streamDeclarations:定義輸入資料的結構(必須與你的應用程式傳送的相符) -
destinations:資料的去向(你的日誌分析工作區) -
dataFlows: 從輸入串流到輸出表的轉換管線 -
dataCollectionEndpointId:用於資料擷取的 DCE 連結
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
- 串流名稱必須以
Custom-前綴開頭。 -
transformKql可以僅使用"source"進行傳遞,或加入 KQL 邏輯以進行資料轉換。 -
outputStream必須與你的資料表名稱搭配Custom-前綴和_CL後綴相符。
連接器定義(UI)
連接器定義控制連接器在 Microsoft Sentinel 資料連接器庫中的呈現方式。 欲了解更多資訊,請參閱 資料連接器定義 API 參考。
連接器定義包括:
- 連接器名稱、描述與品牌
- 前提條件與權限要求,例如工作區存取權限與 Entra 權限
- 部署指令步驟
- 使用者介面控制項,用於顯示連線細節
關鍵使用者介面元素:
-
DeployPushConnectorButton: 觸發自動資源部署 -
CopyableLabel: 部署後顯示連線細節(使用fillWith參數) -
Markdown:提供格式化的指示與上下文 -
IsConnectedQuery:根據最新數據驗證連接器連接性
範例結構(為清晰起見略寫):
{
"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
-
id中的connectorUiConfig必須是唯一且與資料連接器組態中的參考相符。 - 用於
IsConnectedQuery生產連接器(驗證近期資料),或hasDataConnectors用於更簡單的驗證。 -
fillWith參數CopyableLabel會在部署後自動填充。 - 固定值,如串流名稱,則使用參數
value而非fillWith。
推入式連接器設定
推送連接器配置是將連接器定義連結到已部署資源的資料連接器實例。
推接頭配置
- 將連接器定義(UI)連結至已部署的 DCR 及 Entra 應用程式
- 儲存認證細節(應用程式 ID、服務主體 ID)
- 記錄 DCR 配置(端點、不可變 ID、串流名稱)
- 讓使用者介面能檢索並顯示連線細節給使用者
主要特性:
-
connectorDefinitionName: 必須符合id你連接器定義中的條件 -
dcrConfig: 包含 DCR 端點、規則 ID 及串流名稱 -
auth:包含 Entra 應用程式 ID 與服務主體 ID -
kind:推送連接器必須是「Push」
範例:
{
"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
-
connectorDefinitionName必須完全符合連接器定義的id。 - 必須
streamName與你 DCR 中宣告的流域相符。 - 當使用者選擇 DeployPushConnector 按鈕時,該資源會在部署過程中自動建立。
打造你的第一個推接頭
在這個例子中,你建置了一個簡單的推送連接器,從你的應用程式向 Sentinel 發送安全警示。
目標: 即時從應用程式向 Sentinel 發送安全警示
您的申請會傳送事件結構:
{
"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"
}
建立推接連接器的逐步指南
克隆 Azure-Sentinel 資料庫
先派生官方的 Azure-Sentinel 存放庫,再將其複製到您的本機電腦上。 此儲存庫包含打包工具並提供標準解決方案結構。
複製存放庫
git clone https://github.com/<YOUR_FORK>/Azure-Sentinel.git前往解決方案目錄
cd Azure-Sentinel/Solutions
資料庫結構包括:
- Tools/Create-Azure-Sentinel-Solution/V3/
- 包含 createSolutionV3.ps1 包裝腳本
- 解決方案/您將在哪裡建立您的連接器解決方案
建立您的解決方案資料夾結構 依照標準命名慣例,在 Solutions/ 資料夾中建立新的解決方案目錄。 建立解決方案目錄(來自 Azure-Sentinel/Solutions/)
mkdir ContosoSecurityAlerts cd ContosoSecurityAlerts mkdir Data mkdir "Data Connectors" mkdir "Data Connectors/ContosoSecurityAlerts_ccf"你的資料夾結構如下:
Azure-Sentinel/
└── 解決方案/
└── ContosoSecurityAlerts/
├── 資料/
└── 資料連接器/
└── ContosoSecurityAlerts_ccf/定義你的表格
在ContosoSecurityAlerts_ccf資料夾中,建立一個名為 table.json 的檔案,並設定自訂資料表定義:
{ "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" } ] } } }建立DCR
在 ContosoSecurityAlerts_ccf 資料夾中,建立一個名為 DCR.json 的檔案,定義輸入串流並將資料導向你的資料表:
{ "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'))]" } }建立連接器定義
在 ContosoSecurityAlerts_ccf 資料夾中建立一個名為 connectorDefinition.json 的檔案,定義使用者如何與 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" } } ] } ] } } }建立資料連接器設定
在 ContosoSecurityAlerts_ccf 資料夾中,建立一個名為 dataConnector.json 的檔案,將連接器定義連結到已部署的資源:
{ "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": [ "$" ] } } }建立解決方案元資料檔案
Solution_ContosoSecurityAlerts.json 在 Data 資料夾中,請依照你的解決方案細節建立
Solution_ContosoSecurityAlerts.json:{ "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
關鍵現場需求:
-
BasePath:將 Azure-Sentinel 存放庫更新為您實際的本機路徑 -
Metadata: 必須引用SolutionMetadata.json(在第 6B 步建立) -
Version: 語意版本化,例如,3.0.0 -
TemplateSpec:對於內容中樞解決方案,始終設定true -
Is1Pconnector:設為false用於合作夥伴/自訂連接器
-
在解決方案根目錄建立 SolutionMetadata.json 檔案
在 ContosoSecurityAlerts 資料夾中,請在解決方案根目錄(與 Data 資料夾相同層級)建立 SolutionMetadata.json:
{ "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" } }你需要 Content Hub 打包用的 SolutionMetadata.json 檔案:
- 包裝工具期望這個檔案位於解決方案根目錄
- 它包含 Content Hub 分發用的市場元資料
在解決方案根目錄建立 ReleaseNotes.md
版本 日期修改(DD-MM-YYYY) 變革歷史 3.0.0 DD-MM-YYYY 範例解決方案
驗證檢查清單
在進入下一步前,請先確認:
- 例如資料夾名稱沒有空格
ContosoSecurityAlerts -
NameSolution_ContosoSecurityAlerts.json 中的欄位與資料夾名稱完全一致 -
SolutionMetadata.json存在於解決方案根目錄(不在 Data 資料夾中) -
BasePath指向你實際的本地 Azure-Sentinel 儲存庫路徑 -
Metadata欄位引用「SolutionMetadata.json」 -
publisherId和offerId在兩個檔案之間相符
驗證你的解決方案結構
確認你的資料夾結構及所有檔案都符合所需的配置:
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打包你的解決方案
使用 createSolutionV3.ps1 打包工具來產生 ARM 部署範本。
# Navigate to the packaging tools directory (from Azure-Sentinel repository root) cd Tools/Create-Azure-Sentinel-Solution/V3 # Run the packaging tool # When prompted for "Enter solution data folder path:", provide: # <REPO_ROOT>Solutions/ContosoSecurityAlerts/Data (Note! This path is absolute) .\createSolutionV3.ps1此腳本會自動:
- 驗證你的資料/資料夾結構
- 處理連接器構件
預期產出:
包裝腳本顯示 arm-ttk(Azure Resource Manager Template Toolkit)驗證失敗。 這種故障在 CCF Push 連接器中是預期且正常的:
Failed arm-ttk (Test-AzTemplate): Package Failed arm-ttk (Test-AzTemplate) on solutions: Package ************Validating if Package Json files are valid or not*************** File Solutions\ContosoSecurityAlerts\Package\createUiDefinition.json is a valid Json file! File Solutions\ContosoSecurityAlerts\Package\mainTemplate.json is a valid Json file! File Solutions\ContosoSecurityAlerts\Package\testParameters.json is a valid Json file!如果你看到三個 JSON 驗證訊息確認檔案有效,封包就算成功了。 你可以忽略 CCF Push 連接器的
arm-ttk故障。欲了解更多資訊,請參閱 Azure-Sentinel 解決方案工具文件。
部署解決方案套件
將產生的 ARM 範本(套件/mainTemplate.json)部署到你的 Azure 訂閱中。
- 在 Azure 入口網站中,搜尋「Deploy a custom template」
- 在編輯器中選擇「建立你自己的範本」
- 選擇載入檔案,然後從輸出資料夾中選擇
Package/mainTemplate.json - 選擇儲存
- 填寫部署參數:
- 訂閱方式: 你的 Azure 訂閱
- 資源群組: 包含您 Sentinel 工作區的資源群組
- 地區: 和你的 Sentinel 工作區是同一區域
- 工作空間: 你的日誌分析工作區名稱
- 選擇 評論 + 創建,然後 建立
此部署使該連接器可在您的 Microsoft Sentinel 資料連接器圖庫中取得。
詳細步驟請參見[快速入門:使用 Azure 入口網站建立及部署 ARM 模板](/azure/azure-resource-manager/templates/quickstart-create-templates-use-the-portal)。
啟用資料連接器
部署解決方案套件後,啟用連接器以配置資源並產生憑證。
- 在 Azure 首頁中,導航至你的 Microsoft Sentinel 工作區
- 前往 配置>資料連接器
- 搜尋並選擇 Contoso 安全警示(推送)
- 選擇 開啟連接器頁面
- 選擇 部署 Contoso 安全警示連接器 按鈕
- 等待部署完成(建立自訂資料表、DCR、DCE,以及伴隨憑證的 Entra 應用程式)
- 複製顯示的連結細節:
- 租戶識別碼
- 應用程式(用戶端)ID
- 用戶端密碼
- 資料收集端點 URI
- 資料收集規則不變識別碼
- 串流名稱:
Custom-ContosoSecurityAlerts
設定你的應用程式
用第 10 步的憑證和資源細節更新你的申請碼。 程式碼使用 OAuth 2.0 用戶端憑證流程來與 Azure 監視器 進行認證。
Caution
保護你的憑證:切勿直接在應用程式程式碼中硬編碼憑證(租戶 ID、應用程式 ID、客戶端秘密),也不要提交到原始碼控制。 使用安全的憑證儲存解決方案,例如:
- Azure Key Vault 用於生產應用程式
- 環境變數或設定檔(不包含於原始碼控制)
- 在適用的情況下使用管理身份識別
- 秘密管理工具,用於靜態加密憑證
Python 範例應用程式程式碼:
以下範例使用了像 <Your-Tenant-ID> 這樣的佔位值。 請將這些值替換為您實際憑證的安全性參考。
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!")查詢您的資料
發送警報後,請在 Sentinel 查詢。 第一次服用時,請預留5到10分鐘。
// 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
相關內容
現在你已經了解 CCF Push 連接器,請採取以下步驟:
- 設計你的資料結構 ——辨識你想傳送的事件及其欄位。
- 建立連接器工件 - 建立四個 JSON 檔案(表格、DCR、連接器定義、資料連接器)。
- 組織解決方案結構 - 設定 Data/ 和 Data Connectors/資料夾,並正確命名。
-
打包你的解決方案 - 用
createSolutionV3.ps1來產生部署範本。 - 部署與測試 - 部署到您的 Sentinel 工作區並驗證資料流。
- 整合到你的應用程式 ——新增程式碼以即時傳送事件。
- 建立警示與工作簿 ——利用你的資料進行安全監控。
其他資源
CCF 文件
- 建立無程式碼連接器 (CCF Pull) - 輪詢型連接器。
- 資料連接器定義 API 參考 - UI 設定指南。
- 資料連接器連線規則參考 - 輪詢連接器的連線規則。
Azure 監視器 與資料收集
- Azure 監視器 日誌擷取 API - 用於傳送資料的核心 API。
- Azure 監視器 中的資料收集規則 - 了解 DCR。
- 資料收集規則的結構 ——DCR 結構細節。
- Azure 監視器 中的資料收集端點 - DCE 配置。
- 教學:透過日誌擷取 API 將資料傳送到 Azure 監視器 日誌 - 逐步教學。
- 建立自訂表格 - 自訂表格建立指南。
驗證和安全性
- OAuth 2.0 用戶端憑證流程 ——應用程式對服務認證的運作方式。
- Microsoft 身份平台存取權杖 - 理解 OAuth 權杖。
- 在 Microsoft Entra ID 註冊應用程式 - 如何在 Microsoft Entra ID 註冊應用程式。
- Azure AD 應用程式註冊最佳實踐 - Entra 應用程式安全。
- 使用 Azure 資源管理器(ARM)範本指派 Azure 角色 - 使用範本指派角色。
- ARM 範本安全建議 - 保護部署範本。
- Azure 監視器 服務限制 - 速率限制與配額。
Microsoft Sentinel
- 關於 Microsoft Sentinel 解決方案 - 將連接器包裝為解決方案。
- 監控你的資料連接器健康 狀況——健康監測。
- 資料連接器的ARM 範本參考 - 完整的 API 參考資料。
尋求幫助
- 對於正在建置整合的 ISV 合作夥伴,請連絡:azuresentinelpartner@microsoft.com
- 技術問題請使用 Microsoft Q&A 並標註 'azure-sentinel'。