Enviando Notificações de CMA via Webhooks

Visão Geral

O Aplicativo de Gerenciamento Cato (CMA) gera notificações para uma ampla variedade de eventos de segurança e rede na sua conta. Você pode usar integrações de webhook para entregar automaticamente essas notificações a plataformas de terceiros, como ServiceNow, Jira, Slack ou Zendesk. Isso permite que sistemas externos consumam dados de eventos do Cato em tempo real e acionem fluxos de trabalho automatizados para rastreamento de incidentes e resposta.

Cato suporta dois tipos de integrações de webhook:

Webhooks padrão usam solicitações HTTP para criar ou atualizar itens em plataformas externas.
Webhooks correlacionados se integram ao serviço XOps. Eles usam IDs de correlação para criar e atualizar itens que representam o ciclo de vida de histórias de segurança e rede XOps em ferramentas de terceiros. É necessário uma licença XOps.

Integrações de webhook são totalmente configuráveis. Você define o método HTTP (POST ou PUT), a URL de destino, o método de autenticação e o corpo da solicitação. Modelos e variáveis de campo permitem que você personalize a estrutura do payload de acordo com os requisitos da plataforma de terceiros.

Entendendo Integrações de Webhook Cato

Tipos de Integração de Webhook

Cato suporta estes tipos de webhooks para integrar sua conta com plataformas de terceiros e criar fluxos de automação:

Webhooks padrão suportam uma ampla gama de notificações do CMA, tais como notificações baseadas em alertas de conta ou sistema, e notificações baseadas em políticas. Eles permitem que você entregue esses dados a plataformas externas e configure se o webhook cria novos registros ou atualiza os existentes.
Webhooks correlacionados são projetados para o serviço XOps. Eles estendem a funcionalidade de webhook para histórias de segurança e rede, portanto cada história no CMA é mapeada para um registro no sistema externo e atualizada conforme a história avança. É necessário uma licença XOps.

Fluxos de Webhook - Criar ou Atualizar

Os fluxos de webhook definem como o CMA se comunica com uma plataforma de terceiros, criando novos registros ou atualizando os existentes:

POST (Criar) - Cria um novo item na plataforma de terceiros cada vez que o webhook é acionado. Exemplo: abrir um novo ticket no ServiceNow toda vez que a regra do Firewall da Internet bloqueia um fluxo de tráfego.
PUT (Atualizar) – Atualiza um item existente na plataforma de terceiros. A solicitação inclui um ID de item válido na URL ou corpo.

Métodos de Autenticação

Ao criar uma integração de Webhook, há diferentes métodos de autenticação para escolher:

Básico - Nome de usuário e senha
Portador - Token de Portador
Personalizado - Cabeçalhos personalizados para serviços que exigem autenticação exclusiva. Adicione pares de chave-valor conforme necessário.

Nota: Se o acesso ao serviço de terceiros for limitado a endereços IP específicos, por favor, consulte este artigo para a lista de endereços IP da Cato que você precisa permitir (você deve estar conectado para visualizar este artigo).

Personalizando o Conteúdo da Notificação

O campo content no modelo contém o resumo legível gerado do alerta, semelhante ao conteúdo do alerta por e-mail. Você pode escolher esses formatos para o conteúdo: contentText, contentMarkdown, ou contentHTML.

Se você optar por personalizar o corpo, há uma série de campos de dados que você pode usar no conteúdo da mensagem. Assim, você pode definir um corpo (ou estrutura) personalizado e então incorporar os campos de dados do Cato. Ao digitar $, os campos de dados disponíveis são exibidos e você seleciona o campo necessário. Os campos usam auto-completar para filtrar a lista. Para mais informações sobre os campos da Cato, veja Understanding the JSON Fields for Alert Integrations.

Valor Padrão para Campos de Webhook

Você pode definir valores padrão personalizados para campos dinâmicos de webhook para adicionar flexibilidade quando os dados de notificação não incluem um valor. Isso permite que você substitua o valor padrão NA na URL, cabeçalhos ou corpo do webhook. Use o formato ${field:defaultValue} para definir o valor de fallback. Por exemplo, você pode definir ${level:medium} se o campo nível não estiver preenchido. Em um fluxo correlacionado, você também pode usar um ID de fallback na URL do webhook, tal como https://EXAMPLE-INSTANCE.service-now.com/api/now/table/incident/${correlationId:12345}, de modo que notificações não correlacionadas sejam capturadas em um ticket padrão do ServiceNow.

Integrações de Webhook Padrão

