Skip to main content

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

CIシステムでのCodeQLランナーの設定

CodeQL runner がプロジェクトのコードをスキャンして、その結果を GitHub にアップロードする方法を設定できます。

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 の構成」をご覧ください。

CI システムにおける CodeQL code scanning の設定について

code scanning をお使いの CI システムに統合するには、CodeQL runner を使用できます。 詳細については、「CI システムでの CodeQL runner の実行」を参照してください。

一般的に、CodeQL runner は次のように呼び出します。

$ /path/to-runner/codeql-runner-OS  

/path/to-runner/ は、CodeQL runner を、お使いの CI システムのどこにダウンロードしたかによって異なります。 codeql-runner-OS は、お使いのオペレーティング システムによって異なります。 CodeQL runner には、Linux、macOS、Windows システム用に、それぞれ codeql-runner-linuxcodeql-runner-macoscodeql-runner-win の 3 つのバージョンがあります。

CodeQL runner がコードをスキャンする方法をカスタマイズするには、フラグ (--languages--queries など) を使用するか、別の構成ファイルでカスタム設定を指定できます。

Pull Requestをスキャンする

プルリクエストが作成されるたびにコードをスキャンすることで、開発者がコードに新しい脆弱性やエラーを持ち込むことを防げます。

pull request をスキャンするには、analyze コマンドを実行し、--ref フラグを使用して pull request を指定します。 参照は、refs/pull/<PR-number>/head または refs/pull/<PR-number>/merge であり、pull request ブランチの HEAD コミットをチェックアウトしたかどうか、ベース ブランチとのマージ コミットをチェックアウトしたかどうかによって異なります。

$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/merge

: サード パーティ製ツールを使用してコードを分析し、結果を pull request チェックとして表示する場合は、upload コマンドを実行し、--ref フラグを使用してブランチの代わりに pull request を指定する必要があります。 参照は、refs/pull/<PR-number>/head または refs/pull/<PR-number>/merge です。

自動言語検出をオーバーライドする

CodeQL runner は、サポートされている言語で記述されたコードを自動的に検出してスキャンします。

  • C/C++
  • C#
  • Go
  • Java
  • JavaScript/TypeScript
  • Python

サポートされている 1 つ以上の言語のコードがリポジトリに含まれている場合は、分析する言語を選択できます。 言語が分析されないようにする理由は、いくつかあります。 たとえば、プロジェクトで、コードの本体に対する依存関係が別の言語の中にあり、それらの依存関係のアラートを表示したくない場合が考えられます。

言語の自動検出をオーバーライドするには、--languages フラグを指定して init コマンドを実行し、続けて言語キーワードのコンマ区切りのリストを実行します。 サポートされている言語に対するキーワードはcpp, csharp, go, java, javascript, and pythonです。

$ /path/to-runner/codeql-runner-linux init --languages cpp,java

追加のクエリを実行する

コードをスキャンするためにCodeQLを使う場合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。

実行したいクエリが他にあれば、リポジトリ内の QL パックに属していなければなりません。 詳細については、「code scanning と CodeQL について」を参照してください。

1 つの .ql ファイル、複数の .ql ファイルを含むディレクトリ、 .qls クエリ スイート定義ファイル、または任意の組み合わせを指定できます。 クエリ スイート定義の詳細については、「CodeQL クエリ スイートの作成」を参照してください。

以下のクエリスイートはCodeQL code scanningに組み込まれており、利用可能です。

クエリ スイート説明
security-extended既定のスイートからのクエリ、および重要度と精度の低いクエリ
security-and-qualitysecurity-extended からのクエリに加え、保守性および信頼性のクエリ。

クエリ スイートを指定すると、CodeQL の分析エンジンでは、既定の一連のクエリと、追加のクエリ スイートで定義されている追加クエリが実行されます。

1 つ以上のクエリを追加するには、init コマンドの --queries フラグにパスのコンマ区切りのリストを渡します。 設定ファイルに、追加のクエリを指定することもできます。

カスタム設定にも構成ファイルを使用し、--queries フラグで追加のクエリも指定している場合、CodeQL runner は、構成ファイルで指定されたものではなく、--queries フラグで指定された追加のクエリを使用します。 フラグと構成ファイルで指定された追加クエリの組み合わせのセットを使用する場合、--queries に渡される値の前に + 記号を付けますます。 詳細については、「カスタム構成ファイルの使用」を参照してください。

次の例では、+ 記号により、CodeQL runner で追加のクエリが、参照されている構成ファイルの中で指定されている任意のクエリと共に使用されることが確保されます。

$ /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 runner コマンドに追加情報を渡すかわりに、別の設定ファイルでカスタム設定を指定できます。

設定ファイルの形式は YAML ファイルです。 YAML ファイルは、以下の例で示すように、GitHub Actions のワークフロー構文と似た構文を使用します。 詳細については、GitHub Actions のワークフロー構文に関するページを参照してください。

init コマンドの --config-file フラグを使用して、構成ファイルを指定します。 --config-file の値は、使用する構成ファイルへのパスです。 この例では、構成ファイル .github/codeql/codeql-config.yml を読み込みます。

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml

