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

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 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 packs si /<extraction root>/codeql está en PATH.
• 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.

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