Анализ баз данных с помощью интерфейса командной строки CodeQL

Сведения об анализе баз данных с помощью CodeQL CLI

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

Анализ CodeQL дает интерпретируемые результаты , которые могут отображаться в виде оповещений или путей в исходном коде. Сведения о написании запросов для выполнения с database analyzeпомощью см. в разделе Использование пользовательских запросов с CodeQL CLI.

Перед началом анализа необходимо:

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

Самый простой способ выполнения codeql database analyze — использовать пакеты CodeQL. Вы также можете выполнить команду с помощью запросов из локального репозитория CodeQL, что может потребоваться, если вы хотите настроить основные запросы CodeQL.

Работает codeql database analyze

При выполнении database analyzeон:

1. При необходимости скачивает все указанные CodeQL пакеты, недоступные локально.
2. Выполняет один или несколько файлов запросов, выполняя их в базе данных CodeQL.
3. Интерпретирует результаты на основе определенных метаданных запроса, чтобы оповещения могли отображаться в правильном расположении в исходном коде.
4. Сообщает результаты всех диагностических и сводных запросов в стандартные выходные данные.

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

codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...

Необходимо указать следующие данные:

• <database>: путь к базе данных CodeQL, которую требуется проанализировать.
• --format: формат файла результатов, созданного во время анализа. Поддерживается ряд различных форматов, включая форматы CSV, SARIF и графа. Дополнительные сведения о CSV и SARIF см. в разделе Результаты. Сведения о том, какие другие форматы результатов поддерживаются, см. в справочнике по анализу базы данных.
• --output: выходной путь к файлу результатов, созданному во время анализа.

Также можно указать:

• <query-specifiers>...: разделенный пробелами список запросов для выполнения в базе данных. Ниже приведен список аргументов, каждый из которых может быть следующим:

  • Путь к файлу запроса
  • путь к каталогу с файлами запросов;
  • путь к файлу набора запросов;
  • имя пакета запросов CodeQL
    • с необязательным диапазоном версий
    • с необязательным путем к запросу, каталогу или набору запросов в пакете

  Если этот параметр опущен, будет использоваться набор запросов по умолчанию для языка анализируемой базы данных. Полный синтаксис описателей запросов см. в разделе Указание запросов для выполнения в пакете CodeQL.

• --sarif-category: идентифицирующие категорию для результатов. Используется при отправке нескольких наборов результатов для фиксации. Например, если вы используете github upload-results для отправки результатов для нескольких языков в API сканирования кода GitHub. Дополнительные сведения об этом варианте использования см. в разделе Настройка CodeQL CLI в системе CI.

• --sarif-add-query-help: (поддерживается в версии 2.7.1 и выше) добавляет любую пользовательскую справку по запросам, написанную в markdown, в файлы SARIF (версии 2.1.0 или более поздней версии), созданные в результате анализа. Перед выполнением анализа необходимо преобразовать справку по запросам.md, хранящуюся в .qhelp файлах. Дополнительные сведения см. в разделе Включение справки по запросам для пользовательских запросов CodeQL в SARIF-файлах.

• --download: логический флаг, позволяющий CLI скачивать все указанные CodeQL пакеты, недоступные локально. Если этот флаг отсутствует, а указанный пакет CodeQL недоступен локально, команда завершится ошибкой.

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

Указание запросов для выполнения в пакете CodeQL

Описатели запросов используются и другими командами codeql database analyze , которые работают с набором запросов. Полной формой описателя запроса является scope/name@range:path, где:

• scope/name — полное имя пакета CodeQL.

• range — это диапазон semver.

• path — это путь файловой системы к одному запросу, каталогу с запросами или файлу набора запросов.

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

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

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

Примеры описателей запросов

• codeql/python-queries — Все запросы в наборе запросов по умолчанию последней codeql/python-queries версии пакета.

• codeql/python-queries@1.2.3 — все запросы в наборе запросов по умолчанию версии 1.2.3 codeql/python-queries пакета.

• codeql/python-queries@~1.2.3 — Все запросы в наборе запросов по умолчанию последней codeql/python-queries версии пакета, >= 1.2.3 и < 1.3.0.

• codeql/python-queries:Functions — Все запросы в каталоге Functions в последней codeql/python-queries версии пакета.

• codeql/python-queries@1.2.3:Functions — Все запросы в каталоге Functions в версии 1.2.3 codeql/python-queries пакета.

• codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls — Все запросы в каталоге codeql-suites/python-code-scanning.qls в версии 1.2.3 codeql/python-queries пакета.

• suites/my-suite.qls — Все запросы в suites/my-suite.qls файле относительно текущего рабочего каталога.

Примеры выполнения анализа базы данных

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

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

Чтобы выполнить один запрос к базе данных CodeQL для базы кода JavaScript, можно использовать следующую команду из каталога, содержащего базу данных:

codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

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

При анализе создается CSV-файл (js-results.csv) в новом каталоге (js-analysis).

Кроме того, если у вас есть репозиторий CodeQL, можно выполнить те же запросы, указав путь к запросу напрямую:

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

Вы также можете выполнять собственные пользовательские запросы с помощью database analyze команды . Дополнительные сведения о подготовке запросов для использования с CodeQL CLI см. в разделе Использование пользовательских запросов с CodeQL CLI.

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

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

Например, чтобы выполнить все запросы Python, содержащиеся в каталоге Functions в пакете codeql/python-queries запросов, необходимо выполнить следующее:

codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download

Кроме того, если вы извлекли репозиторий CodeQL, можно выполнить те же запросы, указав путь к каталогу напрямую:

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

После завершения анализа создается файл результатов SARIF. Указание --format=sarif-latest гарантирует, что результаты будут отформатированы в соответствии с последней спецификацией SARIF, поддерживаемой CodeQL.

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

Чтобы выполнить набор запросов в базе данных CodeQL для базы кода C/C++, можно использовать следующую команду из каталога, содержащего базу данных:

codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download

Эта команда скачивает codeql/cpp-queries пакет запросов CodeQL, выполняет анализ и создает файл в формате SARIF версии 2.1.0, который поддерживается всеми версиями GitHub. Этот файл можно отправить в GitHub, codeql github upload-results выполнив или API сканирования кода. Дополнительные сведения см. в разделе Установка CodeQL CLI в системе непрерывной интеграции или Проверка кода.

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

Сведения о создании пользовательских наборов запросов см. в разделе Создание наборов запросов CodeQL.

Диагностические и сводные сведения

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

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

Интеграция пакета CodeQL в рабочий процесс сканирования кода в GitHub

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

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

Если вы используете CodeQL CLI для выполнения анализа сканирования кода в системах CI/CD сторонних производителей, вы можете включить справку по запросам для пользовательских запросов в SARIF-файлах, созданных во время анализа. После отправки ФАЙЛА SARIF в GitHub справка по запросу отображается в пользовательском интерфейсе сканирования кода для всех оповещений, созданных пользовательскими запросами.

Начиная с CodeQL CLI версии 2.7.1, вы можете включить справку по запросам, отрисованную с помощью Markdown, в ФАЙЛЫ SARIF, указав --sarif-add-query-help параметр при запуске codeql database analyze. Дополнительные сведения см. в разделе Настройка CodeQL CLI в системе CI.

Вы можете написать справку по запросам для пользовательских запросов непосредственно в файле Markdown и сохранить ее вместе с соответствующим запросом. Кроме того, для согласованности со стандартными запросами CodeQL можно написать справку по запросам .qhelp в формате . Справка по запросам, написанная в .qhelp файлах, не может быть включена в ФАЙЛЫ SARIF и не может быть обработана путем сканирования кода, поэтому ее необходимо преобразовать в markdown перед выполнением анализа. Дополнительные сведения см. в разделах Запрос файлов справки и Тестирование файлов справки запроса.

Результаты

Результаты анализа можно сохранять в различных форматах, включая SARIF и CSV.

Формат SARIF предназначен для представления выходных данных широкого спектра средств статического анализа. Дополнительные сведения см. в разделе Выходные данные SARIF.

Если вы решили создать результаты в формате CSV, то каждая строка в выходном файле соответствует оповещению. Каждая строка представляет собой разделенный запятыми список со следующими сведениями:

Свойство	Описание	Пример
Имя	Имя запроса, который идентифицировал результат.	Inefficient regular expression
Описание	Описание запроса.	A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks.
Статус	Серьезность запроса.	error
Сообщение	Оповещение.	This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.
Путь	Путь к файлу с оповещением.	/vendor/codemirror/markdown.js
Начальная строка	Строка файла, в которой начинается код, активировав оповещение.	617
Начальный столбец	Столбец начальной строки, помечающий начало кода оповещения. Не включается, если равно 1.	32
Конечная линия	Строка файла, в которой заканчивается код, активировав оповещение. Не включается, если значение совпадает с начальной строкой.	64
Конечный столбец	Если доступно, столбец конечной строки, который отмечает конец кода оповещения. В противном случае конечная строка повторяется.	617

Файлы результатов можно интегрировать в собственную инфраструктуру проверки кода или отладки. Например, выходные данные ФАЙЛА SARIF можно использовать для выделения оповещений в правильном расположении в исходном коде с помощью подключаемого модуля средства просмотра SARIF для интегрированной среды разработки.

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

• Анализ проектов в CodeQL для VS Code