Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

管理規則排除條件

支援的服務：

Google SecOps SIEM

本文說明如何使用 API，以程式輔助方式管理 Google Security Operations 中的規則排除項目。排除條件是您根據統合式資料模型 (UDM) 欄位定義的篩選器，可防止特定偵測項目產生快訊。這些篩選器會找出已知或安全的活動，避免資訊主頁顯示不必要的干擾資訊。

注意：請勿直接對複合規則套用規則排除條件。您必須將排除條件套用至構成複合規則的基礎規則。這是因為規則排除條件是根據 UDM 欄位 (例如 principal.user.userid) 評估，但複合規則是根據其他偵測結果 (而非 UDM 欄位) 觸發。如果直接將規則排除條件套用至複合規則，排除條件將無法比對，事件也不會遭到排除。

如要找出基礎規則，請在 Google SecOps 控制台 (依序前往「內容中心」>「精選偵測規則」) 檢查複合規則定義，並查看 YARA-L 邏輯的 events: 部分，找出基礎規則名稱。

使用結果篩選器建立排除條件

您可以透過程式輔助方式建立新的排除規則，抑制符合定義條件的特定偵測發現項目，進而減少干擾，並優先處理高準確度的警示。

使用 POST 端點定義抑制邏輯。所有包含 outcomeFilters 陣列的篩選器都會透過隱含的 AND 子句連結。

方法：POST

端點：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID

更改下列內容：

REGION：Google SecOps 執行個體的 Google Cloud 區域。

PROJECT_ID： Google Cloud 專案 ID。

LOCATION：Google SecOps 執行個體的位置 (通常與區域相同)。

INSTANCE_ID：Google SecOps 執行個體的 ID。

範例：

POST https://us-chronicle.googleapis.com/v1/projects/my-project/locations/us/instances/my-instance/findingsRefinements

要求主體：

{
  "displayName": "Exclusion with outcome filters",
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ]
}

這個範例說明如何定義抑制邏輯，其中 outcomeFilters 陣列中的多個篩選器會透過隱含的 AND 子句連結。

必填欄位：displayName、type、query

系統產生的欄位：請勿指定 name、createTime 或 updateTime。這些欄位由系統管理，如果包含在要求中，系統會忽略或導致錯誤。

抑制邏輯遵循 AND 關係。這項要求會建立排除條件，抑制含有下列事件的偵測項目：

"altostrat.com" 為主要主機名稱
結果變數 ip，值為 127.0.0.1
結果變數 hostnames 至少有一個匯總值為 altostrat.com。

排除條件中指定的所有篩選器，都會透過 AND 子句隱含連結。

API 回應：API 會傳回 FindingsRefinement 資源名稱。

FindingsRefinement 資源包含核心抑制邏輯 (查詢和結果篩選器)。資源名稱 (ID) 用於後續的排除作業

存取排除條件

使用 GET 端點執行下列操作：

依據專屬 ID 取得單一排除定義的詳細資料。
當您有特定的 refinement-id，且需要驗證其中包含的確切查詢或結果篩選條件時。

方法：GET

端點：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

更改下列內容：

REGION：Google SecOps 執行個體的 Google Cloud 區域。

PROJECT_ID： Google Cloud 專案 ID。

LOCATION：Google SecOps 執行個體的位置 (通常與區域相同)。

INSTANCE_ID：Google SecOps 執行個體的 ID。

範例：

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777

將排除條件套用至規則或規則集

您必須將排除條件套用至特定規則或精選規則集。將排除條件套用至規則或規則集時，系統會建立 FindingsRefinementDeployment 資源。您可以使用這項資源，判斷適用於 FindingsRefinement 資源的自訂規則、精選規則或精選規則集。接著，您可以在 API 要求中指定 update_mask 參數，指出要更新 FindingsRefinementDeployment 中的哪些欄位。

方法：PATCH

端點：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID

更改下列內容：

