CIシステ� でのCodeQLランナーの設定

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

code scanning をお使いの CI システ� に統合するために、CodeQL runnerを使用できます。 詳しくは、「CI システ� での CodeQL runnerの実行」を参照してく� さい。

一般的に、CodeQL runnerは次のように呼び出します。

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

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

CodeQL runnerでコードをスキャンする方法をカスタマイズするには、フラグ (--languages、--queries など) を使用するか、別の構成ファイルでカスタ� 設定を指定できます。

Pull Requestをスキャンする

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

pull request をスキャンするには、analyze コマンドを実行し、--ref フラグを使用して pull request を指定します。 参照は、refs/pull/<PR-number>/head または refs/pull/<PR-number>/merge であり、pull request ブランチの HEAD コミットをチェックアウトしたかどうか、ベース ブランチとのマージ コミットをチェックアウトしたかどうかによって異なります。

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

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

CodeQL runnerにより、サポートされている言語で記述されたコードが自動的に検出されてスキャンされます。

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

詳細については、CodeQL Web サイトのドキュメント「サポートされている言語とフレー� ワーク」を参照してく� さい。

サポートされている 1 つ以上の言語のコードがリポジトリに含まれている� �合は、分析する言語を選択できます。 言語が分析されないようにする理由は、いくつかあります。 たとえば、プロジェクトで、コードの本体に対する依存関係が別の言語の中にあり、それらの依存関係のアラートを表示したくない� �合が考えられます。

言語の自動検出をオーバーライドするには、--languages フラグを指定して init コマンドを実行し、続けて言語キーワードのコンマ区切りのリストを実行します。 サポートされている言語に対するキーワードはcpp、csharp、go、java、javascript、 と pythonです。

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

追� のクエリを実行する

コードをスキャンするためにCodeQLを使う� �合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに� えてもっと多くのクエリを実行するよう指定することもできます。

実行したいクエリが他にあれば、リポジトリ内の QL パックに属していなければなりません。 詳細については、「code scanning と CodeQL について」を参照してく� さい。

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

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

クエリ スイート	説明
security-extended	既定のスイートからのクエリ、および重要度と精度の低いクエリ
security-and-quality	security-extended からのクエリに� え、保守性および信� �性のクエリ。

クエリ スイートを指定すると、CodeQL の分析エンジンでは、既定の一連のクエリと、追� のクエリ スイートで定義されている追� クエリが実行されます。

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

また、カスタ� 設定にも構成ファイルを使用し、--queries フラグで追� のクエリも指定している� �合、CodeQL runnerでは、構成ファイルで指定されたものではなく、--queries フラグで指定された追� のクエリが使用されます。 フラグと構成ファイルで指定された追� クエリの組み合わせのセットを使用する� �合、--queries に渡される値の前に + 記号を付けますます。 詳細については、「カスタ� 構成ファイルの使用」を参照してく� さい。

次の例では、+ 記号があるため、CodeQL runnerで追� のクエリが、参照されている構成ファイルで指定されている任意のクエリと共に確実に使用されます。

$ /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 runner コマンドに追� 情� �を渡す代わりに、別の構成ファイルでカスタ� 設定を指定できます。

設定ファイルの形式は 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

構成ファイルは、分析するリポジトリ内、または外部リポジトリ内に� �納できます。 外部リポジトリを使用すると、1 つの� �所の複数のリポジトリに対して構成オプションを指定できます。 外部リポジトリにある構成ファイルを参照する� �合は、 OWNER/REPOSITORY/FILENAME@BRANCH 構文を使用できます。 たとえば、 octo-org/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 は、ビルドされたリポジトリ内のソース ファイルを分析します。 これらの言語の� �合は、autobuild を無効にし、その代わりにカスタ�  ビルド コマンドによってビルドされたファイルのみを分析するためにこれらのカスタ�  コマンドを使用できます。

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

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

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

autobuild コマンドでコードをビルドできない� �合は、init ステップと analyze ステップの間でビルド ステップをご自分で実行できます。 詳しくは、「CI システ� での CodeQL runnerの実行」を参照してく� さい。

code scanning データを GitHub にアップロードする

