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

# CrowdStrike Falcon

> Integração bidirecional entre o CaseBender e o CrowdStrike Falcon para ingestão de detecções (pull ou push) e sincronização de disposições.

## Visão geral

A integração do CrowdStrike Falcon (**INT-008**) ingere as detecções do Falcon no CaseBender e
pode devolver as disposições dos casos ao Falcon quando um caso é fechado.

<CardGroup cols={2}>
  <Card title="Ingestão de entrada" icon="arrow-right-to-bracket">
    As detecções do Falcon são ingeridas — **extraídas automaticamente** de forma
    agendada (recomendado) ou **enviadas** por webhook — e então normalizadas,
    enriquecidas com observáveis e técnicas MITRE ATT\&CK, e convertidas em alertas.
  </Card>

  <Card title="Sincronização de saída" icon="arrow-right-from-bracket">
    Quando um caso vinculado é fechado no CaseBender, o status da detecção do Falcon
    é atualizado com um comentário de auditoria.
  </Card>
</CardGroup>

<Tip>
  **Recomendado: ative a sondagem automática.** O CaseBender pode extrair novas
  detecções de forma agendada usando o mesmo cliente de API do Falcon — nenhum
  webhook ou conector SIEM é necessário. Consulte
  [Sondagem automática](#entrada-sondagem-automatica).
</Tip>

<Note>
  Esta integração usa a **Alerts API v2 do Falcon** e autentica com um **cliente
  de API OAuth2** (client ID + secret) via fluxo client-credentials.
</Note>

## Recursos

| Recurso                          | Direção      | Descrição                                                                                                                 |
| -------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **Sondagem de detecções (pull)** | Entrada      | O CaseBender consulta a Alerts API de forma agendada e ingere novas detecções automaticamente, sem configuração no Falcon |
| Ingestão de detecções (push)     | Entrada      | As detecções do Falcon são enviadas por webhook e normalizadas em alertas                                                 |
| Extração de observáveis          | Entrada      | IPs, hashes de arquivos, nomes de arquivos, hosts e usuários                                                              |
| Correlação MITRE ATT\&CK         | Entrada      | Os IDs de técnica/tática são adicionados como tags e TTPs                                                                 |
| Sincronização de disposições     | Saída        | O status da detecção + comentário são enviados no fechamento do caso                                                      |
| Teste de conexão                 | Bidirecional | Valida as credenciais OAuth2 e o acesso à API                                                                             |

## Pré-requisitos

<Steps>
  <Step title="Cliente de API do Falcon">
    No console do Falcon, vá em **Support and resources → API clients and keys** e crie um cliente
    de API. Conceda o escopo **Alerts: Read** (e **Alerts: Write** se quiser o fechamento de
    saída). Copie o **Client ID** e o **Secret**.
  </Step>

  <Step title="URL base da região de nuvem">
    Anote a URL base da sua nuvem Falcon (ex.: `https://api.crowdstrike.com`,
    `https://api.us-2.crowdstrike.com` ou `https://api.eu-1.crowdstrike.com`).
  </Step>

  <Step title="Saída de rede">
    O serviço de sondagem do CaseBender deve conseguir alcançar a URL base da API do Falcon.
  </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 **CrowdStrike Falcon** na categoria
    **EDR/XDR**.
  </Step>

  <Step title="Inserir as credenciais da API do Falcon">
    | Campo                    | Descrição                                                       |
    | ------------------------ | --------------------------------------------------------------- |
    | API URL                  | URL base da nuvem Falcon (padrão `https://api.crowdstrike.com`) |
    | Falcon API Client ID     | O client ID OAuth2                                              |
    | Falcon API Client Secret | O client secret OAuth2                                          |
  </Step>

  <Step title="Ativar a sondagem automática (recomendado)">
    No cartão **Automatic polling**, ative **Enable automatic polling** e configure:

    | Opção                         | Efeito                                                                                          |
    | ----------------------------- | ----------------------------------------------------------------------------------------------- |
    | `pollingEnabled`              | Ativa a extração agendada de detecções do Falcon                                                |
    | `pollingIntervalMinutes`      | Frequência de sondagem (padrão `5`, intervalo 1–1440)                                           |
    | `pollingInitialLookbackHours` | Na primeira execução, importa detecções atualizadas nesta janela (padrão `24`, intervalo 1–168) |
    | `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 detecção ingerida a um **Caso** (deduplicada por ID de detecção). Se desativado, as detecções permanecem na caixa de alertas |
    | `minSeverityForCase` | Cria casos automaticamente apenas a partir desta severidade                                                                               |
  </Step>
</Steps>

## Entrada (sondagem automática)

Com a **sondagem automática** ativada, o sondador do CaseBender consulta periodicamente a Alerts
API do Falcon e ingere novas detecções por conta própria.

<Steps>
  <Step title="Extração agendada">
    A cada intervalo, o CaseBender consulta os IDs compostos atualizados desde o último cursor via
    Alerts API v2 e então busca as entidades de detecção completas. Na primeira execução não há
    cursor, então as detecções dentro de `pollingInitialLookbackHours` são importadas.
  </Step>

  <Step title="Cursor + deduplicação">
    O CaseBender avança um cursor por integração até o `updated_timestamp` mais recente. As
    detecções são **deduplicadas por ID de detecção**, de modo que janelas de sondagem sobrepostas
    nunca criam alertas duplicados.
  </Step>

  <Step title="Normalização">
    Cada detecção é normalizada em um alerta do CaseBender — mapeando a severidade, construindo o
    título/descrição, extraindo observáveis e gerando TTPs MITRE.
  </Step>
</Steps>

<Info>
  A sondagem é executada no serviço de sondagem em segundo plano do CaseBender. Certifique-se de que
  esse serviço consiga alcançar a URL base da sua API do Falcon (diretamente ou através do seu proxy
  configurado).
</Info>

## Entrada (webhook / push)

Como alternativa à sondagem, o Falcon (ou um intermediário) pode enviar payloads de detecção ao
endpoint de ingestão do CaseBender:

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

As requisições são autenticadas com uma **API key** de integração no cabeçalho `x-api-key`. As
chaves de webhook do Falcon têm o prefixo `cbr_crowdstrike_`.

## Saída: sincronização de disposições para o Falcon

Quando um caso é fechado, o evento `case_closed` é despachado para o manipulador do CrowdStrike. Se
o caso estiver vinculado a uma detecção do Falcon (o ID de detecção é carimbado no alerta ingerido),
o manipulador atualiza o status da detecção e adiciona um comentário de auditoria. O fechamento de
saída requer o escopo **Alerts: Write** no cliente de API.

## Considerações de segurança

* **Privilégio mínimo** — conceda **Alerts: Read** apenas para entrada; adicione **Alerts: Write**
  somente se ativar o fechamento de saída.
* **Manejo de segredos** — o client secret é armazenado nas configurações da integração; faça a
  rotação conforme a política da sua organização.
* **Cache de tokens** — os tokens de acesso são armazenados em cache na memória e renovados antes de
  expirar.
* **Rede** — restrinja a saída à URL base da sua API do Falcon.

## Solução de problemas

<AccordionGroup>
  <Accordion title="O teste de conexão falha com um erro OAuth2">
    Verifique o client ID, o secret e a URL base da API (região). Confirme que o cliente de API
    está habilitado e possui o escopo Alerts.
  </Accordion>

  <Accordion title="A sondagem está ativada, mas nenhuma detecção aparece">
    Confirme que **Enable automatic polling** está ativado e que o cliente de API tem o escopo
    Alerts: Read. Verifique se o sondador consegue alcançar sua URL base do Falcon. Na primeira
    execução, apenas as detecções dentro de `pollingInitialLookbackHours` são importadas.

    **Certifique-se de que todos os serviços do CaseBender estejam em execução.** As detecções são
    buscadas pelo processador em segundo plano e convertidas em alertas (e opcionalmente casos) pelo
    **worker** em segundo plano. Com o Docker, execute `docker compose ps` e confirme que os
    serviços `worker` e `misp-processor` estão `Up`.
  </Accordion>

  <Accordion title="O fechamento do caso não atualiza o Falcon">
    Certifique-se de que o cliente de API tem o escopo Alerts: Write e que o caso está vinculado a
    uma detecção do Falcon. Consulte a linha do tempo do caso para o resultado da sincronização.
  </Accordion>
</AccordionGroup>

## Documentação relacionada

* [Visão geral das integrações](./introduction.mdx)
* [Documentação da API do CrowdStrike Falcon](https://falcon.crowdstrike.com/documentation/)