REGION：Google SecOps 執行個體的 Google Cloud 區域。

PROJECT_ID： Google Cloud 專案 ID。

LOCATION：Google SecOps 執行個體的位置 (通常與區域相同)。

INSTANCE_ID：Google SecOps 執行個體的 ID。

REFINEMENT_ID：發現項目精細化設定的專屬 ID。

範例：

 PATCH https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777?update_mask=enabled,detectionExclusionApplication

要求主體：

{
  "name": "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777",
  "enabled": true,
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/<var>CATEGORY_ID</var>/curatedRuleSets/<var>RULE_SET_ID</var>"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/<var>CURATED_RULE_ID</var>"
    ],
    "rules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/rules/<var>RULE_ID</var>"
    ]
  }
}

在要求主體中，將 CATEGORY_ID、RULE_SET_ID、CURATED_RULE_ID 和 RULE_ID 替換為 curatedRuleSets、curatedRules 和 rules，指定精選規則集、精選規則和規則資源名稱清單。

將排除條件套用至規則或規則集時，系統會建立 FindingsRefinementDeployment 資源。這項資源會決定哪些自訂規則、精選規則和精選規則集適用於 FindingsRefinement 資源。您也可以在 API 要求中加入 update_mask 參數，指定要更新 FindingsRefinementDeployment 中的哪些欄位。

存取排除項目的部署作業

建立或更新排除項目後，請使用這個端點，確認該排除項目已部署至哪些規則或規則集。

方法：GET

端點：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID

更改下列內容：

REGION：Google SecOps 執行個體的 Google Cloud 區域。

PROJECT_ID： Google Cloud 專案 ID。

LOCATION：Google SecOps 執行個體的位置 (通常與區域相同)。

INSTANCE_ID：Google SecOps 執行個體的 ID。

REFINEMENT_ID：發現項目精細化設定的專屬 ID。

範例：

   GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777/deployment

列出所有排除條件

使用這個端點擷取 findingsRefinements 資源清單。

方法：GET

端點：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

更改下列內容：

REGION：Google SecOps 執行個體的 Google Cloud 區域。

PROJECT_ID： Google Cloud 專案 ID。

LOCATION：Google SecOps 執行個體的位置 (通常與區域相同)。

INSTANCE_ID：Google SecOps 執行個體的 ID。

範例：

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements

選用查詢參數：pageSize、pageToken

您可以使用選用參數，列出與 API 中其他清單端點類似的更多結果。

列出所有排除部署作業

使用下列端點，取得在執行個體中建立的 FindingsRefinement 資源清單。

方法：GET

端點：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

更改下列內容：

REGION：Google SecOps 執行個體的 Google Cloud 區域。

PROJECT_ID： Google Cloud 專案 ID。

LOCATION：Google SecOps 執行個體的位置 (通常與區域相同)。

INSTANCE_ID：Google SecOps 執行個體的 ID。

範例：

  GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:listAllFindingsRefinementDeployments

選用查詢參數：

使用 pageSize 和 pageToken 參數，列出更多與 API 中其他清單端點類似的結果。
使用 filter 參數，篩選已套用排除條件的規則或規則集。

使用 API 測試排除條件

下列端點會根據指定規則和規則集的偵測結果測試排除項目，然後驗證排除項目是否能有效抑制不必要的偵測。使用者介面會使用過去 30 天的偵測結果進行測試。

方法：POST

端點：

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:testFindingsRefinement

更改下列內容：

REGION：Google SecOps 執行個體的 Google Cloud 區域。

PROJECT_ID： Google Cloud 專案 ID。

LOCATION：Google SecOps 執行個體的位置 (通常與區域相同)。

INSTANCE_ID：Google SecOps 執行個體的 ID。

範例：

POST https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:testFindingsRefinement

要求主體：

