{"meta":{"title":"Создание наборов запросов CodeQL","intro":"Вы можете создавать наборы запросов для запросов, которые часто используете в своих CodeQL анализах.","product":"Безопасность и качество кода","breadcrumbs":[{"href":"/ru/code-security","title":"Безопасность и качество кода"},{"href":"/ru/code-security/tutorials","title":"Tutorials"},{"href":"/ru/code-security/tutorials/customize-code-scanning","title":"Настройка сканирования кода"},{"href":"/ru/code-security/tutorials/customize-code-scanning/create-query-suites","title":"Создание наборов запросов"}],"documentType":"article"},"body":"# Создание наборов запросов CodeQL\n\nВы можете создавать наборы запросов для запросов, которые часто используете в своих CodeQL анализах.\n\nВы можете создавать наборы запросов для тех запросов, которые хотите часто использовать в своих CodeQL анализах. Дополнительные сведения см. в разделе [Наборы запросов CodeQL](/ru/code-security/concepts/code-scanning/codeql/codeql-query-suites).\n\n> \\[!NOTE]\n> Любые пользовательские запросы, которые вы хотите добавить в набор запросов, должны находиться в [пакетеCodeQL](/ru/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs) и содержать правильные метаданные запроса. Дополнительные сведения см. в разделе [Написание пользовательских запросов для CodeQL CLI](/ru/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli).\n\n## Поиск запросов для добавления в набор запросов\n\nПри создании набора запросов сначала необходимо указать расположения запросов, которые нужно выбрать. Вы можете определить расположение одного или нескольких запросов с помощью:\n\n* Инструкция `query` : Подсказывает CodeQL искать один или несколько заданных `.ql` файлов:\n\n  ```yaml\n  - query: <path-to-query>\n  ```\n\n  Аргумент должен быть одним или несколькими путями к файлу относительно CodeQL пакета, содержащего определение пакета.\n\n* Инструкция `queries` : Подсказывает CodeQL рекурсивно сканировать папку на наличие `.ql` файлов:\n\n  ```yaml\n  - queries: <path-to-subdirectory>\n  ```\n\n  Путь каталога должен быть относительно корня CodeQL пакета, содержащего файл определения пакета. Чтобы найти запросы относительно другого CodeQL пакета, добавьте поле `from` :\n\n  ```yaml\n  - queries: <path-to-subdirectory>\n    from: <ql-pack-name>\n    version: ^x.y.z\n  ```\n\n  Поле `version` является опциональным и указывает ряд совместимых версий этого CodeQL пакета.\n  Если вы не указываете версию, используется последняя версия пакета.\n\n* Инструкция `qlpack` : Указывает CodeQL разрешать запросы в стандартном наборе именованного CodeQL пака:\n\n  ```yaml\n  - qlpack: <qlpack-name>\n    version: ^x.y.z\n  ```\n\n  Набор запросов по умолчанию содержит рекомендуемый набор запросов внутри этого пакета запросов. Не все пакеты запросов имеют набор по умолчанию. Если указанный пакет запросов не определяет набор по умолчанию, инструкция qlpack будет разрешать все запросы в пакете.\n\n  Поле `version` является опциональным и указывает ряд совместимых версий этого CodeQL пакета.\n  Если вы не указываете версию, используется последняя версия пакета.\n\n> \\[!NOTE]\n> Когда имена путей отображаются в определениях набора запросов, они всегда должны быть предоставлены с косой чертой вперед, `/`как разделитель каталогов. Это гарантирует, что определения набора запросов работают во всех операционных системах.\n\nНеобходимо добавить по крайней мере одну `query``queries`или `qlpack` инструкцию в определение набора, в противном случае запросы не будут выбраны. Если в наборе нет дополнительных инструкций, выбираются все запросы, найденные из списка файлов, в данной директории или в именованом CodeQL пакете. Если существуют дополнительные инструкции по фильтрации, будут выбраны только запросы, соответствующие ограничениям, введенным этими инструкциями.\n\n## Фильтрация запросов в наборе запросов\n\nПосле определения начального набора запросов, добавляемых в набор`query``queries``qlpack`, можно добавить `include` и `exclude` инструкции. Эти инструкции определяют критерии выбора на основе определенных свойств:\n\n* При выполнении `include` инструкции по набору запросов все запросы, соответствующие вашим условиям, сохраняются в выборе, а запросы, которые не совпадают, удаляются.\n* При выполнении `exclude` инструкций по набору запросов все запросы, соответствующие вашим условиям, удаляются из выбора, а запросы, которые не соответствуют совпадению, сохраняются.\n\nПорядок инструкций фильтра важен. Первая инструкция фильтра, которая отображается после указания поиска, определяет, включены ли или исключены запросы по умолчанию. Если первый фильтр является фильтром `include`, первоначально расположенные запросы будут только частью набора, если они соответствуют явному `include` фильтру. Если первый фильтр является `exclude`, первоначально расположенные запросы являются частью набора, если они явно не исключены.\n\nПоследующие инструкции выполняются по порядку, а инструкции, которые отображаются позже в файле, имеют приоритет над предыдущими инструкциями. Таким образом, `include` инструкции можно переопределить более поздними `exclude` инструкциями, соответствующими тому же запросу. Аналогичным образом можно `exclude`переопределить более поздние `include`версии.\n\nДля обоих инструкций аргумент является блоком ограничений, т. е. картой YAML, представляющей ограничения. Каждое ограничение — это запись карты, где ключ обычно является свойством метаданных запроса. Значение может быть следующим:\n\n* Одна строка.\n* Закрытое регулярное `/`[выражение](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html).\n* Список, содержащий строки, регулярные выражения или оба.\n\nЧтобы соответствовать ограничению, значение метаданных должно соответствовать одной из строк или регулярных выражений. Если существует несколько ключей метаданных, каждый ключ должен быть сопоставлен.\nСтандартные ключи метаданных, доступные для сопоставления: `description`, `id`, `kind`, , `name`, `tags``precision`и `problem.severity`.\nДля получения дополнительной информации о свойствах метаданных запросов см. [раздел «Метаданные» для CodeQL запросов](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries).\n\nПомимо тегов метаданных ключи в блоке ограничений также могут быть следующими:\n\n* `query filename`: соответствует последнему компоненту пути имени файла запроса.\n* `query path`: Совпадения на пути к файлу запроса относительно его окружающего CodeQL пакета.\n* `tags contain`: одна из указанных строк соответствия должна соответствовать одному из компонентов, разделенных пробелами, значения `@tags` свойства метаданных.\n* `tags contain all`: каждая из указанных строк соответствия должна соответствовать одному из компонентов свойства метаданных `@tags` .\n\n### Примеры фильтрации запросов, которые выполняются\n\nРаспространённый сценарий — создание набора запросов, который запускает все запросы в одном CodeQL пакете, за исключением нескольких конкретных запросов, которые пользователь не хочет запускать. Как правило, рекомендуется отфильтровать запрос `id`, который является уникальным и стабильным идентификатором для каждого запроса. Следующие три определения набора запросов семантически идентичны и фильтруются по запросу `id`:\n\nЭтот фильтр соответствует всем запросам в наборе `codeql/cpp-queries`по умолчанию, за исключением двух запросов с исключенными идентификаторами:\n\n```yaml\n- qlpack: codeql/cpp-queries\n- exclude:\n    id:\n      - cpp/cleartext-transmission\n      - cpp/cleartext-storage-file\n```\n\nВ этом примере для каждого запроса используется отдельная `exclude` инструкция:\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\nВ этом примере регулярное выражение исключает одни и те же два запроса. Он также исключит любые будущие запросы, добавленные в набор с идентификаторами, начинающимися: `cpp/cleartext-`\n\n```yaml\n- qlpack: codeql/cpp-queries\n- exclude:\n    id:\n      - /^cpp\\/cleartext-.*/\n```\n\nЧтобы определить пакет, который выбирает все запросы из стандартного пакета `codeql/cpp-queries`CodeQL пакета и затем уточняет их, чтобы включать только запросы безопасности, используйте следующее:\n\n```yaml\n- qlpack: codeql/cpp-queries\n- include:\n    tags contain: security\n```\n\nЧтобы определить набор, который выбирает все запросы с `@kind problem` каталогом и `@precision high` из нее, используйте следующую `my-custom-queries` команду:\n\n```yaml\n- queries: my-custom-queries\n- include:\n    kind: problem\n    precision: very-high\n```\n\nОбратите внимание, что следующее определение набора запросов отличается от приведенного выше определения. Это определение выбирает запросы, которые являются или`@kind problem`:\n\n```yaml\n- queries: my-custom-queries\n- include:\n    kind: problem\n- include:\n    precision: very-high\n```\n\nЧтобы создать набор, который выбирает все запросы из `@kind problem``my-custom-queries` каталога, кроме тех, с которыми они используются `@problem.severity\nrecommendation`, используйте следующую команду:\n\n```yaml\n- queries: my-custom-queries\n- include:\n    kind: problem\n- exclude:\n    problem.severity: recommendation\n```\n\nЧтобы создать набор, который выбирает все запросы с `@tag security` пакетом или `@precision high``very-high` из `codeql/cpp-queries`CodeQL них, используйте следующее:\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> Чтобы узнать, какие запросы выбраны определением набора запросов, можно использовать `codeql resolve queries /path/to/suite.qls` команду. Дополнительные сведения см. в разделе [разрешение запросов](/ru/code-security/codeql-cli/codeql-cli-manual/resolve-queries).\n\n## Повторное использовать существующие определения набора запросов\n\nСуществующие определения набора запросов можно повторно использовать, указав:\n\n* Инструкция. Добавляет `import` запросы, выбранные ранее `.qls` определенным файлом в текущий набор:\n\n  ```yaml\n  - import: <path-to-query-suite>\n  ```\n\n  Путь к импортированному набору должен быть относительно CodeQL пакета, содержащего текущее определение набора. Если импортированный набор запросов находится в другом пакете QL, можно использовать следующее:\n\n  ```yaml\n  - import: <path-to-query-suite>\n    from: <ql-pack>\n    version: ^x.y.z\n  ```\n\n  Поле `version` является опциональным и указывает ряд совместимых версий этого CodeQL пакета.\n  Если вы не указываете версию, используется последняя версия пакета.\n\n  Запросы, добавленные с помощью инструкции `import` , можно фильтровать с помощью последующих `exclude` инструкций.\n\n* Инструкция. Добавляет `apply` все инструкции из ранее определенного `.qls` файла в текущий набор. Инструкции в примененном `.qls` файле выполняются так же, как если бы они отображались вместо `apply`.\n\n`include` Все `exclude` и инструкции из примененного набора также действуют над запросами, добавленными любыми предыдущими инструкциями:\n\n```yaml\n- apply: <path-to-query-suite>\n```\n\nИнструкцию `apply` также можно использовать для применения набора повторно используемых условий, сохраненных в `.yml` файле, к нескольким определениям запросов. Дополнительные сведения см. в [приведенных ниже примерах](#reusability-examples) .\n\n### Примеры повторного использования\n\nЧтобы использовать одинаковые условия в нескольких определениях набора запросов, создайте отдельный `.yml` файл, содержащий инструкции. Например, сохраните следующее в файле с именем `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\nДобавьте `reusable-instructions.yml` их в тот CodeQL же пакет, что и ваш текущий набор запросов. Затем в одном или нескольких наборах запросов используйте `apply` инструкцию для применения повторно используемых инструкций к текущему набору. Рассмотрим пример.\n\n```yaml\n- queries: queries/cpp/custom\n- apply: reusable-instructions.yml\n```\n\nПри этом запросы будут отфильтровывать `queries/cpp/custom` только те, которые соответствуют условиям повторного использования.\n\nВы также можете создать определение набора с помощью `reusable-instructions.yml` запросов в другом CodeQL пакете. Если `.qls` файл находится в том же CodeQL пакете, что и запросы, вы можете добавить `from` поле сразу после `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\nРаспространенный вариант `import` использования инструкции — применение дополнительного фильтра к запросам из другого набора запросов. Например, этот набор будет дополнительно фильтровать `cpp-security-and-quality` набор и исключать `low` и `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\nЕсли вы хотите выполнить `include` запросы, импортированные из другого набора, синтаксис немного отличается:\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\nОбратите внимание на пустую `exclude` инструкцию. Это необходимо, чтобы последующие `include` инструкции могли фильтровать запросы из импортированного набора.\n\n## Именование набора запросов\n\nВы можете указать имя набора запросов, указав инструкцию `description` :\n\n```yaml\n- description: <name-of-query-suite>\n```\n\n## Сохранение набора запросов\n\nСохраните свой набор запросов в файле с `.qls` расширением и добавьте его в CodeQL\nСтая. Дополнительные сведения см. в разделе [Настройка анализа с помощью пакетов CodeQL](/ru/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#custom-codeql-packs).\n\n## Использование наборов запросов с CodeQL\n\nНаборы запросов можно указать в командной строке для любой команды, которая принимает `.qls` файлы. Например, можно скомпилировать запросы, выбранные определением набора, с помощью `query compile`или использовать запросы в анализе.`database analyze` Для получения дополнительной информации об анализе CodeQL баз данных см. [Analyzing your code with CodeQL queries](/ru/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries).\n\n## Дополнительные материалы\n\n* [\n  CodeQL Запросов](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)"}