운영 워크플로에 직접 맞게 문서 탐색 구조가 재구성되었습니다. 자세한 내용은 출시 노트 및 둘러보기 동영상을 참고하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

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

다음에서 지원:

Google secops SIEM

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

마이그레이션 프로세스에 대한 간략한 개요는 삽입된 동영상을 시청하세요.

Chronicle API 노출 영역은 개발 프로세스를 간소화하고 안정성, 보안, 성능을 개선하고 Cloud 감사 로그, Cloud Monitoring, Cloud Identity, Identity and Access Management (IAM)와의 통합을 강화하기 위해 Google Cloud API 표준을 준수하도록 설계된 여러 개선사항을 도입합니다. 또한 기존 API의 많은 제한사항과 복잡성을 해결합니다.

변경되는 사항

기존 Backstory API 및 Ingestion API 엔드포인트에 대한 모든 프로그래매틱 요청은 최신 Chronicle API로 전환해야 합니다. 조직에서 이러한 기존 엔드포인트를 호출하는 커스텀 통합, 자동화 스크립트 또는 서드 파티 도구를 사용하는 경우 2027년 7월 20일 전에 최신 엔드포인트 및 인증 흐름을 사용하도록 이러한 워크로드를 업데이트해야 합니다.

변경되지 않는 사항

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

주요 변경사항 및 개선사항

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

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

지원 중단 일정

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

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

시작하기 전에

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

최신 SIEM 인프라에 배포: 인스턴스가 최신 SIEM 인프라를 활용하는 프로젝트에 배포되어 있는지 확인합니다. Google Cloud 자세한 내용은 SIEM 마이그레이션 개요를 참조하세요.
Chronicle API 사용 설정: 콘솔에서 프로젝트로 이동하여 Chronicle API (chronicle.googleapis.com)를 사용 설정합니다. 자세한 내용은 프로젝트에서 API 사용 설정을 참조하세요. Google Cloud Google Cloud

Chronicle API로 마이그레이션

다음 단계를 완료하여 기존 API에서 Chronicle API로 스크립트와 통합을 마이그레이션합니다.

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

API 사용 감사

환경을 감사하여 backstory.googleapis.com 또는 malachiteingestion-pa.googleapis.com을 호출하는 스크립트 또는 통합을 식별합니다. 코드베이스, 자동화 스크립트, 서드 파티 도구를 검토하여 이러한 통합을 식별할 수 있습니다.

인증 및 승인 설정

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

인증 방법 선택: 나열된 방법 중 하나를 사용하여 워크로드가 Chronicle API에 인증하는 방법을 선택합니다. 워크로드 아이덴티티 제휴를 사용하면 장기 실행 서비스 계정 키를 관리하고 저장하지 않아도 되므로 보안을 강화할 수 있습니다. 서비스 계정 가장과 같은 고급 인증 시나리오는 Chronicle API 인증을 참조하세요.
- 워크로드 아이덴티티 제휴 (권장): 외부에서 실행되는 워크로드가 외부 ID를 사용하여 인증하도록 워크로드 아이덴티티 제휴를 설정합니다. Google Cloud
- 서비스 계정: 서비스 계정을 사용해야 하는 경우 프로젝트에서 서비스 계정을 만들고 JSON 형식으로 비공개 키를 생성하고 다운로드합니다. Google Cloud 이 키를 안전하게 보관하세요.
IAM 권한 부여: 인증에 사용되는 ID (서비스 계정 또는 외부 ID 주 구성원)에 필요한 IAM 권한을 부여합니다. 필요한 액세스 수준에 따라 필요한 IAM 역할을 ID에 할당합니다. 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요. 사전 정의된 역할에는 다음이 포함됩니다.
최소 권한의 원칙을 사용하여 커스텀 또는 사전 정의된 IAM 역할을 활용하여 자동화에 필요한 권한만 부여하는 것이 좋습니다.

**참고:** 기존 호출을 대체하는 최신 엔드포인트에 필요한 세분화된 특정 IAM 권한을 확인하려면 SIEM API 엔드포인트 매핑을 참조하세요.
사용자 인증 정보 환경 변수 설정: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 설정하여 애플리케이션 기본 사용자 인증 정보 (ADC)로 사용자 인증 정보를 사용하도록 런타임 환경을 구성합니다. 이 변수는 다운로드한 서비스 계정 키 JSON 파일 또는 워크로드 아이덴티티 제휴 사용자 인증 정보 구성 파일을 가리켜야 합니다. 클라이언트 라이브러리는 이 변수를 자동으로 감지하여 요청을 인증합니다.Google Cloud
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
OAuth 범위 업데이트: 기존 통합 스크립트에서 토큰 생성을 위해 OAuth 범위를 명시적으로 요청한 경우 범위 문자열을 업데이트합니다. 기존 범위는 최신 API 노출 영역에 대한 액세스 권한을 부여하지 않습니다.
- 기존 Backstory 범위: 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 Security Operations 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를 참조하세요.

통합 테스트

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

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

문제 해결

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

HTTP 403 금지됨 또는 PERMISSION_DENIED

API 호출이 HTTP 403 Forbidden 또는 PERMISSION_DENIED 오류를 반환하는 경우 다음을 확인합니다.

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

HTTP 401 승인되지 않음 또는 UNAUTHENTICATED

API 호출이 HTTP 401 Unauthorized 또는 UNAUTHENTICATED로 실패하는 경우 다음을 확인합니다.

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 전문가에게 문의하여 답변을 받으세요.