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

Краткие сведения

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

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

Description

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

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

Эта команда объединяет эффект команд run-queries базы данных codeql и codeql database interpret-results . Если вы хотите выполнить запросы, результаты которых не соответствуют требованиям для интерпретации как оповещений исходного кода, используйте [run-querys или codeql-запросы, ](/code-security/codeql-cli/codeql-cli-manual/query-run)а затем декодировать кодql 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.

Если запросы не указаны, интерфейс командной строки автоматически определяет подходящий набор запросов для выполнения. В частности, если файл конфигурации сканирования кода был указан во время создания базы данных с помощью --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. Если этот флаг не предоставляется по умолчанию, необходимо включить справку только для пользовательских запросов, т. е. тех, которые находятся в пакетах запросов, которые не относятся к коду формы`/lang&rt;-querys`<. Этот параметр не действует при передаче в кодql bqrs интерпретации.

--sarif-include-query-help=<mode>

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

always: включите справку по запросу для всех запросов.

custom_queries_only(по умолчанию): включите справку запроса только для пользовательских запросов, т. е. тех, которые находятся в пакетах запросов, которые не относятся к `коде формы/<lang&rt;-querys`.

never: не включать справку по запросу для каких-либо запросов.

Этот параметр не действует при передаче в кодql bqrs интерпретации.

Доступно с момента v2.15.2.

--no-sarif-include-alert-provenance

[[Расширенные форматы SARIF] Не включайте сведения о происхождении оповещений в выходные данные SARIF.

Доступно с момента v2.18.1.

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

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

--[no-]sarif-multicause-markdown

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

--no-sarif-minify

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

--sarif-run-property=<String=String>

[Форматы SARIF] Пара значений ключа, добавляемая в созданный контейнер свойств SARIF "run". Может повторяться.

--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}

--[no-]sublanguage-file-coverage

[GitHub.com и GitHub Enterprise Server версии 3.12.0+ используйте сведения о охвате вложенных файлов. Это вычисляет, отображает и экспортирует отдельные сведения о охвате файлов для языков, которые совместно используют средство извлечения CodeQL, такие как C и C++, Java и Kotlin, и JavaScript и TypeScript.

Доступно с момента v2.15.2.

--sarif-category=<category>

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

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

Это значение будет отображаться (с косой косой чертой, добавленной, если она еще не присутствует) в качестве <run>.automationDetails.id свойства.

--no-database-extension-packs

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

--no-database-threat-models

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

--[no-]download

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

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

--model-packs=<name@range>...

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

Параметры управления моделями угроз для использования

--threat-model=<name>...

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

Аргументом является имя модели угроз, при необходимости предшествуемой "!". Если нет "!", именованной модели угроз и всех его потомков включена. Если присутствует "!", именованной модели угроз и всех его потомков отключены.

Модель угроз по умолчанию включена, но может быть отключена, указав "--threat-model !default".

Модель угроз "все" можно использовать для включения или отключения всех моделей угроз.

Параметры модели --threat-обрабатываются по порядку. Например, "--threat-model local --threat-model !environment" включает все модели угроз в "локальной" группе, за исключением модели угроз "среда".

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

Доступно с момента v2.15.3.

Параметры управления вычислителем запросов

--[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-файл, содержащий строки для внешнего предиката <pred>. Можно указать несколько --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>

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

Значение должно быть не менее 2048 МБ; меньшие значения будут прозрачно округляться вверх.

Параметры управления компиляцией 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>

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

--fail-on-ambiguous-relation-name

[Дополнительно] Сбой компиляции, если во время компиляции создается неоднозначное имя отношения.

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

--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>

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

--compilation-cache=<dir>

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

--no-default-compilation-cache

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

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

--registries-auth-stdin

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

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

При этом переопределяются переменные среды маркера токена CODEQL_И_AUTH и GITHUB_. Если вам нужно выполнить проверку подлинности только в реестре контейнеров github.com, можно вместо этого выполнить проверку подлинности с помощью более --github-auth-stdin простого параметра.

--github-auth-stdin

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

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

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

Распространенные параметры

-h, --help

Отображение этого текста справки.

-J=<opt>

[Дополнительно] Укажите параметр JVM, выполняя команду.

(Убедитесь, что параметры, содержащие пробелы, не будут обрабатываться правильно.)

-v, --verbose

Постепенно увеличьте число отображаемых сообщений о ходе выполнения.

-q, --quiet

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

--verbosity=<level>

[Дополнительно] Явным образом задайте уровень детализации на одну из ошибок, предупреждений, хода выполнения, хода выполнения+, хода выполнения++, хода выполнения+++. Переопределяет -v и -q.

--logdir=<dir>

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

(Чтобы записать файл журнала с именем, над которым у вас есть полный контроль, вместо этого предоставьте --log-to-stderr и перенаправите stderr по мере необходимости.)

--common-caches=<dir>

[Дополнительно] Управляет расположением кэшированных данных на диске, которые будут сохраняться между несколькими запусками интерфейса командной строки, такими как скачанные пакеты QL и скомпилированные планы запросов. Если этот параметр не задан явным образом, по умолчанию используется каталог с именем .codeql в домашнем каталоге пользователя; он будет создан, если он еще не существует.

Доступно с момента v2.15.2.