Skip to main content

​
Visão Geral

O ZeroPath publica notificações de scan e alertas de vulnerabilidades em canais do Microsoft Teams como Adaptive Cards. Cada canal de destino é registrado separadamente, e as regras de notificação escolhem quais eventos vão para quais canais. O ZeroPath entrega em uma URL de incoming webhook por canal, criada pelo Teams Workflows. Cada canal pode usar Webhook URL only ou autenticação Microsoft Entra ID com seu próprio tenant ID, client ID e segredo de cliente. A autenticação Entra exige um aplicativo registrado no tenant do workflow; não exige permissões do Microsoft Graph.
Trate URLs de webhook e segredos de cliente como senhas. O ZeroPath os armazena criptografados e nunca os exibe novamente. Em workflows que usam apenas a URL, qualquer pessoa que a tenha pode publicar no canal.

​
Configuração

​
  1. Crie o webhook no Teams

Faça isso uma vez para cada canal em que deseja receber alertas.
  1. No Microsoft Teams, abra o canal e escolha … (Mais opções) → Workflows.
  2. Selecione o modelo “Post to a channel when a webhook request is received”.
  3. Confirme a equipe e o canal e clique em Add workflow. Abra o gatilho When a Teams webhook request is received e configure Who can trigger the flow?:
    • Anyone para entrega usando apenas a URL.
    • Specific users in my tenant para autenticação Entra; siga os passos abaixo. Any user in my tenant também aceita autenticação Entra, mas não restringe a chamada a um único service principal.
  4. Salve o workflow e copie a HTTP POST URL atual. A Microsoft usa hosts como *.logic.azure.com e *.powerplatform.com.

​
Configure a autenticação Microsoft Entra

  1. No centro de administração Microsoft Entra, abra App registrations → New registration e registre um aplicativo no diretório da sua organização. Se não tiver permissão, peça ajuda ao administrador do tenant.
  2. Copie Directory (tenant) ID e Application (client) ID da visão geral do aplicativo.
  3. Em Certificates & secrets, crie um segredo de cliente e copie seu Value imediatamente. Use o valor do segredo, não seu ID. Anote a data de expiração para substituí-lo a tempo.
  4. Em Enterprise applications, encontre o aplicativo pelo client ID e copie seu Object ID. Esse é o ID do service principal, diferente do client ID e do object ID em App registrations.
  5. No gatilho do workflow, escolha Specific users in my tenant e insira o object ID do service principal em Allowed users. Salve e copie a URL atual do webhook.
O ZeroPath obtém e renova os tokens do serviço Power Automate automaticamente. Não é necessário colar tokens de acesso nem conceder permissões do Microsoft Graph. A autenticação suporta atualmente a nuvem pública da Microsoft. Consulte a documentação de autenticação de workflows da Microsoft para detalhes das restrições de tenant e identidades permitidas.
Criar um workflow exige permissão para adicionar workflows àquela equipe. Se o menu Workflows não aparecer, peça a um proprietário da equipe que crie o workflow e lhe envie a URL.

