使用 Logstash 透過 DCR 型 API 串流管線轉換的記錄
重要
使用 Logstash 輸出外掛程式搭配資料收集規則 (DCR) 的資料擷取目前為公開預覽狀態。 此功能已推出但不提供服務等級協定。 如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。
Microsoft Sentinel 的新 Logstash 輸出外掛程式支援透過資料收集規則 (DCR) 的管線轉換和進階設定。 外掛程式會將任何類型的記錄從外部資料源轉送至 Log Analytics 中的自訂或標準資料表，或 Microsoft Sentinel。
在本文中，您將瞭解如何設定新的 Logstash 外掛程式，以使用 DCR 將資料串流至 Log Analytics 或 Microsoft Sentinel，並完全控制輸出結構描述。 了解如何部署外掛程式。
注意
舊版的 Logstash 外掛程式可讓您經由資料收集 API 透過 Logstash 連線資料來源。
使用新的外掛程式，您可以：
- 控制資料行名稱和類型的設定。
- 執行擷取時轉換，例如篩選或擴充。
- 將自訂記錄內嵌至自訂資料表，或將 Syslog 輸入資料流內嵌至 Log Analytics Syslog 資料表。
僅限擷取到自訂記錄擷取支援的標準資料表。
若要深入了解如何使用 Logstash 資料收集引擎，請參閱開始使用 Logstash。
概觀
架構和背景
Logstash 引擎由三個元件組成：
- 輸入外掛程式：來自各種來源的自訂資料收集。
- 篩選外掛程式：根據指定的準則操作和正規化資料。
- 輸出外掛程式：自訂將已收集和處理的資料傳送到各種目的地。
注意
Microsoft 僅支援這裡討論的 Microsoft Sentinel 提供的 Logstash 輸出外掛程式。 目前的外掛程式名為 microsoft-sentinel-log-analytics-logstash-output-plugin，v1.1.0。 您可以針對輸出外掛程式的任何問題開啟支援票證。
Microsoft 不支援 Microsoft Sentinel 的第三方 Logstash 輸出外掛程式，或任何類型的任何其他 Logstash 外掛程式或元件。
如需外掛程式的 Logstash 版本支援，請參閱先決條件。
Logstash 的 Microsoft Sentinel 輸出外掛程式會使用 Log Analytics 記錄擷取 API，將 JSON 格式的資料傳送至 Log Analytics 工作區。 資料會內嵌至自訂記錄或標準資料表。
- 深入瞭解 記錄擷取 API。
在 Logstash 中部署 Microsoft Sentinel 輸出外掛程式
若要設定外掛程式，請遵循下列步驟：
- 檢閱必要條件
- 安裝外掛程式
- 建立範例檔案
- 建立必要的 DCR 相關資源
- 設定 Logstash 設定檔
- 重新啟動 Logstash
- 檢視 Microsoft Sentinel 中的傳入記錄
- 監視輸出外掛程式稽核記錄
必要條件
安裝支援的 Logstash 版本。 外掛程式支援下列 Logstash 版本：
- 7.0 - 7.17.13
- 8.0 - 8.9
- 8.11 - 8.13
注意
如果您使用 Logstash 8，建議您在管線中停用 ECS。
確認您至少擁有 Log Analytics 工作區的參與者權限。
確認您有權在工作區中建立 DCR 物件。
安裝外掛程式
Logstash 集合中提供 Microsoft Sentinel 輸出外掛程式。
- 請遵循 Logstash 使用外掛程式 檔中的指示，安裝 microsoft-sentinel-log-analytics-logstash-output-plugin 外掛程式。
- 如果您的 Logstash 系統沒有網際網路存取，請遵循 Logstash 離線外掛程式管理文件中的指示，以準備並使用離線外掛程式套件。 (這將需要您建置另一個具有網際網路存取的 Logstash 系統。)
建立範例檔案
在本節中，您會在下列其中一個案例中建立範例檔案：
建立自訂記錄的範例檔案
在此案例中，您會設定 Logstash 輸入外掛程式，將事件傳送至 Microsoft Sentinel。 在此範例中，我們使用產生器輸入外掛程式來模擬事件。 您可以使用任何其他輸入外掛程式。
在此範例中，Logstash 設定檔如下所示：
input {
generator {
lines => [
"This is a test log message"
]
count => 10
}
}
將下列輸出外掛程式設定複製到您的 Logstash 設定檔。
output { microsoft-sentinel-log-analytics-logstash-output-plugin { create_sample_file => true sample_file_path => "<enter the path to the file in which the sample data will be written>" #for example: "c:\\temp" (for windows) or "/tmp" for Linux. } }若要確定參考的檔案路徑在建立範例檔案之前已存在，請啟動 Logstash。
此外掛程式會將十筆記錄寫入至設定路徑中名為
sampleFile<epoch seconds>.json的範例檔案。 例如：c:\temp\sampleFile1648453501.json。 以下是此外掛程式所建立範例檔案的一部分：[ { "host": "logstashMachine", "sequence": 0, "message": "This is a test log message", "ls_timestamp": "2022-03-28T17:45:01.690Z", "ls_version": "1" }, { "host": "logstashMachine", "sequence": 1 ... ]此外掛程式會自動將這些屬性新增至每筆記錄：
ls_timestamp：從輸入外掛程式收到記錄的時間ls_version：Logstash 管線版本。
您可以在建立 DCR時移除這些欄位。
建立範例檔案以將記錄擷取到 Syslog 資料表
在此案例中，您會設定 Logstash 輸入外掛程式，將 syslog 事件傳送至 Microsoft Sentinel。
如果您尚未將 syslog 訊息轉送至 Logstash 電腦，您可以使用記錄器命令來產生訊息。 例如 (適用於 Linux)：
logger -p local4.warn --rfc3164 --tcp -t CEF: "0|Microsoft|Device|cef-test|example|data|1|here is some more data for the example" -P 514 -d -n 127.0.0.1 Here is an example for the Logstash input plugin: input { syslog { port => 514 } }將下列輸出外掛程式設定複製到您的 Logstash 設定檔。
output { microsoft-sentinel-log-analytics-logstash-output-plugin { create_sample_file => true sample_file_path => "<enter the path to the file in which the sample data will be written>" #for example: "c:\\temp" (for windows) or "/tmp" for Linux. } }若要確定檔案路徑在建立範例檔案之前已存在，請啟動 Logstash。
此外掛程式會將十筆記錄寫入至設定路徑中名為
sampleFile<epoch seconds>.json的範例檔案。 例如：c:\temp\sampleFile1648453501.json。 以下是此外掛程式所建立範例檔案的一部分：[ { "logsource": "logstashMachine", "facility": 20, "severity_label": "Warning", "severity": 4, "timestamp": "Apr 7 08:26:04", "program": "CEF:", "host": "127.0.0.1", "facility_label": "local4", "priority": 164, "message": 0|Microsoft|Device|cef-test|example|data|1|here is some more data for the example", "ls_timestamp": "2022-04-07T08:26:04.000Z", "ls_version": "1" } ]此外掛程式會自動將這些屬性新增至每筆記錄：
ls_timestamp：從輸入外掛程式收到記錄的時間ls_version：Logstash 管線版本。
您可以在建立 DCR時移除這些欄位。
建立必要的 DCR 資源
若要設定 Microsoft Sentinel DCR 型 Logstash 外掛程式，您必須先建立 DCR 相關資源。
在本節中，您會在下列其中一個案例中建立要用於 DCR 的資源：
建立 DCR 資源以擷取到自訂資料表
若要將資料擷取到自訂資料表，請遵循下列步驟 (根據使用 REST API (Azure 入口網站) 將資料傳送至 Azure 監視器記錄教學課程)：
請檢閱必要條件。
-
略過「傳送範例資料」步驟。
如果您遇到任何問題，請參閱疑難排解步驟。
建立 DCR 資源以擷取到標準資料表
若要將資料擷取到標準資料表 (例如 Syslog 或 CommonSecurityLog)，您可以運用使用 REST API (Resource Manager 範本) 將資料傳送至 Azure 監視器記錄教學課程中的程序。 雖然此教學課程說明如何將資料擷取到自訂資料表，但您可以輕鬆地調整程序，將資料擷取到標準資料表。 下列步驟指出步驟中的相關變更。
請檢閱必要條件。
-
略過「在 Log Analytics 工作區中建立新資料表」步驟。 將資料擷取到標準資料表時，由於 Log Analytics 中已定義該資料表，因此不需要執行此步驟。
建立 DCR。 在此步驟中：
- 提供您在上一節中建立的範例檔案。
- 使用您建立的範例檔案來定義
streamDeclarations屬性。 範例檔案中的每個欄位都應該有一個具有相同名稱和適當類型的對應資料行 (請參閱下列範例)。 - 將
outputStream屬性值設定為標準資料表 (而不是自訂資料表) 的名稱。 不同於自訂資料表，標準資料表名稱不會以_CL結尾。 - 資料表名稱的開頭應該是
Microsoft-，而不是Custom-。 在我們的範例中，outputStream屬性值為Microsoft-Syslog。
-
略過「傳送範例資料」步驟。
如果您遇到任何問題，請參閱疑難排解步驟。
範例：將資料擷取到 Syslog 資料表的 DCR
請注意：
streamDeclarations資料行名稱和類型應該與範例檔案欄位相同，但您不需要指定所有欄位。 例如，在下列 DCR 中，會從streamDeclarations資料行省略PRI、type和ls_version欄位。dataflows屬性會將輸入轉換成 Syslog 資料表格式，並將outputStream設定為Microsoft-Syslog。
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"dataCollectionRuleName": {
"type": "String",
"metadata": {
"description": "Specifies the name of the Data Collection Rule to create."
}
},
"location": {
"defaultValue": "westus2",
"allowedValues": [
"westus2",
"eastus2",
"eastus2euap"
],
"type": "String",
"metadata": {
"description": "Specifies the location in which to create the Data Collection Rule."
}
},
"location": {
"defaultValue": "[resourceGroup().location]",
"type": "String",
"metadata": {
"description": "Specifies the location in which to create the Data Collection Rule."
}
},
"workspaceResourceId": {
"type": "String",
"metadata": {
"description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
}
}
},
"resources": [
{
"type": "Microsoft.Insights/dataCollectionRules",
"apiVersion": "2021-09-01-preview",
"name": "[parameters('dataCollectionRuleName')]",
"location": "[parameters('location')]",
"properties": {
"streamDeclarations": {
"Custom-SyslogStream": {
"columns": [
{
"name": "ls_timestamp",
"type": "datetime"
}, {
"name": "timestamp",
"type": "datetime"
},
{
"name": "message",
"type": "string"
},
{
"name": "facility_label",
"type": "string"
},
{
"name": "severity_label",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "logsource",
"type": "string"
}
]
}
},
"destinations": {
"logAnalytics": [
{
"workspaceResourceId": "[parameters('workspaceResourceId')]",
"name": "clv2ws1"
}
]
},
"dataFlows": [
{
"streams": [
"Custom-SyslogStream"
],
"destinations": [
"clv2ws1"
],
"transformKql": "source | project TimeGenerated = ls_timestamp, EventTime = todatetime(timestamp), Computer = logsource, HostName = logsource, HostIP = host, SyslogMessage = message, Facility = facility_label, SeverityLevel = severity_label",
"outputStream": "Microsoft-Syslog"
}
]
}
}
],
"outputs": {
"dataCollectionRuleId": {
"type": "String",
"value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
}
}
}
設定 Logstash 設定檔
若要設定 Logstash 設定檔，將記錄擷取到自訂資料表，請擷取下列值：
| 欄位 | 擷取方式 |
|---|---|
client_app_Id |
根據您在本節中使用的教學課程，當您建立 DCR 資源時，您在步驟 3 中建立的 Application (client) ID 值。 |
client_app_secret |
根據您在本節中使用的教學課程，當您建立 DCR 資源時，您在步驟 5 中建立的 Application (client) ID 值。 |
tenant_id |
您的訂閱租用戶識別碼。 您可以在 [首頁]>[Microsoft Entra ID]>[概觀]>[基本資訊] 中找到租用戶識別碼。 |
data_collection_endpoint |
根據您在本節中使用的教學課程，當您建立 DCR 資源時，步驟 3 中 logsIngestion URI 的值。 |
dcr_immutable_id |
根據您在本節中使用的教學課程，當您建立 DCR 資源時，步驟 6 中 DCR immutableId 的值。 |
dcr_stream_name |
針對自訂資料表，請遵循建立 DCR 資源的步驟 6 所述，前往 DCR 的 JSON 檢視，然後複製 dataFlows>streams 屬性。 請參閱下列範例中的 dcr_stream_name。針對標準資料表，此值為 Custom-SyslogStream。 |
擷取必要值之後：
- 將您在上一個步驟所建立 Logstash 設定檔的輸出區段取代為下列範例。
- 將下列範例中的預留位置字串取代為您擷取的值。
- 請務必將
create_sample_file屬性變更為false。
選用設定
| 欄位 | 描述 | 預設值 |
|---|---|---|
azure_cloud |
用來指定正在使用的 Azure 雲端名稱，可用的值為：AzureCloud、AzureChinaCloud 和 AzureUSGovernment。 |
AzureCloud |
key_names |
字串的陣列。 如果您想要將資料行的子集傳送至 Log Analytics，請提供此欄位。 | 無 (欄位空白) |
plugin_flush_interval |
定義將兩則訊息傳送至 Log Analytics 之間的最大時間差異 (秒)。 | 5 |
retransmission_time |
設定傳送失敗後重新傳輸訊息的時間量 (秒)。 | 10 |
compress_data |
當此欄位為 True 時，事件資料會先進行壓縮，再使用此 API。 建議用於高輸送量管線。 |
False |
proxy |
指定要用於所有 API 呼叫的 Proxy URL。 | 無 (欄位空白) |
proxy_aad |
指定要用於 API 呼叫 Microsoft Entra ID 的 Proxy URL。 | 與「proxy」相同的值 (欄位是空的) |
proxy_endpoint |
指定要用於 API 呼叫資料收集端點的 Proxy URL。 | 與「proxy」相同的值 (欄位是空的) |
範例：輸出外掛程式設定區段
output {
microsoft-sentinel-log-analytics-logstash-output-plugin {
client_app_Id => "<enter your client_app_id value here>"
client_app_secret => "<enter your client_app_secret value here>"
tenant_id => "<enter your tenant id here> "
data_collection_endpoint => "<enter your logsIngestion URI here> "
dcr_immutable_id => "<enter your DCR immutableId here> "
dcr_stream_name => "<enter your stream name here> "
create_sample_file=> false
sample_file_path => "c:\\temp"
proxy => "http://proxy.example.com"
}
}
若要設定 Microsoft Sentinel Logstash 輸出外掛程式的其他參數，請參閱輸出外掛程式的讀我檔案。
注意
基於安全性考量，建議您不要在 Logstash 設定檔中隱含指出 client_app_Id、client_app_secret、tenant_id、data_collection_endpoint 和 dcr_immutable_id 屬性。 建議您將此敏感性資訊儲存在 Logstash 金鑰儲存區中。
重新啟動 Logstash
請重新啟動已更新輸出外掛程式設定的 Logstash，並根據您的 DCR 設定查看資料是否已擷取到正確的資料表。
在 Microsoft Sentinel 中檢視傳入記錄
驗證訊息正傳送至輸出外掛程式。
從 Microsoft Sentinel 導覽功能表，按一下 [記錄]。 在 [資料表] 標題下，展開 [自訂記錄] 類別。 尋找並按一下您在組態中指定的資料表的名稱 (具有
_CL尾碼)。
若要查看資料表中的記錄，請使用資料表名稱作為結構描述來查詢資料表。
監視輸出外掛程式稽核記錄
若要監視 Microsoft Sentinel 輸出外掛程式的連線和活動，請啟用適當的 Logstash 記錄檔。 如需記錄檔位置，請參閱 Logstash 目錄配置文件。
如果您在此記錄檔中沒有看到任何資料，請在本機產生並傳送一些事件 (透過輸入和篩選外掛程式)，以確定輸出外掛程式正在接收資料。 Microsoft Sentinel 將僅支援與輸出外掛程式相關的問題。
網路安全性
定義網路設定，並啟用 Microsoft Sentinel Logstash 輸出外掛程式的網路隔離。
虛擬網路服務標籤
Microsoft Sentinel 輸出外掛程式支援 Azure 虛擬網路服務標籤。 需要 AzureMonitor 和 AzureActiveDirectory 標籤。
Azure 虛擬網路服務標籤可用來定義 網路安全性群組、Azure 防火牆 和使用者定義路由的網路存取控制。 建立安全性規則和路由時，請以服務標籤取代特定的 IP 位址。 針對無法使用 Azure 虛擬網路服務標籤的案例，以下提供防火牆需求。
防火牆需求
下表列出無法使用 Azure 虛擬網路服務標籤之案例的防火牆需求。
| 雲端 | 端點 | 目標 | 連接埠 | 方向 | 略過 HTTPS 檢查 |
|---|---|---|---|---|---|
| Azure Commercial | https://login.microsoftonline.com | 授權伺服器 (Microsoft 身分識別平台) | 連接埠 443 | 出埠 | Yes |
| Azure Commercial | https://<data collection endpoint name>.<Azure cloud region>.ingest.monitor.azure.com |
資料收集端點 | 連接埠 443 | 出埠 | Yes |
| Azure Government | https://login.microsoftonline.us | 授權伺服器 (Microsoft 身分識別平台) | 連接埠 443 | 出埠 | Yes |
| Azure Government | 將上述 '.com' 取代為 '.us' | 資料收集端點 | 連接埠 443 | 出埠 | Yes |
| 由 21Vianet 營運的 Microsoft Azure | https://login.chinacloudapi.cn | 授權伺服器 (Microsoft 身分識別平台) | 連接埠 443 | 出埠 | Yes |
| 由 21Vianet 營運的 Microsoft Azure | 將上述 '.com' 取代為 '.cn' | 資料收集端點 | 連接埠 443 | 出埠 | Yes |
限制
- 僅限擷取到自訂記錄擷取支援的標準資料表。
streamDeclarations屬性中輸入資料流的資料行必須以字母開頭。 如果資料行以其他字元開頭 (例如@或_)，則作業會失敗。- 需要
TimeGenerated日期時間欄位。 您必須在 KQL 轉換中包含此欄位。 - 針對其他可能的問題，請檢閱教學課程中的疑難排解一節。
下一步
在本文中，您已了解如何使用 Logstash 將外部資料來源連線到 Microsoft Sentinel。 若要深入了解 Microsoft Sentinel，請參閱下列文章：
- 學習如何洞察資料及潛在威脅。
- 開始 使用 Microsoft Sentinel 來偵測威脅。