Webhooks padrão permitem que você envie notificações CMA para plataformas de terceiros para uma ampla gama de casos de uso. Primeiro, defina o webhook para integrar com a plataforma. Em seguida, selecione quais notificações CMA e regras de política, como ações de firewall, gerarão notificações usando o webhook.

Definir uma Integração de Webhook

Crie uma integração de webhook que envie notificações via itens (ticket, mensagem Slack, etc.) na sua ferramenta de terceiros. Você pode configurar um webhook para criar novos itens com uma solicitação POST ou atualizar itens existentes com uma solicitação PUT. A integração inclui configurações para a URL, corpo da solicitação, método de autenticação e cabeçalhos personalizados opcionais e corpo da mensagem.

Após definir os detalhes, você pode testar a conexão e validar que está funcionando.

Para definir uma integração de Webhook:

No menu de navegação, clique em Conta > Assinaturas e selecione a aba Webhooks.
Clique em Novo Webhook. O painel Nova Integração de Webhook é aberto.
Configure os detalhes do Webhook:
1. Digite o Nome da integração.
2. Clique no controle deslizante para ativar (verde) ou desativar (cinza) a integração (está ativada por padrão).
Configure as configurações para o modelo JSON da integração:
- Em Iniciar a partir do modelo, selecione o modelo JSON padrão que preenche as configurações de integração.
  
  Você pode ajustar e modificar os campos para o Corpo Personalizado (veja abaixo, passo 7).
Nota: Se você escolher um modelo diferente, os campos no Corpo Personalizado serão redefinidos. Para mais informações sobre os modelos, veja abaixo Modelos e Campos.
Configure os Detalhes da Conexão:
1. Digite o URL para o serviço que está recebendo o Webhook.
  
  Você pode usar campos como variáveis na URL. Digite $ para ver os campos disponíveis.
2. No Método de Solicitação, selecione o fluxo para este webhook: POST ou PUT.
3. Se necessário, configure o Método de Autenticação e as configurações para o serviço.
(Opcional) Em Cabeçalhos Personalizados, defina a Chave e o Valor para cada cabeçalho HTTP adicional para a integração.
No Corpo Personalizado, defina o conteúdo da notificação de Webhook:
1. (Opcional) Personalize o conteúdo em Editar Corpo.
  - Digite / como o caractere de escape para usar $ no corpo
  - Digite $ para embutir outros campos
  O ID de Correlação de Resposta não é usado para integrações de webhook padrão
2. Para definir um valor padrão, use o formato ${field:defaultValue}, por exemplo ${ID:12345}
Clique em Teste. O CMA envia uma solicitação HTTP de teste com conteúdo gerado automaticamente para os campos.

Se a integração puder se conectar ao serviço, então uma mensagem de Teste passou com sucesso é exibida.

Se houver um erro de conexão, a página exibirá o código de erro HTTP e a mensagem relatados pelo serviço.
Clique em Salvar. A integração de Webhook é salva e adicionada à aba Integrações na página de Assinaturas.

Defina o Gatilho para Integrações de Webhook Padrão

Webhooks padrão são ativados por notificações do CMA. Você pode configurar dois tipos de notificações:

Notificações CMA: O CMA pode enviar proativamente notificações sobre sua conta, como usuários bloqueados e administradores, ou atualizações de licença. Essas notificações podem ser enviadas diretamente via uma integração de webhook.

Para mais informações, consulte Alertas de Nível de Conta e Notificações de Sistema.
Notificações de regra de política: Você pode configurar a configuração Rastrear em uma regra de política para enviar uma notificação para um webhook sempre que a regra for correspondida.

Ao definir regras em políticas, você pode usar a área de Ações para enviar notificações via integrações de webhook.

Integrações de Webhook Correlacionadas

O serviço XOps suporta webhooks correlacionados que permitem integrar o ciclo de vida de histórias de segurança e rede XOps com uma plataforma de terceiros. Após configurar a integração, a plataforma de terceiros automaticamente cria um novo ticket, problema ou mensagem quando uma história começa, e então a atualiza conforme a história avança ou é resolvida.

Essas integrações usam campos de correlação de Histórias de XOps para mapear cada história no CMA para um ticket, problema ou mensagem na plataforma externa. Isso garante que as atualizações sejam aplicadas consistentemente para o item correto. É necessário uma licença XOps.

Essas integrações requerem:

Uma integração de webhook padrão
Uma integração de webhook correlacionada
Dois tipos de acionadores (um para cada integração)

Defina um Webhook Padrão

Criar uma integração de webhook padrão para criar os itens iniciais (ticket, mensagem do Slack, etc.) na sua ferramenta de terceiros. Esses itens serão então atualizados pela integração de webhook correlacionada.

