Skip to main content

​
Introducción

La CLI de Corgea es una potente herramienta para desarrolladores que ayuda a detectar y corregir vulnerabilidades en el código. Mediante BLAST, el escáner con IA de Corgea, identifica problemas de seguridad complejos, como fallos de lógica de negocio, vulnerabilidades de autenticación y otros errores difíciles de detectar. Incluye comandos para escanear la base de código, inspeccionar hallazgos, trabajar con correcciones y mucho más.
Potencia tu agente de programación con IA. La CLI de Corgea también sirve como base para las integraciones con agentes: instala Corgea Agent Skill para que tu agente de IA (Cursor, Claude Code, Copilot y otros) escanee, clasifique y corrija vulnerabilidades.

​
Características

  • Compatibilidad con varios escáneres: Escanea con BLAST, el escáner con IA de Corgea, y sube informes de Semgrep, Snyk, Checkmarx, CodeQL, Fortify y Coverity.
  • Gestión de hallazgos: Lista, inspecciona y gestiona los hallazgos de seguridad.
  • Integración de correcciones: Consulta y aplica correcciones generadas por IA para vulnerabilidades directamente desde tu terminal.
  • Análisis de dependencias: Crea inventarios de dependencias offline, inspecciona grafos de dependencias, genera SBOM y evalúa políticas de dependencias con corgea deps.
  • Comprobación de avisos de paquetes: Consulta los avisos conocidos antes de seleccionar o instalar un paquete npm o PyPI.
  • Control de instalación del gestor de paquetes: Examina las instalaciones de npm, yarn, pnpm, pip y uv en busca de paquetes vulnerables, maliciosos o sospechosamente recientes antes de instalarlos; consulta Control de instalación del gestor de paquetes.
  • Salida flexible: Admite formatos legibles y JSON para simplificar las integraciones de CI.
  • Integración con CI/CD: Hace fallar las compilaciones según los niveles de gravedad o reglas de bloqueo personalizadas.
  • Gestión de escaneo: Haz un seguimiento del progreso y resultados del escaneo en tus proyectos.
  • Instalación de Agent Skills: Instala skills aprobadas del registro de Corgea en agentes de programación compatibles.

​
Requisitos previos

  • Cuenta de Corgea: Una cuenta activa de Corgea.
  • Token para autenticación: Un token válido de la API de Corgea o token de acceso JWT.
Los comandos offline corgea deps scan, graph, explain, diff, sbom y policy init no requieren una cuenta de Corgea, token, configuración ni acceso a la red.

​
Guía de instalación

​
Instalar con npm

El paquete npm incluye binarios nativos para plataformas compatibles y selecciona el binario correcto para tu sistema operativo y arquitectura en tiempo de ejecución.

​
Instalar con uv

Para los usuarios de Python, este es el método de instalación preferido. uv tool install crea un entorno de herramienta aislado a partir del paquete PyPI y expone la CLI como corgea en tu PATH.
Si uv indica que el directorio de herramientas no está en PATH, ejecuta:

​
Instalar con pip

Si no utilizas uv, puedes instalar la CLI de Corgea con pip, el instalador de paquetes de Python:
Este comando descarga de PyPI (Python Package Index) el paquete de la CLI de Corgea y lo instala en el sistema. Encontrarás más información en https://pypi.org/project/corgea-cli/.

​
Instalar con Homebrew

Para instalar la herramienta de CLI de Corgea usando Homebrew, primero añade el tap de Corgea y luego instala la CLI:

​
Instalar manualmente

Descarga el archivo de tu plataforma desde la versión más reciente, descomprímelo y mueve el binario corgea a un directorio incluido en PATH. Las URL latest/download siguientes siempre apuntan a la versión más reciente.
También se publica una versión de Linux enlazada estáticamente como corgea-x86_64-unknown-linux-musl.zip.

​
Autenticación

​
Inicia sesión con tu CLI

Para autenticarte con la CLI, utiliza el siguiente comando. Se te redirigirá a la aplicación web para que autorices la CLI:

​
Iniciar sesión con un ámbito personalizado (para instancias de un único tenant)

Consejo: El ámbito de la empresa es el subdominio de Corgea, por ejemplo: https://your-company.corgea.app

​
Iniciar sesión con token (API token o JWT)

Para pipelines automatizados y entornos CI/CD, utiliza autenticación por token para un flujo de inicio de sesión fiable y no interactivo. Puedes pasar tanto un token de API de Corgea como un token de acceso JWT:
También puedes establecer el token en una variable de entorno:

​
Especificar una instancia de un único tenant

Los clientes que utilizan una instancia de un único tenant deben configurar la CLI para que apunte a ella mediante la opción --url:
También puedes establecer la URL en una variable de entorno y la CLI la detectará automáticamente:

​
Uso

​
Comandos y opciones