構成ファイルは、分析するリポジトリ内、または外部リポジトリ内に格納できます。 外部リポジトリを使用すると、1 つの場所の複数のリポジトリに対して構成オプションを指定できます。 外部リポジトリにある構成ファイルを参照する場合は、 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 runner はコードを自動的にビルドできます。 コードを自動的にビルドするには、init 手順と analyze 手順の間で autobuild を実行します。 リポジトリに特定のバージョンのビルドツールが必要な場合は、まずそのビルドツールを手動でインストールする必要があることにご注意ください。

autobuild プロセスにより、リポジトリに対してコンパイルされた言語を " 1 つ" だけビルドすることが試みられます。 解析のために自動的に選択される言語は、使用されているファイル数が最も多い言語です。 言語を明示的に選択する場合は、autobuild コマンドの --language フラグを使用します。

$ /path/to-runner/codeql-runner-linux autobuild --language csharp

autobuild コマンドでコードをビルドできない場合は、init ステップと analyze ステップの間でビルド ステップをご自分で実行できます。 詳細については、「CI システムでの CodeQL runner の実行」を参照してください。

code scanning データを GitHub にアップロードする

既定では、analyze コマンドを実行すると、CodeQL runner により結果が code scanning からアップロードされます。 また、upload コマンドを使用して、SARIF ファイルを個別にアップロードすることもできます。

データをアップロードすると、GitHub はリポジトリにアラートを表示します。

  • pull request (たとえば --ref refs/pull/42/merge--ref refs/pull/42/head) にアップロードした場合、結果は pull request チェックのアラートとして表示されます。 詳細については、「pull request での Code Scanning アラートのトリアージ」を参照してください。
  • ブランチ (たとえば --ref refs/heads/my-branch) にアップロードした場合、結果はリポジトリの [セキュリティ] タブに表示されます。 詳細については、「リポジトリの Code Scanning アラートの管理」を参照してください。

CodeQL runner コマンドのリファレンス

CodeQL runner は、次のコマンドおよびフラグをサポートしています。

init

CodeQL runner を初期化し、解析する各言語用の CodeQL データベースを作成します。

フラグ必須入力値
--repository初期化するリポジトリの名前。
--github-urlリポジトリがホストされる GitHub のインスタンス。
--github-auth-stdinGitHub Appsトークンもしくは個人アクセストークンを標準入力から読み込みます。
--languages解析対象言語のカンマ区切りリスト。 デフォルトでは、CodeQL runner はリポジトリにあるサポートされている言語をすべて検出し、解析します。
--queriesデフォルトのセキュリティクエリに加えて実行する、追加クエリのカンマ区切りリスト。 これにより、カスタム構成ファイルの queries 設定がオーバーライドされます。
--config-fileカスタム設定ファイルのパス。
--codeql-path使用する CodeQL CLI 実行ファイルのコピーのパス。 デフォルトでは、CodeQL runner はコピーをダウンロードします。
--temp-dir一時ファイルが保存されるディレクトリ。 既定値は、./codeql-runner です。
--tools-dir実行間で CodeQL ツールやその他のファイルが保存されるディレクトリ。 デフォルトはホームディレクトリのサブディレクトリです。
--checkout-pathリポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。
--debug[なし] : より詳細な出力を表示します。
--trace-process-name高度でWindowsのみ。 このプロセスのWindows tracerが注入されたプロセスの名前。
--trace-process-level高度でWindowsのみ。 このプロセスのWindows tracerが注入された親プロセスまでのレベル数。
-h, --help[なし] : コマンドのヘルプを表示します。

autobuild

コンパイル型言語である C/C++、C#、および Java のコードのビルドを試行します。 これらの言語では、CodeQL は解析前にコードをビルドします。 initanalyze 手順の間で autobuild を実行します。

フラグ必須入力値
--languageビルドする言語。 デフォルトでは、CodeQL runner はファイル数が最も多いコンパイル型言語をビルドします。
--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-stdinGitHub Appsトークンもしくは個人アクセストークンを標準入力から読み込みます。
--checkout-pathリポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。
--no-upload[なし] : CodeQL runner が結果を GitHub Enterprise Server にアップロードすることを停止します。
--output-dir出力される SARIF ファイルが保存されるディレクトリ。 デフォルトは一時ファイルのディレクトリです。
--ramクエリの実行時に使用するメモリの量。 デフォルトでは、使用できるすべてのメモリを使用します。
--no-add-snippets[なし] : SARIF 出力からコードスニペットを除外します。
--categoryこの分析でSARIF結果ファイルに含めるカテゴリ。 カテゴリは、同じツールとコミットについて、ただし様々な言語やコードの様々な部分に対して行われる複数の分析を区別するために使うことができます。 この値は、SARIF v2.1.0 の <run>.automationDetails.id プロパティに表示されます。
--threadsクエリの実行時に使用するスレッドの数。 デフォルトでは、使用できるすべてのコアを使用します。
--temp-dir一時ファイルが保存されるディレクトリ。 既定値は、./codeql-runner です。
--debug[なし] : より詳細な出力を表示します。
-h, --help[なし] : コマンドのヘルプを表示します。

upload

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-stdinGitHub Appsトークンもしくは個人アクセストークンを標準入力から読み込みます。
--checkout-pathリポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。
--debug[なし] : より詳細な出力を表示します。
-h, --help[なし] : コマンドのヘルプを表示します。