メモ: CodeQL runnerは非推奨になっています。 GitHub Enterprise Server 3.0 以降では、CodeQL CLI バージョン 2.6.3 をインストールして、CodeQL runnerを置き換えることができます。
詳しくは、「CodeQL ランナーの非推奨化」をご覧く� さい。 CodeQL CLI への移行については、「CodeQL ランナーから CodeQL CLI への移行」を参照してく� さい。
注: この機能を使用するには、サイト管理者が の code scanning を有効にする必要があります。 詳しくは、「アプライアンスでの code scanning の構成」をご覧く� さい。
CodeQL runner について
CodeQL runner は、サードパーティの継続的インテグレーション (CI) システ� 内で処理しているコードに対して code scanning を実行するのに利用できるツールです。 Code scanning は、開発者が GitHub リポジトリ内のコードを分析して、セキュリティの脆弱性とコーディングエラーを見つけることができる機能です。 分析によって特定されたすべての問題はGitHub Enterprise Serverに表示されます。 詳細については、「CodeQL によるcode scanningについて」を参照してく� さい。
多くの� �合、CIシステ� 内でCodeQL CLIを直接使ってCodeQL code scanningをセットアップするのが容易です。
あるいは、GitHub Actionsを使ってGitHub Enterprise Server内でcode scanningを実行することもできます。 詳細については、「リポジトリの code scanning の設定」を参照してく� さい。
CodeQL runner は、GitHub リポジトリのチェックアウト中に CodeQL 解析を実行するコマンドライン ツールです。 サードパーティーのシステ� にランナーを追� し、ランナーを呼び出してコードを解析し、その結果を GitHub Enterprise Server にアップロードします。 この結果は、リポジトリの code scanning アラートとして表示されます。
注:
- CodeQL runner は Advanced Security ライセンスを持つお客様にご利用いた� けます。
CodeQL runner のダウンロード
CodeQL runner は、 https://HOSTNAME/github/codeql-action/releases からダウンロードできます。 一部のオペレーティングシステ� では、ダウンロードしたファイルの実行前に、その権限を変更する必要があります。
Linux の� �合:
chmod +x codeql-runner-linux
macOS の� �合:
chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos
Windows では、通常、codeql-runner-win.exe
ファイルの権限変更は必要はありません。
CI システ� に CodeQL runner を追� する
CodeQL runner をダウンロードし、実行できることを確認したら、code scanning に使用するそれぞれの CI サーバーでランナーを利用できるようにする必要があります。 たとえば、内部的な中央の� �所からランナーをコピーするよう、各サーバーを設定することになるでしょう。 あるいは、REST API を使用して GitHubから直接ランナーを取得することもできます。例:
wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux
これに� えて、各 CI サーバーは以下の条件も満たす必要があります。
- 使用する CodeQL runner の GitHub App または personal access token。
repo
スコープがあるアクセス トークン、またはsecurity_events
書き込み権限、およびmetadata
とcontents
の読み取り権限を持つ GitHub App を使用する必要があります。 詳しくは、「GitHub Apps を構築する」と「personal access token の作成」を参照してく� さい。 - CodeQL runner のリリースに伴う CodeQL バンドルへのアクセス。 このパッケージには、CodeQL 解析に必要なクエリとライブラリ、さらにランナーによって内部的に使用される CodeQL CLI が含まれています。 詳細については、「CodeQL CLI」を参照してく� さい。
CodeQL バンドルにアクセスを与えるオプションは次の通りです。
- CI サーバーに https://HOSTNAME/github/codeql-action へのアクセスを許可し、CodeQL runner によりバンドルが自動的にダウンロードされるようにします。
- バンドルを手動でダウンロードおよび展開し、他の中央リソースと共に� �納し、
フラグを使用して、CodeQL runner を初期化する呼び出しでバンドルの� �所を指定します。--codeql-path
CodeQL runner の呼び出し
解析するリポジトリのチェックアウトの� �所から、CodeQL runner を呼び出す必要があります。 主なコマンドは次の 2 つです。
init
は、ランナーを初期化し、解析する言語ごとに CodeQL データベースを作成するために必要です。 このデータベースは、続くコマンドにより展開、解析されます。analyze
は、CodeQL データベースを展開し、解析し、結果を GitHub Enterprise Server にアップロードするために必要です。
どちらのコマンドでも、GitHub Enterprise Server の URL、リポジトリの OWNER/NAME、および認証に使用するGitHub Apps または personal access token を指定する必要があります。 CI サーバーで github/codeql-action
リポジトリから直接 CodeQL バンドルをダウンロードできる� �合を除き、そのバンドルの� �所を指定する必要もあります。
--tools-dir
--temp-dir
ランナーのコマンドライン リファレンスを表示するには、-h
フラグを使用します。 たとえば、すべてのコマンドを一覧表示するには、codeql-runner-OS -h
を実行します。または、init
コマンドで使用できるすべてのフラグを一覧表示するには、codeql-runner-OS init -h
を実行します (ここで OS
は、使用している実行可能ファイルによって異なります)。 詳細については、「CI システ� での code scanning の構成」を参照してく� さい。
注:
-
SARIF アップロードでは、アップロードごとに最大 5,000 件の結果がサポートされます。 この制限を超える結果はすべて無視されます。 ツールで生成される結果が多すぎる� �合は、最も重要なルールまたはクエリの結果に焦点を当てるように構成を更新する必要があります。
-
SARIF アップロードでサポートされる
gzip
圧縮の SARIF ファイルの最大サイズは、アップロードごとに 10 MB となります。 この制限を超えるアップロードはすべて拒否されます。 含まれる結果が多すぎるために SARIF ファイルが大きくなりすぎた� �合は、最も重要なルールまたはクエリの結果に焦点を当てるように構成を更新する必要があります。
基本的な例
この例では、https://github.example.com
でホストされている octo-org/example-repo
リポジトリに対して、Linux CI サーバーで CodeQL 解析を実行します。 このリポジトリには、CodeQL により直接解析でき、ビルドされていない言語 (Go、JavaScript、Python、TypeScript) のみが含まれているため、プロセスは非常に単純です。
この例では、サーバーで github/codeql-action
リポジトリから直接 CodeQL バンドルをダウンロードできるので、--codeql-path
フラグを使う必要はありません。
-
解析するリポジトリをチェックアウトします。
-
リポジトリがチェックアウトされるディレクトリに移動します。
-
CodeQL runner を初期化し、検出された言語用の CodeQL データベースを作成します。
$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo --github-url https://github.example.com --github-auth-stdin > Cleaning temp directory /srv/checkout/example-repo/codeql-runner > ... > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
-
CodeQLデータベースを展開し、分析し、その結果をGitHub Enterprise Serverにアップロードしてく� さい。 結果は、リポジトリの [セキュリティ] タブに表示されます。
$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth-stdin --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch > Finalizing database creation > ... > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms > Successfully uploaded results
-
code scanning の結果をプルリクエストのチェックとしてアップロードするには、
フラグを使用してプルリクエストを指定します。--ref
pull_request
Webhook イベントで実行されるように CodeQL runnerを設定することをお勧めします。$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth-stdin --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge > Finalizing database creation > ... > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms > Successfully uploaded results
code scanning アラートの表示の詳細については、「Triaging code scanning alerts in pull requests (プルリクエストでのコード スキャン アラートのトリアージ)」および「Managing code scanning alerts for your repository (リポジトリのコード スキャン アラートの管理)」を参照してく� さい。
コンパイル型言語の例
この例は前の例と似ていますが、今回のリポジトリには C/C++、C#、または Java のコードがあります。 これらの言語用に CodeQL データベースを作成するには、CLI でビルドをモニターする必要があります。 初期化プロセスの最後に、ランナーはコードをビルドする前に環境をセットアップするために必要なコマンドを� �告します。 通常の CI ビルド プロセスを呼び出す前にこのコマンドを実行してから、analyze
コマンドを実行する必要があります。
-
解析するリポジトリをチェックアウトします。
-
リポジトリがチェックアウトされるディレクトリに移動します。
-
CodeQL runner を初期化し、検出された言語用の CodeQL データベースを作成します。
$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2 --github-url https://github.example.com --github-auth-stdin > Cleaning temp directory /srv/checkout/example-repo-2/codeql-runner > ... > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json" and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh". Please export these variables to future processes so that CodeQL can monitor the build, for example by running ". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
-
init
アクションによって生成されたスクリプトを入手し、ビルドを監視する環境を設定します。 次のコードには、先� �にドットとスペースがあることに注意してく� さい。$ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
-
コードをビルドする。 macOS では、ビルド コマンドの前に環境変数
$CODEQL_RUNNER
を付ける必要があります。 詳しくは、「CI システ� での CodeQL runner のトラブルシューティング」を参照してく� さい。 -
CodeQLデータベースを展開し、分析し、その結果をGitHub Enterprise Serverにアップロードしてく� さい。 結果は、リポジトリの [セキュリティ] タブに表示されます。
$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth-stdin --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch > Finalizing database creation > ... > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms > Successfully uploaded results
-
code scanning の結果をプルリクエストのチェックとしてアップロードするには、
フラグを使用してプルリクエストを指定します。--ref
pull_request
Webhook イベントで実行されるように CodeQL runnerを設定することをお勧めします。$ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo --github-url https://github.example.com --github-auth-stdin --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge > Finalizing database creation > ... > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms > Successfully uploaded results
code scanning アラートの表示の詳細については、「Triaging code scanning alerts in pull requests (プルリクエストでのコード スキャン アラートのトリアージ)」および「Managing code scanning alerts for your repository (リポジトリのコード スキャン アラートの管理)」を参照してく� さい。
注: コンテナー化されたビルドを使用している� �合、ビルド タスクを行うコンテナーで CodeQL runner を実行する必要があります。