Миграция из средства выполнения CodeQL в CodeQL CLI

1 апреля 2022 г. Средство выполнения CodeQL был полностью нерекомендуем. Вместо этого следует использовать CodeQL CLI версии 2.6.2 и выше. В этом документе описывается перенос распространенных рабочих процессов из Средство выполнения CodeQL в CodeQL CLI.

Установка

Загрузите CodeQL bundle из репозитория github/codeql-action. Этот пакет сдержит CodeQL CLI и стандартные запросы и библиотеки CodeQL.

Дополнительные сведения о настройке CodeQL CLI см. в разделе Установка CodeQL CLI в системе CI.

Общие сведения об изменениях рабочего процесса

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

codeql-runner-<platform> init для запуска создания баз данных CodeQL и чтения конфигурации.
Для компилируемых языков: задайте переменные среды, созданные на шаге init.
Для компилируемых языков: выполните автоматическую сборку или шаги сборки вручную.
codeql-runner-<platform> analyze для окончания создания баз данных CodeQL, выполните запросы для анализа каждой базы данных CodeQL, подведите итоги результатов в файле SARIF и отправьте результаты на GitHub.

Типичный рабочий процесс, использующий CodeQL CLI для анализа базы кода, состоит из следующих этапов.

codeql database create для создания баз данных CodeQL.
- Для компилируемых языков: при необходимости предоставьте команду сборки.
codeql database analyze для выполнения запросов на анализ каждой базы данных CodeQL и сведения результатов в файле SARIF. Эта команда должна выполняться один раз для каждого языка или базы данных.
codeql github upload-results для отправки результирующих файлов SARIF на GitHub для отображения в виде оповещений о сканировании кода. Эта команда должна выполняться один раз для каждого языка или файла SARIF.

Средство выполнения CodeQL по умолчанию имеет многопоточность. CodeQL CLI использует только один поток по умолчанию, но позволяет указать количество потоков, которые вы хотите использовать. Если вы хотите реплицировать поведение Средство выполнения CodeQL для использования всех потоков, доступных на компьютере при использовании CodeQL CLI, можно передать --threads 0 в codeql database analyze.

Дополнительные сведения см. в разделе Установка CodeQL CLI в системе непрерывной интеграции.

Примеры распространенных применений для CodeQL CLI

О примерах

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

В этих примерах также предполагается, что CodeQL CLI помещается в текущий PATH.

В этих примерах маркер GitHub с подходящими областями хранится в переменной среды $TOKEN и передается в примеры команд с помощью stdin или хранится в переменной среды $GITHUB_TOKEN.

Извлекаемые и анализируемые в этих примерах имя ссылки и SHA фиксации становятся известны во время рабочего процесса. Для ветви используйте refs/heads/BRANCH-NAME в качестве ссылки. Для головной фиксации запроса на вытягивание используйте refs/pull/NUMBER/head. Для фиксации запроса на вытягивание, созданной GitHub, используйте refs/pull/NUMBER/merge. Во всех следующих примерах используется refs/heads/main. При использовании другого имени ветви необходимо изменить пример кода.

Один некомпилируемый язык (JavaScript)

Средство выполнения:

echo "$TOKEN" | codeql-runner-linux init --repository my-org/example-repo \
    --languages javascript \
    --github-url https://github.com --github-auth-stdin

echo "$TOKEN" | codeql-runner-linux analyze --repository my-org/example-repo
    --github-url https://github.com --github-auth-stdin
    --commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 --ref refs/heads/main

Интерфейс командной строки.

codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root=.

# The default query suite is called `<language>-code-scanning.qls`.
codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

echo "$TOKEN" | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

Один некомпилируемый язык (JavaScript) с использованием другого набора запросов (безопасность и качество)

Аналогичный подход можно использовать для компилируемых языков или нескольких языков.

Средство выполнения:

echo "$TOKEN" | codeql-runner-linux init --repository my-org/example-repo \
    --languages javascript \
    --github-url https://github.com --github-auth-stdin

echo "$TOKEN" | codeql-runner-linux analyze --repository my-org/example-repo \
    --queries security-and-quality \
    --github-url https://github.com --github-auth-stdin \
    --commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 --ref refs/heads/main

Интерфейс командной строки.

codeql database create /codeql-dbs/example-repo --language=javascript \
    --source-root=.

# Use `<language>-<suite name>.qls`
codeql database analyze /codeql-dbs/example-repo  \
    javascript-security-and-quality.qls --sarif-category=javascript
    --format=sarif-latest --output=/temp/example-repo-js.sarif

echo "$TOKEN" | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

Один некомпилируемый язык (JavaScript) с использованием пользовательского файла конфигурации

Аналогичный подход можно использовать для компилируемых языков или нескольких языков.

Средство выполнения:

echo "$TOKEN" | codeql-runner-linux init --repository my-org/example-repo \
    --languages javascript \
    --config-file .github/codeql/codeql-config.yml \
    --github-url https://github.com --github-auth-stdin

