API를 사용하여 규칙 제외 관리

다음에서 지원:

이 문서에서는 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'을 주 호스트 이름으로 사용

  • 값이 127.0.0.1인 결과 변수 ip

  • 집계된 값 중 하나 이상이 altostrat.com인 결과 변수 hostnames

제외 내에 지정된 모든 필터는 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: Findings Refinement의 고유 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: Findings Refinement의 고유 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 전문가에게 문의하여 답변을 받으세요.