# Creación de conjuntos de consultas de CodeQL

Puede crear conjuntos de consultas de las consultas que utiliza con frecuencia en sus CodeQL análisis.

> \[!NOTE]
> En este artículo, se describen las características disponibles con el paquete CodeQL CLI 2.24.3 que se incluye en la versión inicial de GitHub Enterprise Server 3.21.
>
> Si el administrador del sitio ha actualizado tu versión de la CodeQL CLI a una versión más reciente, consulta la [versión de GitHub Enterprise Cloud](/es/enterprise-cloud@latest/code-security/tutorials/customize-code-scanning/create-query-suites) de este artículo para obtener información sobre las características más recientes.

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](/es/enterprise-server@3.21/code-security/concepts/code-scanning/codeql/codeql-query-suites).

> \[!NOTE]
> Las consultas personalizadas que quiera agregar a un conjunto de consultas deben estar en un [CodeQL paquete](/es/enterprise-server@3.21/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs) y contener los metadatos de consulta correctos. Para obtener más información, vea [Escritura de consultas personalizadas para la CLI de CodeQL](/es/enterprise-server@3.21/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli).

## 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` :

  ```yaml
  - 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`:

  ```yaml
  - 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:

  ```yaml
  - 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:

  ```yaml
  - 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.

> \[!NOTE]
> Cuando los nombres de rutas de acceso aparecen en las definiciones del conjunto de consultas, siempre deben proporcionarse con una barra diagonal, `/`, como separador de directorios. Esto garantiza que las definiciones del conjunto de consultas funcionen en todos los sistemas operativos.

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 [](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html).
* 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](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries).

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:

```yaml
- 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:

```yaml
- 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-`:

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

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

```yaml
- 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:

```yaml
- 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 problem`*o*`@precision very-high`:

```yaml
- 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:

```yaml
- 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-queries`CodeQL, use:

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

> \[!NOTE]
> Puede usar el comando `codeql resolve queries /path/to/suite.qls` para ver qué consultas ha seleccionado una definición de conjunto de consultas. Para obtener más información, vea [resolver consultas](/es/enterprise-server@3.21/code-security/codeql-cli/codeql-cli-manual/resolve-queries).

## 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:

  ```yaml
  - 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:

  ```yaml
  - 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:

  ```yaml
  - 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](#reusability-examples) 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`:

```yaml
- 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:

```yaml
- 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:

```yaml
# 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`:

```yaml
- 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:

```yaml
- 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`:

```yaml
- 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](/es/enterprise-server@3.21/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#custom-codeql-packs).

## 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](/es/enterprise-server@3.21/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries).

## Lectura adicional

* [
  CodeQL Consultas](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)