CIシステムでのCodeQLランナーの実行

この記事では、次の項目が扱われます。

CodeQL runner を使用して、サードパーティの継続的インテグレーションシステムで CodeQL code scanning を実行できます。

Code scanning は、GitHub Enterprise Server の Organization 所有のリポジトリで利用できます。この機能には、GitHub Advanced Security のライセンスが必要です。詳細については、「GitHub Advanced Security について」を参照してください。

メモ: 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-path フラグを使用して、CodeQL runner を初期化する呼び出しでバンドルの場所を指定します。

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 フラグを使用して、CodeQL runner が今後の解析のためにサーバーに CodeQL バンドルを格納する場所を構成し、--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 コマンドを実行する必要があります。

解析するリポジトリをチェックアウトします。
リポジトリがチェックアウトされるディレクトリに移動します。