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

GitGuardian Enterprise 로그 수집

파서 버전: 1.0

다음에서 지원:

Google SecOps SIEM

이 문서에서는 웹훅을 사용하여 로그를 Google Security Operations로 푸시하도록 GitGuardian Enterprise를 구성하는 방법을 설명합니다.

GitGuardian Enterprise는 소스 코드 저장소, CI/CD 파이프라인, 개발자 워크스테이션에서 노출된 사용자 인증 정보와 민감한 정보를 모니터링하는 비밀 감지 및 해결 플랫폼입니다. 보안 비밀이 감지되면 실시간 알림을 제공하고 보안팀이 사고 해결 워크플로를 관리하도록 지원합니다.

시작하기 전에

다음 기본 요건이 충족되었는지 확인합니다.

Google SecOps 인스턴스
관리자 액세스 수준이 있는 GitGuardian Enterprise 워크스페이스
Google Cloud 콘솔 액세스 (API 키 생성용)
GitGuardian 비즈니스 요금제 이상 (맞춤 웹훅 지원)

Google SecOps에서 웹훅 피드 만들기

피드 만들기

SIEM 설정 > 피드로 이동합니다.
새 피드 추가를 클릭합니다.
다음 페이지에서 단일 피드 구성을 클릭합니다.
피드 이름 필드에 피드 이름을 입력합니다(예: GitGuardian Enterprise Incidents).
소스 유형으로 웹훅을 선택합니다.
로그 유형으로 GitGuardian Enterprise를 선택합니다.
다음을 클릭합니다.
다음 입력 매개변수의 값을 지정합니다.
- 분할 구분 기호 (선택사항): 비워 둡니다 (각 웹훅 요청에는 단일 이벤트가 포함됨).
- 애셋 네임스페이스: 애셋 네임스페이스
- 수집 라벨: 이 피드의 이벤트에 적용할 라벨입니다.
다음을 클릭합니다.
확정 화면에서 새 피드 구성을 검토한 다음 제출을 클릭합니다.

보안 비밀 키 생성 및 저장

피드를 만든 후 인증을 위한 보안 비밀 키를 생성해야 합니다.

피드 세부정보 페이지에서 보안 비밀 키 생성을 클릭합니다.
대화상자에 보안 비밀 키가 표시됩니다.
보안 비밀 키를 안전하게 복사하여 저장합니다.

중요: 비밀 키는 한 번만 표시되며 나중에 검색할 수 없습니다. 분실할 경우 새 보안 키를 생성해야 합니다.

피드 엔드포인트 URL 가져오기

피드의 세부정보 탭으로 이동합니다.
엔드포인트 정보 섹션에서 피드 엔드포인트 URL을 복사합니다.

URL 형식은 다음과 같습니다.

https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

또는

https://<REGION>-malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate

다음 단계를 위해 이 URL을 저장합니다.
완료를 클릭합니다.

Google Cloud API 키 만들기

Google SecOps에는 인증을 위한 API 키가 필요합니다. Google Cloud 콘솔에서 제한된 API 키를 만듭니다.

API 키 만들기

Google Cloud 콘솔 사용자 인증 정보 페이지로 이동합니다.
프로젝트 (Google SecOps 인스턴스와 연결된 프로젝트)를 선택합니다.
사용자 인증 정보 만들기 API 키를 클릭합니다.
API 키가 생성되어 대화상자에 표시됩니다.
API 키 수정을 클릭하여 키를 제한합니다.

API 키 제한

API 키 설정 페이지에서 다음을 수행합니다.
- 이름: 설명이 포함된 이름 (예: Google SecOps GitGuardian Webhook API Key)을 입력합니다.
API 제한사항에서 다음을 실행합니다.
1. 키 제한을 선택합니다.
2. API 선택 드롭다운에서 Google SecOps API (또는 Chronicle API)를 검색하여 선택합니다.
저장을 클릭합니다.
페이지 상단의 API 키 필드에서 API 키 값을 복사합니다.
API 키를 안전하게 저장합니다.

참고: API 키를 제한하면 Chronicle API에서만 사용할 수 있으므로 키가 손상된 경우 보안 위험이 줄어듭니다.

GitGuardian Enterprise 웹훅 구성

웹훅 URL 구성

Google SecOps 엔드포인트 URL과 API 키를 결합합니다.

<ENDPOINT_URL>?key=<API_KEY>

예:

https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=AIzaSyD...

GitGuardian에서 맞춤 웹훅 만들기

개인 작업공간:

