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

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

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

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

Перед созданием базы данных CodeQL необходимо выполнить следующие действия.

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

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

Бег codeql database create

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

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

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

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

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

  Язык	Идентификатор	Необязательные альтернативные идентификаторы (если таковые есть)
  C/C++	c-cpp

              `c` или `cpp` |
  

  | C# | csharp | | | 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 для нескольких языков.

Вариант	Обязательно	Usage
<database>		Укажите имя и расположение каталога, который необходимо создать для базы данных CodeQL. Команда завершится ошибкой, если вы попытаетесь перезаписать существующий каталог. Если также указать --db-cluster, это родительский каталог, а для каждого проанализированного языка создается подкаталог.
--language		Укажите идентификатор языка для создания базы данных, одной из следующих: данных, которые можно использовать повторно.code-scanning.codeql-language-keywords %}. При использовании с --db-cluster параметр принимает список с разделителями-запятыми или может быть указан более одного раза.
--command

          **Рекомендуется**. Используйте для указания команды сборки или скрипта, вызывающего процесс сборки для базы кода. Команды запускаются из текущей папки или, если она определена, из <code><span style="white-space: nowrap;">--source-root</span></code>. Не требуется для анализа Python и JavaScript/TypeScript. |

| --build-mode | | Рекомендуется. Используйте для C# and Java при отсутствии --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# and Javaход извлечения отображается в консоли. Для каждого исходного файла консоль показывает, успешно ли выполнено извлечение или если он завершился ошибкой. При построении скомпилированного языка консоль отобразит выходные данные системы сборки.

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

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

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

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 не требует дополнительных зависимостей. В командной строке необходимо указать --language=ruby. Рассмотрим пример.

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

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

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

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

•         [Автоматическое обнаружение сборки (autobuild)](#automatically-detecting-the-build-system)
  

•         [Пользовательские команды сборки](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis#specifying-build-commands)
  

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

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

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

Автостроитель вызывается автоматически при выполнении 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 в базу данных CodeQL или сделать это ранее 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'
  

• Проект 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 с косвенной трассировкой сборки, выполните следующую команду из корневого каталога проекта:

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