Creación de conjuntos de consultas de CodeQL

Puede crear grupos de consultas a partir de las consultas que use con frecuencia en sus análisis de CodeQL. Para obtener más información, vea Conjuntos de consultas codeQL.

Búsqueda de consultas que se van a agregar a un conjunto de consultas

Al crear un conjunto de consultas, primero debes especificar las ubicaciones de las consultas que quieres seleccionar. Puedes definir la ubicación de una o varias consultas mediante lo siguiente:

• Instrucción query : indica CodeQL a buscar uno o varios archivos especificados .ql :

  - query: <path-to-query>
  

  El argumento debe ser una o más rutas de archivo, relativas al paquete CodeQL que contiene la definición del conjunto.

• Una instrucción queries: indica a CodeQL que analice recursivamente un directorio en busca de archivos .ql:

  - queries: <path-to-subdirectory>
  

  La ruta de acceso del directorio debe ser relativa a la raíz del CodeQL paquete que contiene el archivo de definición del conjunto de aplicaciones. Para buscar las consultas relativas a un paquete diferente CodeQL , agregue un from campo:

  - queries: <path-to-subdirectory>
    from: <ql-pack-name>
    version: ^x.y.z
  

  El version campo es opcional y especifica un intervalo de versiones compatibles de este CodeQL paquete. Si no especificas una versión del paquete, se usará la más reciente.

• Una instrucción qlpack: indica a CodeQL que resuelva consultas en la suite predeterminada del paquete llamado CodeQL:

  - qlpack: <qlpack-name>
    version: ^x.y.z
  

  El conjunto predeterminado de un paquete de consultas incluye un conjunto recomendado de consultas dentro de ese paquete de consultas. No todos los paquetes de consultas tienen un conjunto predeterminado. Si el paquete de consultas dado no define un conjunto predeterminado, la instrucción qlpack se resolverá en todas las consultas del paquete.

  El version campo es opcional y especifica un intervalo de versiones compatibles de este CodeQL paquete. Si no especificas una versión del paquete, se usará la más reciente.

Debes agregar al menos una instrucción query, queries o qlpack a la definición del conjunto; de lo contrario, no se seleccionará ninguna consulta. Si el conjunto no contiene más instrucciones, se seleccionan todas las consultas que se encuentran en la lista de archivos, en el directorio especificado o en el paquete con nombre CodeQL . Si hay instrucciones de filtrado adicionales, solo se seleccionarán las consultas que coincidan con las restricciones que han impuesto esas instrucciones.

Filtrado de las consultas en un conjunto de consultas

Después de definir el conjunto inicial de consultas que se van a agregar al conjunto especificando instrucciones query, queries o qlpack, puedes agregar instrucciones include y exclude. Estas instrucciones definen criterios de selección en función de propiedades específicas:

• Al ejecutar una instrucción include en un conjunto de consultas, las consultas que coincidan con las condiciones se conservan en la selección y las que no coincidan se quitan.
• Al ejecutar una instrucción exclude en un conjunto de consultas, las consultas que coincidan con las condiciones se quitan de la selección y las que no coincidan se conservan.

El orden de las instrucciones de filtro es importante. La primera instrucción de filtro que aparece después de las instrucciones de ubicación determina si las consultas se incluyen o excluyen de manera predeterminada. Si el primer filtro es un elemento include, las consultas ubicadas al principio solo formarán parte del conjunto si coinciden con un filtro explícito include. Si el primer filtro es un elemento exclude, las consultas ubicadas al principio forman parte del conjunto a menos que se excluyan de forma explícita.

Las instrucciones posteriores se ejecutan en orden y las instrucciones que aparecen más adelante en el archivo tienen prioridad sobre las instrucciones anteriores. Por lo tanto, las instrucciones include se pueden invalidar mediante instrucciones exclude posteriores que coincidan con la misma consulta. Del mismo modo, un elemento exclude posterior puede invalidar elementos include.

Para ambas instrucciones, el argumento es un bloque de restricciones, es decir, una asignación de YAML que representa las restricciones. Cada restricción es una entrada de la asignación, donde la clave suele ser una propiedad de metadatos de consulta. El valor puede ser lo siguiente:

