> ## 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

> Ingira os findings do Google Cloud Security Command Center no CaseBender via sondagem automática (pull) ou webhook de notificação (push).

## Visão geral

A integração do Google Cloud Security Command Center (SCC) (**INT-009**) ingere os findings do SCC
no CaseBender e os converte em alertas (e opcionalmente casos).

<CardGroup cols={2}>
  <Card title="Sondagem automática (pull)" icon="arrow-right-to-bracket">
    O CaseBender extrai novos findings diretamente do SCC de forma agendada usando
    uma conta de serviço — sem notificação do Pub/Sub.
  </Card>

  <Card title="Webhook de notificação (push)" icon="bolt">
    Como alternativa, uma notificação do SCC (via Pub/Sub + Cloud Function)
    encaminha os findings ao endpoint de ingestão do CaseBender.
  </Card>
</CardGroup>

<Tip>
  **Recomendado: ative a sondagem automática.** Requer apenas uma conta de serviço
  somente leitura e nenhum endpoint de entrada. Consulte
  [Sondagem automática](#entrada-sondagem-automatica).
</Tip>

<Note>
  A sondagem usa o **SDK oficial do Google Cloud** (`@google-cloud/security-center`)
  para enumerar os findings via API v1 do SCC.
</Note>

## Recursos

| Recurso                         | Direção | Descrição                                                                           |
| ------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| **Sondagem de findings (pull)** | Entrada | O CaseBender consulta a API do SCC de forma agendada e ingere novos findings ACTIVE |
| Ingestão de findings (push)     | Entrada | A notificação do Pub/Sub encaminha os findings ao endpoint de ingestão              |
| Extração de observáveis         | Entrada | IPs e domínios dos indicadores do finding                                           |
| Rotulagem por categoria         | Entrada | A categoria, a classe e o tipo de recurso do finding tornam-se tags                 |

## Pré-requisitos

<Steps>
  <Step title="Criar uma conta de serviço">
    No IAM do Google Cloud, crie uma conta de serviço e baixe uma **chave JSON**. Conceda a ela a
    função **Security Center Findings Viewer** (`roles/securitycenter.findingsViewer`) no nível de
    organização ou projeto.
  </Step>

  <Step title="Reunir o ID de organização ou projeto">
    Anote seu **ID de organização** numérico (recomendado) ou um **ID de projeto**.
  </Step>

  <Step title="Saída de rede">
    O sondador do CaseBender deve alcançar `securitycenter.googleapis.com` e `oauth2.googleapis.com`.
  </Step>
</Steps>

## Configurar a integração no CaseBender

<Steps>
  <Step title="Abrir o catálogo de integrações">
    Vá em **Settings → Integrations → Create** e escolha **Google Cloud SCC** na categoria
    **Cloud Security**.
  </Step>

  <Step title="Inserir as credenciais do GCP">
    | Campo                      | Descrição                                                        |
    | -------------------------- | ---------------------------------------------------------------- |
    | Organization ID            | ID de organização GCP numérico                                   |
    | Project ID (opcional)      | Recorre a findings no nível de projeto se não houver organização |
    | Service Account Key (JSON) | Cole a chave JSON completa                                       |
  </Step>

  <Step title="Ativar a sondagem automática (recomendado)">
    | Opção                         | Efeito                                                                        |
    | ----------------------------- | ----------------------------------------------------------------------------- |
    | `pollingEnabled`              | Ativa a extração agendada de findings                                         |
    | `pollingIntervalMinutes`      | Frequência de sondagem (padrão `5`)                                           |
    | `pollingInitialLookbackHours` | Na primeira execução, importa findings atualizados nesta janela (padrão `24`) |
    | `pollMaxItemsPerRun`          | Limite de segurança de itens por execução (padrão `500`)                      |
  </Step>

  <Step title="Configurar a criação automática de casos">
    | Opção                | Efeito                                                               |
    | -------------------- | -------------------------------------------------------------------- |
    | `autoCreateCases`    | Promove cada finding a um **Caso** (deduplicado por nome de finding) |
    | `minSeverityForCase` | Cria casos automaticamente apenas a partir desta severidade          |
  </Step>
</Steps>

## Entrada (sondagem automática)

<Steps>
  <Step title="Extração agendada">
    A cada intervalo, o CaseBender enumera os findings ACTIVE com `eventTime` igual ou posterior ao
    último cursor, ordenados por horário do evento. Na primeira execução, os findings dentro de
    `pollingInitialLookbackHours` são importados.
  </Step>

  <Step title="Cursor + deduplicação">
    O CaseBender avança o cursor até o `eventTime` mais recente. Os findings são **deduplicados por
    nome de finding**, de modo que janelas sobrepostas nunca criam duplicatas.
  </Step>

  <Step title="Normalização">
    Cada finding é normalizado em um alerta do CaseBender com observáveis e tags de categoria.
  </Step>
</Steps>

<Info>
  A sondagem é executada no serviço de sondagem em segundo plano do CaseBender. Certifique-se de que
  ele consiga alcançar `securitycenter.googleapis.com` (diretamente ou através do seu proxy).
</Info>

## Entrada (webhook de notificação / push)

Como alternativa, uma configuração de notificação do SCC (Pub/Sub → Cloud Function) pode fazer POST
dos findings para:

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

As requisições são autenticadas com a **API key** de integração no cabeçalho `x-api-key`. É
esperado o formato de payload `{ "finding": { ... }, "resource": { ... } }`.

## Considerações de segurança

* **Privilégio mínimo** — conceda apenas **Security Center Findings Viewer**.
* **Manejo de segredos** — a chave JSON da conta de serviço é armazenada nas configurações da
  integração; faça a rotação conforme a política da sua organização e prefira uma conta de serviço
  de integração dedicada.
* **Rede** — restrinja a saída a `securitycenter.googleapis.com` e `oauth2.googleapis.com`.

## Solução de problemas

<AccordionGroup>
  <Accordion title="A chave da conta de serviço não é um JSON válido">
    Cole o conteúdo inteiro do arquivo de chave JSON, incluindo as chaves que o envolvem.
  </Accordion>

  <Accordion title="A sondagem está ativada, mas nenhum finding aparece">
    Confirme que a conta de serviço tem a função Findings Viewer na organização/projeto configurado
    e que existem findings ACTIVE mais recentes que o cursor. Na primeira execução, apenas os
    findings dentro de `pollingInitialLookbackHours` são importados.

    **Certifique-se de que todos os serviços do CaseBender estejam em execução** — com o Docker,
    `docker compose ps` deve mostrar os serviços `worker` e `misp-processor` como `Up`.
  </Accordion>

  <Accordion title="Erros PermissionDenied">
    A conta de serviço não tem `securitycenter.findings.list` no escopo solicitado, ou o ID de
    organização/projeto está incorreto.
  </Accordion>
</AccordionGroup>

## Documentação relacionada

* [Visão geral das integrações](./introduction.mdx)
* [Documentação do Security Command Center](https://cloud.google.com/security-command-center/docs)