GitGuardian 대시보드에 로그인합니다.
설정 > 작업공간 > 통합 > 대상 > 맞춤 웹훅으로 이동합니다.
맞춤 웹훅 추가 또는 새 맞춤 웹훅 만들기를 클릭합니다.
다음 구성 세부정보를 제공합니다.
- 이름: 설명이 포함된 이름을 입력합니다 (예: Google SecOps SIEM Integration).
- URL: 위의 API 키가 포함된 전체 엔드포인트 URL을 붙여넣습니다.
- 서명 토큰: Google SecOps 피드 생성에서 보안 비밀 키를 붙여넣습니다.
- 맞춤 헤더 (선택사항): 환경 또는 서비스 태그를 지정해야 하는 경우가 아니면 비워 둡니다.
이벤트 구독 섹션에서 Google SecOps로 전송할 이벤트를 선택합니다.
- 사고:
  - ☑ 새 사고 감지됨
  - ☑ 새로운 발생 감지됨
  - ☑ 사고 해결됨
  - ☑ 사고 무시됨
  - ☑ 사고가 다시 열림
  - 사고 회귀
  - ☑ 사고 할당됨
  - ☑ 사고 재할당됨
  - ☑ 사고가 할당되지 않음
  - ☑ 인시던트 심각도 변경됨
  - ☑ Incident Validity changed
  - ☑ 사고 액세스 권한 부여됨
  - ☑ 사고 액세스 권한 취소됨
  - ☑ 사고가 공개적으로 공유됨
  - ☑ 사고가 공개적으로 공유되지 않음
  - ☑ 의견 제출됨
  - ☑ 인시던트에 대한 새 댓글
만들기 또는 저장을 클릭합니다.
GitGuardian은 웹훅이 작동하는지 확인하기 위해 테스트 메시지를 전송합니다.

비즈니스 작업공간:

GitGuardian 대시보드에 로그인합니다.
웹훅의 범위를 결정합니다.
- 워크스페이스의 모든 인시던트: All-incidents team으로 이동합니다.
- 특정 팀 인시던트: 원하는 팀으로 이동합니다.
설정 > 작업공간 > 통합 > 대상 > 맞춤 웹훅으로 이동합니다.
- 또는 팀 페이지에서 통합 > 맞춤 웹훅으로 이동합니다.
맞춤 웹훅 추가 또는 새 맞춤 웹훅 만들기를 클릭합니다.
다음 구성 세부정보를 제공합니다.
- 이름: 설명이 포함된 이름을 입력합니다 (예: Google SecOps SIEM Integration).
- URL: 위의 API 키가 포함된 전체 엔드포인트 URL을 붙여넣습니다.
- 서명 토큰: Google SecOps 피드 생성에서 보안 비밀 키를 붙여넣습니다.
- 맞춤 헤더 (선택사항): 환경 또는 서비스 태그를 지정해야 하는 경우가 아니면 비워 둡니다.
이벤트 구독 섹션에서 Google SecOps로 전송할 이벤트를 선택합니다.
- 사고:
  - ☑ 새 사고 감지됨
  - ☑ 새로운 발생 감지됨
  - ☑ 사고 해결됨
  - ☑ 사고 무시됨
  - ☑ 사고가 다시 열림
  - 사고 회귀
  - ☑ 사고 할당됨
  - ☑ 사고 재할당됨
  - ☑ 사고가 할당되지 않음
  - ☑ 인시던트 심각도 변경됨
  - ☑ Incident Validity changed
  - ☑ 사고 액세스 권한 부여됨
  - ☑ 사고 액세스 권한 취소됨
  - ☑ 사고가 공개적으로 공유됨
  - ☑ 사고가 공개적으로 공유되지 않음
  - ☑ 의견 제출됨
  - ☑ 인시던트에 대한 새 댓글
만들기 또는 저장을 클릭합니다.
GitGuardian은 웹훅이 작동하는지 확인하기 위해 테스트 메시지를 전송합니다.

웹훅 전송 확인

GitGuardian 대시보드에서 맞춤 웹훅 구성으로 이동합니다.
테스트 메시지 보내기 또는 웹훅 테스트를 클릭합니다.
GitGuardian이 샘플 페이로드를 Google SecOps에 전송합니다.
Google SecOps 콘솔에서 SIEM 설정 > 피드로 이동합니다.
GitGuardian 피드를 찾아 테스트 이벤트가 수신되었는지 확인합니다.
피드 상태가 최근 처리 타임스탬프와 함께 활성으로 표시되는지 확인합니다.

