API を使用してルールの除外を管理する

以下でサポートされています。

このドキュメントでは、API を使用して Google Security Operations でルール除外をプログラムで管理する方法について説明します。除外は、統合データモデル（UDM）フィールドに基づいて定義するフィルタとして機能し、特定の検出でアラートが生成されないようにします。既知の安全なアクティビティを特定することで、これらのフィルタはダッシュボード内の不要なノイズを排除します。

結果フィルタを使用して除外を作成する

新しい除外ルールをプログラムで作成して、定義した条件に一致する特定の検出結果を抑制し、ノイズを減らして忠実度の高いアラートを優先することができます。

POST エンドポイントを使用して、抑制ロジックを定義します。outcomeFilters 配列を含むすべてのフィルタは、暗黙的な AND 句でリンクされます。

Method: 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

Request body:

  {
  "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」

  • 値が 127.0.0.1 の結果変数 ip

  • 集計値の少なくとも 1 つが altostrat.com である結果変数 hostnames。

除外内で指定されたすべてのフィルタは、AND 句によって暗黙的にリンクされます。

API レスポンス: API は FindingsRefinement リソース名を返します。

FindingsRefinement リソースには、コアの抑制ロジック（クエリと結果のフィルタ）が含まれています。リソース名（ID）は、除外に対する後続のオペレーションで使用されます。

除外にアクセスする

GET エンドポイントを使用すると、次のことができます。

  • 一意の ID で単一の除外定義の詳細を取得します。

  • 特定の refinement-id があり、その中に含まれるクエリまたは結果フィルタを正確に確認する必要がある場合。

Method: 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 のどのフィールドを更新するかを指定できます。

Method: 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

Request body:


  {
  "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 で更新するフィールドを指定することもできます。

除外のデプロイにアクセスする

除外を作成または更新したら、このエンドポイントを使用して、特定の除外がどのルールまたはルールセットにデプロイされているかを確認します。

Method: 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 リソースのリストを取得します。

Method: 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 リソースのリストを取得します。

Method: 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 日間の検出を使用します。

Method: 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

Request body:

 {
  "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）の構成はサポートされていません。ただし、特定の有効期限を計算し、除外定義にタイムスタンプ条件を追加することで、1 回限りの TTL を作成できます。たとえば、除外を年末に期限切れにするには、次のようにクエリを指定します。

    
  ...other fields in FindingsRefinement

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

  outcomeFilters: [your outcome filters]

    この例では、タイムスタンプが年末より前のイベントによって作成された検出結果のみが抑制されることを確認します。

    注: ユーザー インターフェースの [除外を編集] ウィンドウでは、string フィールドのみがサポートされているため、正しく表示されないことがあります。

さらにサポートが必要な場合 コミュニティ メンバーや Google SecOps のプロフェッショナルから回答を得ることができます。