Introducción a la CLI de CodeQL

Introducción a 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.

Configuración de la CodeQL CLI

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 análisis de código, consulta Instalación de la CodeQL CLI en el sistema de CI.

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.

Si usas Linux, Windows o macOS versión 10.14 ("Mojave"), o versiones anteriores, simplemente descarga el archivo ZIP para la versión que necesitas.

Si vas a ejecutar la CLI en una plataforma específica, descarga el archivo codeql-PLATFORM.zip adecuado. Como alternativa, puedes descargar codeql.zip, que contiene la CLI para todas las plataformas compatibles.

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

Si usas macOS versión 10.15 ("Catalina"), versión 11 ("Big Sur") o la próxima versión 12 ("Monterey"), 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… .
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" o "Monterey" 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".

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

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

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 codeql-repo para evitar conflictos con la CodeQL CLI que extraerás en el paso 4. 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.

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.