​
Consulta los avisos de paquete

Utiliza corgea advisories check para consultar los avisos conocidos antes de elegir o instalar un paquete npm o PyPI. Una comprobación que solo indica el paquete enumera su historial de avisos; añade una versión exacta para obtener un veredicto sobre esa versión.
El ecosistema puede ser npm o pypi (pip también se acepta como alias). Las versiones de npm deben ser completas y exactas, como 1.2.3; no se admiten rangos, etiquetas ni versiones parciales. Las comprobaciones de PyPI aceptan tanto la sintaxis package@version como package==version, propia de pip. Los resultados del paquete permiten consultar el historial de avisos antes de elegir una versión. Los resultados de una versión exacta incluyen los avisos conocidos, las versiones corregidas disponibles y una recomendación de versión segura cuando todos los avisos publicados tienen corrección. Este comando es de solo lectura y requiere acceso a la red; el control de instalación del gestor de paquetes sigue siendo el mecanismo de aplicación. Utiliza --json para obtener una respuesta legible por máquina con la versión 1 del esquema. El comando finaliza con el código 0 si no encuentra avisos, 1 si los encuentra y 2 si se produce un error. Si el paquete no figura en la base de datos de avisos, finaliza con el código 0.

​
Control de instalación del gestor de paquetes

Utiliza corgea npm, corgea yarn, corgea pnpm, corgea pip o corgea uv para ejecutar mediante Corgea comandos compatibles de instalación antes de instalar las dependencias.
Corgea compara cada versión resuelta con datos públicos para detectar versiones vulnerables o maliciosas, sin necesidad de token, y bloquea las versiones publicadas hace muy poco (consulta Control de antigüedad). Las versiones vulnerables, maliciosas o demasiado recientes bloquean la instalación antes de ejecutar el gestor de paquetes. Coloca las opciones del wrapper entre el nombre del gestor y su comando; por ejemplo, corgea pip --force install requests. Control de antigüedad. Además de comprobar las vulnerabilidades, Corgea bloquea los paquetes cuya versión resuelta se haya publicado dentro de un intervalo reciente. Esto permite detectar typosquats y secuestros recién publicados antes de que se actualicen las fuentes de avisos. Está habilitado de forma predeterminada con un intervalo de 14 días. Configúralo en ~/.corgea/config.toml (recency_gate = false para desactivarlo y recency_threshold_days para ajustar el intervalo) o mediante las variables de entorno CORGEA_RECENCY_GATE y CORGEA_RECENCY_THRESHOLD_DAYS. Los paquetes cuya fecha de publicación no se pueda determinar no activan este control; los veredictos de paquete vulnerable o malicioso tienen prioridad sobre su antigüedad, y --force omite el control en una instalación concreta. Cobertura. pip install y npm install resuelven todo el conjunto que se instalaría, incluidas las dependencias transitivas, por lo que una dependencia transitiva vulnerable bloquea el comando. Si falla la resolución de prueba, Corgea muestra una advertencia y vuelve a comprobar solo los paquetes indicados. npm ci se controla mediante el lockfile del proyecto y uv sync mediante uv.lock, de modo que se comprueba todo el conjunto bloqueado aunque los comandos no indiquen paquetes. El control de uv también incluye los paquetes indicados en uv add ... y uv pip install ...; uv lock continúa porque no instala nada. yarn y pnpm solo comprueban los paquetes indicados, ya que no ofrecen una resolución de prueba segura. Instalaciones sin paquetes explícitos. Un npm install sin argumentos se controla a partir del package.json del proyecto. Los comandos equivalentes de yarn, pnpm y uv no se pueden comprobar de antemano, por lo que Corgea muestra una nota y los ejecuta sin validarlos.
Modo público y autenticado. Sin token, el control se ejecuta en modo público: los paquetes vulnerables y maliciosos se bloquean, pero los paquetes no verificables y los errores de consulta solo generan advertencias y permiten continuar (los errores repetidos se resumen en una línea). Con un token de CORGEA_TOKEN o corgea login y la API de vulnerabilidades predeterminada, se ejecuta en modo autenticado y aplica un cierre seguro: los paquetes no verificables, los fallos al resolver dependencias, la indisponibilidad de la API y una cobertura degradada del árbol en los gestores que normalmente lo resuelven por completo (pip, npm, uv) bloquean la instalación salvo que se utilice --force. API de vulnerabilidades personalizada. Si configuras CORGEA_VULN_API_URL con un endpoint personalizado, Corgea no le envía el token y el control permanece en modo público. Establece CORGEA_VULN_API_SEND_TOKEN_TO_CUSTOM_URL=1 para habilitar la aplicación autenticada en un endpoint de confianza. Python gestionado externamente. Para pip, Corgea rechaza las instalaciones en entornos gestionados externamente (PEP 668) antes de que se realicen las comprobaciones del registro. Activa un entorno virtual o pasa --force para evitarlo. Corgea ejecuta desde PATH el gestor de paquetes correspondiente. En corgea pip ..., prueba pip3 si no encuentra pip; si no existe ninguno, la CLI finaliza con el código 127 e indica qué binario falta. Hallazgos. Cuando un paquete resuelto es vulnerable, los hallazgos en árboles muestran su origen:
  • (from requirements) — solicitado mediante un archivo de requisitos de pip.
  • (already in package.json) — ya es una dependencia directa de npm.
  • (transitive) — arrastrado por otra dependencia.