Após definir os detalhes, você pode testar a conexão e validar que está funcionando.

Para definir uma integração de Webhook padrão:

No menu de navegação, clique em Conta > Assinaturas e selecione a aba Webhooks.
Clique em Novo Webhook. O painel Nova Integração Webhook é aberto.
Configure os detalhes do Webhook:
1. Insira o Nome da integração.
2. Clique no controle deslizante para ativar (verde) ou desativar (cinza) a integração (está ativada por padrão).
Configure as configurações para o modelo JSON para a integração:
- Em Começar a partir do modelo, selecione o modelo JSON padrão que preenche as configurações da integração.
  
  Você pode ajustar e modificar os campos para o Corpo Personalizado (veja abaixo o passo 7).
Nota: Se você escolher um modelo diferente, os campos no Corpo Personalizado serão redefinidos. Para mais informações sobre os modelos, veja abaixo Modelos e Campos.
Configure os Detalhes da Conexão:
1. Insira o URL para o serviço que está recebendo o Webhook.
  
  Você pode usar campos como variáveis no URL. Digite $ para ver os campos disponíveis.
2. No Método de Solicitação, selecione POST.
3. Se necessário, configure o Método de Autenticação e as configurações para o serviço.
(Opcional) Em Cabeçalhos Personalizados, defina a Chave e o Valor para cada cabeçalho HTTP adicional para a integração.
Em Corpo Personalizado, defina o conteúdo da notificação do Webhook:
1. Em ID de Correlação de Resposta, defina o item em seu terceiro componente que você usará para correlação no URL. Por exemplo, no ServiceNow isso pode ser result.sys_id, e no Zendesk isso pode ser ticket.id.
2. (Opcional) Personalize o conteúdo em Editar Corpo.
  - Digite / como o caractere de escape para usar $ no corpo
  - Digite $ para incorporar outros campos
3. Para definir um valor padrão, use o formato ${field:defaultValue}, por exemplo ${ID:12345}
Clique em Teste. O CMA envia uma solicitação HTTP de teste com conteúdo gerado automaticamente para os campos.

Se a integração puder conectar-se ao serviço, então uma mensagem de Teste passou com sucesso será exibida.

Se houver um erro de conexão, a página exibirá o código de erro HTTP e a mensagem relatada pelo serviço.
Clique em Salvar. A integração de Webhook é salva e adicionada à guia Integrações na página de Assinaturas.

Defina um Webhook Correlacionado

Crie uma integração de webhook correlacionada que envie notificações através de itens (ticket, mensagem do Slack, etc.) na sua ferramenta de terceiros atualizando itens existentes criados no procedimento anterior.

Ao configurar um webhook correlacionado, a URL usa o ID de correlação para atualizar o item correto na plataforma de terceiros. Se o valor do ID de correlação estiver vazio, a atualização não poderá ser correspondida ao item existente e será perdida. Para evitar isso, adicione o item ID ao Corpo Personalizado do webhook padrão que cria o ticket, problema ou mensagem original. Isso permite que o webhook correlacionado use esse ID como valor de fallback para o campo de correlação, de modo que atualizações posteriores continuem a se aplicar ao item original ao longo do ciclo de vida do caso.

Após definir os detalhes, você pode testar a conexão e validar se funciona.

Para definir uma integração de Webhook correlacionada:

No menu de navegação, clique em Conta > Assinaturas e selecione a aba Webhooks.
Clique em Novo Webhook. O painel Nova Integração Webhook é aberto.
Configure os detalhes do Webhook:
1. Insira o Nome da integração.
2. Clique no controle deslizante para ativar (verde) ou desativar (cinza) a integração (está ativada por padrão).
Configure as configurações para o modelo JSON para a integração:
- Em Começar a partir do modelo, selecione o modelo JSON padrão que preenche as configurações da integração.
  
  Você pode ajustar e modificar os campos para o Corpo Personalizado (veja abaixo o passo 7).
Nota: Se você escolher um modelo diferente, os campos no Corpo Personalizado serão redefinidos. Para mais informações sobre os modelos, veja abaixo Modelos e Campos.
Configure os Detalhes da Conexão:
1. Insira o URL para o serviço que está recebendo o Webhook. Correlacione isso com um item existente adicionando o campo Id do Item Correlacionado.
  
  Você pode usar campos como variáveis no URL. Digite $ para ver os campos disponíveis.
