Выполнение запросов CodeQL

О запуске CodeQL запросов

Репозиторий github/codeql содержит большое количество примеров запросов. Доступ к существующим запросам в рабочей области можно получить с помощью представления "Запросы".

Необходимые условия

Для анализа кодовой базы вы запускаете запросы к CodeQL базе данных, извлечённой из кода, поэтому нужно выбрать базу данных для работы в расширении. Вы можете выбрать базу данных локально (из архива ZIP или неархивированной папки), по публичному URL или по URL проекта на GitHub.com. Дополнительные сведения см. в разделе Управление базами данных CodeQL.

Выполнение одного запроса

1. На боковой панели откройте представление "Запросы".

2. Чтобы запустить запрос к выбранной базе данных, наведите указатель мыши на нужный запрос, а затем щелкните значок "Выполнить локальный запрос ".

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

Если возникают проблемы с выполнением запроса, уведомление отображается в правом нижнем углу приложения. В дополнение к сообщению об ошибке уведомление содержит сведения о том, как устранить проблему.

Выполнение всех запросов в каталоге

Вы можете выполнять каждый запрос в каталоге.

1. На боковой панели откройте представление "Запросы".

2. Наведите указатель мыши на нужный каталог запросов, а затем щелкните значок запуска локальных запросов.

Выполнение выбора запросов

Вы можете выполнять несколько запросов с помощью одной команды.

1. Перейдите к проводник.

2. Выберите несколько файлов или папок, содержащих запросы.

3. Кликните правой кнопкой мыши и выберите CodeQL: Запустить запросы в выбранных файлах.

Выполнение запроса без каких-либо настроек

При работе с новым запросом можно открыть вкладку "Быстрый запрос", чтобы легко выполнить код и просмотреть результаты, не сохраняя .ql файл в рабочей области. Выберите CodeQL: Быстрый запрос из VS Code Command Palette, затем для запуска запроса используйте CodeQL: Запустить запрос на выбранной базе данных.

Все быстрые запросы, которые вы выполнили в текущем сеансе, можно увидеть в представлении "Журнал запросов". Щелкните запись, чтобы просмотреть точный текст быстрого запроса, создающего результаты. Дополнительные сведения см. в разделе "Просмотр журнала запросов".

Когда вы будете довольные быстрым запросом, сохраните его в пакете CodeQL , чтобы получить доступ позже. Дополнительные сведения см. в разделе Настройка анализа с помощью пакетов CodeQL.

Выполнение определенной части запроса или библиотеки

Это может быть полезно, если вы выполняете отладку запроса или библиотеки, и хотите найти неправильную часть.

Вместо того чтобы использовать CodeQL: Run Query on Selected Database для запуска всего запроса ( select clause и любые предикаты запроса), вы можете использовать CodeQL: Quick Evaluation для запуска определённой части файла .ql или .qll файла.

          **
          CodeQL: Быстрая оценка** оценивает выбранный вами фрагмент кода вместо всего запроса и отображает результаты этого выбора в виде «Результаты».

Возможные целевые показатели для быстрой оценки:

• Выбор имени CodeQL сущности (например, класса или предиката) для оценки этой сущности.

• Выбор формулы или выражения с бесплатными переменными для вычисления этой формулы или выражения.

Например, в следующем фрагменте кода можно выбрать имя foo предиката или формулу s = "bar" для быстрого вычисления:

predicate foo(string s) { s = "bar" }

Выполнение запроса в нескольких базах данных

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

1. Откройте файл запроса (.ql).

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

3. В раскрывающемся меню выберите базы данных, в которые требуется выполнить запрос.

Просмотр журнала запросов

Чтобы просмотреть запросы, выполняемые в текущем сеансе, откройте представление "Журнал запросов".

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

• Чтобы настроить отображаемые сведения, щелкните правой кнопкой мыши запись и выберите " Переименовать".

• При необходимости отфильтруйте представление по языку с помощью селектора языка. Дополнительные сведения см. в разделе "Фильтрация баз данных и запросов по языку".