既定では、analyze コマンドを実行すると、CodeQL runnerにより結果が code scanning からアップロードされます。 また、upload コマンドを使用して、SARIF ファイルを個別にアップロードすることもできます。

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

• pull request (たとえば --ref refs/pull/42/merge と --ref refs/pull/42/head) にアップロードした� �合、結果は pull request チェックのアラートとして表示されます。 詳細については、「pull request での Code Scanning アラートのトリアージ」を参照してく� さい。
• ブランチ (たとえば --ref refs/heads/my-branch) にアップロードした� �合、結果はリポジトリの [セキュリティ] タブに表示されます。 詳細については、「リポジトリの Code Scanning アラートの管理」を参照してく� さい。

CodeQL runner コマンドのリファレンス

CodeQL runnerでは、次のコマンドとフラグがサポートされています。

init

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

フラグ	必� �	入力値
--repository	✓	初期化するリポジトリの名前。
--github-url	✓	リポジトリがホストされる GitHub のインスタンス。
--github-auth-stdin	✓	GitHub Apps トークンまたは personal access token を標準入力から読み取ります。
--languages		解析対象言語のカンマ区切りリスト。 既定では、CodeQL runnerにより、リポジトリにあるサポートされている言語がすべて検出されて分析されます。
--queries		デフォルトのセキュリティクエリに� えて実行する、追� クエリのカンマ区切りリスト。 これにより、カスタ� 構成ファイルの queries 設定がオーバーライドされます。
--config-file		カスタ� 設定ファイルのパス。
--codeql-path		使用する CodeQL CLI 実行ファイルのコピーのパス。 既定では、CodeQL runnerによってコピーがダウンロードされます。
--temp-dir		一時ファイルが保存されるディレクトリ。 既定値は、./codeql-runner です。
--tools-dir		実行間で CodeQL ツールやその他のファイルが保存されるディレクトリ。 デフォルトはホー� ディレクトリのサブディレクトリです。
--checkout-path		リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。
--debug		[なし] : より詳細な出力を表示します。
--trace-process-name		高度でWindowsのみ。 このプロセスのWindows tracerが注入されたプロセスの名前。
--trace-process-level		高度でWindowsのみ。 このプロセスのWindows tracerが注入された親プロセスまでのレベル数。
-h, --help		[なし] : コマンドのヘルプを表示します。

autobuild

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

フラグ	必� �	入力値
--language		ビルドする言語。 既定では、CodeQL runnerによって、ほとんどのファイルでコンパイル済み言語がビルドされます。
--temp-dir		一時ファイルが保存されるディレクトリ。 既定値は、./codeql-runner です。
--debug		[なし] : より詳細な出力を表示します。
-h, --help		[なし] : コマンドのヘルプを表示します。

analyze

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

フラグ	必� �	入力値
--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	✓	GitHub Apps トークンまたは personal access token を標準入力から読み取ります。
--checkout-path		リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。
--no-upload		[なし] : CodeQL runnerによって結果が GitHub Enterprise Server にアップロードされないようにします。
--output-dir		出力される SARIF ファイルが保存されるディレクトリ。 デフォルトは一時ファイルのディレクトリです。
--ram		クエリの実行時に使用するメモリの量。 デフォルトでは、使用できるすべてのメモリを使用します。
--no-add-snippets		[なし] : SARIF 出力からコードスニペットを除外します。
--category		この分析でSARIF結果ファイルに含めるカテゴリ。 カテゴリは、同じツールとコミットについて、た� し様々な言語やコードの様々な部分に対して行われる複数の分析を区別するために使うことができます。 この値は、SARIF v2.1.0 の <run>.automationDetails.id プロパティに表示されます。
--threads		クエリの実行時に使用するスレッドの数。 デフォルトでは、使用できるすべてのコアを使用します。
--temp-dir		一時ファイルが保存されるディレクトリ。 既定値は、./codeql-runner です。
--debug		[なし] : より詳細な出力を表示します。
-h, --help		[なし] : コマンドのヘルプを表示します。

upload

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

フラグ	必� �	入力値
--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	✓	GitHub Apps トークンまたは personal access token を標準入力から読み取ります。
--checkout-path		リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。
--debug		[なし] : より詳細な出力を表示します。
-h, --help		[なし] : コマンドのヘルプを表示します。