Подготовка кода для анализа CodeQL

Подготовка кода к анализу

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

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

Перед созданием CodeQL базы данных необходимо:

1. Установите и настройте .CodeQL CLI Дополнительные сведения см. в разделе Настройка интерфейса командной строки CodeQL.
2. Извлеките код, который нужно проанализировать:
   • Для ветви извлеките заголовок ветви, которую необходимо проанализировать.
   • Для pull-запроса проверьте либо главный коммит pull-запроса, либо GitHub-genered-merge commit pull-запроса.
3. Настройте среду для базы кода, убедившись, что все зависимости доступны.
4. Чтобы получить наилучшие результаты с скомпилированных языков, найдите команду сборки( если таковые есть) для базы кода. Обычно она доступна в файле конфигурации в системе CI.

После готовности базы кода можно запустить codeql database create для создания базы данных. Дополнительные сведения см. в разделе "Создание баз данных для нескомпилированных языков " и "Создание баз данных для скомпилированных языков".

Бег codeql database create

CodeQL Базы данных создаются путём выполнения следующей команды из корня checkout вашего проекта:

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

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

• <database>: путь к созданной базе данных. Этот каталог будет создан при выполнении команды— нельзя указать существующий каталог.

• --language— идентификатор языка для создания базы данных. При использовании с --db-cluster параметр принимает список с разделителями-запятыми или может быть указан более одного раза. CodeQL Поддерживает создание баз данных для следующих языков:

  Язык	Идентификатор	Необязательные альтернативные идентификаторы (если таковые есть)
  C/C++	c-cpp
  c или cpp
  C#	csharp
  Рабочие процессы GitHub Actions	actions
  Go	go
  Java и Kotlin	java-kotlin
  java или kotlin
  JavaScript/TypeScript	javascript-typescript
  javascript или typescript
  Python	python
  Ruby	ruby
  Rust	rust
  Swift	swift

  Примечание.

  Если указать один из альтернативных идентификаторов, это эквивалентно использованию стандартного идентификатора языка. Например, указание javascript вместо того, чтобы исключить javascript-typescript анализ кода TypeScript. Вместо этого можно использовать --codescanning-config параметр CLI для загрузки файла конфигурации, указывающего файлы для исключения с paths-ignore помощью ключа конфигурации. См . раздел AUTOTITLE.

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

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

   codeql database create <database> --command <build> \
         --language=<language-identifier>

Параметры создания баз данных

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

