Preciso de uma chave de API botoi para este fluxo de trabalho?

Não. O nível gratuito permite cinco solicitações por minuto sem chave de API. O fluxo de trabalho faz 3 solicitações por execução (SPF, DMARC, DKIM), o que se enquadra no limite. Se você executar verificações em vários domínios ou seletores, adicione sua chave de API como um segredo do GitHub e passe-a no cabeçalho de autorização.

Posso verificar vários domínios em uma execução de fluxo de trabalho?

Sim. Faça um loop em uma série de domínios no script de verificação. Cada domínio requer três chamadas de API, portanto, uma execução de nível gratuito lida com um domínio por invocação. Para vários domínios, adicione uma chave de API botoi para evitar limitação de taxa.

Qual seletor DKIM devo usar?

O seletor depende do seu provedor de e-mail. O Google Workspace usa "google", o Microsoft 365 usa "selector1" e "selector2", o Amazon SES usa um seletor baseado em UUID. Verifique seus registros DNS TXT em busca de entradas que correspondam ao padrão [seletor]._domainkey.seudominio.com.

Este fluxo de trabalho bloqueará minhas implantações?

Somente se uma verificação falhar, o que significa que seus registros de segurança de e-mail estão ausentes ou configurados incorretamente. Esse é o ponto: você deseja detectar esses problemas antes que eles causem problemas de entrega. Você pode alterar o fluxo de trabalho para postar um aviso em vez de falhar, substituindo "saída 1" por uma etapa que cria um problema no GitHub ou envia uma mensagem do Slack.

Com que frequência devo executar essa verificação?

Em cada push para seu branch principal está a linha de base. Adicione um cron trigger programado (por exemplo, diariamente às 9h) para capturar alterações de DNS feitas fora do seu repositório, como quando um colega de equipe edita registros no painel do registrador.

Integration

Audite a segurança de e-mail do seu domínio em cada push com GitHub Actions

26 de mar. de 2026 | 7 min read

Uma ação do GitHub que verifica os registros SPF, DMARC e DKIM usando a API botoi e falha na compilação se algum registro estiver ausente ou configurado incorretamente.

GitHub Actions workflow running in a terminal — Photo by Roman Synkevych on Unsplash

Alguém da sua equipe atualiza um registro DNS. Uma entrada TXT é excluída durante uma migração de provedor. Seu registro SPF excede silenciosamente o limite de 10 pesquisas. Os e-mails começam a chegar ao spam. Ninguém avisos por duas semanas até que um cliente mencione que nunca recebeu sua fatura.

Os registros de segurança de e-mail baseados em DNS (SPF, DMARC, DKIM) são o tipo de infraestrutura que funciona perfeitamente até que isso não aconteça. Quando quebra, o modo de falha é silencioso: sem erros, sem alertas, os e-mails desaparecem em pastas de spam.

Este guia configura uma ação GitHub que valida todos os três registros em cada push. Se qualquer registro estiver faltando ou configurado incorretamente, o fluxo de trabalho falhará e informará o que quebrou.

O que o fluxo de trabalho faz

Em cada impulso para main, a ação:

Chama o botoi /v1/dns-security/spf-check endpoint para validar seu registro SPF
Chamadas /v1/dns-security/dmarc-check para validar sua política DMARC
Chamadas /v1/dns-security/dkim-check para verificar se sua chave DKIM foi publicada
Sai com um código diferente de zero se alguma verificação falhar, bloqueando a mesclagem

O fluxo de trabalho do GitHub Action

Criar .github/workflows/dns-security.yml no seu repositório:

Substituir yourdomain.com com seu domínio e google com o seletor DKIM do seu provedor de e-mail. O fluxo de trabalho é executado em cada push para main, em uma programação diária e pode ser acionado manualmente na guia Ações.

O que cada verificação valida

SPF (Estrutura de Política do Remetente)

O SPF declara quais servidores de e-mail estão autorizados a enviar e-mails para o seu domínio. A API retorna o registro bruto, uma lista analisada de mecanismos e se o registro é válido.

Campos principais a serem observados:

has_spf: Existe um registro TXT começando com v=spf1? Se for falso, qualquer servidor pode alegar enviar e-mails do seu domínio.
valid: O registro é analisado corretamente? Os registros SPF quebram quando eles excedem o limite de pesquisa de 10 DNS ou contêm erros de sintaxe.
all_policy: O mecanismo de rastreamento. -all (falha grave) é a configuração mais forte. ~all (soft fail) marca e-mails não autorizados como suspeito. +all anula totalmente o propósito do FPS.

Exemplo de resposta da API para um registro SPF íntegro:

DMARC (Autenticação, Relatórios e Conformidade de Mensagens Baseadas em Domínio)

O DMARC informa aos servidores receptores o que fazer quando as verificações SPF ou DKIM falham. Sem isso, mesmo os registros SPF e DKIM válidos não impedem a falsificação.

Campos principais a serem observados:

policy: o que acontece com mensagens com falha. reject gotas eles, quarantine os envia para spam, none não toma nenhuma ação (somente monitoramento).
pct: a porcentagem de mensagens às quais a política se aplica. Comece em um nível baixo número durante a implementação e, em seguida, vá para 100.
reporting.rua: Para onde os relatórios agregados são enviados. Sem isso, você não têm visibilidade sobre falhas de autenticação.

Exemplo de resposta da API para um registro DMARC:

DKIM (correio identificado por DomainKeys)

