Uso de consultas personalizadas con CodeQL

De forma predeterminada, si no tiene un archivo de configuración personalizado especificado en la configuración de la canalización, CodeQL ejecutará el paquete de consultas security-extended para analizar el código. Puede usar consultas de CodeQL personalizadas para escribir sus propias consultas para buscar vulnerabilidades y errores específicos. También deberá crear un archivo de configuración personalizado para modificar el análisis predeterminado de CodeQL.

Para buscar consultas personalizadas existentes o para contribuir con su propia consulta personalizada, consulte Contribución a CodeQL.

Análisis con consultas personalizadas

La forma más rápida de empezar con una consulta personalizada es escribir una consulta y guardarla en el repositorio local de Azure DevOps. Puede personalizar los detalles de una consulta personalizada según sus necesidades, pero debe tener al menos un ID de regla. Para obtener más información sobre cómo escribir su propia consulta de CodeQL, consulte Escritura de consultas de CodeQL. También puede agrupar varias consultas en un conjunto de consultas o usar paquetes publicados por otras personas. Para obtener más información, consulte Publicación y uso de paquetes de CodeQL.

Uso de un archivo de configuración personalizado

Un archivo de configuración personalizado es una manera de administrar las consultas que se ejecutan durante el análisis de CodeQL en el código. Puede especificar más consultas o paquetes de consultas que se van a ejecutar y cambiar o deshabilitar las consultas de CodeQL predeterminadas.

Para incluir una consulta específica que desee incluir, especifique la consulta con un nombre y una ruta de acceso a la ubicación del archivo de consulta (.ql) en el repositorio.

Para incluir un paquete específico que desee incluir, especifique el nombre del paquete. Puede especificar cualquier número de paquetes de consultas de CodeQL para ejecutarlas en el archivo de configuración.

El siguiente paso consiste en crear un archivo qlpack.yml. Este archivo declara el paquete CodeQL e información sobre él. Los archivos *.ql del mismo directorio (o subdirectorio) como qlpack.yml se consideran parte del paquete.

Sugerencia

El filtro packs del archivo de configuración admite la descarga de paquetes de repositorios hospedados en GitHub, pero el filtro queries no. Si el paquete es privado en GitHub, debe proporcionar un token de acceso de GitHub a través de la tarea AdvancedSecurity-Codeql-Init@1 como una variable de entorno y un nombre de variable como GITHUB_TOKEN, con el ámbito del token read:packages.

Este es un archivo de configuración de ejemplo:

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

Sugerencia

Las especificaciones del archivo de configuración ignoran y tienen prioridad sobre las configuraciones en el nivel de canalización para la tarea AdvancedSecurity-Codeql-Init@1. includepaths / ignorepaths se ignorarán o, si paths/paths-ignore existen, se sobrescribirán con los valores de paths/paths-ignore. querysuite se sobrescribirá con los valores especificados en queries o packs en el archivo de configuración.

Si usa cualquier consulta personalizada, este es un ejemplo de qlpack.yml colocado en el directorio de las consultas personalizadas:

version: 1.0.1
dependencies:
  codeql/javascript-all: "*"
  codeql/javascript-queries: "*"

La variable dependencies contiene todas las dependencias de este paquete y sus intervalos de versiones compatibles. Se hace referencia a cada dependencia como el scope/name de un paquete de biblioteca de CodeQL. Al definir dependencies, su qlpack.yml depende exactamente de uno de los paquetes de idioma principales (por ejemplo, JavaScript, C#, Ruby, etc.), que determina el lenguaje que puede analizar la consulta.

Para obtener consejos y opciones de configuración más específicos con el archivo de configuración, consulte Personalización de la configuración avanzada para el análisis de códigos o, para la configuración de qlpack.yml, consulte Estructura de paquetes CodeQL.

Una vez que tenga el archivo de configuración, deberá personalizar la canalización que ejecuta el análisis de CodeQL para usar el nuevo archivo. Esta es una canalización de ejemplo que apunta a un archivo de configuración:

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis