Como criar conjuntos de consultas do CodeQL

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.

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:

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

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

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

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

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, queriesou 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, excludes 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 .
• 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.

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:

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

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

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

- 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-queriesCodeQL e, em seguida, as restringe para incluir apenas consultas de segurança, use:

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

- 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 problemou@precision very-high:

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

- 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-queriesCodeQL, use:

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

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:

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

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

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

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

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

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

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

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

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

Como salvar um conjunto de consultas

Salvar seu conjunto de consultas em um arquivo com a extensão .qls e adicioná-lo a um CodeQL Pacote. Para obter mais informações, consulte Como personalizar a análise com pacotes CodeQL.

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 Analyzing your code with CodeQL queries.

Leitura adicional

• CodeQL consultas