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 usas Linux, Windows o macOS versión 10.14 ("Mojave"), o versiones anteriores, simplemente sigue los pasos que se indican a continuación. Para macOS versión 10.15 ("Catalina") o versiones posteriores, existen notas adicionales para algunos de los pasos. 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.

Para obtener información sobre la instalación de la CodeQL CLI en un sistema de CI a fin de crear resultados que se muestren en GitHub como alertas de examen de código, consulta "Instalar el CLI de CodeQL en tu sistema de IC".

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)

Desde macOS versión 10.15 ("Catalina") en adelante, debes asegurarte de que el explorador web no extraiga automáticamente los archivos ZIP. Si usas Safari, completa los pasos siguientes antes de descargar el archivo ZIP de la CodeQL CLI:

1. Abre Safari.
2. En el menú Safari, selecciona Preferencias... o Configuración... (versión 13 "Ventura" en adelante).
3. Haz clic en la pestaña General.
4. Asegúrate de que la casilla Abrir archivos "seguros" al descargarlos está desactivada.

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.

Extraer desde una salida satisfactoria:

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>, a menos que estés utilizando una restauración de github/codeql. 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.

(Opcional) Puedes descargar algunos "Personalización del análisis con paquetes de CodeQL" que contengan consultas precompiladas que te gustaría ejecutar. Para ello, ejecuta codeql pack download <pack-name> [...pack-name], donde pack-name es el nombre del paquete que quieres descargar. Los paquetes de consultas principales son un buen punto de partida. Son las siguientes:

• codeql/cpp-queries
• codeql/csharp-queries
• codeql/go-queries
• codeql/java-queries
• codeql/javascript-queries
• codeql/python-queries
• codeql/ruby-queries

Como alternativa, puedes descargar paquetes de consulta durante el análisis mediante la marca --download del comando codeql database analyze.

Generar un token para autenticarse con GitHub

Si finalmente deseas cargar los resultados en GitHub para mostrarlos como alertas de examen de código, deberás generar un personal access token con el permiso de escritura security_events. Para obtener más información, vea «Administración de tokens de acceso personal».

Si has instalado la CodeQL CLI en un sistema de CI de terceros a fin de crear resultados que se muestren en GitHub como alertas de examen de código, puedes usar una GitHub App o un personal access token para cargar los resultados en GitHub. Para obtener más información, vea «Instalar el CLI de CodeQL en tu sistema de IC».

Modificación del código fuente de CodeQL directamente

Algunos usuarios prefieren trabajar directamente con orígenes de consulta de CodeQL para usar consultas compartidas de código abierto o contribuir a ellas. Para esto, se recomienda seguir los pasos siguientes. Ten en cuenta que las instrucciones a continuación son una alternativa ligeramente más complicada que trabajar con paquetes de CodeQL, como se ha explicado anteriormente.

1. Descarga del archivo ZIP de la CodeQL CLI

Sigue el paso 1 de la sección anterior.

2. Creación de un nuevo directorio de CodeQL

Crea un directorio donde puedas incluir la CLI y las consultas y bibliotecas que quieras usar. Por ejemplo, $HOME/codeql-home.

Las operaciones de búsqueda integradas de la CLI buscan automáticamente en todos sus directorios del mismo nivel los archivos usados en la creación y el análisis de la base de datos. Mantener estos componentes en su propio directorio impide que la CLI busque en directorios del mismo nivel no relacionados, a la vez que garantiza que todos los archivos están disponibles sin especificar más opciones en la línea de comandos.

3. Obtención de una copia local de las consultas de CodeQL

El repositorio de CodeQL contiene las consultas y bibliotecas necesarias para el análisis de CodeQL de todos los lenguajes admitidos. Clona una copia de este repositorio en codeql-home.

De forma predeterminada, la raíz del repositorio clonado se llamará codeql. Cambie el nombre de esta carpeta a codeql-repo para evitar conflictos con la CodeQL CLI que extraerás en el paso 1. Si usas Git en la línea de comandos, puedes clonar el repositorio y cambiarle el nombre en un solo paso mediante la ejecución de git clone git@github.com:github/codeql.git codeql-repo en la carpeta codeql-home.

En este repositorio, las consultas y bibliotecas se organizan en paquetes de CodeQL. Además de las propias consultas, los paquetes de CodeQL contienen metadatos importantes que indican a la CodeQL CLI cómo procesar los archivos de consulta. Para obtener más información, vea «Personalización del análisis con paquetes de CodeQL».

4. Extraer el archivo ZIP

Si eres usuario de Linux, Windows y macOS (versión 10.14 "Mojave" y versiones anteriores) simplemente extrae el archivo ZIP en el directorio que has creado en el paso 2.

Por ejemplo, si la ruta de acceso a tu copia del repositorio de CodeQL es $HOME/codeql-home/codeql-repo, extrae la CLI en $HOME/codeql-home/.

5. Iniciar codeql

Consulta el paso 3 de la sección anterior.

6. Comprobación de la configuración de la CodeQL CLI

CodeQL CLI tiene subcomandos que puedes ejecutar para comprobar que la CLI está configurada correctamente para crear y analizar bases de datos:

• Ejecute 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.
• Ejecuta codeql resolve qlpacks para mostrar qué paquetes de CodeQL puede encontrar la CLI. Se mostrarán los nombres de todos los paquetes de CodeQL disponibles directamente para la CodeQL CLI. Esto debería incluir:
• Paquetes de consulta para cada lenguaje admitido, por ejemplo, codeql/{language}-queries. Estos paquetes contienen las consultas estándar que se ejecutarán para cada análisis.
• Paquetes de biblioteca para cada lenguaje admitido, por ejemplo, codeql/{language}-all. Estos paquetes contienen bibliotecas de consultas, como bibliotecas de flujo de control y flujo de datos, que pueden ser útiles para los creadores de consultas.
• Paquetes de ejemplo para cada lenguaje admitido, por ejemplo, codeql/{language}-examples. Estos paquetes contienen fragmentos de código de CodeQL que pueden resultar útiles para los creadores de consultas.
• Paquetes heredados que garantizan que las consultas personalizadas y las bibliotecas creadas con productos anteriores son compatibles con la versión de CodeQL.

Uso de dos versiones de la CodeQL CLI

Si quieres usar las características más recientes de CodeQL para ejecutar consultas o pruebas de CodeQL, pero también quieres preparar bases de datos compatibles con una versión específica del análisis de código de CodeQL en GitHub Enterprise Server, es posible que necesites instalar dos versiones de la CLI. La configuración recomendada del directorio depende de las versiones que quieras instalar:

• Si son dos versiones 2.0.2 (o posteriores), puedes desempaquetar ambos archivos de CLI en el mismo directorio principal.
• Si al menos una de las versiones es 2.0.1 (o anterior), los archivos de CLI desempaquetados no pueden estar en el mismo directorio principal, pero pueden compartir el mismo directorio principal de nivel superior. Por ejemplo, si desempaquetas la versión 2.0.2 en $HOME/codeql-home/codeql-cli, la versión anterior debe desempaquetarse en $HOME/codeql-older-version/old-codeql-cli. Aquí, el directorio principal de nivel superior común es el directorio $HOME.