Подготовка базы данных для CodeQL

Завершено

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

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

Анализ CodeQL использует извлечение реляционных данных из кода и его использование для создания базы данных CodeQL. Эти базы данных содержат все важные сведения о базе кода.

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

Подготовка базы данных для CodeQL

Перед тем как создать базу данных CodeQL, необходимо установить и настроить CodeQL CLI. Затем необходимо проверить версию базы кода, которую необходимо проанализировать.

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

Для интерпретированных языков средство извлечения выполняется непосредственно в исходном коде. Эта возможность дает точное представление базы кода и разрешает все зависимости.

Извлечение исходного файла из базы кода работает путем мониторинга нормального процесса сборки для скомпилированных языков. CodeQL создает копию исходного файла при каждом вызове компилятора для обработки исходного файла. Он собирает все соответствующие сведения о исходном коде с каждым исходным файлом.

Настройка CLI

Чтобы настроить интерфейс командной строки CodeQL, выполните следующие шаги.

1. Скачайте пакет .zip набора CLI CodeQL

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

Пакет скачивания CLI CodeQL — это архив .zip, содержащий инструменты, скрипты и различные файлы CodeQL. Пакет включает в себя: интерфейс командной строки CodeQL, совместимые версии запросов и библиотек из репозитория CodeQL GitHub и предварительно скомпилированные версии включенных запросов.

1. Перейдите на страницу выпусков общедоступного репозитория CodeQL.
2. Скачайте пакет для конкретной платформы в разделе Ресурсы.

На странице "Выпуски " можно также просмотреть журналы изменений для выпусков, а также загрузки для предыдущих версий пакета CodeQL. При необходимости можно скачать codeql-bundle.tar.gz, которая содержит интерфейс командной строки для всех поддерживаемых платформ.

2. Извлеките архив .zip

Если вы используете Linux, Windows или macOS, вы можете извлечь .zip архив в нужный каталог.

Пользователям macOS Catalina (или более поздней версии) необходимо предпринять дальнейшие шаги. Дополнительные сведения см. в документации CodeQL по началу работы с интерфейсом командной строки.

3. Выполнение процессов CodeQL

После извлечения выполните одно из следующих действий, чтобы использовать исполняемый файл codeql для выполнения процессов CodeQL:

• Запустите <extraction-root>/codeql/codeql, где <extraction-root> — это папка, в которой вы извлекли пакет CLI CodeQL.
• Добавьте <extraction-root>/codeql в запись PATH, чтобы можно было запустить исполняемый файл так же, как codeql.

Теперь можно выполнять команды CodeQL.

Проверка настройки интерфейса командной строки

Вы можете запустить подкоманда CodeQL CLI, чтобы убедиться, что вы правильно настроили интерфейс командной строки и можете анализировать базы данных:

• Запустите codeql resolve packs (если вы добавили codeql в PATH), чтобы показать, какие пакеты CodeQL может обнаружить CLI. В противном случае используйте /<extraction-root>/codeql/codeql resolve packs. Эта команда отображает имена пакетов CodeQL, включенных в пакет CLI CodeQL, показанные на предыдущих шагах как <extraction-root>.

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

• Запустите codeql resolve languages, чтобы показать, какие языки поддерживает пакет CLI CodeQL по умолчанию.

Создание базы данных

Создайте базу данных CodeQL, выполнив следующую команду из корневого каталога проекта:

codeql database create <database> --language=<language-identifier>

В команде:

• Замените <database> на путь к базе данных, которую нужно создать.
• Замените <language-identifier> идентификатором языка, используемого для создания базы данных. Этот идентификатор можно использовать с --db-cluster для приема разделенных запятыми списков или его можно указать несколько раз.

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

• Используйте --source-root для идентификации корневой папки для первичных исходных файлов для создания базы данных.
• Используйте --db-cluster для баз кода с несколькими языками, если требуется создать базы данных для нескольких языков.
• Используйте --command при создании базы данных для одного или нескольких скомпилированных языков. Этот параметр не нужен, если вы используете только Python и JavaScript.
• Используйте --no-run-unnecessary-builds вместе с --db-cluster для подавления команды сборки для языков, в которых интерфейс командной строки CodeQL не должен отслеживать сборку.

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

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

Экстракторы

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

Каждый инструмент извлечения определяет собственный набор параметров конфигурации. Ввод codeql resolve extractor --format=betterjson приводит к форматированию данных, как показано в следующем примере:

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

Чтобы узнать, какие параметры доступны для средства извлечения для вашего языка, введите codeql resolve languages --format=betterjson или codeql resolve extractor --format=betterjson. Формат выходных данных betterjson также предоставляет корень извлекателя и другие параметры, зависящие от языка.

Данные в базе данных CodeQL

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

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

Базы данных создаются на одном языке одновременно для баз кода с несколькими языками. Каждый язык имеет собственную уникальную схему базы данных. Схема предоставляет интерфейс между первоначальным лексическим анализом во время извлечения и сложным анализом с помощью CodeQL.

База данных CodeQL включает две основные таблицы:

• Таблица expressions содержит строку для каждого выражения в исходном коде, проанализированном CodeQL во время процесса сборки.
• Таблица statements содержит строку для каждой инструкции в исходном коде, проанализированном CodeQL во время процесса сборки.

Библиотека CodeQL определяет классы для предоставления уровня абстракции по каждой из этих таблиц. Этот слой включает связанные вспомогательные таблицы Expr и Stmt.

Потенциальные недостатки CodeQL

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

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

Если матрица не используется, autobuild пытается создать поддерживаемый скомпилированный язык с наиболее исходными файлами в репозитории. Анализ скомпилированных языков, отличных от Go, часто завершается ошибкой, если вы не предоставляете явные команды для сборки кода перед выполнением шага анализа.

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

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

Более подробную информацию о конкретных языках и autobuild шагах можно найти в документации по автосборке CodeQL.

Расширение VS Code

Вы можете использовать Visual Studio Code (VS Code) и расширение CodeQL для компиляции и выполнения запросов, если вы используете VS Code 1.39 или более поздней версии. Вы можете скачать расширение из Visual Studio Code Marketplace или скачать файл CodeQL VSIX.

Расширение использует установленный интерфейс командной строки, найденный в PATH, если он доступен. В противном случае расширение автоматически управляет доступом к исполняемому файлу интерфейса командной строки. Автоматическое управление гарантирует совместимость интерфейса командной строки с расширением CodeQL.