{
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ],
  "interval": {
    "start_time": {
      "seconds": 1756684800
    },
    "end_time": {
      "seconds": 1759276800
    }
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/<var>CATEGORY_ID</var>/curatedRuleSets/<var>RULE_SET_ID</var>"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/<var>CURATED_RULE_ID</var>"
    ],
    "rules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/rules/<var>RULE_ID</var>"
    ]
  }
}

這個端點會測試排除條件，排除在要求中指定的規則和規則集內產生的偵測結果。這有助於判斷排除項目是否有效抑制不應產生的偵測結果。系統會以過去 30 天的偵測結果做為日期範圍，測試排除條件。在上述範例中，interval 欄位會測試 2025 年 9 月 1 日 00:00 UTC (1756684800) 至 2025 年 10 月 1 日 00:00 UTC (1759276800) 之間的偵測結果，而 detectionExclusionApplication 則會取代 CATEGORY_ID、RULE_SET_ID、CURATED_RULE_ID 和 RULE_ID，指定要測試的資源名稱。

查詢語法和欄位規則

findingsRefinements.query 欄位支援 YARA-L 2.0 語法的受限子集，而非完整的 UDM 搜尋 (udmSearch) 語法。由於這兩種查詢語法不同，在 udmSearch 中成功的查詢可能會在排除項目中失敗，並顯示 400 INVALID_ARGUMENT 錯誤。

以下各節說明 findingsRefinements.query 欄位的語法規則：

布林文法
支援的運算子和常值
支援的 UDM 欄位和路徑深度限制

如要在部署前驗證排除查詢，請呼叫 testFindingsRefinement 端點，而非 udmSearch。

布林語法

findingsRefinements.query 欄位需要平面合取範式 (CNF) 布林語法。在平面 CNF 中，您可以使用 AND 彙整一或多個子句，且每個括號子句只包含平面 OR 比較，不含巢狀括號。

findingsRefinements.query 欄位支援下列布林值結構：

單一比較或 OR 比較的平面序列，例如 field_a = "val_1" OR field_b = "val_2"。
多個子句由 AND (或隱含空白字元 AND) 連結，其中每個括號子句僅包含平面 OR 比較。例如 field_a = "val_1" AND (field_b = "val_2" OR field_c = "val_3")。
在單一比較前加上前置字元 NOT，例如 NOT principal.hostname = "scanner.example.com"。

findingsRefinements.query 欄位會拒絕下列布林值結構，並顯示 400 INVALID_ARGUMENT 錯誤：

巢狀括號，例如 A AND (B OR (C AND D))。
括號子句之間的邏輯 OR 運算子，例如 (A AND B) OR (C AND D)。

您可以將巢狀邏輯 (例如 A OR (B AND C)) 重新編寫為平面 CNF，例如 (A OR B) AND (A OR C)。如果 AND 個條件中須符合 OR 個條件的情況較為複雜，導致 CNF 擴充過大，請為每個 AND 分支建立個別的 FindingsRefinement 資源。

支援的運算子和常值

下表列出各項查詢功能、findingsRefinements.query 是否支援，以及有效範例或替代方案：

功能	`findingsRefinements.query`支援	範例或替代方案
比較運算子	支援 `=`、`!=`、`<`、`<=`、`>` 和 `>=`。字串、規則運算式和對應比較支援 `=` 和 `!=`。	`metadata.log_type = "WINDOWS_SYSMON"`
規則運算式	支援字串和對應欄位中以斜線分隔的規則運算式 (`/.../`)。	`principal.hostname = /^scanner-[0-9]+\.example\.com$/`
不區分大小寫的修飾符	支援字串和規則運算式比較的 `nocase`。列舉欄位不支援 `nocase`。	`principal.user.userid = "admin" nocase`
文字	支援雙引號字串、整數、浮點數、布林值 (`true` 或 `false`) 和 Base64 位元組常值 (`b"..."`)。	`security_result.about.file.sha256 = "e3b0c4..."`
CIDR 範圍比對	支援 IP 位址欄位的 `CIDR_RANGE` 關鍵字。	`principal.ip = CIDR_RANGE "192.0.2.0/24"`
YARA-L 函式	不支援 YARA-L 函式，例如 `net.ip_in_range_cidr` 或 `re.regex`。	使用 `CIDR_RANGE` 代表 IP 子網路，或使用 `/.../` 代表規則運算式。
參考清單和資料表	不支援在排除查詢中查詢參考清單 (`%list_name`) 或資料表。	使用平面 `OR` 比較或 `outcomeFilters` 列舉值。

