CLI
Guias
CLI da Scanverra
Escaneie qualquer código a partir do seu terminal ou pipeline de CI com o @scanverra/cli. A varredura roda na sua própria máquina e apenas os resultados são enviados à Scanverra.
Início rápido
Não instale nada globalmente, ou execute npm i -g @scanverra/cli para ter o comando scanverra de forma permanente.
npx @scanverra/cli login # paste an API key from Dashboard > API keys npx @scanverra/cli scan .
Como funciona
Sempre atualizado
Você sempre executa as verificações mais recentes, sem uma versão separada da CLI para acompanhar ou atualizar manualmente.
O mesmo mecanismo do painel
Os resultados coincidem com os de uma varredura iniciada na Scanverra, não importa onde você a execute.
Escaneia localmente
Seus arquivos-fonte são lidos na sua própria máquina. Por padrão, apenas os resultados são enviados à Scanverra, nunca o conteúdo dos arquivos ou as linhas de código encontradas.
Aparece no seu painel
Cada varredura recebe um resumo escrito por IA e um link, a mesma página de resultados de uma varredura iniciada pelo painel.
Comandos
| Comando | Descrição |
|---|---|
scanverra login | Verifica e salva sua chave de API |
scanverra logout | Remove a chave salva |
scanverra whoami | Mostra a conta e o plano associados à chave |
scanverra scan [path] | Escaneia uma pasta (padrão: pasta atual), mostra os resultados e os envia |
scanverra audit <url> | Audita a velocidade de um site no ar; com --budget, falha se violar um orçamento salvo |
Opções comuns
| Opção | Descrição |
|---|---|
--json / --sarif | Saída legível por máquina. O SARIF funciona com o GitHub code scanning e a importação no Sonar |
--fail-on <severity> | Encerra com falha se existir um achado dessa severidade ou maior (padrão: high) |
--fail-on-new, --baseline-branch <name>, --baseline-commit <sha> | Falha apenas quando esta análise adiciona um problema crítico ou alto em relação à análise enviada anteriormente (o gate de código novo, para pull requests). Adicione --baseline-branch main para comparar com a branch de destino. Se essa branch nunca foi analisada, todo problema crítico ou alto conta como novo. Quando conhecido, é usada a análise do commit de onde sua branch partiu (via git merge-base ou --baseline-commit <sha>), para que correções feitas depois na branch de destino não contem contra você. Substitui --fail-on; exige envio |
--category <list> | Inclui apenas achados de security, dependency, iac ou quality |
--exclude <glob> | Ignora caminhos correspondentes. Um arquivo .scanverraignore funciona da mesma forma |
--no-upload | Apenas escaneia, não envia resultados à Scanverra |
--include-code | Também envia a linha de código encontrada de cada achado (desativado por padrão) |
--offline | Usa as regras em cache sem nenhuma chamada de rede |
--api-key, --api-url | Substitui as credenciais ou o servidor, útil em CI |
--save-budget <file> | Auditoria: salva um orçamento desta execução (limites com folga + terceiros permitidos) |
--budget <file> | Auditoria: compara com um orçamento salvo; sai com 1 em qualquer violação |
O que é enviado
Caminhos de arquivo, números de linha, IDs de regra, títulos, descrições, sugestões de correção, severidades, nomes e versões de dependências, e o nome do projeto, branch, commit e número da PR.
O conteúdo dos arquivos, e a linha de código encontrada de cada achado. Achados de segredos nunca carregam o valor do segredo em si. Use --include-code se quiser ver as linhas encontradas no painel.
Como os arquivos são escolhidos
- Dentro de um repositório git, arquivos rastreados e não rastreados são usados, e o .gitignore é respeitado. Fora do git, pastas comuns de build e dependências são ignoradas.
- Um arquivo .scanverraignore (um padrão glob por linha) e flags --exclude repetíveis adicionam mais exclusões.
- Suprima um achado específico com um comentário scanverra-ignore ou nosec na linha acima dele.
Códigos de saída
| 0 | Sucesso, e nenhum achado atingiu o limite de --fail-on |
| 1 | Um achado atingiu o limite, o quality gate falhou com --fail-on-gate, ou a análise adicionou um problema crítico ou alto com --fail-on-new |
| 2 | Erro de uso, o servidor rejeitou a chave ou o plano, ou um banco de dados de vulnerabilidades não respondeu e o resultado não pôde ser verificado (execute de novo) |
Uso em CI
Guarde a chave de API como um secret, do mesmo jeito que em qualquer outra integração de CI da Scanverra, e mantenha a pasta de regras em cache para que um runner novo não a baixe de novo a cada execução.
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with: { node-version: 24 }
- run: npx @scanverra/cli scan . --fail-on high
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}Colocar as regras em cache entre execuções
- uses: actions/cache@v4
with:
path: ~/.cache/scanverra
key: scanverra-rules-${{ github.run_id }}
restore-keys: scanverra-rules-Orçamento de desempenho do seu site
Faça commit de um orçamento de um deploy bom. Cada execução seguinte falha o build se a página ficar mais lenta ou pesada, ou surgir um terceiro novo.
# once, from a good deploy:
scanverra audit https://staging.example.com --save-budget perf-budget.json
# in CI, after deploying a preview:
- run: npx scanverra audit "$PREVIEW_URL" --budget perf-budget.json
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}Solução de problemas
| Mensagem | O que fazer |
|---|---|
Not logged in | Execute scanverra login, ou defina SCANVERRA_API_KEY |
API key was rejected | A chave está errada ou foi revogada. Crie uma nova em API Keys |
You have reached your free scan limit | Você já usou as verificações gratuitas do Repo Scanner deste mês. Verifique com --no-upload, espere o próximo mês ou faça upgrade. |
Daily limit for downloading the scanner rules reached | Coloque a pasta de regras em cache no CI, veja acima |
No scannable files found | Verifique o caminho e seu .gitignore ou .scanverraignore |
Pronto para escanear pelo terminal?
Gere uma chave de API e execute sua primeira varredura em menos de um minuto.