DKIM adiciona uma assinatura criptográfica às mensagens enviadas. Os servidores receptores verificam o assinatura contra uma chave pública publicada em seu DNS. Se a chave estiver faltando ou girada sem atualizar o DNS, a verificação da assinatura falha.

Campos principais a serem observados:

has_dkim: Uma chave DKIM foi publicada para o seletor fornecido? Cada e-mail provedor usa um nome de seletor diferente.
public_key_length: O NIST recomenda um mínimo de 2.048 bits. Chaves mais curtas mais de 1024 bits são considerados fracos.
key_type: a maioria das chaves usa RSA. As chaves Ed25519 são menores e mais rápidas, mas têm suporte limitado entre provedores de correio.

Exemplo de resposta da API para uma verificação DKIM:

Seletores DKIM comuns por provedor

Provedor de e-mail	Seletor(es) DKIM
Google Workspace	`google`
Microsoft 365	`selector1`, `selector2`
Amazon SES	Baseado em UUID (verifique seu painel SES)
Mailchimp / Mandril	`k1`
SendGrid	`s1`, `s2`
Carimbo postal	Gerado por domínio (verifique as configurações de DNS)

Estendendo o fluxo de trabalho

Vários domínios

Se você gerencia vários domínios, use uma estratégia matricial para verificar cada um deles. Adicione um botoi Chave de API como segredo do GitHub para evitar atingir o limite de taxa do nível gratuito.

Notificações do Slack em caso de falha

Adicione uma etapa de notificação que é acionada quando alguma verificação falha. Isso usa o Ação oficial do Slack GitHub:

Configuração do monorepo

Em um monorepo, você provavelmente não deseja que as verificações de DNS sejam executadas a cada push para cada pacote. Defina o escopo do gatilho para alterações em arquivos relacionados à infraestrutura:

O gatilho programado ainda é executado diariamente, independentemente dos filtros de caminho, para que você capture o DNS alterações feitas fora do repositório.

Usando uma chave de API para limites de taxas mais altos

Se você verifica vários domínios ou executa o fluxo de trabalho com frequência, adicione sua chave de API botoi como um segredo do GitHub Actions:

Vá para Configurações do seu repositório > Segredos e variáveis > Ações
Adicione um segredo chamado BOTOI_API_KEY
Adicione o cabeçalho de autenticação a cada comando curl:

O que fazer quando as verificações falham

Registro SPF ausente: Adicione um registro TXT ao DNS do seu domínio. Comece com v=spf1 include:_spf.google.com ~all (substitua o include pelo seu domínio SPF do provedor de e-mail).
Registro SPF inválido: Você provavelmente atingiu o limite de pesquisa de 10 DNS. Use um Ferramenta de achatamento SPF para substituir include: mecanismos com endereços IP, ou consolidar provedores.
Registro DMARC ausente: Adicione um registro TXT em _dmarc.yourdomain.com. Comece com v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com monitorar antes de aplicar.
A política DMARC é "nenhuma": Isso é bom durante a implementação. Depois de confirmar e-mail legítimo passa por SPF e DKIM, vá para p=quarantine e então p=reject.
Registro DKIM ausente: Verifique se você tem o seletor correto para o seu provedor de e-mail (veja a tabela acima). A chave deve ser publicada como um registro TXT em [selector]._domainkey.yourdomain.com.
Chave DKIM muito curta: Gire sua chave DKIM para 2.048 bits por meio de seu painel de administração do provedor de e-mail e atualize o registro DNS TXT.

FAQ

Preciso de uma chave de API botoi para este fluxo de trabalho?: Não. O nível gratuito permite cinco solicitações por minuto sem chave de API. O fluxo de trabalho faz 3 solicitações por execução (SPF, DMARC, DKIM), o que se enquadra no limite. Se você executar verificações em vários domínios ou seletores, adicione sua chave de API como um segredo do GitHub e passe-a no cabeçalho de autorização.
Posso verificar vários domínios em uma execução de fluxo de trabalho?: Sim. Faça um loop em uma série de domínios no script de verificação. Cada domínio requer três chamadas de API, portanto, uma execução de nível gratuito lida com um domínio por invocação. Para vários domínios, adicione uma chave de API botoi para evitar limitação de taxa.
Qual seletor DKIM devo usar?: O seletor depende do seu provedor de e-mail. O Google Workspace usa "google", o Microsoft 365 usa "selector1" e "selector2", o Amazon SES usa um seletor baseado em UUID. Verifique seus registros DNS TXT em busca de entradas que correspondam ao padrão [seletor]._domainkey.seudominio.com.
Este fluxo de trabalho bloqueará minhas implantações?: Somente se uma verificação falhar, o que significa que seus registros de segurança de e-mail estão ausentes ou configurados incorretamente. Esse é o ponto: você deseja detectar esses problemas antes que eles causem problemas de entrega. Você pode alterar o fluxo de trabalho para postar um aviso em vez de falhar, substituindo "saída 1" por uma etapa que cria um problema no GitHub ou envia uma mensagem do Slack.
Com que frequência devo executar essa verificação?: Em cada push para seu branch principal está a linha de base. Adicione um cron trigger programado (por exemplo, diariamente às 9h) para capturar alterações de DNS feitas fora do seu repositório, como quando um colega de equipe edita registros no painel do registrador.

Comece a construir com botoi

150+ endpoints de API para consultas, processamento de texto, geração de imagens e utilitários para desenvolvedores. Plano gratuito, sem cartão de crédito.

Ver documentação da API Ver todas as ferramentas