# Como criar conjuntos de consultas do CodeQL

Você pode criar conjuntos de consultas para consultas usadas com frequência em suas CodeQL análises.

> \[!NOTE]
> Este artigo descreve os recursos disponíveis com o pacote CodeQL CLI 2.25.6 incluído na versão inicial do GitHub Enterprise Server 3.22.
>
> Se o administrador do site atualizou a versão do CodeQL CLI para uma mais recente, confira a [versão GitHub Enterprise Cloud](/pt/enterprise-cloud@latest/code-security/tutorials/customize-code-scanning/create-query-suites) deste artigo para obter informações sobre os recursos mais recentes.

Você pode criar conjuntos de consultas para as consultas que deseja usar com frequência em suas CodeQL análises. Para obter mais informações, consulte [Conjuntos de consultas CodeQL](/pt/enterprise-server@3.22/code-security/concepts/code-scanning/codeql/codeql-query-suites).

> \[!NOTE]
> Todas as consultas personalizadas que você deseja adicionar a um pacote de consultas devem estar em um [CodeQL pacote](/pt/enterprise-server@3.22/code-security/tutorials/customize-code-scanning/customize-analysis) e conter os metadados de consulta corretos. Para obter mais informações, consulte [Escrevendo consultas personalizadas para a CLI do CodeQL](/pt/enterprise-server@3.22/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-the-command-line/write-custom-queries).

## Como localizar as consultas a serem adicionadas a um conjunto de consultas

Ao criar um conjunto de consultas, primeiro você precisa especificar os locais das consultas que deseja selecionar. Você pode definir o local de uma ou mais consultas usando:

* Uma instrução `query`: instrui CodeQL a procurar um ou mais arquivos `.ql` especificados:

  ```yaml
  - query: <path-to-query>
  ```

  O argumento deve ser um ou mais caminhos de arquivo, relativos ao pacote CodeQL que contém a definição do conjunto.

* Uma instrução `queries`: instrui CodeQL a examinar recursivamente um diretório em busca de arquivos `.ql`:

  ```yaml
  - queries: <path-to-subdirectory>
  ```

  O caminho do diretório deve ser relativo à raiz do CodeQL pacote que contém o arquivo de definição do pacote. Para localizar as consultas relativas a um pacote diferente CodeQL , adicione um `from` campo:

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

  O `version` campo é opcional e especifica um intervalo de versões compatíveis deste CodeQL pacote.
  Se você não especificar uma versão, será usada a mais recente do pacote.

* Uma instrução `qlpack`: instrui CodeQL a resolver consultas no conjunto padrão do pacote CodeQL nomeado:

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

  O conjunto padrão de um pacote de consultas inclui um conjunto recomendado de consultas dentro desse pacote de consultas. Nem todos os pacotes de consultas têm um conjunto padrão. Se o pacote de consultas especificado não definir um conjunto padrão, a instrução qlpack será resolvida para todas as consultas dentro do pacote.

  O `version` campo é opcional e especifica um intervalo de versões compatíveis deste CodeQL pacote.
  Se você não especificar uma versão, será usada a mais recente do pacote.

> \[!NOTE]
> Quando os nomes de caminho aparecem nas definições do conjunto de consultas, eles sempre precisam conter uma barra, `/`, como separador de diretório. Isso garante que as definições do conjunto de consultas funcionem em todos os sistemas operacionais.

Você precisa adicionar pelo menos uma instrução `query`, `queries` ou `qlpack` à definição do conjunto. Caso contrário, nenhuma consulta será selecionada. Se o pacote não contiver instruções adicionais, todas as consultas encontradas na lista de arquivos, no diretório especificado ou no pacote nomeado CodeQL serão selecionadas. Se houver mais instruções de filtragem, somente as consultas que correspondem às restrições impostas por essas instruções serão selecionadas.

## Como filtrar as consultas em um conjunto de consultas

Depois de definir o grupo inicial de consultas a serem adicionadas ao conjunto especificando as instruções `query`, `queries`ou `qlpack`, você pode adicionar as instruções `include` e `exclude`. Estas instruções definem os critérios de seleção com base em propriedades específicas:

