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

8 minutos

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

En esta unidad, repasaremos cómo hacer referencia a consultas adicionales en un archivo de configuración personalizado.

Consultas adicionales en un archivo de configuración personalizado

Un archivo de configuración personalizado es una manera alternativa de especificar paquetes y consultas adicionales para ejecutar. También puede usar el archivo para deshabilitar las consultas predeterminadas y especificar los directorios que se examinarán durante el análisis.

En el archivo de flujo de trabajo, use el parámetro config-file de la acción init para especificar la ruta de acceso al archivo de configuración que desea usar. En este ejemplo se carga el archivo de configuración ./.github/codeql/codeql-config.yml.

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

El archivo de configuración se puede encontrar en el repositorio que va a analizar o en un repositorio externo. El uso de un repositorio externo permite especificar opciones de configuración para varios repositorios en un solo lugar. Al hacer referencia a un archivo de configuración ubicado en un repositorio externo, puede usar la sintaxis OWNER/REPOSITORY/FILENAME@BRANCH. Por ejemplo: octo-org/shared/codeql-config.yml@main.

Si el archivo de configuración se encuentra en un repositorio privado externo, use el parámetro external-repository-token de la acción init para especificar un token que tenga acceso al repositorio privado.

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Los valores del archivo de configuración se escriben en formato YAML.

Especificación de paquetes de consultas de CodeQL en archivos de configuración personalizados

Nota:

La funcionalidad de administración de paquetes de CodeQL, incluidos los paquetes de CodeQL, está actualmente en versión beta, sujeta a cambios.

Puede especificar los paquetes de consulta de CodeQL en una matriz. El formato es diferente del que utiliza el archivo del flujo de trabajo.

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

El formato completo para especificar un paquete de consulta es scope/name[@version][:path]. version y path son opcionales. version es el intervalo de versiones de SemVer. Si falta, se usa la versión más reciente.

Si tiene un flujo de trabajo que genera más de una base de datos de CodeQL, puede especificar los paquetes de consultas de CodeQL que se ejecutarán en un archivo de configuración personalizado mediante un mapa anidado de paquetes.

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Especificación de consultas adicionales en una configuración personalizada

Puede especificar consultas adicionales en una matriz queries. Cada elemento de la matriz contiene un parámetro uses con un valor que identifica un único archivo de consulta, un directorio que contiene archivos de consulta o un archivo de definición de un conjunto de consultas.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Opcionalmente, puede asignar un nombre a cada elemento de matriz, como se muestra en el archivo de configuración de ejemplo siguiente:

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Deshabilitación de las consultas predeterminadas

Si solo desea ejecutar consultas personalizadas, puede deshabilitar las consultas de seguridad predeterminadas mediante disable-default-queries: true. También debe usar esta marca si intenta construir un conjunto de consultas personalizadas que excluya una regla concreta. Esto evita que todas las consultas se ejecuten dos veces.

Exclusión de consultas específicas del análisis

Puede agregar filtros exclude y include al archivo de configuración personalizado para especificar las consultas que desea excluir o incluir en el análisis, como:

Consultas específicas de los conjuntos predeterminados (securitysecurity-extended y security-and-quality).
Consultas específicas cuyos resultados no te interesan.
Todas las consultas que generan advertencias y recomendaciones.

Puede usar filtros exclude similares a los de la configuración del siguiente archivo para excluir las consultas que desea quitar del análisis predeterminado. En el ejemplo de archivo de configuración siguiente, las consultas js/redundant-assignment y js/useless-assignment-to-local se excluyen del análisis.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Para buscar el identificador de una consulta, puede hacer clic en la alerta en la lista de alertas de la pestaña Seguridad. Se abrirá la página de información de la alerta. El campo Id. de regla contiene el identificador de consulta.

Aspectos que se deben tener en cuenta al trabajar con el filtro excludes:

El orden de los parámetros es importante. La primera instrucción de filtro que aparece después de las instrucciones sobre las consultas y los paquetes de consultas determina si las consultas se incluyen o excluyen de forma predeterminada.
Las instrucciones posteriores se ejecutan en orden y las instrucciones que aparecen más adelante en el archivo tienen prioridad sobre las instrucciones anteriores.

Especificación de los directorios que se examinarán

Para los lenguajes interpretados que admite CodeQL (Python, Ruby y JavaScript/TypeScript), puede restringir el examen de código a archivos de directorios específicos agregando una matriz paths de acceso al archivo de configuración. Puede excluir los archivos de directorios específicos del análisis agregando una matriz paths-ignore.

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Nota:

Las palabras clave paths y paths-ignore, que se usan en el contexto del archivo de configuración de examen de código, no deben confundirse con las mismas palabras clave cuando se usan para on.<push|pull_request>.paths en un flujo de trabajo. Cuando se usan para modificar on.<push|pull_request> en un flujo de trabajo, determinan si las acciones se ejecutarán cuando alguien modifique el código en los directorios especificados.
Los caracteres de patrón de filtro ?, +, [, ] y ! no se admiten y coincidirán literalmente.
Los caracteres ** solo pueden colocarse al principio o al final de una línea, o rodeados por barras diagonales, y no se puede mezclar ** ni otros caracteres. Por ejemplo, foo/**, **/foo y foo/**/bar son una sintaxis permitida, pero **foo no lo es. Pero puede usar un solo asterisco junto con otros caracteres, como se muestra en el ejemplo. Tendrá que citar todo lo que contenga un carácter *.

En el caso de los lenguajes compilados, si desea limitar el examen de código a directorios específicos del proyecto, debe especificar los pasos de compilación adecuados en el flujo de trabajo. Los comandos que debe usar para excluir un directorio de la compilación dependerán del sistema de compilación.

Puede analizar rápidamente pequeñas partes de un repositorio mono al modificar el código en directorios específicos. Deberá excluir directorios en los pasos de compilación y usar las palabras clave paths-ignore y paths para on.<push|pull_request> en el flujo de trabajo.

Continuar