echo "$TOKEN" | codeql-runner-linux analyze --repository my-org/example-repo \
    --github-url https://github.com --github-auth-stdin \
    --commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 --ref refs/heads/main

Интерфейс командной строки.

# Use `--codescanning-config` with the path to the YAML configuration file.
codeql database create /codeql-dbs/example-repo --language=javascript \
    --codescanning-config=.github/codeql/codeql-config.yml \
    --source-root=.

codeql database analyze /codeql-dbs/example-repo  \
    --sarif-category=javascript
    --format=sarif-latest --output=/temp/example-repo-js.sarif

echo "$TOKEN" | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-js.sarif --github-auth-stdin

Один компилируемый язык с использованием автоматической сборки (Java)

Средство выполнения:

echo "$TOKEN" | codeql-runner-linux init --repository my-org/example-repo \
    --languages java \
    --github-url https://github.com --github-auth-stdin

# Source the script generated by the init step to set up the environment to monitor the build.
. codeql-runner/codeql-env.sh

# Run the autobuilder for the given language.
codeql-runner-linux autobuild --language java

echo "$TOKEN" | codeql-runner-linux analyze --repository my-org/example-repo
    --github-url https://github.com --github-auth-stdin
    --commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 --ref refs/heads/main

Интерфейс командной строки.

# Run `codeql database create` without `--command`.
# This will run the autobuilder for the given language.
codeql database create /codeql-dbs/example-repo --language=java \
    --source-root=.

codeql database analyze /codeql-dbs/example-repo  \
    javascript-code-scanning.qls --sarif-category=java
    --format=sarif-latest --output=/temp/example-repo-java.sarif

echo "$TOKEN" | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-java.sarif --github-auth-stdin

Один компилируемый язык с использованием пользовательской команды сборки (Java)

Средство выполнения:

echo "$TOKEN" | codeql-runner-linux init --repository my-org/example-repo \
    --languages java \
    --github-url https://github.com --github-auth-stdin

# Source the script generated by the init step to set up the environment to monitor the build.
. codeql-runner/codeql-env.sh

# Run a custom build command.
mvn compile -DskipTests

echo "$TOKEN" | codeql-runner-linux analyze --repository my-org/example-repo
    --github-url https://github.com --github-auth-stdin
    --commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 --ref refs/heads/main

Интерфейс командной строки.

# Provide an explicit build command using `--command`.
codeql database create /codeql-dbs/example-repo --language=java \
    --command="mvn compile -DskipTests" --source-root=.

codeql database analyze /codeql-dbs/example-repo  \
    java-code-scanning.qls --sarif-category=java
    --format=sarif-latest --output=/temp/example-repo-java.sarif

echo "$TOKEN" | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-java.sarif --github-auth-stdin

Один компилируемый язык с использованием непрямой трассировки сборки (C# на Windows в Azure DevOps)

Непрямая трассировка сборки для компилируемого языка позволяет CodeQL обнаруживать все этапы сборки между этапами init и analyze, когда код невозможно собрать с помощью автоматического средства или явной командной строки сборки. Это полезно при использовании предварительно настроенных шагов сборки из системы CI, таких как задачи VSBuild и MSBuild в Azure DevOps.

Средство выполнения:

- task: CmdLine@1
  displayName: CodeQL Initialization
  inputs:
  script: "%CodeQLRunner%\\codeql-runner-win.exe init --repository my-org/example-repo --languages csharp --github-url https://github.com --github-auth $(Token)"
# Set the generated environment variables so they are available for subsequent commands, in the format required by Azure Pipelines.
- task: PowerShell@1
  displayName: Set CodeQL Environment Variables
  inputs:
      targetType: inline
      script: >
          $json = Get-Content $(System.DefaultWorkingDirectory)/codeql-runner/codeql-env.json | ConvertFrom-Json
          $json.PSObject.Properties | ForEach-Object {
              $template = "##vso[task.setvariable variable="
              $template += $_.Name
              $template += "]"
              $template += $_.Value
              echo "$template"
          }

# Execute a clean build using the VSBuild task.
- task: VSBuild@1
  inputs:
      solution: '**/*.sln'
      msbuildArgs: '/p:OutDir=$(Build.ArtifactStagingDirectory) /p:UseSharedCompilation=false'
      platform: Any CPU
      configuration: Release
      clean: True
  displayName: Visual Studio Build

# Analyze the database created as part of the build, by running the selected queries against it, and upload results to GitHub.
- task: CmdLine@2
  displayName: CodeQL Analyze
  inputs:
      script: '%CodeQLRunner%\codeql-runner-win.exe analyze --repository my-org/example-repo --commit $(Build.SourceVersion) --ref $(Build.SourceBranch) --github-url https://github.com --github-auth $(Token)'

Интерфейс командной строки.

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

# Initialize the CodeQL database using `codeql database init --begin tracing`.
- task: CmdLine@1
  displayName: Initialize CodeQL database
  inputs:
      # Assumes the source code is checked out to the current working directory.
      # Creates a database at `/codeql-dbs/example-repo`.
      # 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 /codeql-dbs/example-repo"

# For CodeQL to trace future build steps without knowing the explicit build commands,
# it requires certain environment variables to be set during the build.
# Read these 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 /codeql-dbs/example-repo/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'
      # Disable MSBuild shared compilation for C# builds.
      msbuildArgs: /p:OutDir=$(Build.ArtifactStagingDirectory) /p:UseSharedCompilation=false
      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"
         }