2. No Método de Solicitação, selecione PUT.
3. Se necessário, configure o Método de Autenticação e as configurações para o serviço.
(Opcional) Em Cabeçalhos Personalizados, defina a Chave e o Valor para cada cabeçalho HTTP adicional para a integração.
Em Corpo Personalizado, defina o conteúdo da notificação do Webhook:
1. (Opcional) Personalize o conteúdo em Editar Corpo.
  - Digite / como o caractere de escape para usar $ no corpo
  - Digite $ para incorporar outros campos
2. Para definir um valor padrão, use o formato ${field:defaultValue}, por exemplo ${ID:12345}
Clique em Teste. O CMA envia uma solicitação HTTP de teste com conteúdo gerado automaticamente para os campos.

Se a integração puder conectar-se ao serviço, então uma mensagem de Teste passou com sucesso será exibida.

Se houver um erro de conexão, a página exibirá o código de erro HTTP e a mensagem relatada pelo serviço.
Clique em Salvar. A integração de Webhook é salva e adicionada à guia Integrações na página de Assinaturas.

Definir o Gatilho para a Integração de Webhook Padrão

Webhooks padrão são ativados por notificações do CMA. Você pode configurar dois tipos de notificações:

Notificações do CMA: O CMA pode enviar proativamente notificações sobre sua conta, como usuários bloqueados e administradores, ou atualizações de licença. Essas notificações podem ser enviadas diretamente via uma integração de webhook.

Para mais informações, consulte Alertas de Nível de Conta e Notificações do Sistema.
Notificações de regra de política: Você pode configurar a configuração Rastreamento em uma regra de política para enviar uma notificação a um webhook sempre que a regra for correspondente.

Ao definir regras em políticas, você pode usar a área Ações para enviar notificações via integrações de webhook.

Defina o Gatilho para a Integração Correlacionada usando Notificações de Detecção & Resposta Definido

Com políticas de Detecção e Resposta, você pode automatizar a criação e atualização de itens em plataformas de terceiros para histórias XOps correlacionadas. Assim, seu sistema externo sempre refletirá o estado atual da história.

Você pode configurar regras na política para:

História Criada: Aciona um webhook correlacionado que cria um novo item
História Atualizada: Aciona um webhook correlacionado que atualiza o mesmo item conforme a história avança

Para manter as histórias sincronizadas, configure duas regras: uma para criar o item quando a história começar e outra para atualizá-lo quando a história mudar.

Para definir o gatilho para uma notificação de webhook:

No menu de navegação, clique em Início > Política de Detecção e Resposta.
Selecione a aba Política de Resposta.
Clique em Novo. O painel de Adicionar à Política de Resposta abre.
Digite um Nome para a regra.
Na seção Fonte, selecione o tipo (por exemplo: Host, Faixa de IP, Site) e então selecione um ou mais objetos para a fonte de história para esta regra (ou você pode inserir um endereço IP).

O valor padrão de Fonte é Qualquer.
(Opcional) Defina Critérios que especificam as características que uma história deve ter para corresponder à regra.
Selecione o Gatilho para a regra.
- História Criada para criar novos itens
- História Atualizada para atualizar itens existentes
Na aba Resposta, selecione Enviar Notificação.
Em Enviar notificações para, selecione Integração.
Em Integração, selecione a integração de webhooks que está enviando notificações.
Clique em Salvar. A regra é adicionada à política.

Modelos e Campos

Cada webhook pode ser totalmente personalizado para corresponder ao formato e comportamento do sistema de terceiros. O webhook é fornecido em formato JSON e pode ser ajustado para se adaptar à estrutura da plataforma de destino. Use variáveis de campo do Cato para payloads estáticos e dinâmicos.

Após selecionar um modelo, você pode editar o corpo como um payload JSON e salvá-lo como um template Personalizado. Você também tem a opção de incorporar campos de dados no JSON, que colocarão o valor relevante no payload (ou NA se não estiver disponível).

Quando você digita $, os campos disponíveis são exibidos. Para obter mais informações sobre os campos Cato, veja Compreendendo os Campos JSON para Integrações de Alertas.

Você pode escolher entre estes modelos ao criar um webhook:

Todos os campos - inclui todos os campos disponíveis
Básico - um modelo com os campos mais comumente usados
Jira - um modelo básico de Jira
ServiceNow Criar Ticket - cria um novo ticket no ServiceNow
ServiceNow Atualizar Ticket - atualiza um ticket existente no ServiceNow
Slack - envia uma mensagem para um canal do Slack
Zendesk Criar Ticket - cria um novo ticket no Zendesk
Zendesk Atualizar Ticket - atualiza um ticket existente no Zendesk
Personalizado - personaliza configurações para um modelo

Você também pode usar campos ao definir a URL de uma integração de webhook.