Cuando el paquete solicitado no tiene vulnerabilidades pero el árbol resuelto ya contiene un paquete vulnerable, el mensaje de rechazo identifica el árbol existente como origen. Las líneas de los avisos muestran la versión corregida publicada o indican que no se conoce ninguna. Si todos los avisos de un paquete incluyen datos de corrección, Corgea imprime safe version: axios@0.21.2; para dependencias directas vulnerables de npm, también puede mostrar fix with: corgea npm install package-name@version (advertised fix). El recuento de vulnerabilidades y el código de salida corresponden al objetivo de instalación original. Salida JSON. --json devuelve un único informe por stdout y redirige a stderr el stdout del gestor de paquetes, de modo que Corgea controla stdout. La versión 2 del esquema incluye manager, subcommand, args, recency_threshold_days (el intervalo activo, o null si el control está deshabilitado; se corresponde con age_seconds en cada resultado), un objeto summary con recuentos named y tree, verdict_mode, un array results y un objeto tree cuando se haya resuelto el árbol. Las entradas del árbol indican un origin con los valores requested, pre-existing o transitive. Los paquetes maliciosos conocidos devuelven un status específico con valor malicious, un booleano malware por coincidencia y un recuento malicious separado en cada resumen. Su valor remediation siempre es null, porque el paquete debe eliminarse en lugar de actualizarse. Los veredictos de vulnerabilidad solo indican una versión segura si esta corrige todos los avisos.

​
Instalar Agent Skills

Instala una skill aprobada del registro de Corgea en el directorio de skills del agente de programación:
Los ID de agente compatibles son cursor, claude-code, codex, github-copilot, gemini-cli, windsurf, opencode y universal. Utiliza --scope project para instalar en el repositorio actual, --scope user para instalar en tu cuenta o --dir para instalar en un directorio de skills personalizado. Para instalar una versión concreta, añádela al nombre de la skill:
También puedes guardar un agente por defecto para futuras instalaciones:

​
Sube un informe de escaneo

Sube un informe de escaneo a Corgea a través de STDIN o un archivo (JSON, SARIF, FPR o XML de Coverity):
Para controlar el nombre del proyecto que aparece en Corgea en los informes subidos, utiliza --project-name. Si se omite, la CLI utiliza el nombre del repositorio Git cuando está disponible o, en su defecto, el del directorio actual.
Para informes grandes, la CLI sube los datos en bloques. Durante las subidas fragmentadas, la CLI verifica el progreso de la subida del servidor y sale con un estado distinto de cero si el servidor informa de un desplazamiento inesperado o si la subida se completa sin devolver un ID de escaneo.

​
Escanea tu base de código

Para escanear tu directorio actual usando el escáner BLAST por defecto:
Para especificar un escáner diferente, como Semgrep:
También puedes utilizar --fail-on con una o varias condiciones separadas por comas: CR, HI, ME, LO o malicious. Las condiciones de gravedad coinciden con hallazgos de esa gravedad o superior; por ejemplo, ME también coincide con hallazgos HI y CR. La condición malicious coincide con un hallazgo de dependencia clasificado como malicioso. El comando devuelve un estado distinto de cero si se cumple alguna de las condiciones. Ejemplos:
O fallar según las reglas de bloqueo definidas en la aplicación web:
Por defecto, el comando de escaneo escanea todo el proyecto. Sin embargo, si solo quieres escanear tus cambios antes de comprometerte, puedes usar la opción —only-uncommitted.
También puedes seleccionar archivos o subconjuntos concretos del proyecto (solo en escaneos BLAST) mediante la opción --target. Acepta valores separados por comas: rutas de archivos o directorios, patrones glob, selectores de Git o stdin. Ejemplos:
Puedes excluir archivos de los escaneos BLAST mediante la opción --exclude. Acepta patrones glob separados por comas y se puede utilizar con o sin --target.
Nota: --only-uncommitted y --target no pueden usarse juntos. Para saltar archivos durante un escaneo BLAST, use --exclude con patrones de globos separados por comas. Se puede combinar con --target escanear un subconjunto excluyendo coincidencias dentro de él.
Para controlar el nombre del proyecto mostrado en Corgea, utiliza --project-name. Si se omite, la CLI utiliza el nombre del repositorio Git cuando está disponible o, en su defecto, el del directorio actual.
Para adjuntar metadatos personalizados a un escaneo BLAST, repite --metadata con KEY=VALUE pares. Estos valores se incluyen con el escaneo y en la salida de la lista de escaneo JSON.
--metadata solo es compatible con el escáner BLAST. Cada entrada debe tener una clave no vacía; si la misma clave se suministra más de una vez, se utiliza el último valor. El escaneo BLAST normal incluye múltiples escaneos:
  • Escaneo de IA de la base de explosión
  • Escaneo PolicyIQ
  • Escaneo de detección de código malicioso
  • Escaneo de detección de secretos
  • Escaneo de detección de información personal identificable (PII)
Por defecto, todos estos escaneos se ejecutan (si están habilitados para el plan de tu empresa). Sin embargo, la CLI ofrece la flexibilidad de realizar un escaneo dirigido a uno o más tipos con la opción de tipo —scan.
o tipos multipe
Para aplicar políticas concretas en un escaneo de PolicyIQ, utiliza la opción —policy e indica uno o varios ID de política.

​
Exportar un informe de escaneo

La CLI de Corgea permite exportar los resultados de un escaneo a un archivo, lo que resulta especialmente útil al ejecutar la herramienta en un pipeline de CI. Utiliza las opciones —out-format y —out-file.
Actualmente, la CLI admite HTML, JSON, SARIF y Markdown como formatos de salida.

​
Inventario de dependencias

Utiliza corgea deps para crear un inventario offline de dependencias a partir de manifiestos y lockfiles de npm, Python y Java. El comando evalúa la política de fijación de dependencias, puede hacer que CI falle según los hallazgos y no requiere iniciar sesión ni acceder a la red.
Comandos comunes de inventario de dependencias:
Utiliza --format human, agent, json o quiet para controlar la salida de terminal de scan, graph, explain, diff y policy init. En entornos con agentes detectados, corgea deps utiliza de forma predeterminada el formato compacto agent; pasa --format human para forzar la salida normal de terminal. Para exportar un informe con corgea deps scan, utiliza --out-format table, json o sarif y, si lo necesitas, --out-file. No combines --format y --out-format en el mismo comando deps scan. Para personalizar la política de dependencias, inicializa .corgea/deps.yml:
La política generada controla si los lockfiles son obligatorios, si su ausencia o desactualización provoca un fallo y si se notifican dependencias directas que utilizan comodines, latest o rangos semver. Consulta Escaneo de dependencias para ver ejemplos de CI, la configuración de políticas y la resolución de problemas.

​
Esperar a que finalice un escaneo

Para esperar al último escaneo en curso:
O especifica un ID de escaneo para esperar:

​
Listar escaneos, hallazgos o hallazgos de SCA

Para listar todos los escaneos del directorio actual (con paginación de forma predeterminada):
Para listar los hallazgos de un escaneo concreto:
También puedes controlar la paginación:
La opción --json está disponible en comandos como list e inspect y genera resultados en formato JSON, lo que resulta útil para integraciones y automatizaciones.
La tabla de escaneos incluye los ocho primeros caracteres del SHA del commit de cada escaneo, o N/A cuando no hay ningún SHA disponible. La salida JSON incluye el valor completo de git_sha y los metadatos de escaneo de metadata devueltos por Corgea. Para listar los hallazgos de SCA de un proyecto o escaneo, utiliza --sca-issues o la abreviatura ‘-c’.
o

​
Inspeccionar un escaneo o hallazgo

Para inspeccionar un escaneo específico:
Para inspeccionar hallazgos con una salida detallada:
Para explicaciones o diferencias de corrección:

​
Integración con hooks de Git

Para garantizar la calidad y la seguridad del código, puedes integrar la CLI de Corgea en el flujo de trabajo de Git mediante hooks de pre-commit. Así podrás escanear los cambios antes de hacer commit o push. Para configurar el hook de pre-commit, ejecuta:
Al configurar el hook de pre-commit, se te pedirán las opciones del escaneo. Para utilizar rápidamente la configuración predeterminada —escaneos de PII y secretos, y niveles de fallo CR, HI, ME y LO—, ejecuta:
Para saltarse la comprobación previa al hacer un commit, utiliza el siguiente comando:

​
Modo de depuración

Para habilitar los logs de depuración, establece CORGEA_DEBUG=1 antes de ejecutar un comando.
Cuando el modo de depuración está activado, las solicitudes fallidas de subida incluyen el estado HTTP y el cuerpo de respuesta en la salida de depuración, lo que ayuda con la resolución de problemas.

​
Opciones adicionales

Para más opciones y comandos, utiliza:

​
Notas de la versión

Consulta todas las notas en la página de versiones de GitHub.