Tokens de API

​

Visão Geral

​

Criando Tokens

1. Acesse Settings → API Tokens no painel da ZeroPath (zeropath.com/app/settings/api).
2. Clique em “Create Token”.
3. Informe um nome (opcional, para identificação).
4. Defina uma expiração (1–365 dias, padrão: 30 dias).
5. Clique em Create.
6. Copie o Token Secret imediatamente — ele é exibido apenas uma vez e não pode ser recuperado depois.

• Token ID — um UUID que identifica o token (seguro para registrar em logs).
• Token Secret — a chave secreta (trate como uma senha).

​

Cabeçalhos de Autenticação

X-ZeroPath-API-Token-Id: <your-token-id>
X-ZeroPath-API-Token-Secret: <your-token-secret>

​

Exemplo

curl -X POST https://zeropath.com/api/v2/vulnerabilities/search \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: your-token-id" \
  -H "X-ZeroPath-API-Token-Secret: your-token-secret" \
  -d '{"query": "SQL injection in API endpoints"}'

​

Superfícies de API Suportadas

• Vulnerabilidades — liste, pesquise e gerencie descobertas de segurança, incluindo metadados de remediação e de patch quando disponíveis. Quando um issue do Jira está vinculado a uma descoberta, a resposta da API inclui o título do issue do Jira junto ao ID e à URL do issue já existentes. Você pode filtrar a lista de issues por veredicto de validação em runtime para restringir os resultados a issues com desfechos de validação específicos. Quando um issue foi marcado manualmente como não explorável, a resposta inclui um campo nonExploitableReason contendo a justificativa humana da triagem (distinta do validationSecurityAssessment gerado pelo sistema). Os metadados de status de patch agora incluem o stage da geração atual, permitindo acompanhar o progresso do patch em tempo real. Você pode recuperar todas as justificativas humanas de triagem registradas nas descobertas de um repositório — incluindo falsos positivos, veredictos de não explorável, verdadeiros positivos e mudanças de severidade — com um campo disposition por entrada indicando a ação de triagem. Você pode atualizar notas de usuário de texto livre em issues individuais (compartilhadas na organização, até 5.000 caracteres; enviar um valor vazio ou apenas com espaços em branco limpa a nota). Você também pode regenerar patches para issues — e, se um issue tiver sido marcado como não corrigível, pode passar force=true para sobrescrever essa marcação e solicitar uma nova tentativa de patch. Você pode atualizar a classificação de severidade de um issue por rótulo (por exemplo, rebaixar um “High” para “Medium”) — a plataforma ajusta a pontuação de severidade subjacente para cair na faixa solicitada. Evidências entre repositórios são incluídas nos detalhes do issue quando o scanner identifica código relacionado em múltiplos repositórios, dando visibilidade completa de cadeias de vulnerabilidade multi-repositório. Você pode excluir branches específicos de repositórios dos resultados da lista de issues usando filtros excludedRepositoryBranches
• SCA — liste vulnerabilidades de dependências com severidade, dados de alcançabilidade e metadados de status de patch quando existe uma remediação. Você pode filtrar alertas e vulnerabilidades de SCA apenas para aqueles associados a aplicações expostas pelo Wiz. Os avisos de SCA agora incluem campos de inteligência de exploração — status no CISA KEV (isKnownExploited, kevDateAdded, kevKnownRansomware) e pontuações FIRST EPSS (epssScore, epssPercentile) — para que você possa priorizar com base em dados de exploração no mundo real. Você pode listar avisos de cobertura de resolução de dependências para identificar manifestos em que a árvore de dependências não pôde ser totalmente resolvida, e consultar a cobertura de resolução por ecossistema para quantificar o quão completa é sua verificação de dependências entre os repositórios
• Relatórios — gere relatórios de segurança nos formatos DOCX, CSV, SARIF ou SBOM. Se a geração do relatório falhar, o status do relatório é atualizado para failed com uma mensagem de erro descrevendo o que deu errado
• Relatórios Personalizados — crie, liste e exclua configurações de filtros salvas, recupere estatísticas agregadas (distribuição de severidade, principais classes de vulnerabilidade, MTTR, tendências) e descubra os campos de filtro disponíveis por meio do endpoint de schema de filtros
• Endpoints — busca semântica em endpoints e manipuladores de dados detectados
• Agente — gerencie gatilhos de eventos, patches, pull requests, instruções globais do agente, histórico de gatilhos, streaming de jobs em tempo real via SSE e playbooks (ative, pause e desinstale fluxos de automação de segurança pré-construídos de uma biblioteca de templates). Os templates de playbook suportam tipos de parâmetro ricos, incluindo texto, número, alternadores booleanos e menus de seleção, dando controle refinado ao ativar fluxos de trabalho. Operações somente leitura — incluindo listar gatilhos de eventos, instâncias de playbook e histórico de gatilhos, recuperar um evento de gatilho específico e ler as instruções globais — exigem apenas a permissão Agent View; você não precisa de Agent Run para consultar esses recursos. Conversas e jobs do agente são delimitados pelo controle de acesso no nível de repositório — se uma conversa está vinculada a um repositório, apenas usuários com acesso de visualização a esse repositório podem listar, ler, enviar mensagens ou arquivar a conversa. Perder o acesso ao repositório oculta automaticamente essas conversas e jobs de todos os endpoints do agente
• Verificações de Código Sob Demanda Beta — envie diffs, arquivos e trechos de código para revisão de segurança assíncrona a partir de CLIs, IDEs, hooks de pre-commit e integrações personalizadas
• Pacotes de Regras — navegue por conjuntos curados de templates de regras SAST em linguagem natural cobrindo conformidade, privacidade, logging e mais; habilite ou desabilite templates individuais ou pacotes inteiros para sua organização
• Regras Personalizadas — crie, atualize e liste regras de segurança em linguagem natural. As regras podem ter escopo de todos os repositórios (padrão), de repositórios específicos ou por tag — passe tagIds sem repositoryIds para restringir uma regra aos repositórios que carregam essas tags. A resposta de cada regra inclui um campo scope (allRepositories, repositories ou tags) para que você veja como ela é aplicada
• Organizações — gerencie organizações, liste/convide/remova membros e atualize os papéis dos membros. Ao convidar um novo membro, você pode opcionalmente especificar um papel (ADMIN ou MEMBER); o padrão é MEMBER, e convidar como ADMIN exige permissão de nível administrador. A lista de membros retorna um status claro para cada membro — active, pendingInvite ou scimDeprovisioned — para que você distinga membros ativos de convidados pendentes e de usuários desprovisionados pelo provedor de identidade. A remoção de um membro funciona para membros ativos e para convidados pendentes ou expirados (o convite pendente é revogado automaticamente); administradores ativos não podem ser removidos diretamente — rebaixe-os para membro comum primeiro. Membros desprovisionados via SCIM devem ser gerenciados pelo seu provedor de identidade. Reconvidar um endereço de e-mail que já tem um convite pendente ou expirado revoga automaticamente o convite antigo e envia um novo. O status de sincronização de times do GitHub inclui um timestamp lastTeamSyncAt mostrando quando a sincronização mais recente foi concluída, e você pode disparar uma sincronização imediata sob demanda via API ou pelo painel
• Repositórios — liste, adicione por URL (repositórios públicos), exclua e gerencie configurações de repositório. As respostas de repositório incluem configuração específica de cada VCS para GitHub, GitLab, Bitbucket, Azure DevOps e repositórios Git genéricos, permitindo identificar o provedor de origem e o status de conexão de cada repositório. Para configurações de monorepo, você pode excluir atomicamente todas as partições de um monorepo em uma única operação, e repositórios excluídos anteriormente podem ser reimportados sem problemas. Tags podem ser marcadas como padrão (isDefault: true) para que sejam aplicadas automaticamente a todo repositório recém-adicionado, garantindo etiquetagem consistente e acesso de time desde o momento em que um repositório é importado
• Verificação de Contêineres — envie imagens de contêiner para verificação de vulnerabilidades por referência de registro ou fazendo upload de um arquivo de imagem (para ambientes isolados). Você pode listar e recuperar imagens de contêiner monitoradas, ver resultados de verificação com atribuição por camada e recomendações de atualização da imagem base, listar descobertas de vulnerabilidade agrupadas por pacote com CVEs agregadas e gerenciar agendamentos de monitoramento recorrente via expressões cron. O resumo do painel de contêineres fornece estatísticas de toda a organização, incluindo contagens de imagens, descobertas por severidade e as principais oportunidades de atualização de imagem base. Você pode vincular imagens a repositórios, excluir imagens monitoradas e verificar se a verificação de contêineres está habilitada para sua organização
• Verificações — dispare verificações completas, cancele verificações em execução e gerencie agendamentos de verificação baseados em cron com direcionamento por branch. As respostas de verificação incluem identificadores de repositório para todos os provedores de VCS suportados (GitHub, GitLab, Bitbucket e Azure DevOps). Você pode verificar todos os repositórios conectados a um VCS de uma vez passando allRepositories: true, opcionalmente excluindo repositórios específicos com excludedRepositoryIds. Você pode filtrar a lista de verificações por nível de severidade (Critical, High, Medium, Low) e agrupar verificações de PR por pull request para ver apenas a verificação mais recente por PR junto a uma contagem de reverificações relacionadas. Se uma verificação completa já estiver em andamento para o mesmo repositório e branch, a API retorna um erro em vez de iniciar uma verificação duplicada. Ao reverificar um PR, a flag force agora executa uma verificação completa em vez de uma atualização incremental
• Times — crie times, gerencie associações, configure permissões granulares de organização/repositório/time e gerencie templates de permissão padrão que podem ser aplicados a todos os times ou a times específicos da sua organização. O acesso a repositórios pode ser concedido globalmente (todos os repositórios), por repositório ou por tag — concessões baseadas em tag cobrem automaticamente todo repositório que pertence à tag, de modo que o acesso permanece em sincronia à medida que repositórios são adicionados ou removidos. Atualizar ou excluir uma tag que possui concessões de permissão de time exige a permissão TEAM_MANAGE, e os IDs de repositório fornecidos ao criar ou atualizar uma tag são validados como pertencentes à sua organização. Ao ler as permissões de um time, a resposta inclui um campo estruturado repoAccess que indica explicitamente o modo de acesso (universal ou selected) junto às permissões efetivas, aos IDs de repositório e aos IDs de tag. A permissão Agent Run inclui implicitamente Agent View — conceder a um time a capacidade de executar o agente concede automaticamente o acesso de visualização também, então você não precisa atribuir as duas permissões separadamente
• Fontes Personalizadas — crie, liste, atualize, alterne e exclua declarações personalizadas de fontes de segurança que informam ao scanner sobre pontos de entrada de dados não confiáveis adicionais no seu código
• Sinks Personalizados — crie, liste, atualize, alterne e exclua declarações personalizadas de sinks de segurança que informam ao scanner sobre operações sensíveis à segurança adicionais no seu código
• Pacotes de Fontes Personalizadas — navegue por conjuntos curados de templates de declaração de fontes, habilite ou desabilite templates individuais ou pacotes inteiros
• Pacotes de Sinks Personalizados — navegue por conjuntos curados de templates de declaração de sinks, habilite ou desabilite templates individuais ou pacotes inteiros
• Integrações — leia dados de integrações de terceiros, como o Wiz CSPM, incluindo recuperar as configurações do Wiz, listar projetos do Wiz e pesquisar ativos de nuvem e exposições de rede do Wiz
• Configurações do Scanner — configure módulos de verificação, limiares de confiança, correção automática (auto-patching) e padrões de arquivos a ignorar no escopo de organização, repositório ou aplicação. Os módulos de verificação habilitados agora incluem CONTAINER junto a SAST, IAC, SECRETS, EOL, SCA e AI. O canal de lançamento (release track) para verificações completas e de PR aceita STABLE além de EDGE. A configuração allowPrCheckBypass controla se contribuidores podem ignorar o status do check de PR da ZeroPath sem desabilitar a verificação de PR por completo
• Estatísticas — recupere contagens agregadas de issues e atividade de verificação por escopo, incluindo um detalhamento de issues por aplicação com contagens de abertos e resolvidos por repositório. Os endpoints de estatísticas do painel aceitam filtros opcionais de aplicação para restringir os resultados a aplicações específicas dentro dos repositórios. O resumo de postura de segurança inclui uma contagem reachableExploitableIssues junto às contagens por nível de severidade já existentes

