Опции и шаги сборки CodeQL для скомпилированных языков

Шаги автостроки для скомпилированных языков

Если для GitHub Actions, может потребоваться установить дополнительное программное обеспечение для использования autobuild процесса. Кроме того, что если для вашего репозитория требуется определенная версия инструмента сборки, вам может потребоваться сначала установить его вручную. Для локальных средств выполнения следует установить зависимости непосредственно в самих средствах выполнения. Мы приводим примеры распространённых зависимостей для C/C++, C# и Java в каждом из разделов autobuild этой статьи для этих языков. Дополнительные сведения см. в разделе Локальные средства выполнения тестов.

Создание C/C++

CodeQL поддерживает режимы сборки none, autobuild или manual для кода C/C++.

Если включить настройку по умолчанию для репозитория, содержащего код C/C++, режим сборки устанавливается none автоматически.

Нет сборки для C/C++

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

Точность анализа без сборки для C/C++

Создание базы данных CodeQL C/C++ без сборки может привести к менее точным результатам, чем использование autobuild или ручная сборка в некоторых случаях; например, если:

• Код сильно зависит от пользовательских макросов/определений, недоступных в существующих заголовках
• Кодовая база имеет множество внешних зависимостей

Вы можете обеспечить более точный анализ, выполнив следующие действия.

• Размещение пользовательских макросов и определений в файлах заголовков, которые включены в соответствующие исходные файлы
• Убедитесь, что внешние зависимости (заголовки) доступны в каталогах включения системы или в рабочей области
• Запустите экстракцию на целевой платформе. Например, выберите Windows runner для анализа проектов Windows, чтобы получить доступ к специфичным для платформы заголовкам и компиляторам

Сводка по автостроке для C/C++

Поддерживаемый тип системы	Системное имя
Операционная система	Windows, macOS и Linux
Система сборки	Windows: скрипты для сборки и сборки MS Linux и macOS: Autoconf, Make, CMake, qmake, Meson, Waf, SCons, Linux Kbuild и скрипты сборки

Поведение шага autobuild зависит от операционной системы, в которой выполняется извлечение.

Автоопределение Windows

В Windows шаг autobuild пытается автоматически определить подходящий метод сборки для C/C++ с помощью следующего подхода:

1. Вызов MSBuild.exe для файла решения (.sln) или проекта (.vcxproj), ближайшего к корневому каталогу. Если autobuild обнаруживает несколько файлов решения или проекта с одной и той же (самой короткой) глубиной относительно каталога верхнего уровня, он попытается собрать все из них.
2. Вызов скрипта, который похож на скрипт сборки — build.bat, build.cmd и build.exe (в этом порядке).

Автоматическое обнаружение Linux и macOS

На Linux и macOS шаг autobuild проверяет наличие файлов в репозитории, чтобы определить используемую систему сборки:

1. Поиск системы сборки в корневом каталоге.
2. Если она не будет найдена, выполняется поиск по подкаталогам уникального каталога с системой сборки для C/C++.
3. Выполнение соответствующей команду, чтобы настроить систему.

Требования для запуска для C/C++

В запусках Ubuntu Linux может попытаться автоматически установить зависимости, autobuild необходимые для обнаруженных действий конфигурации и сборки. По умолчанию это поведение включено в GitHubразмещенных в среде runners и отключено на локальных запусках. Вы можете включить или отключить эту функцию явным образом, задав CODEQL_EXTRACTOR_CPP_AUTOINSTALL_DEPENDENCIES или true``false в среде. Дополнительные сведения об определении переменных среды см. в разделе Хранение сведений в переменных.

Для локальных модулей выполнения, если только автоматическая установка зависимостей не включена, скорее всего, потребуется установить gcc компилятор, а для конкретных проектов также может потребоваться доступ к clang исполняемым файлам или msvc файлам. Кроме того, необходимо установить систему сборки (напримерmsbuild, , make, cmake, bazel) и служебные программы (напримерpython, , perl``lexи yacc) от того, от сколько зависят проекты. Если включить автоматическую установку зависимостей, необходимо убедиться, что средство выполнения использует Ubuntu и может выполняться sudo apt-get без необходимости пароля.

Windows бегунам требуется powershell.exe для PATH.

Сборка C#

CodeQL поддерживает режимы сборки none, autobuild или manual код C#.

Если включить настройку по умолчанию для репозитория, содержащего код C#, режим сборки устанавливается none автоматически.

Сборка для C не выполняется#

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

Зависимости восстанавливаются с помощью нескольких эвристических и стратегий. Следующие файлы являются основным источником информации: *.csproj, *.sln, nuget.config, , packages.configи global.json``project.assets.json. Если для организации определен частный веб-канал NuGet, он также используется, см. статью ["Проверка кода по умолчанию" для доступа к частным реестрам и определение того, используется ли настройка по умолчанию для сканирования кода любые частные реестры](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#determining-whether-code-scanning-default-setup-used-any-private-registries).

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

• global созданные using директивы для обработки неявной using функции MSbuild.
• ASP.NET файлы ядра .cshtml преобразуются в .cs файлы.

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

Точность анализа сборки для C#

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

Вы можете обеспечить более точный анализ, выполнив следующие действия.

• Предоставьте доступ к общедоступному Интернету или убедитесь, что доступ к частному веб-каналу NuGet доступен, см. статью "Проверка кода для настройки доступа по умолчанию к частным реестрам".
• Проверьте, требуется ли репозиторию несколько версий одной зависимости NuGet. CodeQL может использовать только одну версию и обычно выбирает более новую версию, в которой существует несколько версий. Этот подход может не работать для всех репозиториев.
• Проверьте, упоминаются ли несколько версий .NET, например, net48, net5.0 и netstandard1.6. CodeQL может использовать только одну версию, и это может повлиять на точность.
• Избегайте сопоставления имен классов, в противном случае это может привести к отсутствием целевых объектов вызова метода, которые влияют на анализ потока данных.

Сводка по автостроке для C#

Поддерживаемый тип системы	Системное имя
Операционная система	Windows, macOS и Linux
Система сборки	.NET и MSbuild, а также скрипты сборки

Автоопределение Windows

Процесс autobuild пытается выполнить автоматическое определение подходящего метода сборки для C# с помощью следующего подхода:

1. Вызов dotnet build для файла решения (.sln) или проекта (.csproj), ближайшего к корневому каталогу.

2.        `MSBuild.exe` Вызовите файл решения или проекта, ближайший к корневому каталогу.
   

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

1. Вызов скрипта, который выглядит как скрипт сборки,build.bat``build.cmd и build.exe (в этом порядке).

Требования к бегу для C# на Windows

Для разработки .NET Core приложения на самостоятельных раннерах требуется .NET SDK (для dotnet).

Для разработки приложений .NET Framework вам понадобятся Microsoft Build Tools (для msbuild) и NuGet CLI (для nuget).

Windows бегунам требуется powershell.exe для PATH.

Если вы планируете создавать базы данных CodeQL с помощью build-mode: none, необходимо также предоставить доступ к общедоступному Интернету или обеспечить доступ к частному веб-каналу NuGet.

Автоматическое обнаружение Linux и macOS

1. Вызов dotnet build для файла решения (.sln) или проекта (.csproj), ближайшего к корневому каталогу.

2.        `MSbuild` Вызовите файл решения или проекта, ближайший к корневому каталогу.
   

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

1. Вызов скрипта, который выглядит как скрипт сборки,build и build.sh (в этом порядке).

Требования runner для C# в Linux и macOS

Для разработки .NET Core приложения на самостоятельных раннерах требуется .NET SDK (для dotnet).

Для разработки .NET фреймворк вам потребуется моно Runtime (для запуска mono, msbuild или nuget).

Если вы планируете создавать базы данных CodeQL с помощью build-mode: none, необходимо также предоставить доступ к общедоступному Интернету или обеспечить доступ к частному веб-каналу NuGet.

Флаги компилятора C#, внедренные CodeQL для сборок вручную

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

/p:MvcBuildViews=true

Когда эта опция установлена в true, представления в проектах ASP.NET модель-просмотр-контроллер (MVC) предварительно компилируются в процессе сборки, что помогает обнаруживать ошибки и повышать производительность. Трассировщик внедряет этот флаг, чтобы убедиться, что CodeQL находит и выделяет проблемы безопасности, которые могут включать поток данных через код, созданный из этих представлений. Дополнительные сведения см. в разделе "Добавление представления в приложение MVC" в Microsoft Learn.

/p:UseSharedCompilation=false

Установка этого параметра для false отключения использования общей функции компиляции, что может привести к более медленному времени сборки. Если /p:UseSharedCompilation=false не указано, msbuild запускается процесс сервера компилятора, и все компиляция будет выполнена одним процессом. Однако трассировщик данных CodeQL зависит от проверки аргументов только что созданных процессов.

/p:EmitCompilerGeneratedFiles=true

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

Для некоторых устаревших проектов и проектов, использующих .sqlproj файлы, можно увидеть, что внедренное /p:EmitCompilerGeneratedFiles=true свойство приводит к непредвиденным проблемам msbuild. Дополнительные сведения об устранении неполадок см. в разделе Непредвиденное сбой компилятора C#.

Сборка Go

CodeQL поддерживает режимы autobuild сборки или manual код Go.

Сводка по автостроке для Go

Поддерживаемый тип системы	Системное имя
Операционная система	Windows, macOS и Linux
Система сборки	Модули Go и Glide, а также скрипты сборки, dep включая скрипты Makefiles и Ninja

Автоматическое обнаружение для Go

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

1.        `make`Вызовите или `ninja``./build``./build.sh` (в этом порядке) до тех пор, пока одна из этих команд не будет успешно выполнена, а последующий `go list ./...` также будет успешно выполнена, указывая, что установлены необходимые зависимости.
   

2. Если ни одна из этих команд не выполнена успешно, найдите go.mod``Gopkg.toml или выполните glide.yaml (если поставщик не используется) go get илиdep ensure -v``glide install, соответственно, попробуйте установить зависимости.
3. Наконец, если файлы конфигураций для этих диспетчеров зависимостей не найдены, переупорядочение структуры каталога репозитория, подходящей для добавления GOPATHи использования go get для установки зависимостей. Структура каталогов возвращается к нормальной после завершения извлечения.
4. Извлеките весь код Go в репозитории, аналогичный выполнению go build ./....

Параметры средства извлечения для Go

По умолчанию тестовый код (код в файлах заканчивается _test.go) не анализируется. Это можно переопределить с помощью параметра --extractor-option extract_tests=true при использовании CodeQL CLIили путем задания переменной CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_TESTS``trueсреды.

Кроме того, vendor каталоги исключаются из CodeQL Анализ Go по умолчанию. Это можно переопределить, передав --extractor-option extract_vendor_dirs=true параметр при использовании CodeQL CLI, или установив для переменной CODEQL_EXTRACTOR_GO_OPTION_EXTRACT_VENDOR_DIRS среды значение true.

Создание Java и Kotlin

CodeQL поддерживает следующие режимы сборки.

• Java: none, autobuild или manual
• Котлин: autobuild или manual

Когда вы впервые включаете настройки репозитория по умолчанию, если обнаруживается только Java коде, режим сборки устанавливается на none. Если обнаруживается Kotlin или комбинация кода Java и Kotlin, то режим сборки устанавливается на autobuild.

Если позже добавить код Kotlin в репозиторий, использующий none режим сборки, CodeQL анализ сообщает предупреждение, объясняющее, что Kotlin не поддерживается. Вам потребуется отключить настройку по умолчанию и повторно включить ее. При повторной настройке по умолчанию режим сборки изменится таким autobuild образом, чтобы оба языка могли быть проанализированы. Кроме того, вы можете измениться на расширенную настройку. Дополнительные сведения см. в разделе Предупреждение. Обнаружены файлы X Kotlin в проекте, которые не удалось обработать без сборки.

Нет сборки для Java

CodeQL попытается запустить Gradle или Maven для извлечения точной информации о зависимости (но не для вызова сборки), прежде чем создать базу данных из всех Java файлов. Каждый корневой файл проекта Maven или Gradle (скрипт сборки без скрипта сборки, присутствующих в каталоге предков), запрашивается сведения о зависимости, а более последние версии зависимостей предпочтительнее при возникновении столкновения. Для получения информации о требованиях к бегуну для участия в Maven или Gradle см. Требования к бегуну для Java.

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

Точность анализа без билдов для Java

Создание Java базы данных данных { variables.product.prodname_codeql %} без сборки может дать менее точные результаты, чем использование autobuild или ручных шагов сборки, если:

• Скрипты сборки Gradle или Maven не могут быть запрошены для получения информации о зависимостях, а догадки о зависимости (основанные на названиях пакетов Java) неточны.
• Репозиторий обычно создает код во время процесса сборки. Это будет проанализировано, если вы создали базу данных CodeQL с помощью другого режима.

Вы можете обеспечить более точный анализ, выполнив следующие действия.

• Предоставьте доступ к общедоступному Интернету или убедитесь, что доступ к частному репозиторию артефактов доступен, см. статью "Проверка кода по умолчанию" для установки доступа к частным реестрам.
• Проверьте, требуется ли репозиторию несколько версий одной зависимости. CodeQL может использовать только одну версию и обычно выбирает более новую версию, в которой существует несколько версий. Этот подход может не работать для всех репозиториев.
• Проверьте, требуется ли более одной версии JDK API для разных исходных Java-файлов. При просмотре нескольких версий CodeQL будет использовать самую высокую версию, необходимую для любого скрипта сборки. Это может означать, что некоторые файлы, требующие более низкой версии JDK, будут частично проанализированы. Например, если для некоторых файлов требуется JDK 8, но требование JDK 17 найдено в одном или нескольких скриптах сборки, CodeQL будет использовать JDK 17. Все файлы, требующие JDK 8, и не удалось создать с помощью JDK 17, будут частично проанализированы.
• Избегайте сопоставления имен классов (например, определения org.myproject.Testнескольких файлов), в противном случае это может привести к отсутствием целевых объектов вызова метода, что влияет на анализ потока данных.

Краткое описание автосборки для Java

Поддерживаемый тип системы	Системное имя
Операционная система	Windows, macOS и Linux (без ограничений)
Система сборки	Gradle, Maven и Ant

Автообнаружение для Java

Процесс autobuild пытается определить систему сборки для Java кодовых баз, применяя следующую стратегию:

1. Поиск файла сборки в корневом каталоге. Проверка наличия файлов сборки Gradle, затем Maven, а затем Ant.
2. Запуск первого найденного файла сборки. Если присутствуют файлы и Gradle, и Maven, используется файл Gradle.
3. В противном случае выполняется поиск файлов сборки в непосредственных подкаталогах корневого каталога. Если только один подкаталог содержит файлы сборки, запускается первый файл, определенный в этом подкаталоге (используя тот же приоритет, что и для 1). Если несколько подкаталогов содержат файлы сборки, возникает об ошибка.

Требования к бегу для Java

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

• Если раннер будет использоваться для анализа репозиториев, которым нужна одна версия Java, то необходимо установить соответствующую версию JDK, которая должна быть представлена в переменной PATH (чтобы можно было найти java и javac).

• Если раннер будет использоваться для анализа репозиториев, требующих нескольких версий Java, необходимо установить соответствующие версии JDK, которые можно задать через файл toolchains.xml. Это файл конфигурации, обычно используемый Apache Maven, который позволяет указать расположение инструментов, версию средств и любую дополнительную конфигурацию, необходимую для использования средств. Дополнительные сведения см. в руководстве по использованию цепочки инструментов в документации Apache Maven.

Следующие исполняемые файлы, вероятно, будут необходимы для ряда Java-проектов и должны присутствовать в переменной PATH, но они не будут обязательны во всех случаях:

• mvn (Апач Мейвен)
• gradle (Градл)
• ant (Муравей-апач)

Кроме того, необходимо установить систему сборки (напримерmake, , cmake) и служебные программы (напримерbazel, python,perl``lex, иyacc) от того, от сколько зависят ваши проекты.

Windows бегунам требуется powershell.exe для PATH.

Строительная ржавчина

CodeQL поддерживает режим none сборки для кода Rust.

Нет сборки для Rust

CodeQL использует rust-analyzer для компиляции и запуска скриптов сборки (build.rs файлов) и компиляции кода макросов, но не вызывает полную сборку. База данных создается из всех присутствующих файлов Rust. Файл или Cargo.toml``rust-project.json должен присутствовать.

Требования к раннеру для Rust

Анализ ржавчины требует rustup и cargo должен быть установлен.

Создание Swift

CodeQL поддерживает режимы autobuild сборки или manual для кода Swift.

Сводка по автостроке для Swift

Поддерживаемый тип системы	Системное имя
Операционная система	macOS
Система сборки	Xcode

Процесс autobuild пытается создать самый большой целевой объект из проекта или рабочей области Xcode.

Сканирование кода Swift использует средства выполнения macOS по умолчанию.

Code scanning кода Swift не поддерживается для runners, которые являются частью Actions Runner Controller (ARC), так как для выполнения ARC используется только Linux и Swift, требуются средства выполнения macOS. Тем не менее, вы можете иметь смесь как runners ARC, так и локальных модулей macOS runners. Дополнительные сведения см. в разделе Контроллер runner действий.

Настройка компиляции Swift в Рабочий процесс анализа CodeQL

          `xcodebuild` и `swift build` поддерживаются для сборок Swift. Рекомендуется использовать только одну архитектуру во время сборки. Например, `ARCH=arm64` для `xcodebuild`или `--arch arm64` для `swift build`.

Вы можете передать параметры archive и test параметры xcodebuild. Тем не менее, стандартная xcodebuild команда рекомендуется, так как она должна быть самой быстрой и должна быть все, что CodeQL требуется для успешной проверки.

Для анализа Swift необходимо всегда явно устанавливать зависимости, управляемые с помощью CocoaPods или Carthage, прежде чем создавать базу данных CodeQL.