Migrieren vom CodeQL-Runner zu CodeQL-CLI

In diesem Artikel

Du kannst die CodeQL CLI verwenden, um die gleichen Aufgaben wie mit dem CodeQL-Runner auszuführen.

Code scanning ist für alle öffentlichen Repositorys auf GitHub.com verfügbar. Zur Verwendung von code scanning in einem privaten organisationseigenen Repository musst du über eine Lizenz für GitHub Advanced Security verfügen. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Am 1. April 2022 wurde CodeQL-Runner vollständig eingestellt. Du solltest die CodeQL CLI-Version 2.6.2 und höher verwenden. In diesem Dokument wird beschrieben, wie allgemeine Workflows vom CodeQL-Runner zur CodeQL CLI migriert werden.

Installation

Lade das CodeQL-Paket aus dem github/codeql-actionRepository herunter. Dieses Paket enthält die CodeQL CLI und die Standarddaten CodeQL-Abfragen und -Bibliotheken.

Weitere Informationen zur Einrichtung der CodeQL CLI findest du unter Installieren der CodeQL-CLI in deinem CI-System.

Übersicht über Workflowänderungen

Ein typischer Workflow, der den CodeQL-Runner zum Analysieren einer Codebasis verwendet, umfasst die folgenden Schritte.

  • codeql-runner-<platform> init: Mit diesem Befehl beginnst du mit dem Erstellen von CodeQL-Datenbanken und lesen die Konfiguration.
  • Für kompilierte Sprachen: Festlegen von Umgebungsvariablen, die von Schritt init erstellt werden.
  • Für kompilierte Sprachen: Führe Autobuild- oder manuelle Buildschritte aus.
  • codeql-runner-<platform> analyze: Mit diesem Befehl schließt du das Erstellen von CodeQL-Datenbanken ab, führst Abfragen aus, um jede CodeQL zu analysieren, die Ergebnisse in einer SARIF-Datei zusammenzufassen und die Ergebnisse in GitHub hochzuladen.

Ein typischer Workflow, der die CodeQL CLI verwendet, um eine Codebase zu analysieren, weist die folgenden Schritte auf.

  • codeql database create: Mit diesem Befehl erstellst du CodeQL-Datenbanken.
    • Für kompilierte Sprachen: Optional stellst du einen Buildbefehl bereit.
  • codeql database analyze: Mit diesem Befehl führst du Abfragen aus, um jede CodeQL-Datenbank zu analysieren und die Ergebnisse in einer SARIF-Datei zusammenzufassen. Dieser Befehl muss für jede Sprache oder Datenbank einmal ausgeführt werden.
  • codeql github upload-results: Mit diesem Befehl lädst du resultierenden SARIF-Dateien in GitHub hoch, damit sie als Codescanwarnungen angezeigt zu werden. Dieser Befehl muss für jede Sprache oder SARIF-Datei einmal ausgeführt werden.

Der CodeQL-Runner unterstützt standardmäßig das Multithreading. Die CodeQL CLI verwendet standardmäßig nur einen einzelnen Thread, ermöglicht ihnen jedoch die Angabe der Anzahl von Threads, die du verwenden möchtest. Wenn du das Verhalten des CodeQL-Runner replizieren möchtest, um bei Verwendung der CodeQL CLI alle für den Computer verfügbaren Threads zu verwenden, kannst Du --threads 0 an codeql database analyze übergeben.

Weitere Informationen findest du unter Konfigurieren der CodeQL-CLI in deinem CI-System.

Beispiele für allgemeine Verwendungen für die CodeQL CLI

Über die Beispiele

In diesen Beispielen wird davon ausgegangen, dass der Quellcode auf das aktuelle Arbeitsverzeichnis ausgecheckt wurde. Wenn du ein anderes Verzeichnis verwendest, ändere das Argument --source-root und die Buildschritte entsprechend.

In diesen Beispielen wird auch davon ausgegangen, dass die CodeQL CLI im aktuellen PFAD platziert werden.

In diesen Beispielen wird ein GitHub mit geeigneten Bereichen in der Umgebungsvariable $TOKEN gespeichert und über stdin an die Beispielbefehle übergeben oder in der Umgebungsvariable $GITHUB_TOKEN gespeichert.

Der Ref-Name und der Commit-SHA, die in diesen Beispielen ausgecheckt und analysiert werden, sind während des Workflows bekannt. Verwende für einen Branch refs/heads/BRANCH-NAME als Referenz. Für den Head-Commit einer Pull Request verwende refs/pull/NUMBER/head. Verwende refs/pull/NUMBER/merge für einen GitHub-generierten Merge-Commit einer Pull Request. Die folgenden Beispiele verwenden alle refs/heads/main. Wenn du einen anderen Branchnamen verwendest, musst du den Beispielcode ändern.

Einzelne nicht kompilierte Sprache (JavaScript)

Runner:

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

Über die CLI:

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

Einzelne nicht kompilierte Sprache (JavaScript) mit einer anderen Abfragensammlung (Sicherheit und Qualität)

Ein ähnlicher Ansatz kann für kompilierte Sprachen oder mehrere Sprachen verwendet werden.

Runner:

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

Über die CLI:

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

Einzelne nicht kompilierte Sprache (JavaScript) mit einer benutzerdefinierten Konfigurationsdatei

Ein ähnlicher Ansatz kann für kompilierte Sprachen oder mehrere Sprachen verwendet werden.

Runner:

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

Über die CLI:

# 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

Einzelne kompilierte Sprache mit von Autobuild (Java)

Runner:

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

Über die CLI:

# 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

Einzelne kompilierte Sprache mit einem benutzerdefinierten Buildbefehl (Java)

Runner:

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

Über die CLI:

# 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

Einzelne kompilierte Sprache mit indirekter Buildablaufverfolgung (C# auf Windows innerhalb Azure DevOps)

Die indirekte Buildablaufverfolgung für eine kompilierte Sprache ermöglicht es der CodeQL, alle Buildschritte zwischen den Schritten init und analyze zu erkennen, wenn der Code nicht mithilfe des Autobuilders oder einer expliziten Buildbefehlzeile erstellt werden kann. Dies ist nützlich, wenn du vordefinierte Buildschritte aus deinem CI-System verwendest, z. B. die Aufgaben VSBuild und MSBuild in Azure DevOps.

Runner:

- 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)'

Über die CLI:

# 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'

Mehrere Sprachen mit Autobuild (C++, Python)

Dieses Beispiel ist mit dem CodeQL-Runner streng genommen nicht durchführbar. Nur eine Sprache (die kompilierte Sprache mit den meisten Dateien) wird analysiert.

Runner:

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

Über die CLI:

# 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

Mehrere Sprachen mit einem benutzerdefinierten Buildbefehl (C++, Python)

Runner:

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

Über die CLI:

# 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