> ## 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. # Splunk > Integração bidirecional entre o CaseBender e o Splunk (Enterprise Security) para ingestão de notables/alertas, encaminhamento de auditoria via HEC e sincronização do fechamento de notables. ## Visão geral A integração com o Splunk (**INT-001**) fornece sincronização **bidirecional** entre o CaseBender e o Splunk, incluindo os eventos notables do **Splunk Enterprise Security (ES)**. Notables e alertas do Splunk são ingeridos no CaseBender — **extraídos automaticamente** de forma agendada via a API REST de busca do ES, ou **enviados** a partir de uma ação de alerta / webhook do Splunk — e então normalizados, enriquecidos com observáveis e transformados em alertas (ou casos). Os eventos do ciclo de vida do caso são encaminhados para um índice do Splunk via **HEC**, e quando um caso vinculado é fechado, o CaseBender pode **fechar o notable de ES original** via a API REST com um comentário de auditoria. **Dois caminhos de entrada.** Use a **ação de alerta / webhook (push)** se você já cria alertas no Splunk, ou a **sondagem automática (pull)** se preferir que o CaseBender execute uma busca salva de forma agendada. A sondagem exige a conexão REST do Enterprise Security; o caminho de webhook não. O HEC de saída usa o **HTTP Event Collector** (padrão `/services/collector/event`, normalmente a porta `8088`). A extração e o fechamento de notables usam a **API REST de gerenciamento** (normalmente a porta `8089`). O Splunk on-premise costuma usar **certificados autoassinados** em ambos — desative **Verify SSL** se necessário (veja abaixo). ## Recursos | Recurso | Direção | Descrição | | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Sondagem de notables (pull)** | Entrada | O CaseBender executa seu SPL de forma agendada via a API REST de busca do ES e ingere os resultados automaticamente, sem configuração no lado do Splunk | | Ingestão de alertas (push) | Entrada | Ações de alerta / webhooks do Splunk enviam cargas normalizadas em alertas do CaseBender | | Extração de observáveis | Entrada | Os campos `src`/`dest`/`user` (e `*_ip`) tornam-se observáveis de IP / hostname / usuário | | Extração de ativos | Entrada | `host` (e `dest` que não seja IP) tornam-se ativos de host | | Criação automática de casos | Entrada | Registros ingeridos podem ser promovidos a casos automaticamente (deduplicados por ID de notable) | | Encaminhamento de auditoria via HEC | Saída | Criação/atualização/fechamento de casos e promoção de alertas são registrados em um índice do Splunk | | Fechamento de notables (write-back) | Saída | No fechamento do caso, o notable de ES original é definido como Fechado com um comentário via `notable_update` | | Teste de conexão | Saída | Envia um evento de teste ao endpoint HEC | ## Pré-requisitos Uma implantação do Splunk. Para extração/fechamento de notables você precisa do **Splunk Enterprise Security** e de uma função com a capacidade `edit_notable_events`. Para o encaminhamento HEC você precisa de um token do **HTTP Event Collector**. A implantação do CaseBender (e o serviço de sondagem em segundo plano, para a sondagem) deve conseguir alcançar o endpoint **HEC** do Splunk (ex. `:8088`) e, para os recursos REST, o endpoint de **gerenciamento** (ex. `:8089`). Você deve conseguir criar e gerenciar integrações em **Configurações → Integrações**. ## Parte A — Preparar o Splunk No Splunk, vá em **Settings → Data inputs → HTTP Event Collector → New Token**. Habilite o HEC globalmente se ainda não estiver, escolha (ou crie) um índice de destino e copie o valor do token. Para a **sondagem** e o **fechamento** de notables, crie um **token de autenticação** do Splunk em **Settings → Tokens** (ou use uma conta de serviço para autenticação Basic). A função associada precisa de `edit_notable_events` para fechar notables e de acesso de busca ao seu índice de notables. ## Parte B — Configurar a integração no CaseBender Vá em **Configurações → Integrações → Criar** e escolha **Splunk** na categoria **SIEM**. Defina `purpose` como **Inbound**, **Outbound** ou **Bidirectional** para exibir os cartões de configuração relevantes. Copie a **URL do webhook** e gere uma **chave de API** (com prefixo `sk_splunk_`). No Splunk, adicione uma ação de alerta **Webhook** que publique na URL com o cabeçalho `Authorization: Bearer `. No cartão **Enterprise Security REST API**, informe a URL de gerenciamento (ex. `https://splunk:8089`) e as credenciais: | Campo | Descrição | | ------------------------------- | ------------------------------------------------------- | | `restUrl` | URI de gerenciamento do Splunk (normalmente porta 8089) | | `restAuthType` | `token` (bearer) ou `basic` (usuário/senha) | | `restToken` | Token de autenticação do Splunk (bearer) | | `restUsername` / `restPassword` | Credenciais de autenticação Basic | Essa conexão viabiliza tanto a **sondagem** quanto o **fechamento** de notables. No cartão **Automatic polling**, ative **Enable automatic polling** e defina: | Opção | Efeito | | ----------------------------- | ---------------------------------------------------------------------------------------------- | | `pollingEnabled` | Ativa a extração agendada de resultados do Splunk | | `searchQuery` | SPL executado a cada intervalo, ex. `` search `notable` `` (deve começar com `search` ou `\|`) | | `pollingIntervalMinutes` | Frequência da sondagem (padrão `5`, faixa 1–1440) | | `pollingInitialLookbackHours` | Na primeira execução, importa resultados desta janela (padrão `24`, faixa 1–168) | Consulte [Sondagem automática](#entrada-sondagem-automatica) para saber como funciona. No cartão **Outbound**, informe a URL, o token e o índice do HEC e habilite: | Opção | Efeito | | ------------------------- | ----------------------------------------------------------------------------------------------- | | `syncCaseUpdates` | Encaminha os eventos de auditoria `case_created` / `case_updated` / `alert_promoted` para o HEC | | `syncCaseClose` | Encaminha um evento de auditoria `case_closed` para o HEC | | `closeNotableOnCaseClose` | Fecha o **notable** de ES original via REST ao fechar um caso vinculado | | `autoCreateCases` | Promove automaticamente cada registro do Splunk ingerido a um **caso** | Use **Test Connection** para enviar um evento de teste ao endpoint HEC. Se o seu Splunk usa um certificado autoassinado, desative **Verify SSL**. ## Entrada (sondagem automática) Com a **sondagem automática** habilitada, o CaseBender executa periodicamente seu SPL através da API REST de busca do Enterprise Security e ingere os resultados por conta própria — **sem necessidade de qualquer ação de alerta ou webhook no lado do Splunk**. ### Como funciona A cada intervalo (`pollingIntervalMinutes`), o CaseBender executa `searchQuery` sobre a janela desde o último cursor por meio do endpoint de exportação em streaming: ``` POST https://:8089/services/search/jobs/export search=&earliest_time=&latest_time=now&output_mode=json ``` Na primeira execução não há cursor, então os resultados dentro de `pollingInitialLookbackHours` são importados. O CaseBender avança um cursor por integração até o `_time` de resultado mais recente que já viu, de modo que cada execução busca apenas atividade nova. Os resultados também são **deduplicados pelo `event_id` do notable** (com fallback para o `sid` da busca), de modo que um notable nunca é ingerido duas vezes — mesmo que a janela de sondagem se sobreponha. Cada linha de resultado é normalizada em um alerta do CaseBender — mapeando a severidade a partir de `urgency`, construindo o título/descrição e extraindo observáveis e ativos de host. O `event_id` do notable é carimbado no alerta para que o fechamento de saída possa encontrá-lo depois. Com **`autoCreateCases` habilitado**, cada notable sondado torna-se automaticamente um **caso** (deduplicado por ID de notable) — isso corresponde ao fluxo "extrair notable → trabalhá-lo como caso". Desabilitado, os resultados chegam à caixa de entrada de **Alertas** para promoção manual. Em ambos os casos, o vínculo com o Splunk é preservado para que o fechamento do caso possa fechar o notable. A sondagem é executada no serviço de sondagem em segundo plano do CaseBender. Garanta que esse serviço consiga alcançar o endpoint de gerenciamento do Splunk (diretamente ou via seu proxy configurado). Hosts internos do Splunk devem ser listados em `NO_PROXY` em redes somente proxy. ## Entrada (webhook / push) Como alternativa (ou em complemento) à sondagem, uma **ação de alerta** do Splunk (ou qualquer remetente de webhook) pode enviar os resultados da busca ao endpoint de ingestão do CaseBender. ### Endpoint ``` POST https:///api/v1/ingest/splunk ``` As requisições são autenticadas com uma **chave de API** de integração passada em `Authorization: Bearer ` (o cabeçalho `x-api-key` também é aceito). As chaves de API de webhook do Splunk têm o prefixo `sk_splunk_`. ### Exemplo de carga A ação de alerta de webhook do Splunk publica um objeto `result` mais metadados da busca: ```bash theme={null} curl -X POST "https:///api/v1/ingest/splunk" \ -H "Authorization: Bearer sk_splunk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "sid": "scheduler__admin__search__RMD5...", "search_name": "Threat - Brute Force Access - Rule", "results_link": "https://splunk.example.com/app/search/...", "app": "SplunkEnterpriseSecuritySuite", "result": { "event_id": "A1B2C3D4-...", "rule_title": "Brute Force Access Behavior Detected", "urgency": "high", "security_domain": "access", "src": "10.0.0.5", "dest": "10.0.0.20", "user": "jdoe" } }' ``` Uma requisição bem-sucedida retorna HTTP `202 Accepted`: ```json theme={null} { "success": true, "messageId": "..." } ``` ### Pipeline de processamento `/api/v1/ingest/splunk` valida a origem e encaminha a requisição ao serviço de ingestão (`POST /v1/sources/splunk`). O serviço de ingestão autentica a chave de API, valida a carga e publica o registro na fila de processamento. O processador do Splunk normaliza o registro em um alerta do CaseBender — mapeando a severidade, construindo o título/descrição e extraindo observáveis e ativos de host. ### Referência de mapeamento de dados **Mapeamento de severidade** (`urgency` do Splunk → CaseBender 1–4): | urgency do Splunk | Severidade do CaseBender | | ----------------------- | ------------------------ | | `critical` | 4 | | `high` | 3 | | `medium` | 2 | | `low` / `informational` | 1 | **Extração de observáveis / ativos:** | Campo do Splunk | Observável / ativo | | ------------------ | -------------------------------------- | | `src` / `src_ip` | observável de `ip` ou `hostname` (IOC) | | `dest` / `dest_ip` | observável de `ip` ou `hostname` | | `user` | observável de `user` | | `host` | ativo de host | O **título** é construído a partir de `rule_title` → `search_name` → `alert_name` → `signature` → `message`. As **tags** aplicadas na ingestão incluem `splunk`, `siem`, `notable` (para notables de ES), `domain:` e `app:`. Os registros ingeridos usam por padrão **TLP:2** e **PAP:2**. ## Saída: encaminhamento de auditoria via HEC Quando habilitado com `syncCaseUpdates` / `syncCaseClose`, o CaseBender publica eventos de auditoria em JSON no seu endpoint HEC para que a atividade dos casos seja pesquisável no Splunk: | Evento | `action` do HEC | Condição | | ---------------- | ------------------------ | ----------------- | | Caso criado | `case_created` | `syncCaseUpdates` | | Caso atualizado | `case_updated` | `syncCaseUpdates` | | Alerta promovido | `alert_promoted_to_case` | `syncCaseUpdates` | | Caso fechado | `case_closed` | `syncCaseClose` | Os eventos são enviados com `source: casebender:case` (ou `casebender:alert`) e `sourcetype: _json` para o índice configurado. ## Saída: fechar o notable do Splunk (write-back) Quando um caso é fechado no CaseBender, o evento `case_closed` é despachado para o handler do Splunk. Se o caso estiver vinculado a um notable do Splunk **e** `closeNotableOnCaseClose` estiver ativado, o CaseBender fecha o notable por meio da API REST do ES. ### Como o notable vinculado é resolvido O pipeline de ingestão carimba `splunkEventId` (o `event_id` do notable) e o ID da integração que o ingeriu nos `customFields` de cada alerta do Splunk. No fechamento do caso, o handler coleta esses IDs de evento dos alertas vinculados ao caso, de modo que um caso promovido a partir de um notable sondado ou de webhook é resolvido automaticamente, independentemente de como foi criado. ### O que é enviado O CaseBender chama o endpoint `notable_update` do ES: ``` POST https://:8089/services/notable_update ruleUIDs=["", ...]&status=&comment=&output_mode=json ``` * `status` tem por padrão **5 (Fechado)** e é configurável via `notableStatusOnClose`. * `comment` é: `Case closed in CaseBender with resolution: `. O resultado (notables fechados, ou um erro) é escrito na linha do tempo do caso para que os analistas possam confirmar a sincronização. `syncCaseClose` (evento de auditoria HEC) e `closeNotableOnCaseClose` (write-back do notable via REST) são alternâncias independentes por integração. O write-back do notable exige a conexão REST do Enterprise Security e uma função com a capacidade `edit_notable_events`. ## Considerações de segurança * **Gerenciamento de tokens** — tokens HEC e tokens/senhas REST são armazenados nas configurações da integração; faça a rotação conforme o cronograma da sua organização e atualize a integração quando o fizer. * **Privilégio mínimo** — a função REST só precisa de acesso de busca ao seu índice de notables e de `edit_notable_events`. Tokens HEC devem apontar para um índice dedicado. * **Chaves de webhook** — trate a chave de API `sk_splunk_` como um segredo. Faça a rotação se exposta e atualize a ação de alerta do Splunk. * **TLS** — prefira certificados confiáveis. Se você precisar usar certificados autoassinados (comum on-premise), **Verify SSL** pode ser desativado; a conexão continua criptografada, mas o certificado não é validado. Restrinja a saída aos seus endpoints HEC e de gerenciamento do Splunk. ## Solução de problemas Confirme a URL e o token do HEC, que o HEC esteja habilitado e que o CaseBender consiga alcançar a porta HEC (normalmente `8088`). Se o Splunk usa um certificado autoassinado, desative **Verify SSL** — caso contrário a requisição falha com um erro de certificado. O cabeçalho `Authorization: Bearer` (ou `x-api-key`) está ausente ou inválido. Confirme que você está enviando a chave `sk_splunk_` que corresponde à chave de API de webhook configurada na integração. Confirme que **Enable automatic polling** está ativado, que a conexão **ES REST** está preenchida e que há uma **consulta de busca** definida. Verifique se a função consegue executar a busca e alcançar a porta de gerenciamento (normalmente `8089`) e se há resultados mais recentes que o cursor. Na primeira execução, apenas resultados dentro de `pollingInitialLookbackHours` são importados. Verifique o último status de sincronização da integração para o erro específico. Certifique-se de que `closeNotableOnCaseClose` esteja ativado e de que a conexão **ES REST** esteja configurada com uma função que tenha `edit_notable_events`. O caso deve estar vinculado a um notable do Splunk — fechar um caso promovido a partir de um notable sondado/de webhook resolve o vínculo automaticamente. Verifique a linha do tempo do caso para o resultado da sincronização. Um `403` significa que a função REST não possui a capacidade `edit_notable_events`. Um `404` normalmente significa que a URL não é o endpoint de gerenciamento do Enterprise Security — confirme que `restUrl` aponta para a porta de gerenciamento do Splunk com o ES instalado. Em redes somente proxy, adicione seu host interno do Splunk ao `NO_PROXY` para que a conexão seja direta e desative **Verify SSL** se o certificado for autoassinado. ## Documentação relacionada * [Visão geral das integrações](./introduction.mdx) * [Splunk HTTP Event Collector](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) * [Ações de eventos notable do Splunk ES](https://docs.splunk.com/Documentation/ES/latest/User/Triagenotableevents)