Configuración de la CLI de CodeQL

En este artículo

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

Las licencias de GitHub CodeQL se otorgan por usuario tras la instalación. Puedes usar CodeQL solo para determinadas tareas según las restricciones de las licencias. Para obtener más información, vea «Acerca de la CLI de CodeQL».

Si tienes una licencia de GitHub Advanced Security, puedes usar CodeQL para el análisis automatizado, la integración continua y la entrega continua. Para obtener más información, vea «Acerca de GitHub Advanced Security».

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 "Versiones" 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.

Nota: La CodeQL CLI no es compatible actualmente con distribuciones de Linux que no sean glibc, como Alpine Linux (basado en musl).

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.

Nota: La funcionalidad de administración de paquetes de CodeQL, incluidos los de CodeQL, se encuentra actualmente en versión beta y está sujeta a cambios.

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".

Nota: Si añades codeql a tu PATH, CodeQL para Visual Studio Code podrá acceder compilar y ejecutar consultas. Para obtener más información sobre cómo configurar VS Code para acceder a CodeQL CLI, vea «Configuración de CodeQL en Visual Studio Code».

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».