Configuración de la CLI de CodeQL

Configuración de la CodeQL CLI

Para ejecutar los comandos CodeQL , 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 tiene previsto usar CodeQL CLI para la investigación en seguridad o para probar o contribuir con consultas, es posible que necesite una configuración más avanzada. Para más información, consulta Configuración avanzada 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.

1. Descarga del archivo tar de CodeQL CLI

El paquete de descarga de la CodeQL CLI es un archivo ZIP 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

2. Extracción del archivo tar de CodeQL CLI

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

Opcional: hacer que CodeQL CLI se encuentre disponible en el sistema de CI.

Si tiene previsto ejecutar CodeQL code scanning en un sistema de CI, asegúrese de que el paquete completo de CodeQL CLI está disponible para cada servidor de CI que ejecutará el análisis.

Por ejemplo, puede hacer lo siguiente:

• Copie la agrupación desde una ubicación interna central y extráigala en cada servidor, o bien
• Utilice la API REST para descargar el paquete directamente desde GitHub, para garantizar que recibe las mejoras más recientes en consultas. Para más información, consulta Puntos de conexión de la API de REST para lanzamientos y recursos de versión.

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.

Prueba de la configuración de la CodeQL CLI

Después de extraer el conjunto de la CodeQL CLI, puedes 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`.
  

•           En caso 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 ser dentro del conjunto de la CodeQL CLI extraído, que se muestra en el ejemplo anterior como <extraction root>. Si el CodeQL CLI no es capaz de localizar los qlpacks para los lenguajes esperados, verifica que hayas descargado el paquete de CodeQL y no una copia independiente del CodeQL CLI.

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

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

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

Pasos siguientes

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