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

> Ingest Google Cloud Security Command Center findings into CaseBender by automatic polling (pull) or notification webhook (push).

## Overview

The Google Cloud Security Command Center (SCC) integration (**INT-009**) ingests SCC findings
into CaseBender and turns them into alerts (and optionally cases).

<CardGroup cols={2}>
  <Card title="Automatic polling (pull)" icon="arrow-right-to-bracket">
    CaseBender pulls new findings directly from SCC on a schedule using a service
    account — no Pub/Sub notification required.
  </Card>

  <Card title="Notification webhook (push)" icon="bolt">
    Alternatively, an SCC notification (via Pub/Sub + Cloud Function) forwards
    findings to the CaseBender ingestion endpoint.
  </Card>
</CardGroup>

<Tip>
  **Recommended: enable Automatic polling.** It requires only a read-only service
  account and no inbound endpoint. See
  [Automatic polling](#inbound-automatic-polling-recommended).
</Tip>

<Note>
  Polling uses the official **Google Cloud SDK** (`@google-cloud/security-center`) to list
  findings via the SCC v1 API.
</Note>

## Capabilities

| Capability                 | Direction | Description                                                                |
| -------------------------- | --------- | -------------------------------------------------------------------------- |
| **Finding polling (pull)** | Inbound   | CaseBender polls the SCC API on a schedule and ingests new ACTIVE findings |
| Finding ingestion (push)   | Inbound   | Pub/Sub notification forwards findings to the ingestion endpoint           |
| Observable extraction      | Inbound   | IPs and domains from finding indicators                                    |
| Category tagging           | Inbound   | Finding category, class, and resource type become tags                     |

## Prerequisites

<Steps>
  <Step title="Create a service account">
    In Google Cloud IAM, create a service account and download a **JSON key**. Grant it the
    **Security Center Findings Viewer** role (`roles/securitycenter.findingsViewer`) at the
    organization or project level.
  </Step>

  <Step title="Collect the organization or project ID">
    Record your numeric **organization ID** (recommended) or a **project ID**.
  </Step>

  <Step title="Network egress">
    The CaseBender poller must reach `securitycenter.googleapis.com` and
    `oauth2.googleapis.com`.
  </Step>
</Steps>

## Configure the integration in CaseBender

<Steps>
  <Step title="Open the integration catalog">
    Go to **Settings → Integrations → Create**, then choose **Google Cloud SCC** from the
    **Cloud Security** category.
  </Step>

  <Step title="Enter GCP credentials">
    | Field                      | Description                                           |
    | -------------------------- | ----------------------------------------------------- |
    | Organization ID            | Numeric GCP organization ID                           |
    | Project ID (optional)      | Falls back to project-level findings if no org is set |
    | Service Account Key (JSON) | Paste the full JSON key                               |
  </Step>

  <Step title="Enable automatic polling (recommended)">
    | Option                        | Effect                                                                  |
    | ----------------------------- | ----------------------------------------------------------------------- |
    | `pollingEnabled`              | Turn on scheduled pulling of findings                                   |
    | `pollingIntervalMinutes`      | How often to poll (default `5`)                                         |
    | `pollingInitialLookbackHours` | On first run, import findings updated within this window (default `24`) |
    | `pollMaxItemsPerRun`          | Safety cap on items ingested per run (default `500`)                    |
  </Step>

  <Step title="Configure auto-case creation">
    | Option               | Effect                                                       |
    | -------------------- | ------------------------------------------------------------ |
    | `autoCreateCases`    | Promote each finding to a **Case** (deduped by finding name) |
    | `minSeverityForCase` | Only auto-create cases at/above this severity                |
  </Step>
</Steps>

## Inbound (automatic polling, recommended)

<Steps>
  <Step title="Scheduled pull">
    On each interval, CaseBender lists ACTIVE findings with `eventTime` at/after the last cursor,
    ordered by event time. On first run, findings within `pollingInitialLookbackHours` are
    imported.
  </Step>

  <Step title="Cursor + deduplication">
    CaseBender advances the cursor to the newest `eventTime`. Findings are **deduplicated by
    finding name**, so overlapping windows never create duplicates.
  </Step>

  <Step title="Normalization">
    Each finding is normalized into a CaseBender alert with observables and category tags.
  </Step>
</Steps>

<Info>
  Polling runs in CaseBender's background poller service. Ensure it can reach
  `securitycenter.googleapis.com` (directly or via your proxy).
</Info>

## Inbound (notification webhook / push)

As an alternative, an SCC notification config (Pub/Sub → Cloud Function) can POST findings to:

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

Requests are authenticated with the integration **API key** in the `x-api-key` header. The
`{ "finding": { ... }, "resource": { ... } }` payload shape is expected.

## Security considerations

* **Least privilege** — grant only **Security Center Findings Viewer**.
* **Secret handling** — the service account JSON key is stored in the integration settings;
  rotate it on your organization's schedule and prefer a dedicated integration service account.
* **Network** — restrict egress to `securitycenter.googleapis.com` and `oauth2.googleapis.com`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Service account key is not valid JSON">
    Paste the entire JSON key file contents, including the surrounding braces.
  </Accordion>

  <Accordion title="Polling is enabled but no findings appear">
    Confirm the service account has the Findings Viewer role at the org/project you configured,
    and that ACTIVE findings exist newer than the cursor. On first run only findings within
    `pollingInitialLookbackHours` are imported.

    **Make sure all CaseBender services are running** — with Docker, `docker compose ps` should
    show the `worker` and `misp-processor` services `Up`.
  </Accordion>

  <Accordion title="PermissionDenied errors">
    The service account lacks `securitycenter.findings.list` at the requested scope, or the
    organization/project ID is incorrect.
  </Accordion>
</AccordionGroup>

## Related documentation

* [Integrations overview](./introduction.mdx)
* [Security Command Center documentation](https://cloud.google.com/security-command-center/docs)