Configuración de la CodeQL CLI
Note
En este artículo se describen las características disponibles con el paquete CodeQL CLI 2.17.6 que se incluye en la versión inicial de GitHub Enterprise Server 3.14.
Si el administrador del sitio ha actualizado tu versión de la CodeQL CLI a una versión más reciente, consulta la versión de GitHub Enterprise Cloud de este artículo para obtener información sobre las características más recientes.
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 obtener más información, consulte "Puntos de conexión de la API de REST para lanzamientos y recursos de versión" en la documentación de la API de REST.
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.
Note
La CodeQL CLI no es compatible actualmente con distribuciones de Linux que no sean glibc, como Alpine Linux (basado en muslc).
1. Descarga del archivo tar de 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
2. Extracción del archivo tar de CodeQL CLI
Extraiga el archivo tar de CodeQL CLI en un directorio de su elección.
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".
Note
Si agregas codeql
a tu PATH
, CodeQL para Visual Studio Code podrá acceder para compilar y ejecutar consultas. Para obtener más información sobre cómo configurar VS Code para acceder a la CodeQL CLI}, consulte “Configuración del acceso a 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 packs
si/<extraction root>/codeql
está enPATH
.- En caso contrario, es
/<extraction root>/codeql/codeql resolve packs
.
Si todo va bien, debería ver una salida similar al fragmento siguiente:
Searching directories specified by `--additional-packs`. All directories have equal priority.
Searching in:
No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
Searching in:
<extraction root>
The following packs were found:
codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...
Los resultados se han truncado por motivos de brevedad. Los resultados reales serán más largos y detallados.
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».
El comando codeql resolve packs
es útil para diagnosticar problemas cuando CodeQL CLI no puede encontrar los paquetes de consultas que espera que estén disponibles para su análisis.
Note
El comando codeql resolve packs
está disponible en CodeQL CLI versiones 2.19.0 y posteriores. En el caso de versiones anteriores de la CLI, debe ejecutar el comando codeql resolve qlpacks
, que genera una salida similar, pero menos detallada.
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».