Menggunakan CodeQL CLI

8 menit

Selain antarmuka pengguna grafis pada GitHub.com, Anda juga dapat mengakses banyak fitur CodeQL utama yang sama melalui antarmuka baris perintah.

Unit ini akan mencakup penggunaan CodeQL CLI untuk membuat database, menganalisis database, dan mengunggah hasilnya ke GitHub.

Perintah CodeQL CLI

Setelah Anda membuat CodeQL CLI tersedia untuk server di sistem CI Anda dan memastikan bahwa mereka dapat mengautentikasi dengan GitHub, Anda siap untuk menghasilkan data.

Anda dapat menggunakan tiga perintah berbeda untuk menghasilkan hasil dan mengunggahnya ke GitHub:

database create untuk membuat database CodeQL untuk mewakili struktur hierarkis dari setiap bahasa pemrograman yang didukung di repositori.
database analyze untuk menjalankan kueri untuk menganalisis setiap database CodeQL dan meringkas hasilnya dalam file SARIF.
github upload-results untuk mengunggah file SARIF yang dihasilkan ke GitHub di mana hasilnya cocok dengan cabang atau permintaan pull dan ditampilkan sebagai pemberitahuan pemindaian kode.

Anda dapat menampilkan bantuan baris perintah untuk perintah apa pun menggunakan --help option.

Mengunggah data SARIF untuk ditampilkan sebagai hasil pemindaian kode di GitHub didukung untuk repositori milik organisasi dengan GitHub Advanced Security diaktifkan, dan repositori publik di GitHub.com.

Membuat database CodeQL untuk dianalisis

Ikuti langkah-langkah ini untuk membuat database CodeQL untuk dianalisis.

Lihat kode yang ingin Anda analisis:
- Untuk cabang, lihat kepala cabang yang ingin Anda analisis.
- Untuk permintaan pull, lihat penerapan kepala permintaan pull, atau lihat penerapan penggabungan yang dihasilkan GitHub dari permintaan pull.
Siapkan lingkungan untuk basis kode, pastikan dependensi apa pun tersedia.
Temukan perintah build, jika ada, untuk basis kode. Biasanya ini tersedia dalam file konfigurasi di sistem CI.
Jalankan codeql database create dari akar cek keluar repositori Anda dan buat basis kode:
- Untuk membuat satu database CodeQL untuk satu bahasa yang didukung, gunakan perintah berikut:
```
codeql database create <database> --command <build> --language=<language-identifier>
```
- Untuk membuat satu database CodeQL per bahasa untuk beberapa bahasa yang didukung, gunakan perintah berikut:
```
codeql database create <database> --command <build> \
  --db-cluster --language=<language-identifier>,<language-identifier>
```

Catatan

Jika Anda menggunakan build kontainer, Anda perlu menjalankan CodeQL CLI di dalam kontainer tempat tugas build Anda berlangsung.

Daftar lengkap parameter untuk database create perintah diperlihatkan dalam tabel berikut:

Opsi	Penggunaan yang Diperlukan
`<database>`	Tentukan nama dan lokasi direktori yang akan dibuat untuk database CodeQL. Perintah akan gagal jika Anda mencoba menimpa direktori yang ada. Jika Anda juga menentukan `--db-cluster`, ini adalah direktori induk, dan subdirektori dibuat untuk setiap bahasa yang dianalisis.
`--language`	Tentukan pengidentifikasi bahasa untuk membuat database untuk salah satu dari `cpp`, , `csharp`, `gojava`, `javascript`, `python`, , dan `ruby` (gunakan JavaScript untuk menganalisis kode TypeScript). Saat digunakan dengan `--db-cluster`, opsi menerima daftar yang dipisahkan koma, atau dapat ditentukan lebih dari sekali.
`--command`	Disarankan. Gunakan untuk menentukan perintah build atau skrip yang memanggil proses build untuk basis kode. Perintah dijalankan dari folder saat ini atau, tempat perintah ditentukan, dari `--source-root`. Tidak diperlukan untuk analisis Python dan JavaScript/TypeScript.
`--db-cluster`	Opsional. Gunakan dalam basis kode multi-bahasa untuk menghasilkan satu database untuk setiap bahasa yang ditentukan oleh `--language`.
`--no-run-unnecessary-builds`	Disarankan. Gunakan untuk menekan perintah build untuk bahasa di mana CodeQL CLI tidak perlu memantau build (misalnya, Python dan JavaScript/TypeScript).
`--source-root`	Opsional. Gunakan jika Anda menjalankan CLI di luar akar checkout repositori. Secara default, perintah pembuatan database mengasumsikan bahwa direktori saat ini adalah direktori akar untuk file sumber; gunakan opsi ini untuk menentukan lokasi yang berbeda.

Contoh bahasa tunggal

Contoh ini membuat database CodeQL untuk repositori yang diperiksa di /checkouts/example-repo. Ini menggunakan ekstraktor JavaScript untuk membuat representasi hierarki kode JavaScript dan TypeScript di repositori. Database yang dihasilkan disimpan di /codeql-dbs/example-repo.

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

