O Secret Scanner detecta possíveis chaves de API, tokens de acesso, credenciais, URLs de webhook e outros valores sensíveis em ativos Apidog suportados. As descobertas mostram onde um possível segredo aparece sem exibir seu valor completo.
Este tutorial explica como revisar uma descoberta, responder a uma exposição real, registrar a resolução e adicionar um padrão de detecção personalizado quando sua equipe usa um formato de segredo interno.
Antes de começar
O Secret Scanner está disponível no plano Enterprise SaaS. Ele não está atualmente disponível no Apidog On-Premises.
O acesso depende do seu papel:
| Função | Ações disponíveis |
|---|---|
| Proprietário ou Administrador da Organização | Visualizar relatórios de nível de organização entre equipes |
| Proprietário ou Administrador da Equipe | Revisar descobertas da equipe, resolver ou reabrir descobertas, gerenciar padrões personalizados e visualizar análises |
| Membro da Equipe ou Convidado | Visualizar descobertas apenas para projetos que podem acessar |
Use valores fictícios ao testar. Nunca cole uma credencial real em um recurso simplesmente para confirmar que a verificação funciona.
Passo 1: Revise o relatório da organização
Os Proprietários e Administradores da Organização podem usar o relatório da organização para identificar equipes com descobertas não resolvidas.
- Abra o relatório de nível de organização do Secret Scanner.
- Revise as contagens de descobertas não resolvidas e vazamentos publicados.
- Verifique a última hora detectada e o status da verificação.
- Abra a equipe afetada ou entre em contato com seu Proprietário ou Administrador de Equipe.
O relatório da organização ajuda os administradores a identificar quais equipes precisam de acompanhamento.
O relatório é uma visão de triagem. A investigação e a resolução ocorrem nas páginas do Secret Scanner da equipe afetada.
Passo 2: Abra e filtre as descobertas da equipe
Na equipe, abra o Secret Scanner e selecione Secrets Detected (Segredos Detectados).
Use os filtros disponíveis para restringir a lista por:
- status
- projeto
- padrão
- tipo de recurso
- palavra-chave
Cada descoberta é agrupada por seu padrão de detecção e uma impressão digital segura. Uma descoberta pode ter várias ocorrências quando o mesmo valor detectado aparece em mais de um local.
Os valores são mascarados. Use o projeto, tipo de recurso, contagem de ocorrências e localização da fonte para investigar a descoberta.
Comece com as descobertas não resolvidas marcadas como exposição publicada e, em seguida, revise as descobertas que aparecem em vários recursos ou projetos.
Passo 3: Inspecione cada ocorrência
Abra uma descoberta e revise suas ocorrências. Para cada ocorrência, confirme:
- o projeto e o recurso que contêm o valor
- o tipo de recurso e o local da fonte
- se o valor aparece na documentação publicada
- a primeira e a última vez detectadas
- se o valor é uma credencial real ou um falso positivo
Não confie apenas no trecho mascarado ao decidir se um valor é real. Verifique o recurso de origem e, quando necessário, peça ao proprietário do recurso para identificar o sistema emissor sem copiar a credencial para um ticket ou mensagem de chat.
Passo 4: Responda a uma exposição real
O Secret Scanner relata uma possível exposição; ele não altera a credencial. Lide com um segredo confirmado no sistema onde foi emitido.
Use esta ordem:
- Revogue, rotacione ou invalide a credencial no serviço externo.
- Revise os logs de uso disponíveis para atividades inesperadas.
- Remova o valor de todas as ocorrências de origem mostradas no Apidog.
- Substitua o valor bruto por uma variável apropriada ou referência de Segredo do Vault quando o fluxo de trabalho ainda precisar da credencial.
- Salve cada recurso alterado para que uma verificação assíncrona possa ser executada novamente.
Se a credencial aparecer em documentação publicada, trate-a como exposta externamente, mesmo quando nenhum uso suspeito for visível.
Remover um valor do Apidog não invalida cópias que já possam existir em outros lugares. A rotação ou revogação é a ação de contenção primária para um vazamento real.
Passo 5: Registre a resolução
Após a conclusão da resposta, defina o motivo da resolução da descoberta.
| Motivo da resolução | Use quando |
|---|---|
| Revogado | O valor era um segredo real e foi revogado, rotacionado ou invalidado fora do Apidog |
| Falso positivo | O valor detectado não é um segredo |
| Não será corrigido | O valor é um segredo real, mas a equipe aceitou o risco e não o alterará |
Marcar uma descoberta como resolvida apenas altera seu status no Apidog. Não revoga, rotaciona, invalida, remove ou substitui o valor subjacente.
Se ações adicionais se tornarem necessárias, reabra a descoberta.
Passo 6: Verifique a limpeza
O Secret Scanner é executado assincronamente em vez de em tempo real. As verificações são acionadas quando um recurso suportado é adicionado ou quando Salvar é selecionado após a alteração de um recurso suportado.
Após a remediação:
- confirme que todas as ocorrências de origem conhecidas foram alteradas
- salve os recursos afetados
- permita tempo para a verificação assíncrona
- revise a descoberta e seu último horário detectado
- confirme separadamente que a credencial antiga não funciona mais no serviço emissor
O status do scanner não é um teste de validade de credencial. Verifique a revogação no serviço externo.
Passo 7: Adicione um padrão de detecção personalizado
Os Proprietários e Administradores de Equipe podem criar padrões personalizados para formatos de segredos específicos da organização.
- Abra Secret Scanner > Patterns (Padrões).
- Selecione a opção para criar um padrão personalizado.
- Insira um nome claro.
- Adicione a expressão regular e quaisquer palavras-chave úteis.
- Teste com um valor fictício.
- Habilite o padrão e salve-o.
Os limites atuais são:
- até 5 padrões personalizados por equipe;
- nome do padrão de até 128 caracteres;
- expressão regular de até 256 caracteres na UI;
- até 10 palavras-chave;
- cada palavra-chave de até 64 caracteres.
Os padrões integrados são somente leitura. Suas expressões regulares internas não são exibidas e não podem ser editadas, excluídas, habilitadas ou desabilitadas.
Passo 8: Revise as análises da equipe
Os Proprietários e Administradores de Equipe podem abrir Analytics (Análises) para revisar onde as descobertas estão concentradas.
Use as análises para identificar projetos, padrões e tipos de ativos que precisam de revisão adicional.
As análises podem ajudar a priorizar o trabalho, mas cada descoberta ainda requer investigação em nível de fonte.
Tipos de ativos suportados
O Secret Scanner atualmente verifica ativos suportados, incluindo:
- APIs e requisições de API
- Casos de API
- Módulos de projeto e variáveis de módulos de projeto
- Exemplos de resposta
- Documentos Markdown e esquemas de dados
- Variáveis de ambiente, globais e de equipe
- Scripts comuns e parâmetros comuns
O detalhe da fonte disponível para uma ocorrência depende do seu tipo de recurso e das permissões do visualizador.
Solução de problemas
| Problema | O que verificar |
|---|---|
| Uma alteração recente ainda não teve resultado | A verificação é assíncrona. Confirme se o recurso foi salvo e revise-o novamente mais tarde. |
| Um membro da equipe não consegue ver uma descoberta | Confirme se o membro tem acesso ao projeto relacionado. |
| Um usuário não consegue gerenciar padrões ou análises | O gerenciamento de padrões e as análises exigem acesso de Proprietário ou Administrador da Equipe. |
| Uma descoberta resolvida ainda contém um segredo funcional | O status de resolução não altera a credencial. Revogue-a ou rotacione-a no serviço emissor. |
| Um repositório externo não é verificado | O Secret Scanner não verifica repositórios externos do GitHub ou GitLab. Use também os controles de verificação do provedor de repositório. |
Limitações importantes
O Secret Scanner não impede que usuários insiram segredos, bloqueie a publicação de documentação, verifique repositórios externos ou garanta a detecção de todos os formatos de segredos. Ele também não remove automaticamente valores de origem ou os substitui por variáveis ou referências do Vault.
Use-o como parte de um processo de gerenciamento de credenciais que também inclui emissão de privilégio mínimo, armazenamento seguro, rotação, revogação e monitoramento de uso.
Tutoriais relacionados sobre governança de API:
Esses tutoriais abordam controles complementares para governar um espaço de trabalho de API empresarial:
- Estrutura de Governança de API — conecta propriedade, controles, evidências e decisões de ciclo de vida.
- Mapeamento de Grupo SAML com Microsoft Entra ID — atribui acesso a equipes a partir de grupos de provedores de identidade.
- Secret Scanner — revisa possíveis credenciais expostas em ativos Apidog suportados.
- Logs de Auditoria — investiga e exporta atividades administrativas da organização.
- Provisionamento SCIM — gerencia usuários da organização durante o ciclo de vida da identidade.
- Políticas Empresariais — configura controles de credenciais, associações, sessões SSO e convites.
- Equipes de API de Autoatendimento Governadas — permite equipes criadas por membros, mantendo a supervisão da propriedade.
- Integração GitHub Enterprise Cloud — conecta repositórios GHE.com suportados para fluxos de trabalho OpenAPI.
Documentação oficial relacionada: