О выполнении запросов CodeQL
Репозиторий github/codeql содержит большое количество примеров запросов. Доступ к существующим запросам в рабочей области можно получить с помощью представления "Запросы".
Необходимые компоненты
Чтобы проанализировать базу кода, необходимо выполнить запросы к базе данных CodeQL, извлеченной из кода, поэтому необходимо выбрать базу данных для работы с расширением. Вы можете выбрать базу данных локально (из ZIP-архива или неархивной папки), из общедоступного URL-адреса или URL-адреса проекта на GitHub.com. Дополнительные сведения см. в разделе Управление базами данных CodeQL.
Выполнение одного запроса
-
На боковой панели откройте представление "Запросы".
-
Чтобы запустить запрос к выбранной базе данных, наведите указатель мыши на нужный запрос, а затем щелкните значок "Выполнить локальный запрос ".
Расширение CodeQL запускает запрос в текущей базе данных и сообщает о ходе выполнения в правом нижнем углу приложения. Когда результаты будут готовы, они отображаются в представлении CodeQL "Результаты запроса".
Если возникают проблемы с выполнением запроса, уведомление отображается в правом нижнем углу приложения. В дополнение к сообщению об ошибке уведомление содержит сведения о том, как устранить проблему.
Выполнение всех запросов в каталоге
Вы можете выполнять каждый запрос в каталоге.
-
На боковой панели откройте представление "Запросы".
-
Наведите указатель мыши на нужный каталог запросов, а затем щелкните значок запуска локальных запросов.
Выполнение выбора запросов
Вы можете выполнять несколько запросов с помощью одной команды.
-
Перейдите к проводник.
-
Выберите несколько файлов или папок, содержащих запросы.
-
Щелкните правой кнопкой мыши и выберите CodeQL: выполнение запросов в выбранных файлах.
Выполнение запроса без каких-либо настроек
При работе с новым запросом можно открыть вкладку "Быстрый запрос", чтобы легко выполнить код и просмотреть результаты, не сохраняя .ql файл в рабочей области. Выберите CodeQL: быстрый запрос из VS Code Command Palette, а затем для выполнения запроса используется CodeQL: выполнение запроса в выбранной базе данных.
Все быстрые запросы, которые вы выполнили в текущем сеансе, можно увидеть в представлении "Журнал запросов". Щелкните запись, чтобы просмотреть точный текст быстрого запроса, создающего результаты. Дополнительные сведения см. в разделе "Просмотр журнала запросов".
Когда вы будете рады быстрому запросу, его следует сохранить в пакете CodeQL, чтобы получить доступ к нему позже. Дополнительные сведения см. в разделе Настройка анализа с помощью пакетов CodeQL.
Выполнение определенной части запроса или библиотеки
Это может быть полезно, если вы выполняете отладку запроса или библиотеки, и хотите найти неправильную часть.
Вместо использования CodeQL: выполните запрос в выбранной базе данных для выполнения всего запроса ( предложение select и любые предикаты запросов), можно использовать CodeQL: быстрая оценка для выполнения определенной .ql части или .qll файла.
CodeQL: быстрая оценка оценивает выбранный фрагмент кода вместо всего запроса и отображает результаты этого выбора в представлении "Результаты".
Возможные целевые показатели для быстрой оценки:
-
Выбор имени сущности CodeQL (например , класса или предиката) для оценки этой сущности.
-
Выбор формулы или выражения с бесплатными переменными для вычисления этой формулы или выражения.
Например, в следующем фрагменте кода можно выбрать имя foo предиката или формулу s = "bar" для быстрого вычисления:
predicate foo(string s) { s = "bar" }
Выполнение запроса в нескольких базах данных
Это может быть полезно, если вы хотите протестировать запрос на нескольких базах кода или найти уязвимость в нескольких проектах.
-
Откройте файл запроса (
.ql). -
Щелкните правой кнопкой мыши и выберите CodeQL: выполните запрос в нескольких базах данных.
-
В раскрывающемся меню выберите базы данных, в которые требуется выполнить запрос.
Просмотр журнала запросов
Чтобы просмотреть запросы, выполняемые в текущем сеансе, откройте представление "Журнал запросов".
Представление "Журнал запросов" содержит сведения, включая дату и время выполнения запроса, имя запроса, базу данных, в которой она выполнялась, и сколько времени потребовалось для выполнения запроса:
-
Чтобы настроить отображаемые сведения, щелкните правой кнопкой мыши запись и выберите " Переименовать".
-
При необходимости отфильтруйте представление по языку с помощью селектора языка. Дополнительные сведения см. в разделе "Фильтрация баз данных и запросов по языку".
-
Щелкните запись, чтобы отобразить соответствующие результаты, и дважды щелкните запрос в редакторе (или щелкните правой кнопкой мыши и выберите "Просмотреть запрос").
-
Чтобы отобразить точный текст, создающий результаты для определенной записи, щелкните его правой кнопкой мыши и выберите "Просмотреть текст запроса". Это может отличаться от представления запроса, так как файл запроса может быть изменен с момента последнего запуска.
-
Чтобы удалить запросы из представления, выберите все запросы, которые требуется удалить, а затем щелкните правой кнопкой мыши и нажмите кнопку " Удалить".
Общие сведения о результатах запроса
-
Щелкните запрос в представлении "Журнал запросов", чтобы отобразить результаты в представлении "Результаты".
Примечание. В зависимости от запроса можно также выбрать различные представления, такие как CSV, Выходные данные CODEQL CLI SARIF или DIL. Например, чтобы просмотреть формат DIL, щелкните правой кнопкой мыши результат и выберите "Вид DIL". Доступные выходные представления определяются форматом и метаданными запроса. Дополнительные сведения см. в разделе "CodeQL запросов".
-
Используйте раскрывающееся меню в представлении "Результаты", чтобы выбрать отображаемые результаты и в какой форме их отобразить, например отформатированный оповещение или таблицу необработанных результатов.
-
Чтобы отсортировать результаты по записям в определенном столбце, щелкните заголовок столбца.
Если результат ссылается на элемент исходного кода, его можно щелкнуть, чтобы отобразить его в источнике.
Чтобы использовать стандартные функции навигации по коду в исходном коде, щелкните правой кнопкой мыши элемент и используйте команды "Перейти к определению " или "Перейти к ссылкам". При этом выполняется запрос CodeQL по активному файлу, который может занять несколько секунд. Этот запрос должен выполняться один раз для каждого файла, поэтому все дополнительные ссылки из одного и того же файла будут быстро выполняться.
Примечание. Если вы используете старую базу данных, команды навигации по коду, такие как Переход к определению и переход к ссылкам , могут не работать.
Чтобы использовать навигацию по коду, попробуйте распаковать базу данных и запустить codeql database cleanup <database> ее в распакованной базе данных с помощью CodeQL CLI. Затем повторно добавьте базу данных в Visual Studio Code. Дополнительные сведения см. в разделе Очистка базы данных.
Сравнение результатов запроса
При написании или отладке запроса полезно понять, как изменения влияют на результаты. Вы можете сравнить два набора результатов, чтобы увидеть, что изменилось. Чтобы сравнить результаты, два запроса должны выполняться в одной базе данных.
-
Щелкните правой кнопкой мыши запрос в представлении "Журнал запросов" и выберите "Сравнить результаты".
-
В меню быстрого выбора отображаются все допустимые запросы для сравнения. Выберите запрос.
-
В представлении "Сравнение" показаны различия в результатах двух запросов.
Устранение неполадок
Чтобы просмотреть журналы выполнения определенного запроса, щелкните правой кнопкой мыши запрос в представлении "Журнал запросов" и выберите "Показать журнал запросов". Если файл журнала слишком велик для открытия расширения в VS Code, файл будет отображаться в проводнике, чтобы открыть его с помощью внешней программы.
Дополнительные сведения о компиляции и выполнении запросов, а также сведения об обновлениях базы данных см. в журнале сервера запросов CodeQL. Дополнительные сведения см. в разделе Доступ к журналам.
По умолчанию расширение удаляет журналы после каждого сеанса рабочей области. Чтобы переопределить это поведение, можно указать пользовательский каталог для журналов сервера запросов. Дополнительные сведения см. в разделе Настройка параметров.
Для перезапуска сервера запросов можно использовать команду CodeQL: перезапустите команду сервера запросов . При этом сервер перезагружается без влияния на журнал сеансов CodeQL. Скорее всего, необходимо перезапустить сервер запросов, если вы вносите внешние изменения в файлы, которые использует расширение. Например, повторное создание базы данных CodeQL, открытой в VS Code. Помимо проблем в журнале, также могут появиться ошибки в выделении кода, неправильных итогов результатов или повторяющихся уведомлений о выполнении запроса.
Следующие шаги
При необходимости можно использовать расширение для создания собственных пользовательских запросов. Дополнительные сведения см. в разделе Создание пользовательского запроса.