​

Escopos de Token

​

Gerenciando Tokens

• Visualizar todos os tokens ativos com seus nomes, datas de criação e datas de expiração.
• Excluir tokens que não são mais necessários ou que possam estar comprometidos.

​

Ciclo de Vida do Token

• Os tokens têm uma data de expiração fixa definida na criação (1–365 dias).
• Tokens expirados são rejeitados automaticamente — não há renovação automática.
• Quando um token expira, crie um novo e atualize suas integrações.
• Os segredos dos tokens passam por hash criptográfico antes do armazenamento — a ZeroPath nunca armazena o segredo em texto puro.

​

Boas Práticas

1. Use nomes descritivos — nomeie os tokens de acordo com sua finalidade (por exemplo, “CI/CD Pipeline”, “VS Code Extension”, “MCP Server”).
2. Defina expirações curtas — use a menor expiração viável para o seu caso de uso.
3. Faça rotação regularmente — crie novos tokens e desative os antigos de forma programada.
4. Nunca faça commit de tokens no controle de versão — use variáveis de ambiente ou um gerenciador de segredos.
5. Um token por integração — evite compartilhar um único token entre múltiplos sistemas para poder revogá-los individualmente.
6. Exclua tokens comprometidos imediatamente — se um token pode ter sido exposto, exclua-o e crie um substituto.