Configuring CodeQL runner in your CI system

CI システムにおける CodeQL code scanning の設定について

code scanning をお使いの CI システムに統合するには、CodeQLランナー を使用できます。 詳しい情報については、「CodeQLランナー を CI システムで実行する」を参照してください。

一般的に、CodeQLランナー は次のように呼び出します。

$ /path/to-runner/codeql-runner-OS  

/path/to-runner/ は、CodeQLランナー を CI のどこにダウンロードしたかによって異なります。 codeql-runner-OS は、お使いのオペレーティングシステムによって異なります。 CodeQLランナー には 3 つのバージョンがあり、codeql-runner-linux、codeql-runner-macos、codeql-runner-win がそれぞれ Linux、macOS、Windows のシステムに対応しています。

CodeQLランナー がコードをスキャンする方法をカスタマイズするには、--languages や --queries などのフラグを用いるか、別の設定ファイルでカスタム設定を指定します。

プルリクエストをスキャンする

プルリクエストが作成されるたびにコードをスキャンすることで、開発者がコードに新しい脆弱性やエラーを持ち込むことを防げます。

プルリクエストをスキャンするには、 analyze コマンドを実行し、 --ref フラグを使用してプルリクエストを指定します。 リファレンスは refs/pull/<PR-number>/head または refs/pull/<PR-number>/merge で、プルリクエストブランチの HEAD コミットまたはベースブランチでマージコミットをチェックアウトしているかにより異なります。

$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/merge

自動言語検出をオーバーライドする

CodeQLランナー は、サポートされている言語で記述されたコードを自動的に検出してスキャンします。

• C/C++
• C#
• Go
• Java
• JavaScript/TypeScript
• Python

リポジトリがサポートされている言語を複数含む場合、分析したい言語を選択できます。 言語が分析されないようにする理由はいくつかあります。 たとえば、プロジェクトには、コードの本文とは異なる言語の依存関係があり、それらの依存関係のアラートを表示する必要がない場合があります。

自動言語検出をオーバーライドするには、init コマンドに --languages フラグを付け、その後に言語のキーワードリストをカンマ区切りで追加して、実行します。 The keywords for the supported languages are cpp、csharp、go、java、javascript、python.

$ /path/to-runner/codeql-runner-linux init --languages cpp,java

追加のクエリを実行する

コードをスキャンするためにCodeQLを使う場合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 詳しい情報については「code scanningについて」を参照してください。

CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。 実行したいクエリは、リポジトリ内のQLパックに属していなければなりません。 詳しい情報については、「QL パックについて」を参照してください。

クエリは、標準ライブラリ（クエリの import LANGUAGE ステートメントで参照されるライブラリ）、またはクエリと同じ QL パック内のライブラリにのみ依存している必要があります。 標準ライブラリは github/codeql リポジトリにあります。 詳しい情報については「CodeQLクエリについて」を参照してください。

単一の .ql ファイル、複数の .ql ファイルを含むディレクトリ、.qls クエリスイート定義ファイル、または任意の組み合わせを指定できます。 クエリスイートの定義に関する詳しい情報については「CodeQLクエリスイートの作成」を参照してください。

github/codeql/cpp/ql/src@mainというように、github/codeqlリポジトリから直接クエリスイートを参照することはおすすめしません。 そういったクエリは、他のクエリで使われるのと同じCodeQLのバージョンでコンパイルされているとは限らないので、分析の際にエラーが生じるかもしれません。

以下のクエリスイートはCodeQL code scanningに組み込まれており、利用可能です。

クエリスイート	説明
security-extended	デフォルトのクエリよりも重要度と精度が低いクエリ
security-and-quality	security-extended からのクエリ、および保守性と信頼性に関するクエリ

クエリスイートを指定すると、CodeQLの分析エンジンは、デフォルトのクエリセットに加えてスイート内に含まれるクエリを実行します。

1 つ以上ののクエリを追加するには、init コマンドの --queries フラグに、カンマで区切ったパスのリストを渡します。 設定ファイルに、追加のクエリを指定することもできます。

カスタム設定にも設定ファイルを使用し、--queries フラグで追加のクエリも指定している場合、CodeQLランナー は、構成ファイルで指定されたものではなく、 --queries フラグで指定された追加クエリを使用します。 フラグで指定された追加クエリと、設定ファイルにある追加クエリを組み合わせて使用する場合、渡す値の前に --queries と + の記号をプレフィクスとして付けてください。 設定ファイルの例については、「Example configuration files」を参照してください。

次の例では、CodeQLランナー が追加のクエリを、参照されている設定ファイルの中で指定されたあらゆるクエリと共に使用するよう、+ の記号を用いています。

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml 
    --queries +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

サードパーティのコードスキャンツールを使用する

