Używanie zapytań niestandardowych z językiem CodeQL

Domyślnie, jeśli nie masz niestandardowego pliku konfiguracji określonego w konfiguracji potoku, codeQL uruchamia security-extended pakiet zapytań w celu przeanalizowania kodu. Możesz użyć niestandardowych zapytań CodeQL do pisania własnych zapytań w celu znalezienia określonych luk w zabezpieczeniach i błędów. Należy również utworzyć niestandardowy plik konfiguracji, aby zmodyfikować domyślną analizę codeQL.

Aby znaleźć istniejące zapytania niestandardowe lub współtworzyć własne zapytanie niestandardowe, zobacz Współtworzenie koduQL.

Analiza za pomocą zapytań niestandardowych

Najszybszym sposobem rozpoczęcia pracy z zapytaniem niestandardowym jest napisanie zapytania i zapisanie go w lokalnym repozytorium usługi Azure DevOps. Możesz dostosować szczegóły zapytania niestandardowego zgodnie z potrzebami, ale musi mieć co najmniej identyfikator reguły. Aby uzyskać więcej informacji na temat pisania własnego zapytania CodeQL, zobacz Pisanie zapytań CodeQL. Można również połączyć wiele zapytań w zestaw zapytań lub korzystać z pakietów opublikowanych przez inne osoby. Aby uzyskać więcej informacji, zobacz Publikowanie i używanie pakietów CodeQL.

Używanie niestandardowego pliku konfiguracji

Niestandardowy plik konfiguracji to sposób zarządzania zapytaniami uruchamianymi podczas analizy kodu w języku CodeQL. Można określić więcej zapytań lub pakietów zapytań do uruchomienia, a następnie zmienić lub wyłączyć domyślne zapytania CodeQL.

Aby dołączyć określone zapytanie, które chcesz uwzględnić, określ zapytanie o nazwie i ścieżce do lokalizacji pliku zapytania (ql) w repozytorium.

Aby uwzględnić określony pakiet, który chcesz uwzględnić, określ nazwę pakietu. Można określić dowolną liczbę pakietów zapytań CodeQL do uruchomienia w pliku konfiguracji.

Następnym krokiem qlpack.yml jest utworzenie pliku. Ten plik deklaruje pakiet CodeQL i informacje o nim. Wszystkie *.ql pliki w tym samym katalogu (lub podkatalogu) jako qlpack.yml część pakietu są traktowane jako część pakietu.

Napiwek

Filtr packs z pliku konfiguracji obsługuje pobieranie pakietów z repozytoriów hostowanych w usłudze GitHub, chociaż filtr queries go nie obsługuje. Jeśli pakiet jest prywatny w usłudze GitHub, musisz podać token dostępu usługi GitHub za pośrednictwem AdvancedSecurity-Codeql-Init@1 zadania jako zmienną środowiskową i nazwę zmiennej jako GITHUB_TOKEN, z zakresem tokenu jest read:packages.

Oto przykładowy plik konfiguracji:

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

Napiwek

Specyfikacje pliku konfiguracji ignorują konfiguracje na poziomie potoku i mają pierwszeństwo przed konfiguracjami na poziomie potoku AdvancedSecurity-Codeql-Init@1 dla zadania. includepaths / ignorepathszostanie zignorowany lub, jeśli paths/paths-ignore są obecne, zastąpione wartościami z .paths/paths-ignore querysuite zostanie zastąpiony wartościami określonymi w queries pliku konfiguracji lub packs w pliku konfiguracji.

Jeśli używasz dowolnego zapytania niestandardowego, oto przykład qlpack.yml umieszczony w katalogu zapytań niestandardowych:

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

Zmienna dependencies zawiera wszystkie zależności tego pakietu i ich zgodne zakresy wersji. Każda zależność jest przywoływana jako scope/name pakiet biblioteki CodeQL. Podczas definiowania dependencieselementu qlpack.yml zależy od dokładnie jednego z podstawowych pakietów językowych (na przykład JavaScript, C#, Ruby itp.), który określa język, który może analizować zapytanie.

Aby uzyskać bardziej szczegółowe porady i opcje konfiguracji w pliku konfiguracji, zobacz Dostosowywanie zaawansowanej konfiguracji na potrzeby skanowania kodu lub qlpack.yml instalacji, zobacz Struktura pakietu CodeQL.

Po utworzeniu pliku konfiguracji należy dostosować potok z uruchomioną analizą CodeQL, aby korzystać z nowego pliku. Oto przykładowy potok wskazujący plik konfiguracji:

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