> Initializing database at /codeql-dbs/example-repo.
> Running command [/codeql-home/codeql/javascript/tools/autobuild.cmd]
    in /checkouts/example-repo.
> [build-stdout] Single-threaded extraction.
> [build-stdout] Extracting
...
> Finalizing database at /codeql-dbs/example-repo.
> Successfully created database at /codeql-dbs/example-repo.

Contoh beberapa bahasa

Contoh ini membuat database CodeQL untuk repositori yang diperiksa di /checkouts/example-repo-multi. Aplikasi ini menggunakan:

--db-cluster untuk meminta analisis lebih dari satu bahasa.
--language untuk menentukan bahasa mana yang akan dibuat databasenya.
--command untuk memberi tahu alat perintah build untuk basis kode, di sini buat.
--no-run-unnecessary-builds untuk memberi tahu alat untuk mengabaikan perintah build untuk bahasa di mana itu tidak diperlukan (seperti Python).

Database yang dihasilkan disimpan di python dan cpp subdirektori dari /codeql-dbs/example-repo-multi.

$ codeql database create /codeql-dbs/example-repo-multi \
    --db-cluster --language python,cpp \
    --command make --no-run-unnecessary-builds \
    --source-root /checkouts/example-repo-multi
Initializing databases at /codeql-dbs/example-repo-multi.
Running build command: [make]
[build-stdout] Calling python3 /codeql-bundle/codeql/python/tools/get_venv_lib.py
[build-stdout] Calling python3 -S /codeql-bundle/codeql/python/tools/python_tracer.py -v -z all -c /codeql-dbs/example-repo-multi/python/working/trap_cache -p ERROR: 'pip' not installed.
[build-stdout] /usr/local/lib/python3.6/dist-packages -R /checkouts/example-repo-multi
[build-stdout] [INFO] Python version 3.6.9
[build-stdout] [INFO] Python extractor version 5.16
[build-stdout] [INFO] [2] Extracted file /checkouts/example-repo-multi/hello.py in 5ms
[build-stdout] [INFO] Processed 1 modules in 0.15s
[build-stdout] <output from calling 'make' to build the C/C++ code>
Finalizing databases at /codeql-dbs/example-repo-multi.
Successfully created databases at /codeql-dbs/example-repo-multi.
$

Menganalisis database CodeQL

Setelah membuat database CodeQL Anda, ikuti langkah-langkah berikut untuk menganalisisnya:

Secara opsional jalankan codeql pack download <packs> untuk mengunduh paket CodeQL (beta) apa pun yang ingin Anda jalankan selama analisis.
Jalankan codeql database analyze pada database, dan tentukan paket dan/atau kueri mana yang akan digunakan.

codeql database analyze <database> --format=<format> \
    --output=<output>  <packs,queries>

Catatan

Jika Anda menganalisis lebih dari satu database CodeQL untuk satu penerapan, Anda harus menentukan kategori SARIF untuk setiap set hasil yang dihasilkan perintah ini. Saat Anda mengunggah hasilnya ke GitHub, pemindaian kode menggunakan kategori ini untuk menyimpan hasil untuk setiap bahasa secara terpisah. Jika Anda lupa melakukan ini, setiap unggahan akan menimpa hasil sebelumnya.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <packs,queries>

Daftar lengkap parameter untuk database analyze perintah diperlihatkan dalam tabel berikut:

Opsi	Penggunaan yang Diperlukan
`<database>`	Tentukan jalur untuk direktori yang berisi database CodeQL untuk dianalisis.
`<packs,queries>`	Tentukan paket atau kueri CodeQL untuk dijalankan. Untuk menjalankan kueri standar yang digunakan untuk pemindaian kode, hilangkan parameter ini. Anda dapat menemukan rangkaian kueri lain yang disertakan dalam bundel CodeQL CLI di `/<extraction-root>/codeql/qlpacks/codeql-<language>/codeql-suites`. Untuk informasi tentang membuat rangkaian kueri Anda sendiri, lihat Membuat suite^{kueri CodeQL[5]} dalam dokumentasi untuk CodeQL CLI.
`--format`	Tentukan format untuk file hasil yang dihasilkan oleh perintah. Untuk diunggah ke GitHub, ini harus: `sarif-latest`.
`--output`	Tentukan tempat menyimpan file hasil SARIF.
`--sarif-category`	Opsional untuk analisis database tunggal. Diperlukan untuk menentukan bahasa saat Anda menganalisis beberapa database untuk satu penerapan dalam repositori. Tentukan kategori yang akan disertakan dalam file hasil SARIF untuk analisis ini. Kategori digunakan untuk membedakan beberapa analisis untuk alat dan penerapan yang sama, tetapi dilakukan pada bahasa yang berbeda atau bagian kode yang berbeda.
`--sarif-add-query-help`	Opsional. Gunakan jika Anda ingin menyertakan bantuan kueri yang dirender markdown yang tersedia untuk kueri kustom yang digunakan dalam analisis Anda. Bantuan kueri apa pun untuk kueri kustom yang disertakan dalam output SARIF akan ditampilkan dalam UI pemindaian kode jika kueri yang relevan menghasilkan pemberitahuan.
`<packs>`	Opsional. Gunakan jika Anda telah mengunduh paket kueri CodeQL dan ingin menjalankan kueri default atau suite kueri yang ditentukan dalam paket.
`--threads`	Opsional. Gunakan jika Anda ingin menggunakan lebih dari satu utas untuk menjalankan kueri. Nilai default adalah 1. Anda dapat menentukan lebih banyak utas untuk mempercepat eksekusi kueri. Untuk mengatur jumlah utas ke jumlah prosesor logis, tentukan 0.
`--verbose`	Opsional. Gunakan untuk mendapatkan informasi lebih rinci tentang proses analisis dan data diagnostik dari proses pembuatan database.