• Una sola cadena.
• Una / incluida entre .
• Una lista que contiene cadenas, expresiones regulares o ambas.

Para que coincida con una restricción, un valor de metadatos debe coincidir con una de las cadenas o expresiones regulares. Cuando hay más de una clave de metadatos, deben coincidir todas las claves. Las claves de metadatos estándar disponibles para establecer coincidencias son: description, id, kind, name, tags, precision y problem.severity. Para obtener más información sobre las propiedades de metadatos de consulta, vea Metadatos para CodeQL consultas.

Además de las etiquetas de metadatos, las claves del bloque de restricciones también pueden ser lo siguiente:

• query filename: coincide con el último componente de ruta de acceso del nombre de archivo de la consulta.
• query path: Coincide con la ruta al archivo de consulta en relación con su paquete contenedor CodeQL.
• tags contain: una de las cadenas de coincidencia especificadas debe coincidir con uno de los componentes separados por espacios del valor de la propiedad de metadatos @tags.
• tags contain all: cada una de las cadenas de coincidencia especificadas debe coincidir con uno de los componentes de la propiedad de metadatos @tags.

Ejemplos de filtrado de las consultas que se van a ejecutan

Un caso de uso común es crear un conjunto de consultas que ejecute todas las consultas de un CodeQL paquete, excepto algunas consultas específicas que el usuario no desea ejecutar. Por lo general, se recomienda filtrar por la consulta id, que es un identificador único y estable para cada consulta. Las tres definiciones de conjunto de consultas siguientes son semánticamente idénticas y filtran por la consulta id:

Este filtro coincide con todas las consultas del conjunto predeterminado de codeql/cpp-queries, excepto para las dos consultas con los identificadores excluidos:

- qlpack: codeql/cpp-queries
- exclude:
    id:
      - cpp/cleartext-transmission
      - cpp/cleartext-storage-file

En este ejemplo, se usa una instrucción exclude independiente para cada consulta:

- qlpack: codeql/cpp-queries
- exclude:
    id: cpp/cleartext-transmission
- exclude:
    id: cpp/cleartext-storage-file

En este ejemplo, una expresión regular excluye las mismas dos consultas. También excluiría las consultas futuras agregadas al conjunto con identificadores que comienzan por cpp/cleartext-:

- qlpack: codeql/cpp-queries
- exclude:
    id:
      - /^cpp\/cleartext-.*/

Para definir un conjunto de aplicaciones que seleccione todas las consultas del paquete predeterminado codeql/cpp-queriesCodeQL y, a continuación, las refina para incluir solo consultas de seguridad, use:

- qlpack: codeql/cpp-queries
- include:
    tags contain: security

Para definir un conjunto que seleccione todas las consultas con @kind problem y @precision high desde el directorio my-custom-queries, usa lo siguiente:

- queries: my-custom-queries
- include:
    kind: problem
    precision: very-high

Tenga en cuenta que la definición siguiente del conjunto de consultas se comporta de forma diferente de la definición anterior. Esta definición selecciona las consultas que son @kind problemo@precision very-high:

- queries: my-custom-queries
- include:
    kind: problem
- include:
    precision: very-high

Para crear un conjunto que seleccione todas las consultas con @kind problem desde el directorio my-custom-queries, excepto aquellas que incluyan @problem.severity recommendation, usa lo siguiente:

- queries: my-custom-queries
- include:
    kind: problem
- exclude:
    problem.severity: recommendation

Para crear un conjunto que seleccione todas las consultas con @tag security y @precision high o very-high del paquete codeql/cpp-queriesCodeQL, use:

- queries: .
  from: codeql/cpp-queries
- include:
    tags contain: security
    precision:
    - high
    - very-high

Reutilización de definiciones del conjunto de consultas existente

Las definiciones del conjunto de consultas existente se pueden reutilizar especificando lo siguiente:

