Skip to main content

このバージョンの GitHub Enterprise はこの日付をもって終了となります: 2022-10-12. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせください

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

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

Code scanning is available for organization-owned repositories in GitHub Enterprise Server. This feature requires a license for 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 への移行」を参照してください。

注: この機能を使用するには、サイト管理者が your GitHub Enterprise Server instance の 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 をダウンロードする

https://HOSTNAME/github/codeql-action/releases から CodeQL runner をダウンロードすることができます。 一部のオペレーティングシステムでは、ダウンロードしたファイルの実行前に、その権限を変更する必要があります。

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 ファイルの権限変更は必要はありません。

CodeQL runner を CI システムに追加する

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

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

  1. CI サーバーに https://HOSTNAME/github/codeql-action へのアクセスを許可し、CodeQL runner がバンドルを自動的にダウンロードできるようにします。
  2. バンドルを手動でダウンロードおよび展開し、他の中央リソースと共に格納し、--codeql-path フラグを使用して、CodeQL runner を初期化する呼び出しでバンドルの場所を指定します。

CodeQL runner を呼び出す

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

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

どちらのコマンドでも、GitHub Enterprise Server の URL、リポジトリの OWNER/NAME、および認証に使用するGitHub Apps または個人用アクセス トークンを指定する必要があります。 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 フラグを使う必要はありません。

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

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

  3. 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.
  4. 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
  5. 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 コマンドを実行する必要があります。

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

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

  3. 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".
  4. init アクションによって生成されたスクリプトを入手し、ビルドを監視する環境を設定します。 次のコードには、先頭にドットとスペースがあることに注意してください。

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

  6. 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
  7. 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 を実行する必要があります。

参考資料