管理規則排除條件

支援：

本文說明如何使用 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) 設定。不過，您可以計算特定到期時間，並在排除條件定義中新增時間戳記條件，藉此建立一次性存留時間。舉例來說，如要將排除條件設為在年底到期，請指定下列查詢：

    
  ...other fields in FindingsRefinement

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

  outcomeFilters: [your outcome filters]

    這個範例確認系統只會抑制在年底前建立的偵測結果。

    注意：使用者介面的「編輯排除條件」視窗可能無法正確顯示，因為該視窗僅支援 string 欄位。

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

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

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