CI システムで CodeQL コードスキャンを実行する

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

Code scanningは、GitHub Advanced Securityのライセンスを持っているなら利用できます。

ノート: Code scanningはGitHub Enterprise Server 2.22ではベータです。 Code Scanningの一般に利用なリリースについては、GitHub Enterprise Serverの最新リリースにアップグレードしてください。

ノート: この機能を使用するには、サイト管理者がGitHub Enterprise Serverのインスタンスのcode scanningを有効にする必要があります。 詳しい情報については「アプライアンスのためのcode scanningの設定」を参照してください。

既存の CI システムで CodeQL code scanning を使用する

GitHub Actions 以外の継続的インテグレーションまたは継続的デリバリ/デプロイメント (CI/CD) システムを使用している場合、GitHub の CodeQL 解析を実行して、その結果を GitHub にアップロードできます。 これを実行するには、CodeQLランナー を使用します。

CodeQLランナー について

Code scanning は、開発者が GitHub リポジトリ内のコードを分析して、セキュリティの脆弱性とコーディングエラーを見つけることができる機能です。 分析によって特定されたすべての問題はGitHub Enterprise Serverに表示されます。詳細については、「code scanning について」を参照してください。

CodeQLランナー を使用して、サードパーティ継続的インテグレーション (CI) システムで処理しているコード上で code scanning を実行できます。 また、GitHub Actions を使用して、GitHub Enterprise Server 上で code scanning を実行することもできます。 詳細については、「リポジトリに対する code scanning をセットアップする」を参照してください。

CodeQLランナー は、GitHub リポジトリのチェックアウト中に CodeQL 解析を実行するコマンドラインツールです。 サードパーティーのシステムにランナーを追加し、ランナーを呼び出してコードを解析し、その結果を GitHub Enterprise Server にアップロードします。 この結果は、リポジトリの code scanning アラートとして表示されます。

ノート:

  • The CodeQLランナー is available to customers with an Advanced Security license.
  • The CodeQLランナー shouldn't be confused with the CodeQL CLI. The CodeQL CLI is an interactive command-line interface that lets you create CodeQL databases for security research and run CodeQL queries. For more information, see "CodeQL CLI."

CodeQLランナー をダウンロードする

CodeQLランナー は、https://github.com/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

On Windows, the codeql-runner-win.exe file usually requires no change to permissions.

CodeQLランナー を CI システムに追加する

Once you download the CodeQLランナー and verify that it can be executed, you should make the runner available to each CI server that you intend to use for code scanning. For example, you might configure each server to copy the runner from a central, internal location. Alternatively, you could use the REST API to get the runner directly from GitHub, for example:

wget https://github.com/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux

これに加えて、各 CI サーバーは以下の条件も満たす必要があります。

  • CodeQLランナー が使用するための GitHub App または個人アクセストークン。 repo スコープのあるアクセストークン、または security_events の書き込み権限、ならびに metadata および contents の読み取り権限を持つ GitHub App を使用する必要があります。 詳細は「GitHub Apps をビルドする」および「個人アクセストークンを作成する」を参照してください。
  • CodeQLランナー のリリースに伴う CodeQL バンドルへのアクセス。 このパッケージには、CodeQL 解析に必要なクエリとライブラリ、さらにランナーによって内部的に使用される CodeQL CLI が含まれています。 詳細は「CodeQL CLI」を参照してください。

CodeQL バンドルにアクセスを与えるオプションは次の通りです。

  1. CI サーバーに https://github.com/github/codeql-action へのアクセスを許可し、CodeQLランナー がバンドルを自動的にダウンロードできるようにする。
  2. GitHub Enterprise Server に github/codeql-action リポジトリをミラーする。 --codeql-path フラグを指定してない限り、ランナーは GitHub.com のこの場所にバンドルがあるかどうか自動的に確認します。
  3. バンドルを手動でダウンロード/展開し、他の中央リソースに保存して、 --codeql-path フラグで、呼び出しにおいて CodeQLランナー を初期化するバンドルの場所を指定します。

CodeQLランナー を呼び出す

解析するリポジトリのチェックアウトの場所から、CodeQLランナー を呼び出す必要があります。 主なコマンドは次の 2 つです。

  1. init は、ランナーを初期化し、解析する各言語に CodeQL データベースを作成するために必要です。 このデータベースは、続くコマンドにより展開、解析されます。
  2. analyze は、CodeQL データベースを展開、解析し、結果を GitHub Enterprise Server にアップロードするために必要です。

