Написание и обмен пользовательскими запросами для CodeQL CLI

Вы можете написать собственные запросы CodeQL для поиска конкретных уязвимостей и ошибок.

Кто может использовать эту функцию?

CodeQL доступен для следующих типов репозитория:

В этой статье

Эта статья посвящена написанию запросов для использования с командой AUTOTITLE для получения интерпретируемых результатов. Для концептуальной информации о пользовательских запросах см. АВТОЗАГОЛОВОК.

Написание допустимого запроса

Перед выполнением пользовательского анализа необходимо написать допустимый запрос и сохранить его в файле с расширением .ql . Существует обширная документация, помогая создавать запросы. Дополнительные сведения см. в статье CodeQL запросов.

Включение метаданных запроса

При выполнении запросов с database analyze помощью команды необходимо включить следующие два свойства, чтобы убедиться, что результаты интерпретируются правильно:

  • Идентификатор запроса (@id): последовательность слов, состоящих из строчных букв или цифр, разделенных разделителями / или -идентифицируя и классифицируя запрос.

  • Тип запроса (@kind): определяет запрос как простое оповещение (@kind problem), оповещение, задокументированное последовательностью расположений кода (), для устранения неполадок средства извлечения (@kind path-problem``@kind diagnostic) или сводной метрики (@kind metricи@tags summary).

Дополнительные сведения об этих свойствах метаданных см. в разделе ["Метаданные" для запросов CodeQL и руководства по стилю метаданных](https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md) запросов.

Упаковка пользовательских запросов

Когда вы пишете запросы для обмена с другими, сохраняйте их в пользовательском CodeQL пакете.

Чтобы упаковать свои индивидуальные запросы:

  1. Создайте пакет CodeQL с qlpack.yml файлом в корневой директории.
  2. Сохраняйте свои пользовательские запросы (.ql файлы) в корне pack или его подкаталогах.
  3. Настройте qlpack.yml файл так, чтобы задать следующее:
    • Как скомпилировать запросы
    • Зависимости от других CodeQL пакетов и библиотек
    • Определения набора запросов Для получения дополнительной информации о qlpack.yml свойствах см. АВТОЗАГОЛОВОК.
  4. Опубликуйте свой пакет в GitHub Packages — GitHub Container registry. Дополнительные сведения см. в разделе Настройка анализа с помощью пакетов CodeQL.

Включение справки по запросу для пользовательских запросов CodeQL в файлах SARIF

Для информации о помощи с запросами и форматах документации см. АВТОЗАГОЛОВОК.

Чтобы включить помощь с запросами в файлы SARIF при выполнении анализа сканирования кода:

  1. Напишите справку с запросом в одном из следующих форматов: * Файл Markdown: Сохраните файл Markdown вместе с вашим запросом с тем же именем (например, my-query.md для my-query.ql) * ** .qhelp file**: Напишите справку с запросом в .qhelp формате, затем конвертируйте её в Markdown перед запуском анализа. Дополнительные сведения см. в разделе "Файлы справки по запросу" и Тестирование файлов справки по запросу.

  2. Используйте codeql database analyze этот --sarif-add-query-help вариант:

    codeql database analyze <database> --format=sarif-latest --output=results.sarif --sarif-add-query-help

    Примечание.

    Эта --sarif-add-query-help опция доступна начиная с CodeQL CLI версии 2.7.1 и далее.

  3. Загрузите файл SARIF в GitHub.

Дополнительные материалы

  •         [Запросы CodeQL](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries)