Анализ баз данных с помощью интерфейса командной строки 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

Чтобы выполнить существующий пакет запросов CodeQL из GitHub Container registry, можно указать одно или несколько имен пакетов:

codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

Эта команда выполняет набор запросов по умолчанию из двух пакетов запросов CodeQL: microsoft/coding-standards версии 1.0.0 и последней версии в указанной github/security-queries базе данных. Дополнительные сведения о наборах по умолчанию см. в разделе Публикация и использование пакетов CodeQL.

Флаг --download является необязательным. При его использовании пакет запросов будет скачан, если он еще недоступен локально.

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

Чтобы выполнить один запрос к базе данных 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

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

Полный способ указать набор запросов можно в форме scope/name@range:path, где:

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

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

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

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

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

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

Для анализа базы данных с помощью всех запросов в папке experimental/Security в пакете codeql/cpp-queries CodeQL можно использовать:

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

Чтобы выполнить RedundantNullCheckParam.ql запрос в пакете codeql/cpp-queries CodeQL, используйте:

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

Для анализа базы данных с помощью cpp-security-and-quality.qls набора запросов из версии codeql/cpp-queries пакета CodeQL, >= 0.0.3 и < 0.1.0 (будет выбрана самая совместимая версия), можно использовать:

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

Если необходимо сослаться на файл запроса, каталог или набор, путь к которому содержит литерал @ или :, можно указать в спецификации запроса префикс path: следующим образом:

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

Дополнительные сведения о пакетах CodeQL см. в разделе О пакетах 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, вы можете включить в SARIF-файлы справку --sarif-add-query-help по запросам markdown, указав параметр при запуске 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
Message	Оповещение.	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