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.
Nota: La CodeQL CLI no es compatible actualmente con distribuciones de Linux que no sean glibc, como Alpine Linux (basado en musl).
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.
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)
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:
- Abre Safari.
- En el menú Safari, selecciona Preferencias... o Configuración... (versión 13 "Ventura" en adelante).
- Haz clic en la pestaña General.
- 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:
mv ~/Downloads/codeql\*.zip ${extraction-root}
cd ${extraction-root}
/usr/bin/xattr -c codeql\*.zip
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
aPATH
, para poder ejecutar el archivo ejecutable simplemente comocodeql
.
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 agregas codeql
a tu PATH
, CodeQL puede acceder a ella para permitir que Visual Studio Code compile y ejecute consultas.
Para obtener más información sobre cómo configurar VS Code para acceder a la CodeQL CLI, consulta "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á enPATH
.- 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».
Nota: Hay diferentes versiones disponibles de las consultas de CodeQL para distintos usuarios. Elige la versión correcta según tu caso de uso:
- Para las consultas que se usarán con la versión más reciente de la CodeQL CLI, consulta la rama etiquetada como
codeql-cli/latest
. Debes usar esta rama para las bases de datos que has creado mediante la CodeQL CLI, has capturado del análisis de código en GitHub o has descargado recientemente de GitHub.com. - Para las consultas más actualizadas de CodeQL, consulta la rama
main
. Esta rama representa la versión más reciente del análisis 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
.