참고: 테스트 메시지에는 검열된 보안 비밀 값이 포함된 샘플 데이터가 포함되어 있습니다. 프로덕션 웹훅에는 실제 인시던트 데이터가 포함됩니다.

인증 방법 참조

Google SecOps 웹훅 피드는 여러 인증 방법을 지원합니다. 공급업체에서 지원하는 방법을 선택합니다.

방법 1: 쿼리 매개변수 (GitGuardian에 권장)

GitGuardian 맞춤 웹훅은 URL에 추가된 사용자 인증 정보와 함께 가장 잘 작동합니다.

URL 형식:
```
<ENDPOINT_URL>?key=<API_KEY>
```
예:
```
https://malachiteingestion-pa.googleapis.com/v2/unstructuredlogentries:batchCreate?key=AIzaSyD...
```
GitGuardian 웹훅 구성:
- URL: API 키 매개변수가 포함된 전체 엔드포인트 URL
- 서명 토큰: Google SecOps 보안 키 (HMAC 확인용)

요청 형식:

POST <ENDPOINT_URL>?key=<API_KEY> HTTP/1.1
Content-Type: application/json
Timestamp: 1234567890
Gitguardian-Signature: sha256=abc123...

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00Z",
    "action": "incident_triggered",
    "incident": {...}
}

방법 2: 맞춤 헤더 (대안)

사용자 인증 정보를 URL에서 제외하려면 맞춤 헤더를 사용하세요.

요청 형식:

POST <ENDPOINT_URL> HTTP/1.1
Content-Type: application/json
x-goog-chronicle-auth: <API_KEY>
Timestamp: 1234567890
Gitguardian-Signature: sha256=abc123...

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00Z",
    "action": "incident_triggered",
    "incident": {...}
}

GitGuardian 웹훅 서명 확인

GitGuardian은 신뢰성을 보장하고 조작을 방지하기 위해 HMAC-SHA256을 사용하여 모든 웹훅 페이로드에 서명합니다.

서명 헤더

GitGuardian은 웹훅 요청에 다음 헤더를 포함합니다.

Gitguardian-Signature: sha256=<hex_digest> 형식의 HMAC-SHA256 서명
타임스탬프: 요청이 전송된 시점의 Unix 타임스탬프
X-GitGuardian-Signature: 지원 중단된 헤더 (이전 버전과의 호환성을 위해 계속 지원됨)

서명 알고리즘

서명은 다음과 같이 계산됩니다.
```
HMAC-SHA256(key=timestamp + signature_token, message=payload)
```
각 항목의 의미는 다음과 같습니다.
- timestamp: Timestamp 헤더의 값
- signature_token: GitGuardian 웹훅 설정에 구성된 보안 키
- payload: 원시 JSON 요청 본문(UTF-8 문자열)

확인 예시 (Python)

import hmac
import hashlib

def verify_signature(signature: str, timestamp: str, signature_token: str, payload: str) -> bool:
    if not signature.startswith("sha256="):
        return False

    signature = signature.split("sha256=")[-1]

    hmac_digest = hmac.new(
        key=bytes(timestamp + signature_token, "utf-8"),
        msg=bytes(payload, "utf-8"),
        digestmod=hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, hmac_digest)

재전송 공격 보호

Timestamp 헤더는 재전송 공격을 방지합니다. 현재 타임스탬프가 웹훅 타임스탬프와 몇 초 이상 (권장: 300초) 차이가 나면 요청을 거부합니다.

참고: Google SecOps는 웹훅 인증을 자동으로 처리합니다. Google SecOps 웹훅 피드를 사용하는 경우 서명 확인을 구현할 필요가 없습니다.

이벤트 유형 및 페이로드 구조

GitGuardian은 인시던트 수명 주기 변경에 따라 다양한 이벤트 유형을 전송합니다.

사고 이벤트

