ZeroPath CLI - ZeroPath Documentation

Visão Geral

A ZeroPath CLI oferece acesso via linha de comando à plataforma de verificação de segurança com IA da ZeroPath. Envie e verifique seu código diretamente do terminal, com suporte a múltiplos formatos de saída e integração com CI/CD.

Obtenha a CLI

Baixe a versão mais recente no nosso repositório do GitHub

O Que a ZeroPath CLI Detecta

A CLI verifica uma ampla gama de vulnerabilidades de segurança:

Vulnerabilidades de autenticação e autorização
Falhas de lógica de aplicação
Problemas em dependências
Configurações de segurança incorretas
Vulnerabilidades de injeção de comandos
Ataques de inclusão de arquivos e path traversal
Segredos e credenciais codificadas no código

Início Rápido

# Install CLI (see installation guide)
# Authenticate with your API credentials
zeropath auth <clientId> <clientSecret>

# Scan current directory
zeropath scan . output.sarif

# Scan by repository ID
zeropath scan --repository-id <repositoryId>

# Scan by repository URL
zeropath scan --repository-url https://github.com/owner/repo --vcs github

Comandos Principais

Autenticação

# Authenticate with API credentials
zeropath auth <clientId> <clientSecret>

Verificação de Diretório Local

# Basic scan
zeropath scan <directory> <outputFile.sarif>

# Example
zeropath scan ./my-project results.sarif

Verificação de Repositório

# Scan by repository ID
zeropath scan --repository-id <repositoryId>

# Scan by repository URL
zeropath scan --repository-url https://github.com/owner/repo --vcs github

Verificações de Código Sob Demanda Beta

Use scan-code para enviar um diff, um arquivo, um conjunto de arquivos ou um trecho de código para revisão de segurança assíncrona sem iniciar uma verificação completa do repositório.

# Scan the current Git working-tree diff
zeropath scan-code --diff

# Scan staged changes
zeropath scan-code --staged

# Scan one file
zeropath scan-code --file src/api.ts

# Force standalone mode when you do not want linked repository context
zeropath scan-code --diff --standalone

Por padrão, scan-code usa a URL do seu remote Git para utilizar automaticamente o contexto do repositório vinculado quando exatamente um repositório ZeroPath acessível corresponde. Se não houver correspondência, a execução ocorre como uma verificação independente (standalone).

As Verificações de Código Sob Demanda estão atualmente em beta. Comportamento, limites e campos de resposta podem mudar antes da disponibilidade geral.

Consulte Verificações de Código Sob Demanda Beta para formatos de requisição, modos de alvo, limites e exemplos de API.

Verificação de Contêineres

Use os comandos container para verificar imagens de contêiner já construídas em busca de vulnerabilidades em pacotes do sistema operacional e em dependências embutidas. As imagens podem ser baixadas por referência de registro — inclusive de registros privados com credenciais — ou enviadas como um arquivo local gerado com docker save. As descobertas aparecem na seção Supply Chain com atribuição por camada e recomendações de atualização da imagem base.

# One-shot scan of a built image
zeropath container test <image>

# Example
zeropath container test registry.example.com/app:1.4.2

Para verificar uma imagem em um registro privado, informe as credenciais do registro. A ZeroPath se autentica com elas ao baixar a imagem; os tokens são transmitidos via TLS e armazenados criptografados.

# Scan an image from a private registry
zeropath container test registry.example.com/app:1.4.2 \
  --registry-username <username> \
  --registry-token <token>

Para imagens em ambientes isolados (air-gapped) que não podem ser baixadas, exporte a imagem para um tarball com docker save e verifique esse arquivo diretamente com --file. Dê a ele um rótulo com --name para que seja identificável nos resultados.

# Export the built image, then scan the archive
docker save -o image.tar registry.example.com/app:1.4.2
zeropath container test --file image.tar --name app-1.4.2

Arquivos enviados são verificados uma única vez e não podem ser monitorados: não há referência de registro para baixar novamente de forma agendada, então container monitor rejeita --file. Use uma referência de imagem em registro para reverificações recorrentes.

Por padrão, container test aguarda a verificação terminar e imprime um relatório legível. As flags a seguir controlam esse comportamento:

--json — imprime o payload bruto da resposta como JSON em vez do relatório formatado.
--wait / --no-wait — aguarda a conclusão da verificação (o padrão). Passe --no-wait para enviar a verificação e retornar imediatamente com o ID da imagem de contêiner.
--timeout <seconds> — número máximo de segundos a aguardar pela conclusão antes de sair com um erro. Deve ser um número positivo.