CodeQLランナー コマンドに追加情報を渡すかわりに、別の設定ファイルでカスタム設定を指定できます。

設定ファイルの形式は YAML ファイルです。 YAML ファイルは、以下の例で示すように、GitHub Actions のワークフロー構文と似た構文を使用します。 詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

init コマンドの --config-file フラグを使用して、設定ファイルを指定します。 --config-file の値は、使用する設定ファイルへのパスです。 この例では、設定ファイル .github/codeql/codeql-config.yml を読み込みます。

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml

設定ファイルは、分析しようとしているリポジトリ内、あるいは外部のリポジトリに配置できます。 外部リポジトリを利用すると、複数のリポジトリに対する設定オプションを一カ所で指定できます。 外部リポジトリにある設定ファイルを参照する際には、OWNER/REPOSITORY/FILENAME@BRANCHという構文が利用できます。 たとえばmonacorp/shared/codeql-config.yml@mainといったようにします。

設定ファイルの例

この設定ファイルは、コードのスキャン時に CodeQL によって実行されるクエリのリストに security-and-quality クエリスイートを追加します。 使用可能なクエリスイートの詳細については、「追加のクエリを実行する」を参照してください。

name: "My CodeQL config"

queries:
  - uses: security-and-quality

以下の設定ファイルはデフォルトのクエリを無効化し、その代わりに実行するカスタムクエリのセットを指定します。 また、CodeQLがsrc/node_modulesディレクトリと.test.jsで名前が終わるファイルを除く、srcディレクトリ（ルートに対する相対）内のファイルをスキャンするようにも設定します。 したがって、 src/node_modules内のファイル や、.test.jsで名前が終わるファイルは分析から除外されます。

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src 
paths-ignore: 
  - src/node_modules
  - '**/*.test.js'

コンパイルされた言語の code scanning を設定する

コンパイル言語の C/C++、C#、および Java では、CodeQL は解析前にコードをビルドします。 CodeQLは、プロジェクトをセットアップするためにGoのプロジェクトのビルドも実行します。 ただし、他のコンパイル言語とは対照的に、リポジトリ内のGoのファイルはビルドされるものだけでなく、すべてが展開されます。 ビルドが処理しないGoのファイルの展開をスキップするために、カスタムのビルドコマンドを使うこともできます。

多くの一般的なビルドシステムに対して、CodeQLランナー はコードを自動的にビルドできます。 コードの自動的なビルドを試行するには、init と analyze のステップの間で autobuild を実行します。 リポジトリに特定のバージョンのビルドツールが必要な場合は、まずそのビルドツールを手動でインストールする必要があることにご注意ください。

autobuild プロセスは、リポジトリに対して 1 つ のコンパイル型言語のみをビルドするよう試行します。 解析のために自動的に選択される言語は、使用されているファイル数が最も多い言語です。 言語を明示的に選択する場合は、autobuild コマンドの --language フラグを使用します。

$ /path/to-runner/codeql-runner-linux autobuild --language csharp

autobuild コマンドがコードをビルドできない場合、init とanalyze のステップの間にビルドのステップを手動で実行できます。 詳しい情報については、「CodeQLランナー を CI システムで実行する」を参照してください。

code scanning 用の設定ファイルを作成できます。

デフォルトでは、CodeQLランナー は analyze コマンドを実行した際の code scanning による結果をアップロードします。 また、upload コマンドを使用して、SARIF ファイルを別にアップロードすることもできます。

データをアップロードすると、GitHub はリポジトリにアラートを表示します。

• --ref refs/pull/42/merge や --ref refs/pull/42/head などのようにプルリクエストにアップロードした場合、結果はプルリクエストのチェックでアラートとして表示されます。 詳しい情報については、「プルリクエストでコードスキャンアラートをトリアージする」を参照してください。
• --ref refs/heads/my-branch といったようにブランチにアップロードした場合、結果はリポジトリの [Security] タブに表示されます。 詳しい情報については、「リポジトリの コードスキャンアラートを管理する」を参照してください。

CodeQLランナー コマンドのリファレンス

CodeQLランナー は、次のコマンドおよびフラグをサポートしています。

init

CodeQLランナー を初期化し、解析する各言語用の CodeQL データベースを作成します。

フラグ	必須	入力値
--repository	✓	初期化するリポジトリの名前。
--github-url	✓	リポジトリがホストされる GitHub のインスタンス。
--github-auth-stdin	✓	Read the GitHub Apps token or personal access token from standard input.