이벤트 유형	액션 가치	설명
새 사고 감지됨	`incident_triggered`	새로운 보안 비밀 사고가 감지되었습니다.
새로운 발생 감지됨	`new_occurrence`	기존 사고의 새로운 발생이 발견됨
사고 해결됨	`incident_resolved`	사고가 해결된 것으로 표시됨
사고 무시됨	`incident_ignored`	사고가 무시됨으로 표시되었습니다.
사고가 다시 열림	`incident_reopened`	이전에 종료된 인시던트가 다시 열림
사고 회귀	`incident_regression`	이 사고에 대한 새로운 회귀가 발견됨
사고 할당됨	`incident_assigned`	인시던트가 사용자에게 할당됨
사고 재할당됨	`incident_reassigned`	사고가 다른 사용자에게 재할당되었습니다.
사고 할당 해제됨	`incident_unassigned`	사용자가 이 인시던트에서 할당 해제됨
심각도 변경됨	`incident_severity_changed`	심각도 수준이 업데이트되었습니다.
유효성 변경됨	`incident_validity_changed`	유효성 상태가 업데이트됨
액세스 권한 부여됨	`incident_access_granted`	사용자에게 이 이슈에 대한 액세스 권한이 부여되었습니다.
액세스 권한이 취소됨	`incident_access_revoked`	사용자의 이 인시던트 액세스 권한이 취소됨
공개적으로 공유됨	`incident_shared_publicly`	공개 공유 링크가 생성됨
공개적으로 공유되지 않음	`incident_unshared_publicly`	공개 공유 링크가 비활성화되었습니다.
의견 제출됨	`issue_feedback_received`	이 사고에 대한 의견이 제출되었습니다.
새 댓글	`incident_note_created`	이 인시던트에 대한 새 메모가 생성되었습니다.

샘플 페이로드 구조

모든 웹훅 페이로드는 다음 구조를 따릅니다.

{
    "source": "GitGuardian",
    "timestamp": "2025-01-15T10:30:00.123456Z",
    "action": "incident_triggered",
    "message": "A new incident has been detected.",
    "target_user": "john.doe@example.com",
    "target_team": "Security Team",
    "custom_webhook_name": "Google SecOps SIEM Integration",
    "incident": {
        "id": 12345,
        "date": "2025-01-15T10:29:58.123456Z",
        "detector": {
            "name": "aws_iam",
            "display_name": "AWS Keys",
            "nature": "specific",
            "family": "credentials"
        },
        "secret_hash": "abc123...",
        "secret_revoked": false,
        "validity": "valid",
        "occurrence_count": 1,
        "status": "triggered",
        "assignee_email": null,
        "severity": "high",
        "gitguardian_url": "https://dashboard.gitguardian.com/workspace/1/incidents/12345"
    }
}

웹훅 한도 및 권장사항

요청 한도

한도	값
최대 요청 크기	4MB
최대 QPS (초당 쿼리 수)	15,000
요청 제한 시간	30초
재시도 동작	지수 백오프를 사용한 자동 재시도

권장사항

이벤트 선택: 보안 운영과 관련된 이벤트만 구독하여 노이즈를 줄입니다.
팀 범위 지정: 비즈니스 워크스페이스의 경우 팀 수준에서 웹훅을 만들어 팀 소유권별로 인시던트를 필터링합니다.
서명 확인: 서명 토큰을 안전하게 저장하고 소스 코드에 커밋하지 않습니다.
모니터링: GitGuardian 대시보드에서 웹훅 전송 상태를 정기적으로 확인합니다.
테스트: 프로덕션에서 사용하기 전에 테스트 메시지 기능을 사용하여 웹훅 구성을 확인합니다.

전송 보장

중요: 웹훅 전송은 최선의 노력을 다하는 기준(best effort basis)으로 수행되며 보장되지 않습니다. Google SecOps 엔드포인트에 연결할 수 없거나 네트워크 문제가 있는 경우 웹훅 이벤트를 수신하지 못할 수 있습니다. 웹훅은 일반적으로 안정적이지만 전송이 보장되지는 않습니다.

중요한 사용 사례의 경우 사고가 누락되지 않도록 주기적인 API 폴링으로 웹훅을 보완하는 것이 좋습니다.

UDM 매핑 테이블

로그 필드	UDM 매핑	로직
날짜	metadata.event_timestamp	ISO8601 형식을 사용하여 변환됨
has_user	metadata.event_type	has_user가 true이면 'USER_UNCATEGORIZED', 그렇지 않으면 'GENERIC_EVENT'로 설정됩니다.
event_name	metadata.product_event_type	값이 직접 복사됨
id	metadata.product_log_id	값이 직접 복사됨
	metadata.product_name	'GitGuardian Enterprise'로 설정
	metadata.vendor_name	'GitGuardian'으로 설정합니다.
member_email	principal.user.email_addresses	member_email에서 병합됨
member_name	principal.user.user_display_name	값이 직접 복사됨
member_id	principal.user.userid	문자열로 변환됨
action_type	security_result.action_details	값이 직접 복사됨
target_ids	target.resource.product_object_id	target_ids의 첫 번째 요소 값

변경 로그

이 파서의 변경 로그 보기

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