Option	Обязательный	Использование
<database>		Укажите имя и местоположение каталога для создания для CodeQL базы данных. Команда завершится ошибкой, если вы попытаетесь перезаписать существующий каталог. Если также указать --db-cluster, это родительский каталог, а для каждого проанализированного языка создается подкаталог.
--language		Укажите идентификатор для языка для создания базы данных, одного из: c-cpp, csharp, go, java-kotlin, javascript-typescript``python, , { ruby% ifversion codeql-rust-available %}, rust иswift. При использовании с --db-cluster параметр принимает список с разделителями-запятыми или может быть указан более одного раза.
--command
Рекомендуется. Используйте для указания команды сборки или скрипта, вызывающего процесс сборки для базы кода. Команды запускаются из текущей папки или, если она определена, из --source-root. Не требуется для анализа Python и JavaScript/TypeScript.
--build-mode
Рекомендуется. Используйте , C/C++, C#, Java и Rust когда не предоставляете a --command , чтобы указать, создавать ли базу данных CodeQL без сборки (none) или пытаться автоматически обнаружить команду сборки (autobuild). По умолчанию используется обнаружение автостроек. Сравнение режимов сборки см. в разделе "Режимы сборки CodeQL".
--db-cluster		Используйте в многоязычных базах кода для создания одной базы данных для каждого языка, заданного --language.
--no-run-unnecessary-builds
Рекомендуется. Используйте для подавления команды сборки для языков, где CodeQL CLI не требует мониторинга сборки (например, Python и JavaScript/TypeScript).
--source-root		Используйте, если вы запускаете CLI за пределами корневого элемента извлечения репозитория. По умолчанию командой database create предполагается, что текущий каталог является корневым каталогом для исходных файлов. Используйте этот параметр, чтобы указать другое местоположение.
--codescanning-config		Advanced. Используй, если у вас есть конфигурационный файл, который указывает, как создавать CodeQL базы данных и какие запросы запускать на следующих этапах. Дополнительные сведения см. в разделе [AUTOTITLE и Параметры настройки рабочих процессов для сканирования кода](/code-security/codeql-cli/codeql-cli-manual/database-create#--codescanning-configfile).

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

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

Пример использования одного языка

Этот пример создаёт единую CodeQL базу данных для репозитория, взятого по адресу /checkouts/example-repo. Он использует средство извлечения JavaScript для создания иерархического представления кода JavaScript и TypeScript в репозитории. Результирующая база данных хранится в /codeql-dbs/example-repo.

$ codeql database create /codeql-dbs/example-repo --language=javascript-typescript \
    --source-root /checkouts/example-repo

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Пример с несколькими языками

В этом примере создаются две CodeQL базы данных для репозитория, проверенные по адресу /checkouts/example-repo-multi. Он использует следующую информацию:

• --db-cluster для запроса анализа более чем одного языка.
• --language для указания, для каких языков следует создавать базы данных.
• --command, чтобы сообщить инструменту команду сборки для базы кода. Здесь это make.
• --no-run-unnecessary-builds чтобы сказать инструменту пропускать команду сборки для языков, где она не нужна (например, Python).

Результирующие базы данных хранятся в подкаталогах python и cpp в /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,c-cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Ход выполнения и результаты

Сообщается об ошибках, если возникли проблемы с указанными параметрами. Для интерпретируемых языков и при указании --build-mode none для C/C++, C#, Java и Rust, прогресс извлечения отображается в консоли. Для каждого исходного файла консоль показывает, успешно ли выполнено извлечение или если он завершился ошибкой. При построении скомпилированного языка консоль отобразит выходные данные системы сборки.

После успешного создания базы данных вы найдете новый каталог по пути, указанному в команде. Если вы использовали --db-cluster параметр для создания нескольких баз данных, для каждого языка создается подкаталог. Каждый CodeQL каталог базы данных содержит несколько подкаталогов, включая реляционные данные (необходимые для анализа) и архив исходного кода — копию исходных файлов, созданных на момент создания базы данных — который используется для отображения результатов анализа.

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

CodeQL CLI включает экстракторы для создания баз данных для некомпилируемых языков — в частности, JavaScript (и TypeScript), Python и Ruby. Эти экстракторы автоматически вызываются, когда при выполнении --language указания JavaScript, Python или Ruby в качестве опции database create. При создании баз данных для этих языков необходимо убедиться, что доступны все дополнительные зависимости.

JavaScript и TypeScript

Создание баз данных для JavaScript не требует дополнительных зависимостей, но если проект включает файлы TypeScript, Node.js 14 или более поздних версий должны быть установлены и доступны в PATH качестве node. В командной строке можно указать --language=javascript-typescript , чтобы извлечь файлы JavaScript и TypeScript:

codeql database create --language=javascript-typescript --source-root <folder-to-extract> <output-folder>/javascript-database

Здесь мы указали --source-root путь, который является расположением, где выполняется создание базы данных, но не обязательно является корнем извлечений базы кода.

По умолчанию файлы в node_modules каталогах bower_components не извлекаются.

Python

При создании баз данных для Python необходимо обеспечить:

• У вас установлены Python 3, доступные для экстрактора CodeQL.
• У вас установлена версия Python, используемая вашим кодом.

В командной строке необходимо указать --language=python. Рассмотрим пример.

codeql database create --language=python <output-folder>/python-database

Это выполняет подкоманду database create с корня checkout кода, генерируя новую базу данных Python в <output-folder>/python-database.

Ruby

Создание баз данных для Ruby не требует дополнительных зависимостей. В командной строке необходимо указать --language=ruby. Рассмотрим пример.

codeql database create --language=ruby --source-root <folder-to-extract> <output-folder>/ruby-database

Здесь мы указали --source-root путь, который является расположением, где выполняется создание базы данных, но не обязательно является корнем извлечений базы кода.

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

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

• Автоматическое обнаружение сборки (autobuild)
• Пользовательские команды сборки

Кроме того, для C/C++, C#, Java и Rust, есть возможность генерировать базу данных без создания кода. Это особенно полезно, когда вы хотите включить code scanning множество репозиториев. Дополнительные сведения см. в режимах сборки CodeQL.

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

Включает CodeQL CLI автостроителей для C/C++, C#, Go, Java, Kotlin и Swift кодекса. CodeQL Autobuilders позволяют создавать проекты на скомпилированных языках без указания команд сборки. При вызове автоконструктора CodeQL он проверяет исходный код на наличие доказательств системы сборки и пытается выполнить оптимальный набор команд, необходимых для извлечения базы данных. Дополнительные сведения см. в разделе CodeQL code scanning for compiled languages.

Автостроитель вызывается автоматически при выполнении codeql database create для скомпилированного языка, если вы не включаете --command параметр или набор --build-mode none. Например, для базы кода Swift можно просто запустить:

codeql database create --language=swift <output-folder>/swift-database

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

Указание команд сборки

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

• Проект C/C++, построенный с помощью make:

  # Disable parallel execution via `-j1` or other techniques: https://www.gnu.org/software/make/manual/make.html#Parallel-Execution
  codeql database create cpp-database --language=c-cpp --command=make
  

• Проект C#, построенный с помощью dotnet build:

  Полезно добавлять /t:rebuild , чтобы убедиться, что весь код будет создан, или сделать предшествующий dotnet clean (код, который не собран, не будет включен в CodeQL базу данных):

  codeql database create csharp-database --language=csharp --command='dotnet build /t:rebuild'
  

• Проект Go, созданный с помощью переменной CODEQL_EXTRACTOR_GO_BUILD_TRACING=on среды:

  CODEQL_EXTRACTOR_GO_BUILD_TRACING=on codeql database create go-database --language=go
  

• Перейти к проекту, созданному с помощью пользовательского скрипта сборки:

  codeql database create go-database --language=go --command='./scripts/build.sh'
  

• Java-проект, построенный с использованием Gradle:

  # Use `--no-daemon` because a build delegated to an existing daemon cannot be detected by CodeQL.
  # To ensure isolated builds without caching, add `--no-build-cache` on persistent machines.
  codeql database create java-database --language=java-kotlin --command='gradle --no-daemon clean test'
  

• Java-проект, созданный с использованием Maven:

  codeql database create java-database --language=java-kotlin --command='mvn clean install'
  

• Java-проект, созданный с помощью Ant:

  codeql database create java-database --language=java-kotlin --command='ant -f build.xml'
  

• Проект Rust, построенный с использованием Cargo:

  codeql database create rust-database --language=rust
  

• Проект Swift, созданный из проекта или рабочей области Xcode. По умолчанию создается самый большой целевой объект Swift:

  Рекомендуется убедиться, что проект находится в чистом состоянии и что артефакты сборки недоступны.

  xcodebuild clean -all
  codeql database create -l swift swift-database
  

• Проект Swift, созданный с помощью swift build:

  codeql database create -l swift -c "swift build" swift-database
  

• Проект Swift, созданный с помощью xcodebuild:

  codeql database create -l swift -c "xcodebuild build -target your-target" swift-database
  

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

• Проект Swift, созданный с помощью пользовательского скрипта сборки:

  codeql database create -l swift -c "./scripts/build.sh" swift-database
  

• Проект построен с помощью Bazel:

  # Navigate to the Bazel workspace.
  
  # Before building, remove cached objects
  # and stop all running Bazel server processes.
  bazel clean --expunge
  
  # Build using the following Bazel flags, to help CodeQL detect the build:
  # `--spawn_strategy=local`: build locally, instead of using a distributed build
  # `--nouse_action_cache`: turn off build caching, which might prevent recompilation of source code
  # `--noremote_accept_cached`, `--noremote_upload_local_results`: avoid using a remote cache
  # `--disk_cache=`: avoid using a disk cache. Note that a disk cache is no longer considered a remote cache as of Bazel 6.
  codeql database create new-database --language=<language> \
  --command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results --disk_cache= //path/to/package:target'
  
  # After building, stop all running Bazel server processes.
  # This ensures future build commands start in a clean Bazel server process
  # without CodeQL attached.
  bazel shutdown
  

• Проект, созданный с помощью пользовательского скрипта сборки:

  codeql database create new-database --language=<language> --command='./scripts/build.sh'
  

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

Использование непрямой трассировки сборки

Если CodeQL CLI автоконструкторы для скомпилированных языков не работают с вашим CI-рабочим процессом и вы не можете обернуть вызовы команд сборки , codeql database trace-commandвы можете использовать косвенное трассирование сборки для создания CodeQL базы данных. Чтобы использовать непрямую трассировку сборки, система CI должна иметь возможность задавать пользовательские переменные среды для каждого действия сборки.

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

codeql database init ... --begin-tracing <database>

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

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

Вы можете указать другие параметры для команды в обычном режиме codeql database init .

Команда codeql database init выводит сообщение:

Created skeleton <database>. This in-progress database is ready to be populated by an extractor. In order to initialise tracing, some environment variables need to be set in the shell your build will run in. A number of scripts to do this have been created in <database>/temp/tracingEnvironment. Please run one of these scripts before invoking your build command.

Based on your operating system, we recommend you run: ...

Команда codeql database init создаёт <database>/temp/tracingEnvironment файлы, содержащие переменные среды и значения, позволяющие CodeQL проследить последовательность шагов сборки. Эти файлы называются start-tracing.{json,sh,bat,ps1}. Используйте один из этих файлов с механизмом системы CI для настройки переменных среды для будущих шагов. Можно сделать следующее:

• Чтение JSON-файла, его обработка и печать переменных среды в формате, ожидаемом системой CI. Например, Azure DevOps ожидает echo "##vso[task.setvariable variable=NAME]VALUE".
• Или, если ваша система CI сохраняет эту среду, используйте соответствующий start-tracing скрипт для установки CodeQL переменных в оболочной среде CI-системы.

Создание кода; При необходимости отмените переменные среды с помощью end-tracing.{json,sh,bat,ps1} скрипта из каталога, в котором start-tracing хранятся скрипты, а затем выполните команду codeql database finalize <database>.

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

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

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

steps:
    # Download the CodeQL CLI and query packs...
    # Check out the repository ...

    # Run any pre-build tasks, for example, restore NuGet dependencies...

    # Initialize the CodeQL database.
    # In this example, the CodeQL CLI has been downloaded and placed on the PATH.
    - task: CmdLine@1
       displayName: Initialize CodeQL database
      inputs:
          # Assumes the source code is checked out to the current working directory.
          # Creates a database at `<current working directory>/db`.
          # Running on Windows, so specifies a trace process level.
          script: "codeql database init --language csharp --trace-process-name Agent.Worker.exe --source-root . --begin-tracing db"

    # Read the generated environment variables and values,
    # and set them so they are available for subsequent commands
    # in the build pipeline. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Set CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/start-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    # Execute the pre-defined build step. Note the `msbuildArgs` variable.
    - task: VSBuild@1
        inputs:
          solution: '**/*.sln'
          msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory)
          platform: Any CPU
          configuration: Release
          # Execute a clean build, in order to remove any existing build artifacts prior to the build.
          clean: True
       displayName: Visual Studio Build

    # Read and set the generated environment variables to end build tracing. This is done in PowerShell in this example.
    - task: PowerShell@1
       displayName: Clear CodeQL environment variables
       inputs:
          targetType: inline
          script: >
             $json = Get-Content $(System.DefaultWorkingDirectory)/db/temp/tracingEnvironment/end-tracing.json | ConvertFrom-Json
             $json.PSObject.Properties | ForEach-Object {
                 $template = "##vso[task.setvariable variable="
                 $template += $_.Name
                 $template += "]"
                 $template += $_.Value
                 echo "$template"
             }

    - task: CmdLine@2
       displayName: Finalize CodeQL database
       inputs:
          script: 'codeql database finalize db'

    # Other tasks go here, for example:
    # `codeql database analyze`
    # then `codeql github upload-results` ...

Дальнейшие действия

• Чтобы узнать, как CodeQL CLI использовать их для анализа базы данных, созданной из вашего кода, смотрите Analyzing your code with CodeQL queries.