анализ базы данных

В этом материале описывается последний выпуск Интерфейса командной строки CodeQL. Дополнительные сведения об этом выпуске см. в разделе https://github.com/github/codeql-cli-binaries/releases.

Чтобы просмотреть сведения о параметрах, доступных для этой команды в более раннем выпуске, выполните команду с параметром в терминале --help .

Краткий обзор

Shell

codeql database analyze --format=<format> --output=<output> [--threads=<num>] [--ram=<MB>] <options>... -- <database> <query|dir|suite|pack>...

Описание

Анализ базы данных с получением значимых результатов в контексте исходного кода.

Выполните набор запросов (или некоторые отдельные запросы) к базе данных CodeQL, создавая результаты в виде оповещений или путей в формате SARIF или другом интерпретируемом формате.

Эта команда сочетает в себе эффект выполнения запросов базы данных codeql и команд interpret-results базы данных codeql . Если вы хотите выполнять запросы, результаты которых не соответствуют требованиям к интерпретации в качестве оповещений исходного кода, используйте вместо этого запросы запуска базы данных codeql или выполнение запросов codeql , а затем выполните декодирование codeql bqrs , чтобы преобразовать необработанные результаты в удобочитаемую нотацию.

Основные параметры

`<database>`

[Обязательный] Путь к базе данных CodeQL для запроса.

`<querysuite|pack>...`

Выполняемые запросы. Каждый аргумент имеет вид scope/name@range:path , где:

scope/name — это полное имя пакета CodeQL.
range — это диапазон semver.
path — это путь к файловой системе.

scope/name Если задано значение , range и являются path необязательными. Отсутствует range означает последнюю версию указанного пакета. Отсутствует path подразумевает набор запросов по умолчанию для указанного пакета.

Может path быть файлом *.ql запроса, каталогом, содержащим один или несколько запросов, или файлом .qls набора запросов. Если имя пакета не указано, path необходимо указать и интерпретироваться относительно текущего рабочего каталога текущего процесса.

Чтобы указать path , содержащий литерал @ или :, используйте path: в качестве префикса аргумента, как показано ниже: path:directory/with:and@/chars.

scope/name Если указаны и path , то path не может быть абсолютным. Он учитывается относительно корня пакета CodeQL.

Если запросы не указаны, CLI автоматически определит подходящий набор запросов для выполнения. В частности, если файл конфигурации сканирования кода был указан во время создания базы данных с помощью --codescanning-config , будут использоваться запросы из этого файла. В противном случае будут использоваться запросы по умолчанию для анализируемого языка.

`--format=<format>`

[Обязательный] Формат, в котором записываются результаты. Одно из двух значений:

csv: форматированные значения, разделенные запятыми, включая столбцы с метаданными правил и оповещений.

sarif-latest: формат обмена результатами статического анализа (SARIF), основанный на JSON для описания результатов статического анализа. Этот параметр форматирования использует последнюю поддерживаемую версию (2.1.0). Этот параметр не подходит для использования в автоматизации, так как он создает разные версии SARIF для разных версий CodeQL.

sarifv2.1.0: SARIF версии 2.1.0.

graphtext: текстовый формат, представляющий граф. Совместим только с запросами с @kind графом.

dgml: направленный язык разметки графа, основанный на XML-формате для описания графов. Совместим только с запросами с @kind графом.

dot: язык Graphviz DOT, текстовый формат для описания графов. Совместим только с запросами с @kind графом.

`-o, --output=<output>`

[Обязательный] Выходной путь для записи результатов. Для форматов графа это должен быть каталог, и результат (или результаты, если эта команда поддерживает интерпретацию нескольких запросов) будут записаны в этом каталоге.

`--[no-]rerun`

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

`--no-print-diagnostics-summary`

Не выводите сводку проанализированных диагностика в стандартные выходные данные.

`--no-print-metrics-summary`

Не выводите сводку по проанализированным метрикам в стандартные выходные данные.

`--max-paths=<maxPaths>`

Максимальное количество путей для каждого оповещения с путями. (По умолчанию: 4)

`--[no-]sarif-add-file-contents`

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

`--[no-]sarif-add-snippets`

[Только форматы SARIF] Включите фрагменты кода для каждого расположения, указанного в результатах, с двумя строками контекста до и после указанного расположения.

`--[no-]sarif-add-query-help`

[Только форматы SARIF] Включите справку по запросу Markdown в результаты. Он загружает справку запроса для /path/to/query.ql из файла /path/to/query.md. Этот параметр не действует при передаче в codeql bqrs interpret.

`--[no-]sarif-group-rules-by-pack`

[Только форматы SARIF] Поместите объект правила для каждого запроса в соответствующий пакет QL в свойстве <run>.tool.extensions . Этот параметр не действует при передаче в codeql bqrs interpret.

`--[no-]sarif-multicause-markdown`

[Только форматы SARIF] Для оповещений, которые имеют несколько причин, включите их в виде элементарного списка в формате Markdown в выходные данные в дополнение к в виде простой строки.

`--no-group-results`

