使用 API 管理規則排除項目

支援的國家/地區：

Google SecOps SIEM

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

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

您可以透過程式輔助建立新的排除規則，根據定義的條件抑制特定偵測結果，藉此減少干擾並優先處理高準確度的快訊。

使用 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.01",
      "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": [
      ...list curated rule set resource names
    ],
    "curatedRules": [
      ...list curated rule resource names
    ],
    "rules": [
      ...list rule resource names
    ],
  }
}

將排除條件套用至規則或規則組合時，系統會建立 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 測試排除條件

這個端點會根據指定規則和規則集的偵測結果測試排除條件，然後驗證排除條件在抑制不必要的偵測結果方面的效用。UI 會使用過去 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.01",
      "outcome_filter_operator": "EQUAL",
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS",
    },
  ]
  "interval": {
    "start_time": {
      "seconds": 1756684800, // Sep. 1 2025 00:00 UTC
    },
    "end_time": {
      "seconds": 1759276800, // Oct. 1 2025 00:00 UTC
    },
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      ...curated rule set resource names
    ],
    "curatedRules": [
      ...curated rule resource names
    ],
    "rules": [
      ...rule resource names
    ],
  }
}

這個端點會針對要求中指定的規則和規則集所產生的偵測項目，測試排除條件。這有助於判斷排除項目在抑制不應產生的偵測結果方面有多有效。系統會使用過去 30 天的偵測結果做為時間範圍，測試排除條件。

限制

所有排除條件 (無論是否包含結果篩選條件) 都必須指定 query 欄位。如要只使用 outcomeFilters 建立排除條件，請指定 match-all 規則運算式。
```
  ...other fields in FindingsRefinement

  query: "principal.hostname = /.*/"

  outcomeFilters: [ your outcome filters ]
```
規則運算式會比對任何主機名稱。因此，這項查詢會比對所有偵測結果。因此，有效篩選條件完全取決於結果篩選條件。
排除條件不支援存留時間 (TTL) 設定。不過，您可以計算特定到期時間，並在排除定義中新增時間戳記條件，藉此建立一次性 TTL。舉例來說，如要將排除條件設為在年底到期，請指定下列查詢：
```
  ...other fields in FindingsRefinement

  query: "metadata.event_timestamp.seconds < 1767225600" // Jan 1 2026 00:00 UTC

  outcomeFilters: [your outcome filters]
```
這個範例確認系統只會抑制在年底前建立的偵測結果。

注意：由於使用者介面僅支援 string 欄位，因此這項資訊可能無法在「編輯排除條件」視窗中正確顯示。

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