Personalización del flujo de trabajo de examen de código con CodeQL: parte 1

• 10 minutos

Los flujos de trabajo de examen de código que usan CodeQL tienen varias opciones de configuración que se pueden ajustar para satisfacer mejor las necesidades de la organización.

Cuando se usa CodeQL para examinar código, el motor de análisis de CodeQL genera una base de datos a partir del código, en la que ejecuta consultas. El análisis de CodeQL usa un conjunto predeterminado de consultas, pero puede especificar más consultas para ejecutarlas, además de las predeterminadas.

Puede ejecutar consultas adicionales si forman parte de un paquete de CodeQL (beta) publicado en el registro de contenedor de GitHub o un paquete de QL almacenado en un repositorio.

Hay dos opciones para especificar qué consultas se quieren ejecutar con el examen de código de CodeQL:

• Uso del flujo de trabajo de examen de código
• Uso de un archivo de configuración personalizado

En esta unidad, aprenderá a editar un archivo de flujo de trabajo para hacer referencia a consultas adicionales, a usar consultas de paquetes de consulta y a combinar consultas de un archivo de flujo de trabajo y un archivo de configuración personalizado.

Especificación de consultas adicionales en un archivo de flujo de trabajo

Las opciones disponibles para especificar las consultas adicionales que se quieren ejecutar son las siguientes:

• packs para instalar uno o varios paquetes de consulta de CodeQL (beta) y ejecutar el conjunto de consultas predeterminado o las consultas para esos paquetes.
• queries para especificar un único archivo .ql, un directorio que contiene varios archivos .ql, un archivo de definición del conjunto de consultas .qls o cualquier combinación.

Puede usar paquetes y consultas en el mismo flujo de trabajo.

No se recomienda hacer referencia a conjuntos de consultas directamente desde el repositorio github/codeql, como github/codeql/cpp/ql/src@main. Es posible que estas consultas no se compilen con la misma versión de CodeQL que se usa para las demás consultas, lo que podría provocar errores durante el análisis.

Uso de paquetes de consulta de CodeQL

Para agregar uno o varios paquetes de consulta de CodeQL (beta), agregue una entrada with: packs: dentro de la sección uses: github/codeql-action/init@v1 del flujo de trabajo. Dentro de los paquetes, puede especificar uno o varios paquetes para usar y, opcionalmente, qué versión descargar. Cuando no se especifica una versión, se descarga la más reciente. Si quiere usar paquetes que no están disponibles de forma pública debe establecer la variable de entorno GITHUB_TOKEN en un secreto que tenga acceso a los paquetes.

En el ejemplo siguiente, el ámbito es la cuenta personal o de la organización que ha publicado el paquete. Cuando se ejecuta el flujo de trabajo, los tres paquetes de consulta de CodeQL se descargan de GitHub y las consultas predeterminadas o el conjunto de consultas para cada ejecución de paquete. En el ejemplo siguiente, cada uno de los paquetes de la lista se descargará en función de sus especificaciones:

• Se descarga la versión más reciente de pack1 y se ejecutan todas las consultas predeterminadas.
• Se descarga la versión 1.2.3 de pack2 y se ejecutan todas las consultas predeterminadas.
• Se descarga la versión más reciente de pack3 que es compatible con la versión 3.2.1 y se ejecutan todas las consultas.
• La versión 4.5.6 de pack4 se descarga y solo se ejecutan las consultas que se encuentran en path/to/queries.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Uso de consultas en paquetes de QL

Para agregar una o varias consultas, agregue una entrada with: queries: dentro de la sección uses: github/codeql-action/init@v3 del flujo de trabajo. Si las consultas están en un repositorio privado, use el parámetro external-repository-token para especificar un token que tenga acceso para extraer del repositorio privado.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

También puede especificar conjuntos de consultas en el valor de queries. Los conjuntos de consultas son colecciones de consultas, normalmente agrupadas por propósito o lenguaje.

Los siguientes conjuntos de consultas están integrados en el examen de código de CodeQL y disponibles para su uso:

Conjunto de consultas	Descripción
security-extended	Consultas del conjunto predeterminado, además de consultas de gravedad y precisión más bajas
security-and-quality	Consultas de security-extended, además de consultas de mantenimiento y confiabilidad.

Cada uno de estos conjuntos de consultas contiene otro subconjunto de las consultas incluidas en el paquete de consultas de CodeQL integrado para ese lenguaje. Los conjuntos de consultas se generan automáticamente con los metadatos de cada consulta.

Cuando se especifica un conjunto de consultas, el motor de análisis de CodeQL ejecutará las contenidas en el conjunto de consultas, además del conjunto predeterminado.

Combinación de consultas de un archivo de flujo de trabajo y un archivo de configuración personalizado

Si también usa un archivo de configuración para la configuración personalizada, se usan los paquetes o consultas adicionales especificados en el flujo de trabajo en lugar de los especificados en el archivo de configuración. Si quiere ejecutar el conjunto combinado de paquetes o consultas adicionales, use el símbolo + como prefijo del valor packs o queries en el flujo de trabajo.

En el ejemplo siguiente, el símbolo + garantiza que los paquetes y consultas adicionales especificados se usan junto con los especificados en el archivo de configuración al que se hace referencia:

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries