> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud SCC

> 자동 폴링(pull) 또는 알림 웹훅(push)을 통해 Google Cloud Security Command Center 발견 항목을 CaseBender로 수집합니다.

## 개요

Google Cloud Security Command Center(SCC) 통합(**INT-009**)은 SCC 발견 항목(findings)을 CaseBender로
수집하여 알림(및 선택적으로 케이스)으로 변환합니다.

<CardGroup cols={2}>
  <Card title="자동 폴링(pull)" icon="arrow-right-to-bracket">
    CaseBender는 서비스 계정을 사용하여 예약된 일정에 따라 SCC에서 직접 새 발견
    항목을 가져옵니다. Pub/Sub 알림이 필요하지 않습니다.
  </Card>

  <Card title="알림 웹훅(push)" icon="bolt">
    대안으로 SCC 알림(Pub/Sub + Cloud Function 경유)이 발견 항목을 CaseBender 수집
    엔드포인트로 전달합니다.
  </Card>
</CardGroup>

<Tip>
  **권장: 자동 폴링을 활성화하세요.** 읽기 전용 서비스 계정만 필요하며 인바운드
  엔드포인트가 필요하지 않습니다. [자동 폴링](#인바운드자동-폴링)을 참조하세요.
</Tip>

<Note>
  폴링은 **공식 Google Cloud SDK**(`@google-cloud/security-center`)를 사용하여 SCC v1
  API로 발견 항목을 열거합니다.
</Note>

## 기능

| 기능                 | 방향   | 설명                                                         |
| ------------------ | ---- | ---------------------------------------------------------- |
| **발견 항목 폴링(pull)** | 인바운드 | CaseBender가 예약된 일정에 따라 SCC API를 조회하고 새 ACTIVE 발견 항목을 수집합니다 |
| 발견 항목 수집(push)     | 인바운드 | Pub/Sub 알림이 발견 항목을 수집 엔드포인트로 전달합니다                         |
| 관찰 대상 추출           | 인바운드 | 발견 항목 인디케이터의 IP 및 도메인                                      |
| 카테고리별 태그 지정        | 인바운드 | 발견 항목의 카테고리, 클래스, 리소스 유형이 태그가 됩니다                          |

## 사전 요구 사항

<Steps>
  <Step title="서비스 계정 생성">
    Google Cloud IAM에서 서비스 계정을 생성하고 **JSON 키**를 다운로드합니다. 조직 또는 프로젝트
    수준에서 **Security Center Findings Viewer** 역할(`roles/securitycenter.findingsViewer`)을
    부여합니다.
  </Step>

  <Step title="조직 또는 프로젝트 ID 수집">
    숫자 **조직 ID**(권장) 또는 **프로젝트 ID**를 기록합니다.
  </Step>

  <Step title="네트워크 아웃바운드">
    CaseBender 폴러가 `securitycenter.googleapis.com`과 `oauth2.googleapis.com`에 도달할 수 있어야
    합니다.
  </Step>
</Steps>

## CaseBender에서 통합 구성

<Steps>
  <Step title="통합 카탈로그 열기">
    **Settings → Integrations → Create**로 이동하여 **Cloud Security** 카테고리에서 **Google Cloud SCC**
    를 선택합니다.
  </Step>

  <Step title="GCP 자격 증명 입력">
    | 필드                         | 설명                         |
    | -------------------------- | -------------------------- |
    | Organization ID            | 숫자 GCP 조직 ID               |
    | Project ID(선택)             | 조직이 없으면 프로젝트 수준 발견 항목으로 대체 |
    | Service Account Key (JSON) | 전체 JSON 키 붙여넣기             |
  </Step>

  <Step title="자동 폴링 활성화(권장)">
    | 옵션                            | 효과                                        |
    | ----------------------------- | ----------------------------------------- |
    | `pollingEnabled`              | 발견 항목의 예약 가져오기 활성화                        |
    | `pollingIntervalMinutes`      | 폴링 주기(기본값 `5`)                            |
    | `pollingInitialLookbackHours` | 첫 실행 시 이 범위 내에 업데이트된 발견 항목을 가져옴(기본값 `24`) |
    | `pollMaxItemsPerRun`          | 실행당 수집 항목 안전 상한(기본값 `500`)                |
  </Step>

  <Step title="케이스 자동 생성 구성">
    | 옵션                   | 효과                                     |
    | -------------------- | -------------------------------------- |
    | `autoCreateCases`    | 각 발견 항목을 **케이스**로 승격(발견 항목 이름으로 중복 제거) |
    | `minSeverityForCase` | 이 심각도 이상일 때만 케이스를 자동 생성                |
  </Step>
</Steps>

## 인바운드(자동 폴링)

<Steps>
  <Step title="예약 가져오기">
    각 주기마다 CaseBender는 `eventTime`이 마지막 커서 이후인 ACTIVE 발견 항목을 이벤트 시간순으로
    열거합니다. 첫 실행 시에는 `pollingInitialLookbackHours` 이내의 발견 항목을 가져옵니다.
  </Step>

  <Step title="커서 + 중복 제거">
    CaseBender는 커서를 가장 최근의 `eventTime`까지 진행합니다. 발견 항목은 **발견 항목 이름으로 중복
    제거**되므로 윈도우가 겹쳐도 중복이 생성되지 않습니다.
  </Step>

  <Step title="정규화">
    각 발견 항목은 관찰 대상과 카테고리 태그를 포함한 CaseBender 알림으로 정규화됩니다.
  </Step>
</Steps>

<Info>
  폴링은 CaseBender의 백그라운드 폴링 서비스에서 실행됩니다. `securitycenter.googleapis.com`에 (직접
  또는 프록시를 통해) 도달할 수 있는지 확인하세요.
</Info>

## 인바운드(알림 웹훅 / 푸시)

대안으로 SCC 알림 구성(Pub/Sub → Cloud Function)이 발견 항목을 다음으로 POST할 수 있습니다.

```
POST https://<your-casebender-domain>/api/v1/ingest/gcpscc
```

요청은 `x-api-key` 헤더의 통합 **API 키**로 인증됩니다. 페이로드 형식은
`{ "finding": { ... }, "resource": { ... } }`를 예상합니다.

## 보안 고려 사항

* **최소 권한** — **Security Center Findings Viewer**만 부여하세요.
* **시크릿 처리** — 서비스 계정 JSON 키는 통합 설정에 저장됩니다. 조직 정책에 따라 교체하고 전용
  통합 서비스 계정을 사용하세요.
* **네트워크** — 아웃바운드를 `securitycenter.googleapis.com`과 `oauth2.googleapis.com`으로 제한하세요.

## 문제 해결

<AccordionGroup>
  <Accordion title="서비스 계정 키가 유효한 JSON이 아님">
    감싸는 중괄호를 포함하여 JSON 키 파일의 전체 내용을 붙여넣으세요.
  </Accordion>

  <Accordion title="폴링은 활성화되어 있지만 발견 항목이 표시되지 않음">
    서비스 계정이 구성한 조직/프로젝트에 대해 Findings Viewer 역할을 가지고 있고 커서보다 새로운
    ACTIVE 발견 항목이 존재하는지 확인하세요. 첫 실행 시에는 `pollingInitialLookbackHours` 이내의
    발견 항목만 가져옵니다.

    **모든 CaseBender 서비스가 실행 중인지 확인하세요** — Docker에서는 `docker compose ps`에서
    `worker` 및 `misp-processor` 서비스가 `Up` 상태여야 합니다.
  </Accordion>

  <Accordion title="PermissionDenied 오류">
    서비스 계정에 요청된 범위에 대한 `securitycenter.findings.list` 권한이 없거나, 조직/프로젝트 ID가
    올바르지 않습니다.
  </Accordion>
</AccordionGroup>

## 관련 문서

* [통합 개요](./introduction.mdx)
* [Security Command Center 문서](https://cloud.google.com/security-command-center/docs)