Configuración avanzada de la CLI de CodeQL

Puedes modificar el programa de instalación de la CodeQL CLI para usar una restauración local del repositorio de CodeQL para su análisis, configurar varias versiones de la CodeQL CLI y analizar las bases de datos que descargaste de GitHub.com.

¿Quién puede utilizar esta característica?

Las licencias de GitHub CodeQL se otorgan por usuario tras la instalación. Puedes usar CodeQL solo para determinadas tareas según las restricciones de las licencias. Para obtener más información, vea «Acerca de la CLI de CodeQL».

Si tienes una licencia de GitHub Advanced Security, puedes usar CodeQL para el análisis automatizado, la integración continua y la entrega continua. Para obtener más información, vea «Acerca de GitHub Advanced Security».

En este artículo

Acerca de la configuración avanzada de la CodeQL CLI

Si tienes previsto usar CodeQL para algo más que el análisis de código, puede que prefieras una configuración avanzada de la CodeQL CLI.

  • Si deseas contribuir a consultas compartidas de código abierto de CodeQL, quizás prefieras trabajar directamente con el código fuente de CodeQL.
  • Si deseas usar las características más recientes de CodeQL para generar alertas de análisis de código para un código base, pero también quieres analizar otro código base que solo sea compatible con una versión específica de la CodeQL CLI, puedes instalar varias versiones de la CodeQL CLI.
  • Si estás investigando o desarrollando consultas, puede que desees descargar bases de datos interesantes o únicas de GitHub.com.

Para más Información sobre la configuración de CodeQL CLI, consulta «Configuración de la CLI de CodeQL».

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.

1. Descarga del archivo 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

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

From macOS version 10.15 ("Catalina") onwards you need to ensure that your web browser does not automatically extract zip files. If you use Safari, complete the following steps before downloading the CodeQL CLI zip archive:

  1. Open Safari.
  2. From the Safari menu, select Preferences... or Settings... (version 13 "Ventura" onwards).
  3. Click the General Tab.
  4. Ensure the check-box labeled Open "safe" files after downloading is unchecked.

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 «Creación y uso de 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 o 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/.

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

5. Iniciar 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".

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. Puedes descargar las versiones de CodeQL CLI que desees y desempaquetar ambos archivos de la CLI en el mismo directorio principal.

Descarga de bases de datos desde el GitHub.com

GitHub almacena bases de datos de CodeQL para más de 200 000 repositorios en el GitHub.com, que puedes descargar mediante la API REST. La lista de repositorios está creciendo y evolucionando constantemente a fin de garantizar que incluye los códigos base más interesantes para la investigación de seguridad.

También puedes analizar bases de datos de GitHub.com mediante la extensión CodeQL para VS Code. Para obtener más información, vea «Ejecución de consultas de CodeQL».

Puedes comprobar si un repositorio tiene bases de datos de CodeQL disponibles para su descarga mediante el punto de conexión /repos/<owner>/<repo>/code-scanning/codeql/databases. Por ejemplo, para comprobar si hay bases de datos de CodeQL con la GitHub CLI, ejecutarías lo siguiente:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases

Este comando devuelve información sobre cualquier base de datos de CodeQL que está disponible para un repositorio, incluido el lenguaje que representa la base de datos y cuándo se actualizó por última vez la base de datos. Si no hay bases de datos de CodeQL disponibles, la respuesta está vacía.

Cuando hayas confirmado que existe una base de datos de CodeQL para el lenguaje para el que muestras interés, puedes descargarla con el comando siguiente:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

Para obtener más información, consulta la documentación del punto de conexión de base de datos Get de CodeQL.

Para poder ejecutar un análisis con la CodeQL CLI, debes descomprimir las bases de datos.