Skip to main content

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

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

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

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

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

: JavaScript、TypeScript、またはその両方で記述されたコードを分析するには javascript を使用します。

詳細については、CodeQL Web サイトのドキュメント「サポートされている言語とフレー� ワーク」を参照してく� さい。

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

言語の自動検出をオーバーライドするには、--languages フラグを指定して init コマンドを実行し、続けて言語キーワードのコンマ区切りのリストを実行します。 サポートされている言語に対するキーワードはcppcsharpgojavajavascript、 と 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 は、ビルドされたリポジトリ内のソース ファイルを分析します。 これらの言語の� �合は、autobuild を無効にし、その代わりにカスタ�  ビルド コマンドによってビルドされたファイルのみを分析するためにこれらのカスタ�  コマンドを使用できます。

多くの一般的なビルド システ� に対して、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 トークンまたは personal access token を標準入力から読み取ります。
--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 トークンまたは personal access token を標準入力から読み取ります。
--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 トークンまたは personal access token を標準入力から読み取ります。
--checkout-pathリポジトリをチェックアウトするパス。 デフォルトは現在のワーキングディレクトリです。
--debug[なし] : より詳細な出力を表示します。
-h, --help[なし] : コマンドのヘルプを表示します。