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

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

           Если вы используете самостоятельные раннеры для GitHub Actions, возможно, потребуется установить дополнительное программное обеспечение для использования процесса `autobuild` . Кроме того, что если для вашего репозитория требуется определенная версия инструмента сборки, вам может потребоваться сначала установить его вручную. 
           Для самостоятельных раннеров следует устанавливать зависимости непосредственно в самих раннерах. Мы приводим примеры распространённых зависимостей для C/C++, C# и Java в каждом из разделов `autobuild` этой статьи для этих языков. Для получения дополнительной информации см. [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).

Создание 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-hosted 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, это также используется, см. раздел «Сканирование кода, доступ к частным реестрам по умолчанию » и «Определение, использовала ли настройка сканирования кода по умолчанию какие-либо приватные реестры».

Следующие сгенерированные исходные файлы являются необязательными, но значительно повышают корректность 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](#runner-requirements-for-java).


          Если для организации определен приватный реестр Maven, он также используется, см. [раздел «Код сканирование по умолчанию для настройки доступа к частным реестрам](/code-security/securing-your-organization/enabling-security-features-in-your-organization/giving-org-access-private-registries#code-scanning-default-setup-access-to-private-registries) » и [«Определение, использует ли настройка сканирования кода по умолчанию какие-либо приватные реестры](/code-security/code-scanning/managing-your-code-scanning-configuration/viewing-code-scanning-logs#determining-whether-code-scanning-default-setup-used-any-private-registries)».

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

Создание базы данных CodeQL Java без сборки может дать менее точные результаты, чем использование 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 для успешного сканирования.

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