• Una instrucción import: agrega las consultas que ha seleccionado previamente un archivo .qls definido al conjunto actual:

  - import: <path-to-query-suite>
  

  La ruta de acceso al conjunto importado debe ser relativa al CodeQL paquete que contiene la definición del conjunto actual. Si el conjunto de consultas importado está en otro paquete de QL, puedes usar lo siguiente:

  - import: <path-to-query-suite>
    from: <ql-pack>
    version: ^x.y.z
  

  El version campo es opcional y especifica un intervalo de versiones compatibles de este CodeQL paquete. Si no especificas una versión del paquete, se usará la más reciente.

  Las consultas agregadas mediante una instrucción import se pueden filtrar mediante instrucciones exclude posteriores.

• Una instrucción apply: agrega todas las instrucciones de un archivo .qls definido previamente al conjunto actual. Las instrucciones del archivo .qls aplicado se ejecutan como si aparecieran en lugar de apply. Las instrucciones include y exclude del conjunto aplicado también actúan en las consultas que han agregado instrucciones anteriores:

  - apply: <path-to-query-suite>
  

  La instrucción apply también se puede usar para aplicar un conjunto de condiciones reutilizables, guardadas en un archivo .yml, en varias definiciones de consulta. Para obtener más información, consulta los ejemplos que se indican a continuación.

Ejemplos de reutilización

Para usar las mismas condiciones en varias definiciones del conjunto de consultas, crea un archivo .yml independiente que incluya las instrucciones. Por ejemplo, guarda lo siguiente en un archivo denominado reusable-instructions.yml:

- include:
    kind:
    - problem
    - path-problem
    tags contain: security
    precision:
    - high
    - very-high

Agregue reusable-instructions.yml al mismo paquete CodeQL que su suite de consultas actual. Después, en uno o varios conjuntos de consultas, usa la instrucción apply para aplicar las instrucciones reutilizables en el conjunto de consultas actual. Por ejemplo:

- queries: queries/cpp/custom
- apply: reusable-instructions.yml

Esto filtrará las consultas en queries/cpp/custom para incluir solo las que coincidan con las condiciones reutilizables.

También puede crear una definición de suite mediante reusable-instructions.yml en consultas de otro paquete CodeQL. Si el .qls archivo está en el mismo CodeQL paquete que las consultas, puede agregar un from campo inmediatamente después de la apply instrucción:

# load queries from the default suite of my-org/my-other-custom-queries
- qlpack: my-org/my-other-custom-queries

# apply the reusable instructions from the my-org/my-custom-instructions CodeQL pack
- apply: reusable-instructions.yml
  from: my-org/my-custom-instructions
  version: ^1.2.3 # optional

Un caso de uso común para una instrucción import es aplicar un filtro adicional a las consultas desde otro conjunto de consultas. Por ejemplo, este conjunto filtrará aún más el conjunto cpp-security-and-quality y excluirá las consultas de precisión low y medium:

- import: codeql-suites/cpp-security-and-quality.qls
  from: codeql/cpp-queries
- exclude:
    precision:
      - low
      - medium

Si quieres que las consultas include se importen desde otro conjunto, la sintaxis es un poco diferente:

- import: codeql-suites/cpp-security-and-quality.qls
  from: codeql/cpp-queries
- exclude: {}
- include:
    precision:
      - very-high
      - high

Observe la instrucción exclude vacía. Esto es necesario para garantizar que la instrucción include posterior pueda filtrar las consultas del conjunto importado.

Nomenclatura de un conjunto de consultas

Puedes proporcionar un nombre para el conjunto de consultas especificando una instrucción description:

- description: <name-of-query-suite>

Almacenamiento de un conjunto de consultas

Guarde el conjunto de consultas en un archivo con una .qls extensión y agréguelo a un CodeQL paquete Para obtener más información, vea Personalización del análisis con paquetes de CodeQL.

Uso de conjuntos de consultas con CodeQL

Puedes especificar conjuntos de consultas en la línea de comandos para cualquier comando que acepte archivos .qls. Por ejemplo, puedes compilar las consultas que ha seleccionado una definición de conjunto mediante query compile o bien usar las consultas de un análisis mediante database analyze. Para obtener más información sobre el análisis de CodeQL bases de datos, consulte Analyzing your code with CodeQL queries.

Lectura adicional

• CodeQL Consultas