* Quando você executa uma instrução `include` em um conjunto de consultas, todas as consultas que correspondem às condições são mantidas na seleção e as que não correspondem são removidas.
* Quando você executa uma instrução `exclude` em um conjunto de consultas, todas as consultas que correspondem às condições são removidas da seleção e as que não correspondem são mantidas.

A ordem das instruções de filtro é importante. A primeira instrução de filtro exibida após as instruções de localização determina se as consultas são incluídas ou excluídas por padrão. Se o primeiro filtro for um `include`, as consultas localizadas inicialmente só farão parte do conjunto se corresponderem a um filtro explícito `include`. Se o primeiro filtro for um `exclude`, as consultas localizadas inicialmente farão parte do conjunto, a menos que sejam excluídas explicitamente.

As instruções subsequentes são executadas em ordem e as instruções que aparecem posteriormente no arquivo têm precedência sobre as instruções anteriores. Portanto, as instruções `include` poderão ser substituídas por instruções `exclude` posteriores que correspondam à mesma consulta. Da mesma forma, `exclude`s podem ser substituídas por uma `include` posterior.

Para as duas instruções, o argumento é um bloco de restrição, ou seja, um mapa YAML que representa as restrições. Cada restrição é uma entrada de mapa, em que a chave normalmente é uma propriedade de metadados de consulta. O valor pode ser:

* Uma só cadeia de caracteres.
* Uma `/` entre [](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html).
* Uma lista que contém cadeias de caracteres e/ou expressões regulares.

Para corresponder a uma restrição, um valor de metadados precisa corresponder a uma das cadeias de caracteres ou expressões regulares. Quando há mais de uma chave de metadados, cada chave precisa ser correspondida.
As chaves de metadados padrão disponíveis para correspondência são: `description`, `id`, `kind`, `name`, `tags`, `precision` e `problem.severity`.
Para obter mais informações sobre as propriedades de metadados de consulta, consulte [Metadados para CodeQL consultas](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries).

Além das marcas de metadados, as chaves no bloco de restrição também podem ser:

* `query filename`: Corresponde ao último componente de caminho do nome do arquivo de consulta.
* `query path`: corresponde ao caminho para o arquivo de consulta em relação ao pacote CodeQL que o contém.
* `tags contain`: Uma das cadeias de caracteres de correspondência fornecidas precisa corresponder a um dos componentes separados por espaço do valor da propriedade de metadados `@tags`.
* `tags contain all`: Cada uma das cadeias de caracteres de correspondência fornecidas precisa corresponder a um dos componentes da propriedade de metadados `@tags`.

### Exemplos de filtragem das consultas que serão executadas

Um caso de uso comum é criar um conjunto de consultas que executa todas as consultas em um CodeQL pacote, exceto para algumas consultas específicas que o usuário não deseja executar. Em geral, recomendamos a filtragem na `id` da consulta, que é um identificador exclusivo e estável de cada consulta. As três definições de conjunto de consultas a seguir são semanticamente idênticas e filtram pela consulta `id`:

Esse filtro corresponde a todas as consultas no conjunto padrão de `codeql/cpp-queries`, exceto às duas consultas com os identificadores excluídos:

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

Neste exemplo, uma instrução `exclude` separada é usada para cada consulta:

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

Neste exemplo, uma expressão regular exclui as mesmas duas consultas. Ela também excluiria todas as consultas futuras adicionadas ao conjunto com identificadores que começam com: `cpp/cleartext-`:

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

Para definir uma suíte que seleciona todas as consultas na suíte padrão do pacote `codeql/cpp-queries`CodeQL e, em seguida, as restringe para incluir apenas consultas de segurança, use:

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

Para definir um conjunto que seleciona todas as consultas com `@kind problem` e `@precision high` no diretório `my-custom-queries`, use:

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

Observe que a definição do conjunto de consultas a seguir se comporta de maneira diferente da definição acima. Essa definição seleciona as consultas que são `@kind problem`*ou*`@precision very-high`:

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

Para criar um conjunto que selecione todas as consultas com `@kind problem` no diretório `my-custom-queries`, exceto aquelas com `@problem.severity
recommendation`, use:

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

Para criar uma suite que seleciona todas as consultas que tenham `@tag security` e `@precision high` ou `very-high` do pacote `codeql/cpp-queries`CodeQL, use:

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

> \[!NOTE]
> Você pode usar o comando `codeql resolve queries /path/to/suite.qls` para ver quais consultas são selecionadas por uma definição de conjunto de consultas. Para obter mais informações, consulte [resolver consultas](/pt/enterprise-server@3.22/code-security/reference/code-scanning/codeql/codeql-cli-manual/resolve-queries).

## Como reutilizar definições de conjunto de consultas existentes

As definições de conjunto de consultas existentes podem ser reutilizadas especificando:

* Uma instrução `import`: Adiciona as consultas selecionadas por um arquivo `.qls` já definido ao conjunto atual:

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

  O caminho para a suíte importada deve ser relativo ao pacote CodeQL que contém a definição da suíte atual. Se o conjunto de consultas importado estiver em um pacote do QL diferente, use:

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

  O `version` campo é opcional e especifica um intervalo de versões compatíveis deste CodeQL pacote.
  Se você não especificar uma versão, será usada a mais recente do pacote.

  As consultas adicionadas usando uma instrução `import` podem ser filtradas usando as instruções subsequentes `exclude`.

* Uma instrução `apply`: Adiciona todas as instruções de um arquivo `.qls` já definido ao conjunto atual. As instruções no arquivo `.qls` aplicado são executadas como se aparecessem no lugar de `apply`.
  As instruções `include` e `exclude` do conjunto aplicado também atuam em consultas adicionadas por instruções anteriores:

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

  A instrução `apply` também pode ser usada para aplicar um conjunto de condições reutilizáveis, salvas em um arquivo `.yml`, a várias definições de consulta. Veja os [exemplos](#reusability-examples) abaixo para obter mais informações.

### Exemplos de reutilização

Para usar as mesmas condições em várias definições de conjunto de consultas, crie um arquivo `.yml` separado contendo as instruções. Por exemplo, salve o seguinte em um arquivo chamado `reusable-instructions.yml`:

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

Adicione `reusable-instructions.yml` ao mesmo pacote CodeQL da sua suíte de consultas atual. Depois, em um ou mais conjuntos de consultas, use a instrução `apply` para aplicar as instruções reutilizáveis ao conjunto atual. Por exemplo:

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

Isso filtrará as consultas em `queries/cpp/custom` para incluir apenas aquelas que correspondem às condições reutilizáveis.

Você também pode criar uma definição de suíte usando `reusable-instructions.yml` em consultas de um pacote CodeQL diferente. Se o `.qls` arquivo estiver no mesmo CodeQL pacote que as consultas, você poderá adicionar um `from` campo imediatamente após a `apply` instrução:

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

Um caso de uso comum de uma instrução `import` é aplicar um filtro adicional a consultas de outro conjunto de consultas. Por exemplo, esse conjunto filtrará ainda mais o conjunto `cpp-security-and-quality` e excluirá as consultas de precisão `low` e `medium`:

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

Se você quiser executar `include` nas consultas importadas de outro pacote, a sintaxe será um pouco diferente:

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

Observe a instrução vazia `exclude`. Isso é necessário para garantir que a próxima instrução `include` consiga filtrar as consultas do conjunto importado.

## Nomeando um conjunto de consultas

Você pode dar um nome para o conjunto de consultas especificando uma instrução `description`:

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

## Como salvar um conjunto de consultas

Salve o conjunto de consultas em um arquivo com uma extensão `.qls` e adicione-o a um CodeQL.
pacote. Para obter mais informações, consulte [Como personalizar a análise com pacotes CodeQL](/pt/enterprise-server@3.22/code-security/tutorials/customize-code-scanning/customize-analysis).

## Usando conjuntos de consultas com CodeQL

Você pode especificar conjuntos de consultas na linha de comando para qualquer comando que aceite arquivos `.qls`. Por exemplo, você pode compilar as consultas selecionadas por uma definição de conjunto usando `query compile` ou usar as consultas em uma análise usando `database analyze`. Para obter mais informações sobre como analisar bancos de CodeQL dados, consulte [Como analisar o código com as consultas CodeQL](/pt/enterprise-server@3.22/code-security/tutorials/customize-code-scanning/analyze-code).

## Leitura adicional

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