CLI
Guías
CLI de Scanverra
Analiza cualquier código desde tu terminal o pipeline de CI con @scanverra/cli. El análisis se ejecuta en tu propia máquina y solo los resultados se envían a Scanverra.
Inicio rápido
No instales nada globalmente, o ejecuta npm i -g @scanverra/cli para tener el comando scanverra de forma permanente.
npx @scanverra/cli login # paste an API key from Dashboard > API keys npx @scanverra/cli scan .
Cómo funciona
Siempre actualizado
Siempre ejecutas las comprobaciones más recientes, sin una versión de CLI aparte que rastrear o actualizar a mano.
El mismo motor que el panel
Los resultados coinciden con los de un análisis iniciado en Scanverra, sin importar dónde lo ejecutes.
Analiza en local
Tus archivos fuente se leen en tu propia máquina. Por defecto, solo se envían a Scanverra los hallazgos, no el contenido de los archivos ni las líneas de código detectadas.
Aparece en tu panel
Cada análisis recibe un resumen escrito por IA y un enlace, la misma página de resultados que un análisis iniciado desde el panel.
Comandos
| Comando | Descripción |
|---|---|
scanverra login | Verifica y guarda tu clave de API |
scanverra logout | Elimina la clave guardada |
scanverra whoami | Muestra la cuenta y el plan asociados a la clave |
scanverra scan [path] | Analiza una carpeta (por defecto, la actual), muestra los resultados y los sube |
scanverra audit <url> | Audita la velocidad de un sitio en vivo; con --budget, falla si incumple un presupuesto guardado |
Opciones habituales
| Opción | Descripción |
|---|---|
--json / --sarif | Salida legible por máquina. SARIF funciona con GitHub code scanning y la importación en Sonar |
--fail-on <severity> | Termina con error si existe un hallazgo de esta severidad o superior (por defecto: high) |
--fail-on-new, --baseline-branch <name>, --baseline-commit <sha> | Falla solo si este análisis añade un problema crítico o alto respecto al análisis subido anteriormente (el gate de código nuevo, para pull requests). Añade --baseline-branch main para comparar con la rama de destino. Si esa rama nunca se ha analizado, cada problema crítico o alto cuenta como nuevo. Cuando se conoce, se usa el análisis del commit desde el que partió tu rama (con git merge-base o --baseline-commit <sha>), para que las correcciones posteriores en la rama de destino no cuenten en tu contra. Sustituye a --fail-on; requiere subir resultados |
--category <list> | Incluye solo hallazgos de security, dependency, iac o quality |
--exclude <glob> | Omite las rutas que coincidan. Un archivo .scanverraignore funciona igual |
--no-upload | Solo analiza, no envía resultados a Scanverra |
--include-code | Sube también la línea de código detectada de cada hallazgo (desactivado por defecto) |
--offline | Usa las reglas en caché sin llamadas de red |
--api-key, --api-url | Sustituye las credenciales o el servidor, útil en CI |
--save-budget <file> | Auditoría: guarda un presupuesto de esta ejecución (límites con margen + servicios externos permitidos) |
--budget <file> | Auditoría: compara con un presupuesto guardado; sale con 1 ante cualquier incumplimiento |
Qué se sube
Rutas de archivo, números de línea, IDs de regla, títulos, descripciones, sugerencias de corrección, severidades, nombres y versiones de dependencias, y el nombre del proyecto, la rama, el commit y el número de PR.
El contenido de los archivos y la línea de código detectada de cada hallazgo. Los hallazgos de secretos nunca incluyen el valor del secreto en sí. Usa --include-code si quieres ver las líneas detectadas en el panel.
Cómo se eligen los archivos
- Dentro de un repositorio git se usan los archivos rastreados y no rastreados, y se respeta .gitignore. Fuera de git se omiten las carpetas habituales de build y dependencias.
- Un archivo .scanverraignore (un patrón glob por línea) y las flags --exclude repetibles añaden más exclusiones.
- Suprime un hallazgo concreto con un comentario scanverra-ignore o nosec en la línea anterior.
Códigos de salida
| 0 | Éxito, y ningún hallazgo alcanzó el umbral de --fail-on |
| 1 | Un hallazgo alcanzó el umbral, el quality gate falló con --fail-on-gate, o el análisis añadió un problema crítico o alto con --fail-on-new |
| 2 | Error de uso, el servidor rechazó la clave o el plan, o no se pudo contactar una base de datos de vulnerabilidades y el resultado no se pudo verificar (vuelve a ejecutar) |
Uso en CI
Guarda la clave de API como secreto, igual que en cualquier otra integración de CI de Scanverra, y guarda en caché la carpeta de reglas para que un runner nuevo no las vuelva a descargar en cada ejecución.
- 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 }}Cachear las reglas entre ejecuciones
- uses: actions/cache@v4
with:
path: ~/.cache/scanverra
key: scanverra-rules-${{ github.run_id }}
restore-keys: scanverra-rules-Presupuesto de rendimiento para tu sitio
Guarda en el repositorio un presupuesto de un despliegue bueno. Cada ejecución posterior hace fallar el build si la página se vuelve más lenta o pesada, o aparece un servicio externo nuevo.
# 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 }}Solución de problemas
| Mensaje | Qué hacer |
|---|---|
Not logged in | Ejecuta scanverra login, o define SCANVERRA_API_KEY |
API key was rejected | La clave es incorrecta o fue revocada. Crea una nueva en API Keys |
You have reached your free scan limit | Ya usaste los análisis gratuitos de Repo Scanner de este mes. Analiza con --no-upload, espera al mes siguiente o mejora tu plan. |
Daily limit for downloading the scanner rules reached | Cachea la carpeta de reglas en CI, ver arriba |
No scannable files found | Revisa la ruta y tu .gitignore o .scanverraignore |
¿Listo para analizar desde la terminal?
Genera una clave de API y ejecuta tu primer análisis en menos de un minuto.