支援的 UDM 欄位和路徑深度限制

findingsRefinements.query 欄位會強制執行下列 UDM 欄位規則：

欄位路徑最多支援 6 個以點分隔的區段，例如 target.process.file.sha256 (4 個區段) 或 target.resource.attribute.labels["env"] (4 個區段)。
如果欄位路徑包含 7 個以上以點分隔的區隔，則會驗證失敗，並顯示 400 INVALID_ARGUMENT (Not a valid field path) 錯誤。例如，target.process.file.signature_info.sigcheck.signers.name 有 7 個區段，因此遭到拒絕。
葉欄位支援純量 (string、整數、浮點數和 bool)、enum 和 bytes 資料類型。
對應和 Label 欄位支援括號鍵查詢，例如 additional.fields["key"] = "value" 和 target.resource.attribute.labels["project"] = "prod"。
除了完整的 UDM 事件欄位路徑外，系統也支援分組的 UDM 搜尋別名，例如 ip、hostname、user 和 hash。
排除查詢不支援實體圖表路徑 (graph.*) 和未鍵入的 message 欄位。

限制

所有排除條件 (無論是否包含結果篩選器) 都必須指定 query 欄位。如要僅使用 outcomeFilters 欄位建立排除項目，請加入必要的 FindingsRefinement 欄位，並將 query 欄位設為 match-all 規則運算式：
```
{
  "displayName": "Exclusion with only outcome filters",
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = /.*/",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    }
  ]
}
```
規則運算式會比對任何主機名稱。因此，這項查詢會比對所有偵測結果。因此，有效的篩選完全取決於結果篩選器。
排除項目不支援存留時間 (TTL) 設定。不過，您可以計算特定到期時間，並在排除定義中新增時間戳記條件，建立一次性存留時間。舉例來說，如要將排除項目設為在 2026 年 1 月 1 日 00:00 UTC (1767225600) 到期，請指定下列查詢：
```
{
  "displayName": "Exclusion with expiration timestamp",
  "type": "DETECTION_EXCLUSION",
  "query": "metadata.event_timestamp.seconds < 1767225600",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    }
  ]
}
```
視需要加入其他必要的 FindingsRefinement 欄位和結果篩選條件。上述範例確認，只有在 2026 年 1 月 1 日 00:00 UTC (1767225600) 之前，由事件建立的偵測結果才會遭到抑制。

注意：使用者介面的「編輯排除條件」視窗可能無法正確顯示，因為該視窗僅支援 string 欄位。
複合規則：請勿直接對複合規則套用規則排除條件。您必須將排除條件套用至構成複合規則的基礎規則。這是因為規則排除條件是根據 UDM 欄位 (例如 principal.user.userid) 評估，但複合規則是根據其他偵測結果 (而非 UDM 欄位) 觸發。如果直接將規則排除條件套用至複合規則，排除條件將無法比對，且事件不會遭到排除。

如要找出基礎規則，請在 Google SecOps 控制台 (依序前往「內容中心」>「精選偵測規則」) 檢查複合規則定義，並查看 YARA-L 邏輯的 events: 部分，找出基礎規則名稱。
查詢語法和欄位深度：排除查詢必須使用扁平合取範式 (CNF) 布林語法，以及最多 6 個以點分隔區段的 UDM 欄位路徑。詳情請參閱「查詢語法和欄位規則」。

還有其他問題嗎？向社群成員和 Google SecOps 專業人員尋求解答。