[Только форматы SARIF] Создание одного результата для каждого сообщения, а не одного результата в уникальном расположении.

`--csv-location-format=<csvLocationFormat>`

Формат, в котором создаются расположения в выходных данных CSV. Один из: URI, столбец строки, смещение длины. (По умолчанию: line-column)

`--dot-location-url-format=<dotLocationUrlFormat>`

Строка формата, определяющая формат, в котором создаются URL-адреса расположения файлов в выходных данных DOT. Следующие заполнители можно использовать {path} {start:line} {start:column} {end:line} {end:column}, {offset}, {length}

`--sarif-category=<category>`

[Только форматы SARIF] Укажите категорию для этого анализа, включаемую в выходные данные SARIF. Категорию можно использовать для различения нескольких анализов, выполненных в одной фиксации и репозитории, но на разных языках или в разных частях кода.

Если проанализировать одну и ту же версию базы кода несколькими разными способами (например, для разных языков) и отправить результаты в GitHub для представления в разделе "Сканирование кода", это значение должно отличаться для каждого анализа, которое сообщает, что анализ дополняет, а не заменяет друг друга. (Значения должны быть согласованными при выполнении одного анализа для разных версий базы кода.)

Это значение будет отображаться (с добавлением косой черты в конце, если ее еще нет) в качестве свойства <run>.automationId в SARIF v1, свойства <run>.automationLogicalId в SARIF v2 и свойства <run>.automationDetails.id в SARIF v2.1.0.

`--[no-]download`

Скачайте все отсутствующие запросы перед анализом.

Параметры для управления оценщиком запросов

`--[no-]tuple-counting`

[Дополнительно] Отображение счетчиков кортежей для каждого этапа оценки в журналах средства оценки запросов. --evaluator-log Если этот параметр указан, счетчики кортежей будут включены в текстовые и структурированные журналы JSON, созданные командой . (Это может быть полезно для оптимизации производительности сложного кода QL.)

`--timeout=<seconds>`

[Дополнительно] Установите время ожидания для оценки запроса в секундах.

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

Если время ожидания не указано или равно 0, время ожидания не устанавливается (за исключением тестового запуска codeql, где время ожидания по умолчанию составляет 5 минут).

`-j, --threads=<num>`

Используйте это количество потоков для оценки запросов.

По умолчанию равен 1. Можно передать 0, чтобы использовать один поток на каждом ядре на компьютере, или -N , чтобы оставить N ядер неиспользуемых (за исключением использования хотя бы одного потока).

`--[no-]save-cache`

[Дополнительно] Агрессивно записывайте промежуточные результаты в кэш диска. Это занимает больше времени и использует (гораздо) больше места на диске, но может ускорить последующее выполнение аналогичных запросов.

`--[no-]expect-discarded-cache`

[Дополнительные возможности. Принимать решения о том, какие предикаты следует оценивать и что записывать в кэш диска, исходя из предположения, что кэш будет удален после выполнения запросов.

`--[no-]keep-full-cache`

[Дополнительно. Не очищайте кэш диска после завершения оценки. Это может сэкономить время, если вы собираетесь выполнить очистку набора данных codeql или очистку базы данных codeql .

`--max-disk-cache=<MB>`

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

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

`--min-disk-free=<MB>`

[Дополнительно] Задайте целевой объем свободного места в файловой системе.

Если --max-disk-cache значение не задано, средство оценки попытается ограничить использование кэша диска, если свободное пространство в файловой системе окажется ниже этого значения.

`--min-disk-free-pct=<pct>`

[Дополнительно] Задайте целевую долю свободного места в файловой системе.

Если --max-disk-cache значение не задано, средство оценки попытается ограничить использование кэша диска, если свободное пространство в файловой системе будет меньше этого процента.

`--external=<pred>=<file.csv>`

CSV-файл, содержащий строки для внешнего предиката \. Можно указать несколько --external вариантов.

`--xterm-progress=<mode>`

[Дополнительно] Определяет, следует ли отображать отслеживание хода выполнения во время оценки QL с помощью последовательностей элементов управления xterm. Возможны следующие значения:

no: никогда не производить фантазии прогресса; Предположим, глупый терминал.

auto(по умолчанию): автоматически определяет, выполняется ли команда в соответствующем терминале.

yes: предположим, что терминал может понимать последовательности элементов управления xterm. Функция по-прежнему зависит от возможности автоматического определение размера терминала и также будет отключена, если -q она задана.

25x80 (или аналогично): нравится yes, а также явно укажите размер терминала.

25x80:/dev/pts/17 (или аналогично): отображение необычного хода выполнения в терминале, отличном от stderr. В основном полезно для внутреннего тестирования.

Параметры управления выходными данными структурированных журналов средства оценки

`--evaluator-log=<file>`

[Дополнительно] Вывод структурированных журналов о производительности средства оценки в указанный файл. Формат этого файла журнала может быть изменен без уведомления, но будет потоком объектов JSON, разделенных двумя символами новой строки (по умолчанию) или одним, если --evaluator-log-minify параметр передан. Используйте для codeql generate log-summary <file> создания более стабильной сводки по этому файлу и избегайте непосредственного анализа файла. Файл будет перезаписан, если он уже существует.

`--evaluator-log-minify`

[Дополнительно] Если --evaluator-log параметр передается, также передача этого параметра позволит свести к минимуму размер создаваемого журнала JSON за счет того, что сделать его гораздо менее удобочитаемым.

Параметры управления использованием ОЗУ

`-M, --ram=<MB>`

Задайте общий объем ОЗУ, который должен использовать средство оценки запросов.

Параметры управления компиляцией QL

`--warnings=<mode>`

Обработка предупреждений от компилятора QL. Одно из двух значений:

hide: подавление предупреждений.

show(по умолчанию): вывод предупреждений, но продолжение компиляции.

error: предупреждения обрабатываются как ошибки.

`--no-debug-info`

Не указывайте сведения о расположении источника в RA для отладки.

`--[no-]fast-compilation`

[Не рекомендуется] [Дополнительно] Пропускать особенно медленные шаги оптимизации.

`--no-release-compatibility`

[Дополнительно] Используйте новейшие функции компилятора за счет переносимости.

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

Если вы не заботитесь о том, чтобы ваши запросы были совместимы с другими (более ранними или более поздними) выпусками CodeQL, иногда можно достичь небольшой дополнительной производительности, используя этот флаг, чтобы включить последние улучшения в компиляторе на ранних этапах.

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

Доступно начиная с v2.11.1.

`--[no-]local-checking`

Выполняйте начальные проверки только той части источника QL, которая используется.

`--no-metadata-verification`

Не проверка внедренные метаданные запроса в комментариях QLDoc для допустимости.

`--compilation-cache-size=<MB>`

[Дополнительно] Переопределите максимальный размер по умолчанию для каталога кэша компиляции.

Параметры настройки среды компиляции

`--search-path=<dir>[:<dir>...]`

Список каталогов, в которых можно найти пакеты QL. Каждый каталог может быть либо пакетом QL (или пакетом пакетов, .codeqlmanifest.json содержащим файл в корне), либо непосредственным родительским элементом одного или нескольких таких каталогов.

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

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

Если вы извлекли репозиторий CodeQL как одноуровневый элемент неупакованной цепочки инструментов CodeQL, вам не нужно предоставлять этот параметр. в таких одноуровневых каталогах всегда будет выполняться поиск пакетов QL, которые не могут быть найдены в противном случае. (Если это значение по умолчанию не работает, настоятельно рекомендуется настроить --search-path один раз и для всех в файле конфигурации для каждого пользователя.

(Примечание. В Windows разделителем пути является ;).

`--additional-packs=<dir>[:<dir>...]`

Если указан этот список каталогов, в них будет выполняться поиск пакетов перед каталогами в --search-path. Порядок между ними не имеет значения; Это ошибка, если имя пакета найдено в двух разных местах в этом списке.

Это полезно, если вы временно разрабатываете новую версию пакета, которая также отображается в пути по умолчанию. С другой стороны, не рекомендуется переопределять этот параметр в файле конфигурации; некоторые внутренние действия добавляют этот параметр на лету, переопределяя любое настроенное значение.

(Примечание. В Windows разделителем пути является ;).

`--library-path=<dir>[:<dir>...]`

[Дополнительно] Необязательный список каталогов, которые будут добавлены в необработанный путь поиска импорта для библиотек QL. Это следует использовать, только если вы используете библиотеки QL, которые не были упакованы как пакеты QL.

(Примечание. В Windows разделителем пути является ;).

`--dbscheme=<file>`

[Дополнительно] Явно определяет, какие запросы dbscheme следует компилировать. Это должно быть дано только вызывающими абонентами, которые очень уверены, что они делают.

`--compilation-cache=<dir>`

[Дополнительно] Укажите дополнительный каталог для использования в качестве кэша компиляции.

`--no-default-compilation-cache`

[Дополнительно] Не используйте кэши компиляции в стандартных расположениях, например в пакете QL, содержавшем запрос, или в каталоге цепочки инструментов CodeQL.

Параметры настройки диспетчера пакетов CodeQL

`--registries-auth-stdin`

Выполните проверку подлинности в реестрах контейнеров GitHub Enterprise Server, передав список \<registry_url>=\ пар, разделенный запятыми.

Например, можно передать https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2 для проверки подлинности в двух экземплярах GitHub Enterprise Server.

Это переопределяет переменные среды CODEQL_REGISTRIES_AUTH и GITHUB_TOKEN. Если вам нужно пройти проверку подлинности только в реестре контейнеров github.com, можно использовать более простой --github-auth-stdin вариант.

`--github-auth-stdin`

Выполните проверку подлинности в реестре контейнеров github.com, передав github.com маркер GitHub Apps или личный маркер доступа через стандартные входные данные.

Чтобы пройти проверку подлинности в реестрах контейнеров GitHub Enterprise Server, передайте --registries-auth-stdin или используйте переменную среды CODEQL_REGISTRIES_AUTH.

Это переопределяет переменную среды GITHUB_TOKEN.

анализ базы данных

В этой статье