Note: The CodeQLランナー is being deprecated. Please use the CodeQL CLI version 2.6.2 or greater instead. GitHub Enterprise Server 3.3 will be the final release series that supports the CodeQLランナー. On GitHub Enterprise Cloud, the CodeQLランナー will be supported until March 2022. For more information, see the CodeQL runner deprecation.
ノート: Code scanningはGitHub Enterprise Server 2.22ではベータです。 Code Scanningの一般に利用なリリースについては、GitHub Enterprise Serverの最新リリースにアップグレードしてください。
ノート: この機能を使用するには、サイト管理者がGitHub Enterprise Serverのインスタンスのcode scanningを有効にする必要があります。 詳しい情報については「アプライアンスのためのcode scanningの設定」を参照してください。
CI システムにおける CodeQL code scanning の設定について
code scanning をお使いの CI システムに統合するには、CodeQLランナー を使用できます。 詳しい情報については、「CI システムで CodeQL code scanning を実行する」を参照してください。
一般的に、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
注釈: コードをサードパーティーのツールで解析し、その結果をプルリクエストのチェックで表示したい場合は、upload
コマンドを実行し、--ref
フラグでブランチではなくプルリクエストを指定する必要があります。 リファレンスは refs/pull/<PR-number>/head
または refs/pull/<PR-number>/merge
です。
自動言語検出をオーバーライドする
CodeQLランナー は、サポートされている言語で記述されたコードを自動的に検出してスキャンします。
- C/C++
- C#
- Go
- Java
- JavaScript/TypeScript
- Python
リポジトリがサポートされている言語を複数含む場合、分析したい言語を選択できます。 言語が分析されないようにする理由はいくつかあります。 たとえば、プロジェクトには、コードの本文とは異なる言語の依存関係があり、それらの依存関係のアラートを表示する必要がない場合があります。
自動言語検出をオーバーライドするには、init
コマンドに --languages
フラグを付け、その後に言語のキーワードリストをカンマ区切りで追加して、実行します。 サポートされている言語に対するキーワードはcpp
、csharp
、go
、java
、javascript
、python
です。
$ /path/to-runner/codeql-runner-linux init --languages cpp,java
追加のクエリを実行する
コードをスキャンするためにCodeQLを使う場合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。
Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About code scanning."
単一の .ql ファイル、複数の .ql ファイルを含むディレクトリ、.qls クエリスイート定義ファイル、または任意の組み合わせを指定できます。 クエリスイートの定義に関する詳しい情報については「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
$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml
設定ファイルは、分析しようとしているリポジトリ内、あるいは外部のリポジトリに配置できます。 外部リポジトリを利用すると、複数のリポジトリに対する設定オプションを一カ所で指定できます。 外部リポジトリにある設定ファイルを参照する際には、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は、プロジェクトをセットアップするためにGoのプロジェクトのビルドも実行します。 ただし、他のコンパイル言語とは対照的に、リポジトリ内のGoのファイルはビルドされるものだけでなく、すべてが展開されます。 ビルドが処理しないGoのファイルの展開をスキップするために、カスタムのビルドコマンドを使うこともできます。
多くの一般的なビルドシステムに対して、CodeQLランナー はコードを自動的にビルドできます。 コードの自動的なビルドを試行するには、init
と analyze
のステップの間で autobuild
を実行します。 リポジトリに特定のバージョンのビルドツールが必要な場合は、まずそのビルドツールを手動でインストールする必要があることにご注意ください。
autobuild
プロセスは、リポジトリに対して 1 つ のコンパイル型言語のみをビルドするよう試行します。 解析のために自動的に選択される言語は、使用されているファイル数が最も多い言語です。 言語を明示的に選択する場合は、autobuild
コマンドの --language
フラグを使用します。
$ /path/to-runner/codeql-runner-linux autobuild --language csharp
autobuild
コマンドがコードをビルドできない場合、init
とanalyze
のステップの間にビルドのステップを手動で実行できます。 詳しい情報については、「CI システムで CodeQL code scanning を実行する」を参照してください。
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 | ✓ | GitHub Apps トークンまたは個人アクセストークン。 |
--languages | 解析対象言語のカンマ区切りリスト。 デフォルトでは、CodeQLランナー はリポジトリにあるサポートされている言語をすべて検出し、解析します。 | |
--queries | デフォルトのセキュリティクエリに加えて実行する、追加クエリのカンマ区切りリスト。 | |
--config-file | カスタム設定ファイルのパス。 | |
--codeql-path | 使用する CodeQL CLI 実行ファイルのコピーのパス。 デフォルトでは、CodeQLランナー はコピーをダウンロードします。 | |
--temp-dir | 一時ファイルが保存されるディレクトリ。 デフォルトは ./codeql-runner です。 | |
--tools-dir | 実行間で CodeQL ツールやその他のファイルが保存されるディレクトリ。 デフォルトはホームディレクトリのサブディレクトリです。 | |
--checkout-path | リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。 | |
--debug | なし. より詳細な出力を表示します。 | |
-h , --help | なし. コマンドのヘルプを表示します。 |
autobuild
コンパイル型言語である C/C++、C#、および Java のコードのビルドを試行します。 これらの言語では、CodeQL は解析前にコードをビルドします。 autobuild
を、init
と analyze
のステップの間に実行します。
フラグ | 必須 | 入力値 |
---|---|---|
--language | ビルドする言語。 デフォルトでは、CodeQLランナー はファイル数が最も多いコンパイル型言語をビルドします。 | |
--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 | ✓ | GitHub Apps トークンまたは個人アクセストークン。 |
--checkout-path | リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。 | |
--no-upload | なし. CodeQLランナー が結果を GitHub Enterprise Server にアップロードすることを停止します。 | |
--output-dir | 出力される SARIF ファイルが保存されるディレクトリ。 デフォルトは一時ファイルのディレクトリです。 | |
--ram | クエリの実行時に使用するメモリの量。 デフォルトでは、使用できるすべてのメモリを使用します。 | |
--no-add-snippets | なし. SARIF 出力からコードスニペットを除外します。 | |
--threads | クエリの実行時に使用するスレッドの数。 デフォルトでは、使用できるすべてのコアを使用します。 | |
--temp-dir | 一時ファイルが保存されるディレクトリ。 デフォルトは ./codeql-runner です。 | |
--debug | なし. より詳細な出力を表示します。 | |
-h , --help | なし. コマンドのヘルプを表示します。 |
アップロード
SARIF ファイルを GitHub Enterprise Server にアップロードします。
注釈: 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 | ✓ | GitHub Apps トークンまたは個人アクセストークン。 |
--checkout-path | リポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。 | |
--debug | なし. より詳細な出力を表示します。 | |
-h , --help | なし. コマンドのヘルプを表示します。 |