기존 SIEM API에서 Chronicle API로 마이그레이션

다음에서 지원:

이 문서는 기존 SIEM API (Backstory API 및 Ingestion API)를 호출하는 애플리케이션을 관리하는 데 도움이 됩니다. 프로그래매틱 액세스를 설정하고 기존 SIEM API 엔드포인트에서 최신 Chronicle API 엔드포인트로 참조를 업데이트하기 위해 따라야 하는 단계를 설명합니다.

마이그레이션 프로세스를 간략하게 살펴보려면 삽입된 동영상을 시청하세요.

Chronicle API 서페이스에는 개발 프로세스를 간소화하고 안정성, 보안, 성능을 개선하며 Cloud 감사 로그, Cloud 모니터링, Cloud ID, ID 및 액세스 관리 (IAM)와의 통합을 강화하기 위해 Google Cloud API 표준을 준수하도록 설계된 여러 개선사항이 도입되었습니다. 또한 기존 API의 여러 제한사항과 복잡성을 해결합니다.

변경되는 사항

기존 Backstory API 및 Ingestion API 엔드포인트에 대한 모든 프로그래매틱 요청은 최신 Chronicle API로 전환해야 합니다. 조직에서 이러한 기존 엔드포인트를 호출하는 맞춤 통합, 자동화 스크립트 또는 서드 파티 도구를 사용하는 경우 2027년 7월 20일 전에 최신 엔드포인트 및 인증 흐름을 사용하도록 이러한 워크로드를 업데이트해야 합니다. 또한 조직에서 Google Security Operations SOAR을 사용하는 경우 Chronicle API를 사용하도록 SOAR 통합 및 커넥터 (예: Google Chronicle 통합)를 업데이트해야 합니다. 자세한 내용은 SOAR 통합 마이그레이션을 참고하세요.

변경되지 않는 사항

Google Security Operations 사용자 인터페이스 (UI)에서 직접 수행되는 작업은 이미 최신 Chronicle API를 호출합니다. 조직에서 UI를 통해서만 Google SecOps와 상호작용하거나 통합에서 이미 Chronicle API 엔드포인트를 호출하는 경우 별도의 조치를 취하지 않아도 됩니다.

주요 변경사항 및 개선사항

다음 표에서는 기존 SIEM API와 Chronicle API의 주요 차이점을 보여줍니다.

기능 영역 기존 SIEM API Chronicle API 세부정보
사용자 인증 정보 관리 Google 담당자가 참여하는 수동 프로세스 서비스 계정, 사용자 인증 정보, IAM 권한의 셀프 서비스 관리 셀프 서비스 사용자 인증 정보 및 IAM 관리를 통해 온보딩이 간소화되고 수동 지원 요청에 대한 의존성이 제거됩니다.
규정 준수 표준 제한적 지원 데이터 레지던시 제어, VPC 서비스 제어, 액세스 투명성, CMEK, FedRAMP에 대한 기본 지원 최신 기본 제공 인프라 컨트롤은 업계 규정 준수 및 규제 표준을 충족합니다.
로깅 및 감사 기존 감사 스트림 Google Cloud 프로젝트에 통합된 Cloud 감사 로그 직접 통합은 중앙 집중식 감사 추적 및 모니터링을 제공합니다.
인증 API 토큰 및 서비스 계정 사용자 인증 정보 Google Cloud API 및 서비스 인증에 설명된 대로 워크로드 아이덴티티 및 서비스 계정을 비롯한 최신 인증 방법을 지원하는 OAuth 2.0 이러한 최신 인증 방법은 보안을 강화하고 사용자 인증 정보 흐름을 표준화합니다.
데이터 모델 및 API 설계 플랫한 독점 구조 리소스 중심 설계, RESTful 아키텍처, AIP를 따르는 표준화된 명명 이 최신 디자인은 데이터 일관성을 개선하고 API를 더 직관적으로 만들며 객체 조작을 간소화합니다.
엔드포인트 이름 지정 일관성 없음 RESTful 및 표준화됨 이름을 일관되게 지정하면 API가 더 직관적이고 통합하기 쉬워집니다.
생태계 매우 제한적 MCP, Terraform, 클라이언트 라이브러리, SDK와의 통합 최신 클라우드 도구 및 자동화 프레임워크와의 광범위한 호환성
파트너 승인 고객 코드에서 직접 사용되는 파트너 토큰 또는 API 키 테넌트 리소스의 프로젝트 간 IAM 위임, 파트너 범위 TenantService 메서드 TenantService 메서드는 파트너 프로젝트에서 실행됩니다. 다른 모든 테넌트 API에는 테넌트 프로젝트에서 테넌트가 부여한 교차 프로젝트 IAM 위임이 필요합니다.