Contoh dasar

Contoh ini menganalisis database CodeQL yang disimpan di /codeql-dbs/example-repo dan menyimpan hasilnya sebagai file SARIF: /temp/example-repo-js.sarif. Ini menggunakan --sarif-category untuk menyertakan informasi tambahan dalam file SARIF yang mengidentifikasi hasilnya sebagai JavaScript. Ini penting ketika Anda memiliki lebih dari satu database CodeQL untuk menganalisis satu penerapan dalam repositori.

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

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/
    codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Unggah hasil ke GitHub

Unggahan SARIF mendukung maksimal 25.000 hasil per unggahan. Namun, hanya 5.000 hasil teratas yang ditampilkan, diprioritaskan oleh tingkat keparahan. Jika alat menghasilkan terlalu banyak hasil, Anda harus memperbarui konfigurasi untuk fokus pada hasil untuk aturan atau kueri yang paling penting.

Untuk setiap unggahan, unggahan SARIF mendukung ukuran maksimum 10 MB untuk file SARIF yang dikompresi gzip. Setiap unggahan yang melebihi batas ini akan ditolak. Jika file SARIF Anda terlalu besar karena berisi terlalu banyak hasil, Anda harus memperbarui konfigurasi untuk fokus pada hasil untuk aturan atau kueri yang paling penting. Untuk informasi selengkapnya tentang batasan dan memvalidasi file SARIF, lihat dokumentasi^[6].

Sebelum dapat mengunggah hasil ke GitHub, Anda harus menentukan cara terbaik untuk meneruskan Aplikasi GitHub atau token akses pribadi yang Anda buat sebelumnya ke CodeQL CLI. Kami menyarankan agar Anda meninjau panduan sistem CI Anda tentang penggunaan penyimpanan rahasia yang aman. CodeQL CLI mendukung:

Berinteraksi dengan penyimpanan rahasia menggunakan opsi --github-auth-stdin. Ini adalah cara yang disarankan untuk mengautentikasi.
Menyimpan rahasia dalam variabel GITHUB_TOKEN lingkungan dan menjalankan CLI tanpa menyertakan opsi --github-auth-stdin.
Teruskan opsi baris perintah --github-auth-stdin dan berikan token sementara melalui input standar. Ini direkomendasikan untuk tujuan pengujian.

Ketika Anda telah memutuskan metode yang paling aman dan dapat diandalkan untuk server CI Anda, jalankan codeql github upload-results pada setiap file hasil SARIF dan sertakan --github-auth-stdin kecuali token tersedia dalam variabel GITHUB_TOKENlingkungan .

# GitHub App or personal access token available from a secret store
<call-to-retrieve-secret> | codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file> --github-auth-stdin

# GitHub App or personal access token available in GITHUB_TOKEN
codeql github upload-results \
    --repository=<repository-name> \
    --ref=<ref> --commit=<commit> \
    --sarif=<file>

Daftar lengkap parameter untuk github upload-results perintah diperlihatkan dalam tabel sebagai berikut.

Opsi	Penggunaan yang Diperlukan
`--repository`	Tentukan PEMILIK/NAMA repositori yang akan diunggah datanya. Pemilik harus menjadi organisasi dalam perusahaan yang memiliki lisensi untuk GitHub Advanced Security, dan GitHub Advanced Security harus diaktifkan untuk repositori kecuali repositori bersifat publik.
`--ref`	Tentukan nama ref yang Anda cek keluar dan analisis sehingga hasilnya dapat dicocokkan dengan kode yang benar. Untuk cabang, gunakan `refs/heads/BRANCH-NAME`; untuk penerapan kepala permintaan pull, gunakan `refs/pulls/NUMBER/head`; atau untuk penerapan penggabungan yang dihasilkan GitHub dari permintaan pull, gunakan `refs/pulls/NUMBER/merge`.
`--commit`	Tentukan SHA lengkap dari penerapan yang Anda analisis.
`--sarif`	Tentukan file SARIF yang akan dimuat.
`--github-auth-stdin`	Opsional. Gunakan untuk meneruskan CLI GitHub App atau token akses pribadi yang dibuat untuk autentikasi dengan REST API GitHub melalui input standar. Ini tidak diperlukan jika perintah memiliki akses ke variabel lingkungan yang `GITHUB_TOKEN` diatur dengan token ini.

Saran dan Komentar

Apakah halaman ini membantu?