# Use `codeql database finalize` to complete database creation after the build is done.
- task: CmdLine@2
   displayName: Finalize CodeQL database
   inputs:
      script: 'codeql database finalize /codeql-dbs/example-repo'

# Analyze the database and upload the results.
- task: CmdLine@2
   displayName: Analyze CodeQL database
   inputs:
      script: 'codeql database analyze /codeql-dbs/example-repo csharp-code-scanning.qls --sarif-category=csharp --format=sarif-latest --output=/temp/example-repo-csharp.sarif'

- task: CmdLine@2
   displayName: Upload CodeQL results
   inputs:
      script: 'echo "$TOKEN" | codeql github upload-results --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=/temp/example-repo-csharp.sarif --github-auth-stdin'

Несколько языков с использованием автоматической сборки (C++, Python)

Этот пример не является строго возможным в Средство выполнения CodeQL. Будет проанализирован только один язык (компилируемый язык с большинством файлов).

Средство выполнения:

echo "$TOKEN" | codeql-runner-linux init --repository my-org/example-repo \
    --languages cpp,python \
    --github-url https://github.com --github-auth-stdin

# Source the script generated by the init step to set up the environment to monitor the build.
. codeql-runner/codeql-env.sh

# Run the autobuilder for the language with the most files.
codeql-runner-linux autobuild

echo "$TOKEN" | codeql-runner-linux analyze --repository my-org/example-repo
    --github-url https://github.com --github-auth-stdin
    --commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 --ref refs/heads/main

Интерфейс командной строки.

# Create multiple databases using `--db-cluster`.
# Run autobuild by omitting `--command`.
codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language cpp,python \
    --no-run-unnecessary-builds \
    --source-root .

# Analyze each database in turn and upload the results.
for language in cpp python; do
  codeql database analyze "/codeql-dbs/example-repo-multi/$language"  \
      "$language-code-scanning.qls" --sarif-category="$language"
      --format=sarif-latest --output="/temp/example-repo-$language.sarif"

  echo "$TOKEN" | codeql github upload-results --repository=my-org/example-repo \
      --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
      --sarif="/temp/example-repo-$language.sarif" --github-auth-stdin
done

Несколько языков с помощью пользовательской команды сборки (C++, Python)

Средство выполнения:

echo "$TOKEN" | codeql-runner-linux init --repository my-org/example-repo \
    --languages cpp,python \
    --github-url https://github.com --github-auth-stdin

# Source the script generated by the init step to set up the environment to monitor the build.
. codeql-runner/codeql-env.sh

# Run a custom build command.
make

echo "$TOKEN" | codeql-runner-linux analyze --repository my-org/example-repo
    --github-url https://github.com --github-auth-stdin
    --commit deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 --ref refs/heads/main

Интерфейс командной строки.

# Create multiple databases using `--db-cluster`.
codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language cpp,python \
    --command make --no-run-unnecessary-builds \
    --source-root .

# Analyze each database in turn and upload the results.
for language in cpp python; do
  codeql database analyze "/codeql-dbs/example-repo-multi/$language"  \
      "$language-code-scanning.qls" --sarif-category="$language"
      --format=sarif-latest --output="/temp/example-repo-$language.sarif"

  echo "$TOKEN" | codeql github upload-results --repository=my-org/example-repo \
      --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
      --sarif="/temp/example-repo-$language.sarif" --github-auth-stdin
done

Миграция из средства выполнения CodeQL в CodeQL CLI

В этой статье

Установка

Общие сведения об изменениях рабочего процесса

Примеры распространенных применений для CodeQL CLI

О примерах

Один некомпилируемый язык (JavaScript)

Один некомпилируемый язык (JavaScript) с использованием другого набора запросов (безопасность и качество)

Один некомпилируемый язык (JavaScript) с использованием пользовательского файла конфигурации

Один компилируемый язык с использованием автоматической сборки (Java)

Один компилируемый язык с использованием пользовательской команды сборки (Java)

Один компилируемый язык с использованием непрямой трассировки сборки (C# на Windows в Azure DevOps)

Несколько языков с использованием автоматической сборки (C++, Python)

Несколько языков с помощью пользовательской команды сборки (C++, Python)