ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。
GitHub AEは、現在限定リリース中です。詳細については営業チームにお問い合わせください。

Configuring CodeQL runner in your CI system

CodeQLランナー がプロジェクトのコードをスキャンして、その結果を GitHub にアップロードする方法を設定できます。

Code scanningは、ベータリリースの間は無料のGitHub Advanced Securityの一部として利用できます。 詳しい情報については、「GitHub Advanced Security について」を参照してください。

ノート: Code scanningは現在ベータで、変更されることがあります。

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-linuxcodeql-runner-macoscodeql-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

注釈: コードをサードパーティーのツールで解析し、その結果をプルリクエストのチェックで表示したい場合は、upload コマンドを実行し、--ref フラグでブランチではなくプルリクエストを指定する必要があります。 リファレンスは refs/pull/<PR-number>/head または refs/pull/<PR-number>/merge です。

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

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

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

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

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

$ /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クエリスイートの作成」を参照してください。

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

クエリスイート説明
security-extendedデフォルトのクエリよりも重要度と精度が低いクエリ
security-and-qualitysecurity-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ランナー はコードを自動的にビルドできます。 コードの自動的なビルドを試行するには、initanalyze のステップの間で autobuild を実行します。 リポジトリに特定のバージョンのビルドツールが必要な場合は、まずそのビルドツールを手動でインストールする必要があることにご注意ください。

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

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

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

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

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

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

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

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

init

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

フラグ必須入力値
--repository初期化するリポジトリの名前。
--github-urlリポジトリがホストされる GitHub のインスタンス。
--github-auth-stdinRead 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 を、initanalyze のステップの間に実行します。

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

analyze

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

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

| --checkout-path | | リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。 | | --no-upload | | なし. CodeQLランナー が結果を GitHub AE にアップロードすることを停止します。 | | --output-dir | | 出力される SARIF ファイルが保存されるディレクトリ。 デフォルトは一時ファイルのディレクトリです。 | | --ram | | クエリの実行時に使用するメモリの量。 デフォルトでは、使用できるすべてのメモリを使用します。 | | --no-add-snippets | | なし. SARIF 出力からコードスニペットを除外します。 | | --threads | | クエリの実行時に使用するスレッドの数。 デフォルトでは、使用できるすべてのコアを使用します。 | | --temp-dir | | 一時ファイルが保存されるディレクトリ。 デフォルトは ./codeql-runner です。 | | --debug | | なし. より詳細な出力を表示します。 | | -h, --help | | なし. コマンドのヘルプを表示します。 |

アップロード

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

注釈: 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/mainrefs/pull/42/merge)。 Git や Jenkins では、git symbolic-ref HEAD の値に相当します。 Azure DevOps では、$(Build.SourceBranch) に相当します。
--github-urlリポジトリがホストされる GitHub のインスタンス。
--github-auth-stdinRead the GitHub Apps token or personal access token from standard input.

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

このドキュメントは役立ちましたか?プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?

GitHubコミュニティで質問するサポートへの連絡