For both commands, you must specify the URL of GitHub Enterprise Server, the repository OWNER/NAME, and the GitHub Apps or personal access token to use for authentication. You also need to specify the location of the CodeQL bundle, unless the CI server has access to download it directly from the github/codeql-action repository.

将来の解析のため CodeQLランナー が CodeQL バンドルを保存する場所を --tools-dir フラグで設定できます。また、解析中に一時ファイルを保存する場所を、--temp-dir で設定できます。 --temp-dir.

ランナーのコマンドラインリファレンスを表示するには、-h フラグを使用します。 たとえば、動作するすべてのコマンドを一覧表示するには codeql-runner-OS -h と入力し、init コマンド実行時に使用できるすべてのコマンドを一覧表示するには codeql-runner-OS init -h と入力します (OS 変数は使用している実行ファイルによります)。 詳しい情報については、「code scanning を CI システムで設定する」を参照してください。

ノート: SARIFのアップロードは、アップロードごとに最大で1000件の結果をサポートしています。 この制限を超えた結果は無視されます。 ツールがあまりに多くの結果を生成する場合、最も重要なルールやクエリに対する結果に焦点を当てるよう、設定を更新すべきです。

基本的な例

この例では、https://github.example.com にホストされている octo-org/example-repo リポジトリに対し、Linux CI サーバーで CodeQL 解析を実行します。 このリポジトリには、CodeQL により直接解析でき、ビルドされていない言語 (Go、JavaScript、Python、TypeScript) のみが含まれているため、プロセスは非常に単純です。

In this example, the server has access to download the CodeQL bundle directly from the github/codeql-action repository, so there is no need to use the --codeql-path flag.

  1. 解析するリポジトリをチェックアウトします。

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

  3. CodeQLランナー を初期化し、検出された言語用の CodeQL データベースを作成します。

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
    > Cleaning temp directory /srv/checkout/example-repo/codeql-runner
    > ...
    > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
  4. CodeQLデータベースを展開し、分析し、その結果をGitHub Enterprise Serverにアップロードしてください。 その結果は、リポジトリのSecurity(セキュリティ)タブに表示されます。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --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
  5. code scanningの結果をPull Requestのチェックとしてアップロードするには、 --ref フラグを使ってPull Requestを指定してください。 CodeQLランナーは、pull_request webhookイベントで実行されるようにセットアップすることをおすすめします。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --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アラートの表示に関する詳しい情報については「Code ScanningのアラートのPull Requestでのトリアージ」及び「リポジトリのCode Scanningアラートの管理」を参照してください。

コンパイル型言語の例

この例は前の例と似ていますが、今回のリポジトリには C/C++、C#、または Java のコードがあります。 これらの言語用に CodeQL データベースを作成するには、CLI でビルドをモニターする必要があります。 初期化プロセスの最後に、ランナーはコードをビルドする前に環境をセットアップするために必要なコマンドを報告します。 通常の CI ビルドプロセスを呼び出す前にこのコマンドを実行してから、analyze コマンドを実行する必要があります。

  1. 解析するリポジトリをチェックアウトします。

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

  3. CodeQLランナー を初期化し、検出された言語用の CodeQL データベースを作成します。

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
        --github-url https://github.example.com --github-auth TOKEN
    > 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".
  4. init アクションによって生成されたスクリプトを入手し、ビルドを監視する環境をセットアップします。 次のコードには、先頭にドットとスペースがあることに注意してください。

    $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
  5. コードをビルドします。 macOS では、build コマンドのプレフィックスに環境変数 $CODEQL_RUNNER を付ける必要があります。 詳しい情報については、「CI システムにおせるコードスキャンのトラブルシューティング」を参照してください。

  6. CodeQLデータベースを展開し、分析し、その結果をGitHub Enterprise Serverにアップロードしてください。 その結果は、リポジトリのSecurity(セキュリティ)タブに表示されます。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --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
  7. code scanningの結果をPull Requestのチェックとしてアップロードするには、 --ref フラグを使ってPull Requestを指定してください。 CodeQLランナーは、pull_request webhookイベントで実行されるようにセットアップすることをおすすめします。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --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アラートの表示に関する詳しい情報については「Code ScanningのアラートのPull Requestでのトリアージ」及び「リポジトリのCode Scanningアラートの管理」を参照してください。

注釈: コンテナ化されたビルドを使用している場合、ビルドタスクを行うコンテナで CodeQLランナー を実行する必要があります。

参考リンク

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

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

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

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

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

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

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