​
  1. Registre o canal no ZeroPath

  1. Navegue até Settings → Integrations no painel do ZeroPath.
  2. Clique em Add Integration e depois em Microsoft Teams.
  3. Informe um rótulo do canal — é ele que aparece no seletor das regras de notificação, então use o nome do canal (por exemplo #appsec-alerts).
  4. Cole a HTTP POST URL do passo 1.
  5. Selecione Webhook URL only para um workflow Anyone, ou Microsoft Entra ID e informe tenant ID, client ID e valor do segredo de cliente.
  6. Salve o canal. Salvar armazena a configuração; use Send a test message para verificar a entrega.
O ZeroPath valida o host da URL antes de aceitá-la; apenas hosts de webhook emitidos pela Microsoft (*.logic.azure.com, *.webhook.office.com, *.azure-apihub.net, *.powerplatform.com) sobre HTTPS são permitidos. Para adicionar mais canais depois, selecione a integração Microsoft Teams em Settings → Integrations e use Add a channel.

​
  1. Envie uma mensagem de teste

No painel da integração Microsoft Teams, clique no ícone de envio ao lado de um canal. O ZeroPath publica um card de confirmação usando o mesmo formato de payload das notificações reais, então um teste bem-sucedido comprova que o canal aceita o que o ZeroPath realmente envia — e não apenas que a URL responde.

​
  1. Direcione notificações para o canal

Canais do Teams não recebem nada até que uma regra de notificação os selecione.
  1. Navegue até Settings → Notifications.
  2. Crie uma regra (ou edite uma existente) e selecione Microsoft Teams como canal.
  3. Marque os canais do Teams para os quais a regra deve entregar.
  4. Escolha os tipos de evento, o escopo de repositórios e o limite de pontuação de vulnerabilidade.
Uma regra que seleciona Microsoft Teams precisa indicar ao menos um canal do Teams, para que nunca exista uma regra habilitada que não entrega em lugar algum.

​
Tipos de Notificação

Qualquer evento de notificação suportado pelo ZeroPath pode ser direcionado ao Teams, incluindo: Defina um limite de pontuação de vulnerabilidade (0–100) na regra para filtrar ruído de baixa severidade: apenas descobertas com pontuação igual ou superior ao limite são incluídas.

​
Formato da Notificação

Notificações de novas vulnerabilidades renderizam uma seção de card por descoberta, mostrando:
  • Título — com link direto para a descoberta no aplicativo ZeroPath
  • Severidade — selo colorido com a pontuação composta (por exemplo 🔴 Critical (92))
  • Status — status atual da descoberta (Open, Patched, False positive, …)
  • Arquivo afetado — o arquivo e a linha onde a descoberta foi detectada
  • Pull request — o PR que disparou o scan, em notificações de scan de PR
  • Introduzido por — o autor do git blame que introduziu as linhas vulneráveis, quando disponível
  • Trecho da descrição — um resumo curto da descoberta
Até cinco descobertas aparecem por mensagem, das mais severas para as menos severas. Quando existem mais descobertas do que isso, o card termina com um link para os resultados completos do scan no ZeroPath. Notificações do Teams e do Slack são geradas a partir dos mesmos modelos de evento, então os dois canais permanecem consistentes em texto, truncamento e em quais descobertas incluem.

​
Gerenciando Canais

Selecione a integração Microsoft Teams em Settings → Integrations para gerenciar os destinos:
  • Enviar uma mensagem de teste — verifica se o webhook ainda aceita publicações.
  • Edit authentication — altere o modo de autenticação, substitua credenciais ou informe uma nova URL sem mudar as regras de notificação do canal. Deixe a URL de substituição vazia para manter a atual. Atualizações Entra exigem o valor do segredo a cada salvamento; segredos salvos nunca são preenchidos no formulário.
  • Remover um canal — exclui a URL de webhook armazenada. As regras de notificação que o indicavam são atualizadas: o canal é removido de cada regra, regras que ficam sem canais do Teams deixam de direcionar ao Teams, e uma regra que fica sem nenhum canal é desabilitada.
  • Desconectar o Microsoft Teams — remove todos os canais registrados e atualiza as regras que os utilizavam.
Um canal exibido como Paused é ignorado na entrega. O ZeroPath pausa canais cujos webhooks ou credenciais a Microsoft rejeita permanentemente. Atualize a configuração em Edit authentication e envie uma mensagem de teste. Um teste bem-sucedido reativa a entrega; apenas salvar não reativa o canal. Para substituir um segredo, crie um novo no Entra, salve seu valor em Edit authentication e envie um teste antes de revogar o antigo. Se a Microsoft alterar a URL do webhook ao mudar o modo de autenticação, informe a nova URL na mesma atualização.

​
Limitação de Taxa

As entregas para cada canal do Teams são espaçadas de forma independente, e um canal que começa a falhar sofre recuo exponencial. Assim, um destino com problemas não pode atrasar as entregas para os seus outros canais ou para outras integrações. O Teams rejeita cards muito grandes, então o ZeroPath trunca títulos, descrições e cabeçalhos para manter cada card confortavelmente dentro do limite.

​
Solução de Problemas

Não estou recebendo notificações
  • Confirme que uma regra de notificação seleciona Microsoft Teams e marca o canal específico — registrar um canal, por si só, não entrega nada.
  • Verifique se a regra está habilitada e cobre o repositório e o tipo de evento esperados.
  • Verifique se o limite de pontuação não está filtrando todas as descobertas.
  • Envie uma mensagem de teste para confirmar que o webhook ainda funciona.
“Invalid Microsoft Teams webhook URL”
  • A URL precisa ser HTTPS e estar em um host de webhook da Microsoft. Copie a HTTP POST URL do próprio workflow do Teams, em vez da barra de endereços do navegador, e cole-a por completo.
O canal aparece como Paused
  • Verifique se o workflow existe e está ligado. Em canais autenticados, confirme que o segredo não expirou e que o service principal está autorizado no gatilho. Atualize a configuração e envie um teste para reativar a entrega.
Falha na autenticação
  • Confirme que o tenant ID e o client ID pertencem ao tenant do workflow e use o valor do segredo, não seu ID.
  • Em Specific users in my tenant, use o object ID do service principal de Enterprise applications em Allowed users.
  • O modo do ZeroPath deve corresponder ao workflow: apenas URL exige Anyone; Entra exige um gatilho autenticado. A Microsoft rejeita o cabeçalho Authorization em gatilhos Anyone.
  • Substitua credenciais expiradas ou revogadas em Edit authentication. Falhas temporárias e limites de requisições do serviço de tokens são tratados com novas tentativas, sem pausar o canal.
O Teams exibe um card com < ou &amp; literais
  • Reporte isso como um bug: o texto das notificações é traduzido do dialeto de marcação do Slack para o markdown que o Teams renderiza, e escapes remanescentes indicam um template que ignorou essa tradução.