Freigeben über

Verwenden benutzerdefinierter Abfragen mit CodeQL

  • Artikel

Wenn in Ihrem Pipelinesetup keine benutzerdefinierte Konfigurationsdatei angegeben ist, führt CodeQL zur Analyse Ihres Codes standardmäßig das Abfragepaket security-extended aus. Sie können benutzerdefinierte CodeQL-Abfragen verwenden, um eigene Abfragen zur Suche nach bestimmten Sicherheitsrisiken und Fehlern zu schreiben. Sie müssen auch eine benutzerdefinierte Konfigurationsdatei erstellen, um die CodeQL-Standardanalyse zu ändern.

Informationen zur Suche nach vorhandenen benutzerdefinierten Abfragen oder zum Schreiben Ihrer eigenen benutzerdefinierten Abfragen finden Sie unter Eigene CodeQL-Abfrage schreiben.

Analyse mit benutzerdefinierten Abfragen

Am schnellsten können Sie mit einer benutzerdefinierten Abfrage beginnen, indem Sie eine Abfrage schreiben und diese in Ihrem lokalen Azure DevOps-Repository speichern. Sie können eine benutzerdefinierten Abfrage entsprechend Ihrer Anforderung anpassen, sie muss jedoch mindestens eine Regel-ID beinhalten. Weitere Informationen zum Schreiben Ihrer eigenen CodeQL-Abfrage finden Sie unter CodeQL-Abfragen schreiben. Sie können auch mehrere Abfragen in einer Abfragesammlung bündeln oder von anderen Personen veröffentlichte Pakete verwenden. Weitere Informationen finden Sie unter Veröffentlichen und Verwenden von CodeQL-Paketen.

Verwenden einer benutzerdefinierten Konfigurationsdatei

Mithilfe einer benutzerdefinierten Konfigurationsdatei können Sie bestimmen, welche Abfragen während der CodeQL-Analyse ausgeführt werden sollen. Sie können festlegen, welche weiteren Abfragen oder Abfragepakete ausgeführt werden sollen, und die standardmäßigen CodeQL-Abfragen ändern oder deaktivieren.

Um eine bestimmte Abfrage einzuschließen, geben Sie für die Abfrage einen Namen sowie einen Pfad an, der zu dem Ort führt, an dem die Abfragedatei (.ql) in Ihrem Repository gespeichert ist.

Um ein bestimmtes Paket einzuschließen, geben Sie den Namen des Pakets an. Sie können eine beliebige Anzahl von CodeQL-Abfragepaketen angeben, die in Ihrer Konfigurationsdatei ausgeführt werden sollen.

Im nächsten Schritt wird eine qlpack.yml Datei erstellt. Diese Datei deklariert das CodeQL-Paket und Informationen darüber. Alle *.ql Dateien im selben Verzeichnis (oder Unterverzeichnis) als qlpack.yml gelten als Teil des Pakets.

Tipp

Der packs Filter aus der Konfigurationsdatei unterstützt das Herunterladen von Paketen aus Repositorys, die in GitHub gehostet werden, der queries-Filter macht dies nicht. Wenn das Paket in GitHub privat ist, müssen Sie über die Aufgabe AdvancedSecurity-Codeql-Init@1 ein GitHub-Zugriffstoken als Umgebungsvariable und einen Variablennamen als GITHUB_TOKEN bereitstellen und den Gültigkeitsbereich des Tokens auf read:packages festlegen.

Hier sehen Sie eine Beispielkonfigurationsdatei:

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

Tipp

Konfigurationsdateispezifikationen ignorieren Konfigurationen auf Pipelineebene für die Aufgabe AdvancedSecurity-Codeql-Init@1 und haben diesen gegenüber Vorrang. includepaths / ignorepaths werden ignoriert, oder, wenn paths/paths-ignore vorhanden sind, werden sie mit Werten aus paths/paths-ignore überschrieben. querysuite wird mit Werten aus queries oder mit packs aus der Konfigurationsdatei überschrieben.

Wenn Sie eine benutzerdefinierte Abfrage verwenden, sehen Sie hier ein Beispiel qlpack.yml im Verzeichnis Ihrer benutzerdefinierten Abfragen:

version: 1.0.1
dependencies:
  codeql/javascript-all: "*"
  codeql/javascript-queries: "*"

Die dependencies Variable enthält alle Abhängigkeiten dieses Pakets und deren kompatible Versionsbereiche. Jede Abhängigkeit wird als Teil eines scope/name CodeQL-Bibliothekspakets verwiesen. Beim Definieren dependencieshängt Ihr qlpack.yml von genau einem der wichtigsten Sprachpakete (z. B. JavaScript, C#, Ruby usw.) ab, die die Sprache bestimmt, die Ihre Abfrage analysieren kann.

Weitere spezifische Empfehlungen und Konfigurationsoptionen für Ihre Konfigurationsdatei finden Sie unter Anpassen der erweiterten Einstellungen für das Scannen von Codes oder qlpack.ymlunter CodeQL-Paketstruktur.

Sobald Sie über Ihre Konfigurationsdatei verfügen, müssen Sie Ihre Pipeline anpassen, indem Sie eine CodeQL-Analyse ausführen, um Ihre neue Datei verwenden zu können. Hier ist eine Beispielpipeline, die auf eine Konfigurationsdatei zeigt:

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis