Menggunakan kueri kustom dengan CodeQL

Secara default, jika Anda tidak memiliki file konfigurasi kustom yang ditentukan dalam penyiapan alur Anda, CodeQL menjalankan security-extended paket kueri untuk menganalisis kode Anda. Anda dapat menggunakan kueri CodeQL kustom untuk menulis kueri Anda sendiri untuk menemukan kerentanan dan kesalahan tertentu. Anda juga perlu membuat file konfigurasi kustom untuk memodifikasi analisis default CodeQL.

Untuk menemukan kueri kustom yang sudah ada atau untuk menyumbangkan kueri kustom Anda sendiri, lihat Berkontribusi ke CodeQL.

Analisis dengan kueri kustom

Cara tercepat untuk memulai dengan kueri kustom adalah dengan menulis kueri dan menyimpannya di repositori Azure DevOps lokal Anda. Anda bisa mengkustomisasi detail kueri kustom sesuai dengan kebutuhan Anda, tetapi harus memiliki setidaknya ID aturan. Untuk informasi selengkapnya tentang cara menulis kueri CodeQL Anda sendiri, lihat Menulis kueri CodeQL. Anda juga dapat menggabungkan beberapa kueri bersama-sama ke dalam rangkaian kueri, atau menggunakan paket yang diterbitkan oleh orang lain. Untuk informasi selengkapnya, lihat Menerbitkan dan menggunakan paket CodeQL.

Menggunakan file konfigurasi khusus

File konfigurasi kustom adalah cara untuk mengelola kueri apa yang dijalankan selama analisis CodeQL terhadap kode Anda. Anda dapat menentukan lebih banyak kueri atau paket kueri yang akan dijalankan, dan mengubah atau menonaktifkan kueri CodeQL default.

Untuk menyertakan kueri tertentu yang ingin Anda sertakan, tentukan kueri dengan nama dan jalur ke lokasi file kueri (.ql) di repositori Anda.

Untuk menyertakan paket tertentu yang ingin Anda sertakan, tentukan nama paket. Anda dapat menentukan sejumlah paket kueri CodeQL untuk dijalankan dalam file konfigurasi Anda.

Langkah selanjutnya adalah membuat qlpack.yml file. File ini mendeklarasikan paket CodeQL dan informasi tentang hal itu. File apa pun *.ql dalam direktori yang sama (atau sub-direktori) sebagai qlpack.yml dianggap sebagai bagian dari paket.

Tip

Filter packs dari file konfigurasi mendukung pengunduhan paket dari repositori yang dihosting di GitHub, meskipun filter queries tidak. Jika paket bersifat privat di GitHub, maka Anda perlu memberikan token akses GitHub melalui AdvancedSecurity-Codeql-Init@1 tugas sebagai variabel lingkungan dan nama variabel sebagai GITHUB_TOKEN, dengan cakupan token menjadi read:packages.

Berikut adalah contoh file konfigurasi:

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

Tip

Spesifikasi file konfigurasi mengabaikan dan lebih diutamakan daripada konfigurasi tingkat alur untuk tugas tersebut AdvancedSecurity-Codeql-Init@1 . includepaths / ignorepaths akan diabaikan atau, jika paths/paths-ignore ada, ditimpa dengan nilai dari paths/paths-ignore. querysuite akan ditimpa dengan nilai yang ditentukan dalam queries atau packs dalam file konfigurasi.

Jika Anda menggunakan kueri kustom apa pun, berikut adalah contoh qlpack.yml yang ditempatkan di direktori kueri kustom Anda:

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

Variabel dependencies berisi semua dependensi paket ini dan rentang versi yang kompatibel. Setiap dependensi dirujuk sebagai scope/name paket pustaka CodeQL. Saat menentukan dependencies, Anda qlpack.yml bergantung pada salah satu paket bahasa inti (misalnya, JavaScript, C#, Ruby, dll.), yang menentukan bahasa yang dapat dianalisis kueri Anda.

Untuk saran dan opsi konfigurasi yang lebih spesifik dengan file konfigurasi Anda, lihat Menyesuaikan penyiapan tingkat lanjut Anda untuk pemindaian kode atau untuk qlpack.yml penyiapan, lihat Struktur paket CodeQL.

Setelah memiliki file konfigurasi, Anda kemudian perlu menyesuaikan alur yang menjalankan analisis CodeQL untuk menggunakan file baru Anda. Berikut adalah contoh alur yang menunjuk ke file konfigurasi:

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