Configuración de la CLI de CodeQL

Para empezar a trabajar con CodeQL CLI, debe descargar y configurar la CLI para que pueda acceder a las herramientas y bibliotecas necesarias para crear y analizar bases de datos.

¿Quién puede utilizar esta característica?

CodeQL está disponible para los siguientes tipos de repositorios:

En este artículo

Configuración del CodeQL CLI

Para ejecutar CodeQL comandos, debe configurar CodeQL CLI para que pueda acceder a las herramientas, consultas y bibliotecas necesarias para crear y analizar bases de datos.

          CodeQL CLI admite una variedad de casos de uso y estructuras de directorio. En este artículo se explica una configuración sencilla que funciona para la mayoría de los usuarios y entornos.

Si planea usar el CodeQL CLI para la investigación de seguridad o para probar o contribuir a consultas, es posible que necesite una configuración más avanzada. Para obtener más información, vea Acerca de la CLI de CodeQL.

Antes de empezar

Si usas macOS en Apple Silicon (por ejemplo, Apple M1), asegúrate de tener instaladas las herramientas de desarrollo de la línea de comandos de Xcode y Rosetta 2.

Nota:

          CodeQL CLI Actualmente, no es compatible con distribuciones linux no glibc como Alpine Linux (basada en muslc).

1. Descargar el archivo tar CodeQL CLI

El paquete de descarga de la CodeQL CLI es un archivo tar que contiene herramientas, scripts y varios archivos específicos de CodeQL. Si no tienes una licencia de GitHub Enterprise, al descargar este archivo aceptas los términos y condiciones de GitHub CodeQL.

Debes descargar el conjunto de CodeQL desde https://github.com/github/codeql-action/releases. La agrupación contiene lo siguiente:

  • El producto de CodeQL CLI
  • Una versión compatible de las consultas y bibliotecas de https://github.com/github/codeql
  • Versiones precompiladas de todas las consultas incluidas en la agrupación

Debe usar siempre el conjunto de CodeQL. Esto garantiza la compatibilidad y también da un rendimiento mucho mejor que una descarga independiente del CodeQL CLI y una verificación de las consultas de CodeQL. Si solo vas a ejecutar la CLI en una plataforma específica, descarga el archivo codeql-bundle-PLATFORM.tar.zst adecuado. Como alternativa, puedes descargar codeql-bundle.tar.zst, que contiene la CLI para todas las plataformas compatibles.

También hay variantes tar.gz del conjunto, que son idénticas a las variantes tar.zst, excepto que se comprimen mediante el algoritmo gzip menos eficaz. La única razón para descargar las variantes tar.gz es si usa herramientas de descompresión anteriores que no admiten el algoritmo de compresión Zstandard.

2. Extraer el archivo tar CodeQL CLI

Extraiga el archivo tar CodeQL CLI en un directorio de su elección.

Opcional: Hacer que CodeQL CLI esté disponible en su sistema de CI

Si tiene previsto ejecutar CodeQLcode scanning análisis en un sistema de CI, asegúrese de que el contenido completo de la CodeQL CLI agrupación está disponible para cada servidor de CI que ejecutará el análisis.

Por ejemplo, puede hacer lo siguiente:

3. Iniciar codeql

Una vez extraído, puedes ejecutar procesos de CodeQL mediante el archivo ejecutable codeql de dos maneras:

  • Ejecutando <extraction-root>/codeql/codeql, donde <extraction-root> es la carpeta en la que has extraído el paquete de la CodeQL CLI.
  • Agregando <extraction-root>/codeql a PATH, para poder ejecutar el archivo ejecutable simplemente como codeql.

A partir de este momento, ya puedes ejecutar comandos de CodeQL. Para ver una lista completa de los comandos de CodeQL CLI, consulta Manual de comandos de la CLI de CodeQL.

Nota:

Si agrega codeql a su PATH, CodeQL puede acceder a ello para que Visual Studio Code compile y ejecute consultas. Para obtener más información sobre cómo configurar VS Code para acceder al CodeQL CLI, vea Administración de la CLI de CodeQL en la extensión de VS Code.

Prueba de la CodeQL CLI configuración

Después de extraer la CodeQL CLI agrupación, puede ejecutar el siguiente comando para comprobar que la CLI está configurada correctamente para crear y analizar bases de datos:

  •         `codeql resolve packs` si `/<extraction root>/codeql` está en `PATH`.
  • De lo contrario, /<extraction root>/codeql/codeql resolve packs.

Si todo se ha hecho correctamente, debería ver un resultado similar al extracto siguiente:

Searching directories specified by `--additional-packs`. All directories have equal priority.
  Searching in:
    No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
  Searching in:
      <extraction root>
    The following packs were found:
      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...

Los resultados se han truncado por motivos de brevedad. Los resultados reales serán más largos y detallados.

Debes verificar que la salida contenga los lenguajes esperados y también que la ubicación del directorio para el archivo de qlpack sea correcta. La ubicación debe estar dentro del lote extraído CodeQL CLI , que se muestra en el ejemplo anterior como <extraction root>. Si CodeQL CLI no puede encontrar los qlpacks para los idiomas esperados, compruebe que descargó el paquete CodeQL y no una copia independiente de CodeQL CLI.

También puedes ejecutar codeql resolve languages para mostrar qué lenguajes están disponibles para la creación de bases de datos. Esto enumerará los idiomas admitidos de forma predeterminada en el CodeQL CLI paquete.

De manera opcional, puede descargar algunos paquetes de CodeQL que contengan consultas precompiladas que le gustaría ejecutar. Para obtener más información, vea Personalización del análisis con paquetes de CodeQL.

El comando codeql resolve packs es útil para diagnosticar problemas cuando el CodeQL CLI no puede localizar los paquetes de consultas que usted espera que estén disponibles para el análisis.

Nota:

El codeql resolve packs comando está disponible en las CodeQL CLI versiones 2.19.0 y posteriores. Para versiones anteriores de la CLI, debe ejecutar el comando codeql resolve qlpacks, que genera una salida similar, pero menos detallada.

Pasos siguientes

Para obtener información sobre cómo preparar el código que va a ser analizado, CodeQL CLI consulte Preparación del código para el análisis de CodeQL.