# Submit without waiting, emitting JSON for scripting
zeropath container test registry.example.com/app:1.4.2 --no-wait --json

# Wait up to 10 minutes for completion
zeropath container test registry.example.com/app:1.4.2 --timeout 600

Para continuar acompanhando uma imagem depois que ela entra em produção, registre-a para reverificações recorrentes. O monitoramento revela CVEs recém-divulgadas contra uma imagem já construída sem necessidade de reexecução manual. container monitor também aceita --json para imprimir o payload bruto da resposta.

# Monitor an image on the default schedule
zeropath container monitor <image>

# Monitor an image on a custom schedule (crontab expression)
zeropath container monitor <image> --schedule "0 6 * * *"

# Example, emitting JSON
zeropath container monitor registry.example.com/app:1.4.2 --schedule "0 6 * * *" --json

Vinculação a Repositórios

Imagens de contêiner podem ser vinculadas a um repositório já integrado para que as descobertas apareçam junto aos resultados de verificação de código desse repositório. Por padrão, os comandos de contêiner detectam automaticamente o repositório a partir do remote git do checkout atual. Você pode controlar isso com:

--repository-id <id> — vincula explicitamente a imagem a um repositório específico, substituindo a detecção automática.
--no-auto-repository — desativa completamente a detecção automática; a imagem não será vinculada a nenhum repositório a menos que --repository-id também seja fornecido.

A vinculação automática funciona para container test, container monitor e container link.

# Explicitly link the scanned image to a repository
zeropath container test registry.example.com/app:1.4.2 --repository-id <repositoryId>

# Disable auto-linking from the local git remote
zeropath container test registry.example.com/app:1.4.2 --no-auto-repository

Vinculando uma Imagem Existente

Use container link para vincular (ou revincular) uma imagem de contêiner já verificada a um repositório. Isso é útil quando a imagem foi verificada sem contexto de repositório, ou quando você precisa movê-la para um repositório diferente.

# Link an image to the repository matching the current checkout
zeropath container link <containerImageId>

# Link an image to a specific repository
zeropath container link <containerImageId> --repository-id <repositoryId>

# Emit JSON output
zeropath container link <containerImageId> --json

Consulte Verificação de Contêineres para o fluxo completo, descobertas por camada, verificação em registros privados e de arquivos locais, e recomendações de atualização da imagem base.

Integração com CI/CD

A CLI foi projetada para integração transparente com CI/CD — ela encerra com código 1 quando problemas de segurança são encontrados ou quando ocorre um erro durante a verificação:

# Scan a repository (exits 1 if issues found)
zeropath scan --repository-id <repositoryId>

# Generate SARIF output (local scan only)
zeropath scan . results.sarif

Tempo Limite de Verificação

Verificações de diretório local têm um tempo limite máximo de polling de aproximadamente 50 minutos. Se a verificação não for concluída dentro dessa janela, a CLI encerra com um erro. Isso evita que pipelines de CI/CD fiquem travados indefinidamente em verificações de longa duração.

Formatos de Saída

A ZeroPath CLI suporta múltiplos formatos de saída para diferentes casos de uso:

SARIF: formato padrão para resultados de análise estática (verificações locais)
Console: saída formatada e legível para visualização no terminal

Obtendo Credenciais de API

Para usar a CLI, você precisará de credenciais de API da sua conta ZeroPath:

Faça login no ZeroPath Dashboard
Acesse API Settings
Gere novas credenciais de API (Client ID e Client Secret)
Use essas credenciais com zeropath auth

Próximos Passos

Guia de Instalação - Configure a CLI no seu sistema
Repositório no GitHub - Código-fonte e versões
Referência da API - Crie integrações personalizadas

​Visão Geral

Obtenha a CLI

​O Que a ZeroPath CLI Detecta

​Início Rápido

​Comandos Principais

​Autenticação

​Verificação de Diretório Local

​Verificação de Repositório

​Verificações de Código Sob Demanda Beta

​Verificação de Contêineres

​Vinculação a Repositórios

​Vinculando uma Imagem Existente

​Integração com CI/CD

​Tempo Limite de Verificação

​Formatos de Saída

​Obtendo Credenciais de API

​Próximos Passos

Visão Geral

O Que a ZeroPath CLI Detecta

Início Rápido

Comandos Principais

Autenticação

Verificação de Diretório Local

Verificação de Repositório

Verificações de Código Sob Demanda Beta

Verificação de Contêineres

Vinculação a Repositórios

Vinculando uma Imagem Existente

Integração com CI/CD

Tempo Limite de Verificação

Formatos de Saída

Obtendo Credenciais de API

Próximos Passos