> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ZeroPath CLI

> Acesso via linha de comando à plataforma de verificação de segurança com IA da ZeroPath

<h2 id="overview">
  Visão Geral
</h2>

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.

<Card title="Obtenha a CLI" icon="github" href="https://github.com/ZeroPathAI/zeropath-cli">
  Baixe a versão mais recente no nosso repositório do GitHub
</Card>

<h2 id="what-zeropath-cli-detects">
  O Que a ZeroPath CLI Detecta
</h2>

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**

<h2 id="quick-start">
  Início Rápido
</h2>

```bash theme={null}
# 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
```

<h2 id="core-commands">
  Comandos Principais
</h2>

<h3 id="authentication">
  Autenticação
</h3>

```bash theme={null}
# Authenticate with API credentials
zeropath auth <clientId> <clientSecret>
```

<h3 id="local-directory-scanning">
  Verificação de Diretório Local
</h3>

```bash theme={null}
# Basic scan
zeropath scan <directory> <outputFile.sarif>

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

<h3 id="repository-scanning">
  Verificação de Repositório
</h3>

```bash theme={null}
# Scan by repository ID
zeropath scan --repository-id <repositoryId>

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

<h3 id="on-demand-code-scans-beta">
  Verificações de Código Sob Demanda Beta
</h3>

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.

```bash theme={null}
# 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).

<Warning>
  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.
</Warning>

Consulte [Verificações de Código Sob Demanda Beta](/pt/developer-tools/async-code-scans) para formatos
de requisição, modos de alvo, limites e exemplos de API.

<h3 id="container-scanning">
  Verificação de Contêineres
</h3>

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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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
```

<Note>
  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.
</Note>

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.

```bash theme={null}
# 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.

```bash theme={null}
# 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
```

<h4 id="repository-linking">
  Vinculação a Repositórios
</h4>

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`.

```bash theme={null}
# 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
```

<h4 id="linking-an-existing-image">
  Vinculando uma Imagem Existente
</h4>

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.

```bash theme={null}
# 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](/pt/scanning/container-scanning) 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.

<h2 id="ci-cd-integration">
  Integração com CI/CD
</h2>

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:

```bash theme={null}
# Scan a repository (exits 1 if issues found)
zeropath scan --repository-id <repositoryId>

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

<h3 id="scan-timeout">
  Tempo Limite de Verificação
</h3>

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.

<h2 id="output-formats">
  Formatos de Saída
</h2>

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

<h2 id="getting-api-credentials">
  Obtendo Credenciais de API
</h2>

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

1. Faça login no [ZeroPath Dashboard](https://zeropath.com/app)
2. Acesse API Settings
3. Gere novas credenciais de API (Client ID e Client Secret)
4. Use essas credenciais com `zeropath auth`

<h2 id="next-steps">
  Próximos Passos
</h2>

* [Guia de Instalação](/pt/cli/installation) - Configure a CLI no seu sistema
* [Repositório no GitHub](https://github.com/ZeroPathAI/zeropath-cli) - Código-fonte e versões
* [Referência da API](/api-reference/introduction) - Crie integrações personalizadas