Configuración de la CLI de CodeQL

Configuración de la CodeQL CLI

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

La CodeQL CLI se pueden configurar para admitir muchos casos de uso y estructuras de directorio diferentes. Para empezar a trabajar rápidamente, se recomienda adoptar una configuración relativamente sencilla, como se describe en los siguientes pasos.

Si tienes previsto usar la CodeQL CLI para la investigación de seguridad o para probar o contribuir consultas, puede que prefieras una configuración más avanzada de la CodeQL CLI. Para obtener más información, vea «Configuración avanzada de la CLI de CodeQL».

Si estás configurando la CodeQL CLI en tu sistema de IC, necesitas habilitar el contenido integral del paquete de la CodeQL CLI para cada servidor de IC en el que quieras ejecutar el análisis code scanning de CodeQL. Por ejemplo, puedes configurar cada servidor para copiar el paquete desde una ubicación intera y centrar y extraerlo. Como alternativa, puedes utilizar la API de REST para obtener el paquete directamente desde GitHub para garantizar que te beneificarás de las últimas mejoras a las consultas. Para más información, consulta "Puntos de conexión de la API de REST para lanzamientos y recursos de versión" en la documentación de REST API.

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 paquete ZIP de la 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

Siempre debes utilizar Siempre debes utilizar el paquete de CodeQL, ya que este garantiza la compatibilidad y también te 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.gz adecuado. Como alternativa, puedes descargar codeql-bundle.tar.gz, que contiene la CLI para todas las plataformas compatibles.

Información de descarga para usuarios de macOS "Catalina" (o versiones más recientes)

From macOS version 10.15 ("Catalina") onwards you need to ensure that your web browser does not automatically extract zip files. If you use Safari, complete the following steps before downloading the CodeQL CLI zip archive:

1. Open Safari.
2. From the Safari menu, select Preferences... or Settings... (version 13 "Ventura" onwards).
3. Click the General Tab.
4. Ensure the check-box labeled Open "safe" files after downloading is unchecked.

2. Extracción del archivo ZIP

Para los usuarios de Linux, Windows y macOS (versión 10.14 "Mojave" y versiones anteriores) simplemente extrae el archivo ZIP.

Información de extracción para usuarios de macOS "Catalina" (o versiones más recientes)

Los usuarios de macOS "Catalina", "Big Sur", "Monterey" o "Ventura" deben ejecutar los siguientes comandos en el terminal, donde ${extraction-root} es la ruta de acceso al directorio donde extraerás el archivo ZIP de la CodeQL CLI:

1. mv ~/Downloads/codeql\*.zip ${extraction-root}
2. cd ${extraction-root}
3. /usr/bin/xattr -c codeql\*.zip
4. unzip codeql\*.zip

3. Ejecución de 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 qlpacks si /<extraction-root>/codeql está en PATH.
• En caso contrario, es /<extraction-root>/codeql/codeql resolve qlpacks.

Si todo va bien, deberías ver una salida similar a la siguiente:

codeql/cpp-all (/<extraction-root>/qlpacks/codeql/cpp-all/<version>)
codeql/cpp-examples (/<extraction-root>/qlpacks/codeql/cpp-examples/<version>)
codeql/cpp-queries (/<extraction-root>/qlpacks/codeql/cpp-queries/<version>)
codeql/csharp-all (/<extraction-root>/qlpacks/codeql/charp-all/<version>)
codeql/csharp-examples (/<extraction-root>/qlpacks/codeql/charp-examples/<version>)
codeql/csharp-queries (/<extraction-root>/qlpacks/codeql/charp-queries/<version>)
codeql/java-all (/<extraction-root>/qlpacks/codeql/java-all/<version>)
codeql/java-examples (/<extraction-root>/qlpacks/codeql/java-examples/<version>)
codeql/java-queries (/<extraction-root>/qlpacks/codeql/java-queries/<version>)
codeql/javascript-all (/<extraction-root>/qlpacks/codeql/javascript-all/<version>)
codeql/javascript-examples (/<extraction-root>/qlpacks/codeql/javascript-examples/<version>)
codeql/javascript-queries (/<extraction-root>/qlpacks/codeql/javascript-queries/<version>)
codeql/python-all (/<extraction-root>/qlpacks/codeql/python-all/<version>)
codeql/python-examples (/<extraction-root>/qlpacks/codeql/python-examples/<version>)
codeql/python-queries (/<extraction-root>/qlpacks/codeql/python-queries/<version>)
codeql/ruby-all (/<extraction-root>/qlpacks/codeql/ruby-all/<version>)
codeql/ruby-examples (/<extraction-root>/qlpacks/codeql/ruby-examples/<version>)
codeql/ruby-queries (/<extraction-root>/qlpacks/codeql/ruby-queries/<version>)
...

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, puedes descargar algunos paquetes de CodeQL que contengan consultas precompiladas que te gustaría ejecutar. Para obtener más información, vea «Personalización del análisis con paquetes de CodeQL».

Pasos siguientes

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