Personalización del flujo de trabajo de examen de código con CodeQL: parte 2
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 (
security
security-extended
ysecurity-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
ypaths-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 paraon.<push|pull_request>.paths
en un flujo de trabajo. Cuando se usan para modificaron.<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
yfoo/**/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.