• Щелкните запись, чтобы отобразить соответствующие результаты, и дважды щелкните запрос в редакторе (или щелкните правой кнопкой мыши и выберите "Просмотреть запрос").

• Чтобы отобразить точный текст, создающий результаты для определенной записи, щелкните его правой кнопкой мыши и выберите "Просмотреть текст запроса". Это может отличаться от представления запроса, так как файл запроса может быть изменен с момента последнего запуска.

• Чтобы удалить запросы из представления, выберите все запросы, которые требуется удалить, а затем щелкните правой кнопкой мыши и нажмите кнопку " Удалить".

Общие сведения о результатах запроса

1. Щелкните запрос в представлении "Журнал запросов", чтобы отобразить результаты в представлении "Результаты".

   Примечание.

   В зависимости от запроса можно также выбрать различные представления, такие как CSV, Выходные данные CODEQL CLI SARIF или DIL. Например, чтобы просмотреть формат DIL, щелкните правой кнопкой мыши результат и выберите "Вид DIL". Доступные выходные представления определяются форматом и метаданными запроса. Для получения дополнительной информации смотрите CodeQL запросы.

2. Используйте раскрывающееся меню в представлении "Результаты", чтобы выбрать отображаемые результаты и в какой форме их отобразить, например отформатированный оповещение или таблицу необработанных результатов.

3. Чтобы отсортировать результаты по записям в определенном столбце, щелкните заголовок столбца.

Если результат ссылается на элемент исходного кода, его можно щелкнуть, чтобы отобразить его в источнике.

Чтобы использовать стандартные функции навигации по коду в исходном коде, щелкните правой кнопкой мыши элемент и используйте команды "Перейти к определению " или "Перейти к ссылкам". Это запускает CodeQL запрос по активному файлу, что может занять несколько секунд. Этот запрос должен выполняться один раз для каждого файла, поэтому все дополнительные ссылки из одного и того же файла будут быстро выполняться.

Сравнение результатов запроса

При написании или отладке запроса полезно понять, как изменения влияют на результаты. Вы можете сравнить два набора результатов, чтобы увидеть, что изменилось. Чтобы сравнить результаты, два запроса должны выполняться в одной базе данных.

1. Щелкните правой кнопкой мыши запрос в представлении "Журнал запросов" и выберите "Сравнить результаты".

2. В меню быстрого выбора отображаются все допустимые запросы для сравнения. Выберите запрос.

3. В представлении "Сравнение" показаны различия в результатах двух запросов.

Troubleshooting

Чтобы просмотреть журналы выполнения определенного запроса, щелкните правой кнопкой мыши запрос в представлении "Журнал запросов" и выберите "Показать журнал запросов". Если файл журнала слишком велик для открытия VS Codeрасширения, файл будет отображаться в проводнике, чтобы вы могли открыть его с помощью внешней программы.

Для получения информации о компиляции и запуске запросов, а также информации об обновлении базы данных ознакомьтесь CodeQL с журналом сервера запросов. Дополнительные сведения см. в разделе Доступ к логам для CodeQL входа Visual Studio Code.

По умолчанию расширение удаляет журналы после каждого сеанса рабочей области. Чтобы переопределить это поведение, можно указать пользовательский каталог для журналов сервера запросов. Дополнительные сведения см. в разделе Настройка параметров.

Вы можете использовать CodeQLкоманду : Restart Query Server , чтобы перезапустить сервер запросов. Это перезагружает сервер, не затрагивая историю CodeQL сессий. Скорее всего, необходимо перезапустить сервер запросов, если вы вносите внешние изменения в файлы, которые использует расширение. Например, восстановление CodeQL базы данных, открытой в VS Code. Помимо проблем в журнале, также могут появиться ошибки в выделении кода, неправильных итогов результатов или повторяющихся уведомлений о выполнении запроса.

Дальнейшие действия

При необходимости можно использовать расширение для создания собственных пользовательских запросов. Дополнительные сведения см. в разделе Создание пользовательского запроса.