{"meta":{"title":"Como criar conjuntos de consultas do CodeQL","intro":"Você pode criar conjuntos de consultas para consultas usadas com frequência nas análises do CodeQL.","product":"Qualidade de segurança e código","breadcrumbs":[{"href":"/pt/code-security","title":"Qualidade de segurança e código"},{"href":"/pt/code-security/tutorials","title":"Tutorials"},{"href":"/pt/code-security/tutorials/customize-code-scanning","title":"Personalizar a verificação de código"},{"href":"/pt/code-security/tutorials/customize-code-scanning/creating-codeql-query-suites","title":"Como criar conjuntos de consultas do CodeQL"}],"documentType":"article"},"body":"# Como criar conjuntos de consultas do CodeQL\n\nVocê pode criar conjuntos de consultas para consultas usadas com frequência nas análises do CodeQL.\n\nVocê pode criar conjuntos de consultas para as consultas que deseja usar com frequência em suas análises de CodeQL. Para saber mais, confira [Conjuntos de consultas CodeQL](/pt/code-security/concepts/code-scanning/codeql/codeql-query-suites).\n\n> \\[!NOTE]\n> Todas as consultas personalizadas que você deseja adicionar a um conjunto de consultas precisam estar em um pacote do [CodeQL](/pt/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs) e conter os metadados de consulta corretos. Para saber mais, confira [Escrevendo consultas personalizadas para a CLI do CodeQL](/pt/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli).\n\n## Como localizar as consultas a serem adicionadas a um conjunto de consultas\n\nAo 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:\n\n* Uma instrução `query` solicita que o CodeQL procure um ou mais arquivos especificados `.ql`:\n\n  ```yaml\n  - query: <path-to-query>\n  ```\n\n  O argumento precisa ser um ou mais caminhos de arquivo, em relação ao pacote do CodeQL que contém a definição do conjunto.\n\n* Uma instrução `queries` solicita que o CodeQL verifique recursivamente um diretório em busca de arquivos `.ql`:\n\n  ```yaml\n  - queries: <path-to-subdirectory>\n  ```\n\n  O caminho do diretório precisa ser relativo à raiz do pacote do CodeQL que contém o arquivo de definição do conjunto. Para localizar as consultas relativas a um pacote do CodeQL diferente, adicione um campo `from`:\n\n  ```yaml\n  - queries: <path-to-subdirectory>\n    from: <ql-pack-name>\n    version: ^x.y.z\n  ```\n\n  O campo `version` é opcional e especifica um intervalo de versões compatíveis deste pacote do CodeQL.\n  Se você não especificar uma versão, será usada a mais recente do pacote.\n\n* Uma instrução `qlpack` solicita que o CodeQL resolva consultas no conjunto padrão do pacote do CodeQL nomeado:\n\n  ```yaml\n  - qlpack: <qlpack-name>\n    version: ^x.y.z\n  ```\n\n  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.\n\n  O campo `version` é opcional e especifica um intervalo de versões compatíveis deste pacote do CodeQL.\n  Se você não especificar uma versão, será usada a mais recente do pacote.\n\n> \\[!NOTE]\n> 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.\n\nVocê precisa adicionar pelo menos uma instrução `query`, `queries` ou `qlpack` à definição do conjunto. Caso contrário, nenhuma consulta será selecionada. Se o conjunto não contiver mais instruções, todas as consultas encontradas na lista de arquivos, no diretório especificado ou no pacote do CodeQL nomeado 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.\n\n## Como filtrar as consultas em um conjunto de consultas\n\nDepois 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:\n\n* 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.\n* 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.\n\nA 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.\n\nAs 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.\n\nPara 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:\n\n* Uma só cadeia de caracteres.\n* Uma `/` entre [](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html).\n* Uma lista que contém cadeias de caracteres e/ou expressões regulares.\n\nPara 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.\nAs chaves de metadados padrão disponíveis para correspondência são: `description`, `id`, `kind`, `name`, `tags`, `precision` e `problem.severity`.\nPara obter mais informações sobre as propriedades de metadados de consulta, confira [Metadados para consultas do CodeQL](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries).\n\nAlém das marcas de metadados, as chaves no bloco de restrição também podem ser:\n\n* ```\n          `query filename`: Corresponde ao último componente de caminho do nome do arquivo de consulta.\n  ```\n* ```\n          `query path`: Corresponde ao caminho para o arquivo de consulta em relação ao pacote do CodeQL que ele contém.\n  ```\n* ```\n          `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`.\n  ```\n* ```\n          `tags contain all`: Cada uma das cadeias de caracteres de correspondência fornecidas precisa corresponder a um dos componentes da propriedade de metadados `@tags`.\n  ```\n\n### Exemplos de filtragem das consultas que serão executadas\n\nUm caso de uso comum é criar um conjunto de consultas que execute todas as consultas em um pacote do CodeQL, exceto 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`:\n\nEsse filtro corresponde a todas as consultas no conjunto padrão de `codeql/cpp-queries`, exceto às duas consultas com os identificadores excluídos:\n\n```yaml\n- qlpack: codeql/cpp-queries\n- exclude:\n    id:\n      - cpp/cleartext-transmission\n      - cpp/cleartext-storage-file\n```\n\nNeste exemplo, uma instrução `exclude` separada é usada para cada consulta:\n\n```yaml\n- qlpack: codeql/cpp-queries\n- exclude:\n    id: cpp/cleartext-transmission\n- exclude:\n    id: cpp/cleartext-storage-file\n```\n\nNeste 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-`:\n\n```yaml\n- qlpack: codeql/cpp-queries\n- exclude:\n    id:\n      - /^cpp\\/cleartext-.*/\n```\n\nPara definir um conjunto que selecione todas as consultas no conjunto padrão do pacote `codeql/cpp-queries` do CodeQL e depois refine-as para incluir apenas consultas de segurança, use:\n\n```yaml\n- qlpack: codeql/cpp-queries\n- include:\n    tags contain: security\n```\n\nPara definir um conjunto que seleciona todas as consultas com `@kind problem` e `@precision high` no diretório `my-custom-queries`, use:\n\n```yaml\n- queries: my-custom-queries\n- include:\n    kind: problem\n    precision: very-high\n```\n\nObserve 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`:\n\n```yaml\n- queries: my-custom-queries\n- include:\n    kind: problem\n- include:\n    precision: very-high\n```\n\nPara criar um conjunto que selecione todas as consultas com `@kind problem` no diretório `my-custom-queries`, exceto aquelas com `@problem.severity\nrecommendation`, use:\n\n```yaml\n- queries: my-custom-queries\n- include:\n    kind: problem\n- exclude:\n    problem.severity: recommendation\n```\n\nPara criar um conjunto que selecione todas as consultas com `@tag security` e `@precision high` ou `very-high` no pacote `codeql/cpp-queries` do CodeQL, use:\n\n```yaml\n- queries: .\n  from: codeql/cpp-queries\n- include:\n    tags contain: security\n    precision:\n    - high\n    - very-high\n```\n\n> \\[!NOTE]\n> 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 saber mais, confira [resolver consultas](/pt/code-security/codeql-cli/codeql-cli-manual/resolve-queries).\n\n## Como reutilizar definições de conjunto de consultas existentes\n\nAs definições de conjunto de consultas existentes podem ser reutilizadas especificando:\n\n* Uma instrução `import`: Adiciona as consultas selecionadas por um arquivo `.qls` já definido ao conjunto atual:\n\n  ```yaml\n  - import: <path-to-query-suite>\n  ```\n\n  O caminho para o conjunto importado precisa ser relativo ao pacote do CodeQL que contém a definição do conjunto atual. Se o conjunto de consultas importado estiver em um pacote do QL diferente, use:\n\n  ```yaml\n  - import: <path-to-query-suite>\n    from: <ql-pack>\n    version: ^x.y.z\n  ```\n\n  O campo `version` é opcional e especifica um intervalo de versões compatíveis deste pacote do CodeQL.\n  Se você não especificar uma versão, será usada a mais recente do pacote.\n\n  As consultas adicionadas usando uma instrução `import` podem ser filtradas usando as instruções subsequentes `exclude`.\n\n* 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`.\n  As instruções `include` e `exclude` do conjunto aplicado também atuam em consultas adicionadas por instruções anteriores:\n\n  ```yaml\n  - apply: <path-to-query-suite>\n  ```\n\n  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.\n\n### Exemplos de reutilização\n\nPara 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`:\n\n```yaml\n- include:\n    kind:\n    - problem\n    - path-problem\n    tags contain: security\n    precision:\n    - high\n    - very-high\n```\n\nAdicione `reusable-instructions.yml` ao mesmo pacote do CodeQL que o conjunto 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:\n\n```yaml\n- queries: queries/cpp/custom\n- apply: reusable-instructions.yml\n```\n\nIsso filtrará as consultas em `queries/cpp/custom` para incluir apenas aquelas que correspondem às condições reutilizáveis.\n\nVocê também pode criar uma definição de conjunto usando `reusable-instructions.yml` em consultas em um pacote do CodeQL diferente. Se o arquivo `.qls` estiver no mesmo pacote do CodeQL que as consultas, você poderá adicionar um campo `from` logo após a instrução `apply`:\n\n```yaml\n# load queries from the default suite of my-org/my-other-custom-queries\n- qlpack: my-org/my-other-custom-queries\n\n# apply the reusable instructions from the my-org/my-custom-instructions CodeQL pack\n- apply: reusable-instructions.yml\n  from: my-org/my-custom-instructions\n  version: ^1.2.3 # optional\n```\n\nUm 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`:\n\n```yaml\n- import: codeql-suites/cpp-security-and-quality.qls\n  from: codeql/cpp-queries\n- exclude:\n    precision:\n      - low\n      - medium\n```\n\nSe você quiser executar `include` nas consultas importadas de outro pacote, a sintaxe será um pouco diferente:\n\n```yaml\n- import: codeql-suites/cpp-security-and-quality.qls\n  from: codeql/cpp-queries\n- exclude: {}\n- include:\n    precision:\n      - very-high\n      - high\n```\n\nObserve a instrução vazia `exclude`. Isso é necessário para garantir que a próxima instrução `include` consiga filtrar as consultas do conjunto importado.\n\n## Nomeando um conjunto de consultas\n\nVocê pode dar um nome para o conjunto de consultas especificando uma instrução `description`:\n\n```yaml\n- description: <name-of-query-suite>\n```\n\n## Como salvar um conjunto de consultas\n\nSalve o conjunto de consultas em um arquivo com uma extensão `.qls` e adicione-o a um pacote do CodeQL. Para saber mais, confira [Como personalizar a análise com pacotes CodeQL](/pt/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#custom-codeql-packs).\n\n## Usando conjuntos de consultas com CodeQL\n\nVocê 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 dados do CodeQL, confira [Como analisar o código com as consultas CodeQL](/pt/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries).\n\n## Leitura adicional\n\n* ```\n          [Consultas CodeQL](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)\n  ```"}