파트너 승인

멀티 테넌트 파트너 워크플로의 경우 Chronicle API의 승인은 리소스 소유권에 따라 달라집니다. 리소스를 호스팅하는 프로젝트에 따라 파트너에게 필요한 사용자 인증 정보와 IAM 권한이 결정됩니다. 테넌트 작업을 테넌트 위임 사용자 인증 정보로 범위 지정하는 것은 파트너가 테넌트가 부여한 명시적 권한 없이 테넌트 데이터에 액세스하거나, 테넌트 데이터를 검색하거나, 테넌트 데이터를 수정할 수 없어야 한다는 핵심 보안 원칙과 일치합니다. 다음 표에서는 기존 Backstory API와 Chronicle API의 파트너 승인을 비교합니다.

API 메서드 리소스 범위 승인
기존 Backstory API 엔드포인트 /v1/partner/customer/*개 파트너의 모든 고객 코드 파트너는 자체 파트너 토큰 또는 API 키를 사용하여 이러한 엔드포인트를 직접 호출합니다.
Chronicle API: TenantService CreateTenant, ListTenants, UpdateTenant 파트너의 인스턴스: projects/{partner_project}/locations/{location}/instances/{partner_instance}/tenants/* 파트너는 파트너 프로젝트에서 chronicle.googleapis.com/tenants.* 권한이 있는 자체 서비스 계정 또는 사용자 인증 정보로 이러한 메서드를 직접 호출합니다.
Chronicle API: InstanceService, ForwarderService과 같은 기타 서비스 GetInstance, UpdateInstance, GenerateForwarderFiles 및 기타 테넌트 범위 메서드 테넌트의 인스턴스: projects/{tenant_project}/locations/{location}/instances/{tenant_instance}/... 파트너 사용자 인증 정보만으로는 테넌트 데이터에 액세스하거나 수정할 수 없습니다. 테넌트 관리자는 테넌트의 Google Cloud 프로젝트에서 파트너의 서비스 계정 또는 워크로드 아이덴티티 제휴 주 구성원에게 roles/chronicle.admin, roles/chronicle.viewer 또는 커스텀 역할과 같은 IAM 역할을 부여해야 합니다.

지원 중단 일정

기존 SIEM API는 2027년 7월 20일에 종료될 예정입니다. 서비스 중단을 방지하려면 다음 날짜 전에 마이그레이션을 완료하는 것이 좋습니다.

  • 2026년 10월 26일부터 새 인스턴스에서 기존 API (Backstory API 및 Ingestion API)를 호출할 수 없습니다.
  • 기존 API를 더 이상 사용할 수 없으므로 2027년 7월 20일까지 모든 기존 인스턴스를 Chronicle API로 마이그레이션해야 합니다.

시작하기 전에

Chronicle API로 이전하기 전에 다음을 완료해야 합니다.

  • 최신 SIEM 인프라에 배포: 최신 SIEM 인프라를 사용하여 인스턴스가 사용자 또는 MSSP 파트너의 Google Cloud 프로젝트에 배포되어 있는지 확인합니다. 자세한 내용은 SIEM 이전 개요를 참고하세요.
  • Chronicle API 사용 설정: Google Cloud 콘솔에서 인스턴스를 호스팅하는 프로젝트로 이동하여 Chronicle API (chronicle.googleapis.com)를 사용 설정합니다. 자세한 내용은 Google Cloud 프로젝트에서 API 사용 설정을 참고하세요.
  • SOAR 통합 식별: 환경에서 Google SecOps SOAR를 Google Security Operations SIEM에 연결하는 경우 기존 커넥터를 확인합니다. 자세한 내용은 SOAR 통합 마이그레이션을 참고하세요.

SOAR 통합 마이그레이션

조직에서 Google SecOps SOAR를 Google SecOps SIEM에 연결하는 경우 Chronicle API를 사용하도록 SOAR 통합 및 커넥터 (예: Google Chronicle 통합)를 이전해야 합니다.

Google Chronicle 통합 및 커넥터를 업그레이드하여 Chronicle API를 사용하는 방법에 관한 자세한 안내(환경의 Chronicle API 루트 찾기 및 인증 사용자 인증 정보 구성 포함)는 Backstory API에서 Chronicle API로 이전을 참고하세요.

Chronicle API로 마이그레이션

다음 단계를 완료하여 기존 API에서 Chronicle API로 커스텀 스크립트와 통합을 이전합니다.

  1. API 사용 감사: 환경에서 기존 엔드포인트를 호출하는 모든 커스텀 스크립트와 통합을 파악합니다.
  2. 인증 및 승인 설정: Chronicle API에 대한 요청을 인증하고 승인하도록 환경을 구성합니다.
  3. 엔드포인트 매핑 및 URL 업데이트: 기존 엔드포인트를 최신 리전 엔드포인트로 대체합니다.
  4. API 로직 업데이트: 최신 API의 데이터 모델과 일치하도록 요청 페이로드와 응답 처리를 조정합니다.
  5. 통합 테스트: 프로덕션에 배포하기 전에 스테이징 환경에서 변경사항을 검증합니다.

감사 API 사용량

환경을 감사하여 backstory.googleapis.com 또는 malachiteingestion-pa.googleapis.com를 호출하는 맞춤 스크립트 또는 통합을 식별합니다. 코드베이스, 자동화 스크립트, 서드 파티 도구를 검토하여 이러한 통합을 식별할 수 있습니다. 조직에서 Google SecOps SOAR도 사용하는 경우 SOAR 통합 마이그레이션을 참고하세요.

인증 및 승인 설정

Chronicle API에 대한 요청을 인증하고 승인하도록 환경을 구성합니다.

  1. 인증 방법 선택: 나열된 방법 중 하나를 사용하여 워크로드가 Chronicle API에 인증하는 방법을 선택합니다. 장기 서비스 계정 키를 관리하고 저장하지 않으므로 보안을 강화하려면 워크로드 아이덴티티 제휴를 사용하는 것이 좋습니다. 고급 인증 시나리오 (예: 서비스 계정 가장)의 경우 Chronicle API 인증을 참고하세요.
  2. IAM 권한 부여: 인증에 사용되는 ID (서비스 계정 또는 외부 ID 보안 주체)에 필요한 IAM 권한을 부여합니다. SIEM API 엔드포인트 매핑에서 기존 호출을 대체하는 최신 엔드포인트에 필요한 특정 IAM 권한을 확인하세요.
    • 커스텀 역할 (권장): 필요한 권한으로 커스텀 IAM 역할을 만들고 서비스 계정 또는 외부 ID 주 구성원에 커스텀 역할을 부여합니다.
    • 사전 정의된 역할: 서비스 계정 또는 외부 ID 주 구성원에 Google SecOps 사전 정의된 역할을 부여합니다. 이렇게 하면 특정 자동화에 필요한 것보다 더 많은 액세스 권한이 부여될 수 있습니다.
    • 멀티 테넌트 파트너 위임: TenantService GetInstance UpdateInstance GenerateForwarderFiles 외부에서 테넌트 리소스를 관리하는 MSSP 또는 파트너인 경우 테넌트 관리자가 테넌트의 Google Cloud 프로젝트에서 서비스 계정 또는 워크로드 아이덴티티 페더레이션 주 구성원에 필요한 IAM 역할을 명시적으로 부여해야 합니다.

  3. 사용자 인증 정보 환경 변수 설정: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하여 애플리케이션 기본 사용자 인증 정보 (ADC)와 함께 사용자 인증 정보를 사용하도록 런타임 환경을 구성합니다. 이 변수는 다운로드한 서비스 계정 키 JSON 파일 또는 워크로드 아이덴티티 제휴 사용자 인증 정보 구성 파일을 가리켜야 합니다. Google Cloud 클라이언트 라이브러리는 요청을 인증하기 위해 이 변수를 자동으로 감지합니다.

    export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"

  4. OAuth 범위 업데이트: 기존 통합 스크립트에서 토큰 생성을 위해 OAuth 범위를 명시적으로 요청한 경우 범위 문자열을 업데이트합니다. 기존 범위는 최신 API 표시 경로에 대한 액세스 권한을 부여하지 않습니다.

    • 기존 배경 스토리 범위: https://www.googleapis.com/auth/chronicle-backstory
    • Chronicle 범위: https://www.googleapis.com/auth/chronicle (또는 더 넓은 https://www.googleapis.com/auth/cloud-platform 범위)

엔드포인트 매핑 및 URL 업데이트

Chronicle API 노출 영역을 숙지하고, 기존 호출을 매핑하고, 애플리케이션에서 서비스 엔드포인트를 업데이트합니다.

참고 문서 검토

Chronicle API에 관한 포괄적인 문서를 숙지하세요.

엔드포인트를 Chronicle API에 매핑

애플리케이션에서 실행하는 각 기존 API 호출에 해당하는 최신 엔드포인트를 식별합니다. 마찬가지로 스키마 변경사항이나 추가 필드를 고려하여 기존 데이터 모델을 최신 구조에 매핑합니다. 모든 SIEM 엔드포인트에 대한 자세한 내용은 SIEM API 엔드포인트 매핑을 참고하세요. 워크플로가 SOAR 엔드포인트와도 상호작용하는 경우 SOAR API 엔드포인트 매핑 표를 참고하세요.

서비스 엔드포인트 업데이트

API 호출의 기준 URL을 업데이트하여 올바른 리전별 서비스 엔드포인트를 가리키도록 합니다. Chronicle API는 리전 서비스이므로 Google SecOps 인스턴스의 위치와 일치하는 리전 서비스 엔드포인트를 호출해야 합니다.

모든 최신 엔드포인트는 일관된 접두사를 사용하므로 최종 엔드포인트 주소를 예측할 수 있습니다. 다음 예시에서는 최신 엔드포인트 URL 구조를 보여줍니다.

[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

이 구조는 엔드포인트의 최종 주소를 다음과 같이 만듭니다.

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

각 항목의 의미는 다음과 같습니다.

  • service_endpoint: 지역 서비스 주소입니다.
  • api_version: 쿼리할 API 버전입니다. v1alpha, v1beta 또는 v1일 수 있습니다.
  • project_id: 프로젝트 ID입니다 (IAM 권한에 정의한 프로젝트와 동일).
  • location: 프로젝트의 위치 (리전)입니다. 리전 엔드포인트와 동일합니다.
  • instance_id: Google SecOps SIEM 고객 ID입니다.

지역 주소:

  • africa-south1: https://africa-south1-chronicle.googleapis.com 또는 https://chronicle.africa-south1.rep.googleapis.com
  • asia-northeast1: https://asia-northeast1-chronicle.googleapis.com 또는 https://chronicle.asia-northeast1.rep.googleapis.com
  • asia-south1: https://asia-south1-chronicle.googleapis.com 또는 https://chronicle.asia-south1.rep.googleapis.com
  • asia-southeast1: https://asia-southeast1-chronicle.googleapis.com 또는 https://chronicle.asia-southeast1.rep.googleapis.com
  • asia-southeast2: https://asia-southeast2-chronicle.googleapis.com 또는 https://chronicle.asia-southeast2.rep.googleapis.com
  • australia-southeast1: https://australia-southeast1-chronicle.googleapis.com 또는 https://chronicle.australia-southeast1.rep.googleapis.com
  • europe-west12: https://europe-west12-chronicle.googleapis.com 또는 https://chronicle.europe-west12.rep.googleapis.com
  • europe-west2: https://europe-west2-chronicle.googleapis.com 또는 https://chronicle.europe-west2.rep.googleapis.com
  • europe-west3: https://europe-west3-chronicle.googleapis.com 또는 https://chronicle.europe-west3.rep.googleapis.com
  • europe-west6: https://europe-west6-chronicle.googleapis.com 또는 https://chronicle.europe-west6.rep.googleapis.com
  • europe-west9: https://europe-west9-chronicle.googleapis.com 또는 https://chronicle.europe-west9.rep.googleapis.com
  • me-central1: https://me-central1-chronicle.googleapis.com 또는 https://chronicle.me-central1.rep.googleapis.com
  • me-central2: https://me-central2-chronicle.googleapis.com 또는 https://chronicle.me-central2.rep.googleapis.com
  • me-west1: https://me-west1-chronicle.googleapis.com 또는 https://chronicle.me-west1.rep.googleapis.com
  • northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com 또는 https://chronicle.northamerica-northeast2.rep.googleapis.com
  • southamerica-east1: https://southamerica-east1-chronicle.googleapis.com 또는 https://chronicle.southamerica-east1.rep.googleapis.com
  • 미국 (us): https://us-chronicle.googleapis.com 또는 https://chronicle.us.rep.googleapis.com
  • 유럽 (eu): https://eu-chronicle.googleapis.com 또는 https://chronicle.eu.rep.googleapis.com

지원되는 모든 엔드포인트의 전체 목록은 Chronicle API 서비스 엔드포인트 문서의 공식 참조를 확인하세요.

예를 들어 us 위치에 있는 인스턴스의 모든 감지 규칙을 나열하려면 다음 요청을 전송합니다.

GET
  https://us-chronicle.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/rules

마찬가지로 리전 엔드포인트 (rep) 별칭을 사용하여 케이스와 같은 SOAR 리소스를 쿼리하려면 다음 요청을 전송합니다.

GET
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

API 로직 업데이트

Chronicle API REST 참조를 검토하여 애플리케이션의 필드 이름과 데이터 구조를 변경할 부분을 파악하고 변경사항을 구현합니다. 일부 기존 엔드포인트는 유사하게 유지될 수 있지만 최신 데이터 모델 및 엔드포인트 구조와 일치하도록 통합을 업데이트해야 합니다.

Google Cloud 클라이언트 라이브러리 사용

인증, 토큰 새로고침, 전송 세부정보를 자동으로 처리하도록 통합을 간소화하세요. 공식 Google Cloud 클라이언트 라이브러리를 사용하는 것이 좋습니다. Chronicle API 지원은 Python, Go, Java, Node.js, C#을 비롯한 8개 프로그래밍 언어로 제공됩니다. 설치 및 사용에 대한 자세한 내용은 클라이언트 라이브러리 및 SDK를 참고하세요.

통합 테스트

프로덕션에 배포하기 전에 스테이징 환경에서 업데이트된 애플리케이션을 테스트합니다.

  1. 테스트 계획 만들기: 마이그레이션된 모든 기능을 포함하는 테스트 사례를 정의합니다.
  2. 테스트 실행: 자동 및 수동 테스트를 실행하여 정확성과 유효성을 확인합니다.
  3. 성능 모니터링: 최신 API로 애플리케이션의 성능을 평가합니다.

문제 해결

이 섹션에서는 마이그레이션 중에 발생할 수 있는 일반적인 오류를 해결하는 방법을 설명합니다.

HTTP 403 금지됨 또는 PERMISSION_DENIED

API 호출에서 HTTP 403 Forbidden 또는 PERMISSION_DENIED 오류가 반환되면 다음을 확인하세요.

  • 인증 방법 및 주 구성원: 올바른 사용자 인증 정보를 사용하고 있는지 확인합니다.
    • 워크로드 아이덴티티 제휴를 사용하는 경우 외부 ID 주 구성원이 프로젝트의 IAM 역할에 바인딩된 주 구성원과 일치하는지 확인합니다.
    • 서비스 계정을 사용하는 경우 올바른 서비스 계정이 사용되고 있으며 사용 중지되지 않았는지 확인합니다. 최신 Chronicle API 엔드포인트에는 레거시 서비스 계정 (이메일 주소에 bk 또는 malachite-cx가 포함된 경우가 많음)을 사용하지 마세요.
  • IAM 역할: 서비스 계정 또는 외부 ID 주 구성원에 Google Cloud 프로젝트에서 필요한 사전 정의된 IAM 역할 또는 맞춤 IAM 역할 (예: Chronicle API Viewer 또는 Chronicle API Editor)이 부여되었는지 확인합니다. 세부적인 엔드포인트 권한은 SIEM API 엔드포인트 매핑을 참고하세요.

HTTP 401 승인되지 않음 또는 인증되지 않음

HTTP 401 Unauthorized 또는 UNAUTHENTICATED 오류로 API 호출이 실패하면 다음을 확인하세요.

  • OAuth 범위: 맞춤 스크립트가 최신 범위인 https://www.googleapis.com/auth/chronicle (또는 더 광범위한 https://www.googleapis.com/auth/cloud-platform 범위)를 요청하는지 확인합니다. 기존 범위 (https://www.googleapis.com/auth/chronicle-backstory)는 최신 Chronicle API에 대한 액세스 권한을 부여하지 않습니다.
  • 환경 변수: 런타임 환경에서 GOOGLE_APPLICATION_CREDENTIALS 환경 변수가 설정되어 있고 올바른 JSON 키 파일 또는 워크로드 아이덴티티 제휴 구성 파일을 가리키는지 확인합니다.

HTTP 404 찾을 수 없음 또는 지역 불일치

API 호출이 HTTP 404 Not Found을 반환하거나 연결에 실패하면 지역 엔드포인트를 확인하세요.

  • 리전 엔드포인트: Chronicle API는 리전 서비스입니다. Google SecOps 인스턴스의 리전과 일치하는 엔드포인트를 호출하고 있는지 확인합니다 (예: 프랑크푸르트의 인스턴스인 경우 https://europe-west3-chronicle.googleapis.com). 다른 리전으로 요청을 보내면 오류가 발생합니다. 리전 주소의 전체 목록은 서비스 엔드포인트 업데이트 또는 공식 서비스 엔드포인트 참조를 참고하세요.

다음 단계

도움이 더 필요하신가요? 커뮤니티 회원 및 Google SecOps 전문가에게 문의하여 답변을 받으세요.