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

Сведения о создании баз данных CodeQL

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

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

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

• Установите и настройте CodeQL CLI. Дополнительные сведения см. в разделе Начало работы с CodeQL CLI.
• Ознакомьтесь с версией базы кода, которую вы хотите проанализировать. Каталог должен быть готов к сборке со всеми зависимостями, которые уже установлены.

Сведения об использовании CodeQL CLI в сторонней системе CI для создания результатов для отображения в GitHub в качестве оповещений сканирования кода см. в разделе Настройка CodeQL CLI в системе CI. Сведения о включении сканирования кода CodeQL с помощью GitHub Actions см. в разделе Настройка сканирования кода для репозитория.

Работает codeql database create

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

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

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

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

Язык	Идентификатор
C/C++	cpp
C#	csharp
Go	go
Java/Kotlin	java
JavaScript/TypeScript	javascript
Python	python
Ruby	ruby

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

• --source-root: корневая папка для первичных исходных файлов, используемых при создании базы данных. По умолчанию команда предполагает, что текущий каталог является корнем источника. Используйте этот параметр, чтобы указать другое расположение.
• --db-cluster: используется для многоязыковых баз кода, если требуется создать базы данных для нескольких языков.
• --command: используется при создании базы данных для одного или нескольких скомпилированных языков. Опустить, если запрашиваются только python и JavaScript. Это указывает команды сборки, необходимые для вызова компилятора. Команды выполняются из текущей папки или --source-root , если она указана. Если не включить --command, CodeQL попытается обнаружить систему сборки автоматически с помощью встроенного автобилизатора.
• --no-run-unnecessary-builds: используется с --db-cluster для подавления команды сборки для языков, в которых CodeQL CLI не требуется отслеживать сборку (например, Python и JavaScript/TypeScript).

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

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

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

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

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

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

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

JavaScript и TypeScript

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

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

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

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

Python

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

• У вас установлен Python 3, доступный для средства извлечения CodeQL.
• У вас установлена версия Python, используемая вашим кодом.
• У вас есть доступ к системе управления упаковкой pip и вы можете установить любые пакеты, от которых зависит база кода.
• Вы установили модуль pip virtualenv .

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

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

При этом выполняется database create подкоманда из корневого каталога получения кода, создавая новую базу данных 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 CLI включает автобилизаторы для кода C/C++, C#, Go и Java. Автобилизаторы CodeQL позволяют создавать проекты для скомпилированных языков без указания команд сборки. При вызове автобилизатора CodeQL проверяет источник на наличие доказательств системы сборки и пытается выполнить оптимальный набор команд, необходимых для извлечения базы данных.

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

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

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

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

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

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

  CodeQL database create cpp-database --language=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: CodeQL database create java-database --language=java --command='gradle --no-daemon clean test'
  

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

  CodeQL database create java-database --language=java --command='mvn clean install'
  

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

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

• Проект, созданный с использованием 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
  CodeQL database create new-database --language=<language> \
  --command='bazel build --spawn_strategy=local --nouse_action_cache --noremote_accept_cached --noremote_upload_local_results //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` ...

Скачивание баз данных из GitHub.com

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

Вы можете проверить, есть ли в репозитории базы данных CodeQL, доступные для скачивания с помощью конечной /repos/<owner>/<repo>/code-scanning/codeql/databases точки. Например, чтобы проверить наличие баз данных CodeQL с помощью GitHub CLI , выполните следующую команду:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/

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

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

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

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

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

Дополнительные материалы

• "Анализ проектов в CodeQL для VS Code"