| --languages | | 解析対象言語のカンマ区切りリスト。 デフォルトでは、CodeQLランナー はリポジトリにあるサポートされている言語をすべて検出し、解析します。 | | --queries | | デフォルトのセキュリティクエリに加えて実行する、追加クエリのカンマ区切りリスト。 This overrides the queries setting in the custom configuration file. | | --config-file | | カスタム設定ファイルのパス。 | | --codeql-path | | 使用する CodeQL CLI 実行ファイルのコピーのパス。 デフォルトでは、CodeQLランナー はコピーをダウンロードします。 | | --temp-dir | | 一時ファイルが保存されるディレクトリ。 デフォルトは ./codeql-runner です。 | | --tools-dir | | 実行間で CodeQL ツールやその他のファイルが保存されるディレクトリ。 デフォルトはホームディレクトリのサブディレクトリです。 | | --checkout-path | | リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。 | | --debug | | なし. より詳細な出力を表示します。 | | --trace-process-name | | Advanced, Windows only. Name of the process where a Windows tracer of this process is injected. | | --trace-process-level | | Advanced, Windows only. Number of levels up of the parent process where a Windows tracer of this process is injected. | | -h, --help | | なし. コマンドのヘルプを表示します。 |

autobuild

コンパイル型言語である C/C++、C#、および Java のコードのビルドを試行します。 これらの言語では、CodeQL は解析前にコードをビルドします。 autobuild を、init と analyze のステップの間に実行します。

フラグ	必須	入力値
--language		ビルドする言語。 デフォルトでは、CodeQLランナー はファイル数が最も多いコンパイル型言語をビルドします。
--temp-dir		一時ファイルが保存されるディレクトリ。 デフォルトは ./codeql-runner です。
--debug		なし. より詳細な出力を表示します。
-h, --help		なし. コマンドのヘルプを表示します。

analyze

CodeQL データベースにあるコードを解析し、結果を GitHub にアップロードします。

フラグ	必須	入力値
--repository	✓	解析するリポジトリの名前。
--commit	✓	解析するコミットの SHA。 Git および Azure DevOps では、git rev-parse HEAD の値に相当します。 Jenkins では、$GIT_COMMIT に相当します。
--ref	✓	解析するレファレンスの名前 (例: refs/heads/main、refs/pull/42/merge)。 Git や Jenkins では、git symbolic-ref HEAD の値に相当します。 Azure DevOps では、$(Build.SourceBranch) に相当します。
--github-url	✓	リポジトリがホストされる GitHub のインスタンス。
--github-auth-stdin	✓	Read the GitHub Apps token or personal access token from standard input.

| --checkout-path | | リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。 | | --no-upload | | なし. CodeQLランナー が結果を GitHub にアップロードすることを停止します。 | | --output-dir | | 出力される SARIF ファイルが保存されるディレクトリ。 デフォルトは一時ファイルのディレクトリです。 | | --ram | | クエリの実行時に使用するメモリの量。 デフォルトでは、使用できるすべてのメモリを使用します。 | | --no-add-snippets | | なし. SARIF 出力からコードスニペットを除外します。 | | --category | | Category to include in the SARIF results file for this analysis. A category can be used to distinguish multiple analyses for the same tool and commit, but performed on different languages or different parts of the code. This value will appear in the <run>.automationDetails.id property in SARIF v2.1.0.

| --threads | | クエリの実行時に使用するスレッドの数。 デフォルトでは、使用できるすべてのコアを使用します。 | | --temp-dir | | 一時ファイルが保存されるディレクトリ。 デフォルトは ./codeql-runner です。 | | --debug | | なし. より詳細な出力を表示します。 | | -h, --help | | なし. コマンドのヘルプを表示します。 |

アップロード

SARIF ファイルを GitHub にアップロードします。

注釈: CodeQL ランナーでコードを解析する場合、analyze コマンドはデフォルトで SARIF の結果をアップロードします。 upload コマンドを使用して、他のツールで生成された SARIF の結果をアップロードできます。

フラグ	必須	入力値
--sarif-file	✓	アップロードする SARIF ファイル、または複数の SARIF ファイルを含むディレクトリ。
--repository	✓	解析したリポジトリの名前。
--commit	✓	解析したコミットの SHA。 Git および Azure DevOps では、git rev-parse HEAD の値に相当します。 Jenkins では、$GIT_COMMIT に相当します。
--ref	✓	解析したレファレンスの名前 (例: refs/heads/main、refs/pull/42/merge)。 Git や Jenkins では、git symbolic-ref HEAD の値に相当します。 Azure DevOps では、$(Build.SourceBranch) に相当します。
--github-url	✓	リポジトリがホストされる GitHub のインスタンス。
--github-auth-stdin	✓	Read the GitHub Apps token or personal access token from standard input.

| --checkout-path | | リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。 | | --debug | | なし. より詳細な出力を表示します。 | | -h, --help | | なし. コマンドのヘルプを表示します。 |