CodeQL を使用してコード スキャン ワークフローをカスタマイズする - パート 1

  • 10 分

CodeQL を使用するコード スキャン ワークフローには、組織のニーズに合わせて適切に調整できるさまざまな構成オプションがあります。

CodeQL を使用してコードをスキャンすると、CodeQL 分析エンジンによって、コードからデータベースが生成され、それに対してクエリが実行されます。 CodeQL 分析では、既定のクエリ セットが使用されます。既定のクエリに加えて、実行するクエリをさらに指定することもできます。

お客様が追加のクエリを実行できるのは、それらが、GitHub Container Registry に公開された CodeQL パック (ベータ版) またはリポジトリに格納されている QL パックの一部である場合となります。

CodeQL コード スキャンで実行するクエリを指定するには、次の 2 つのオプションがあります。

  • コード スキャン ワークフローの使用
  • カスタム構成ファイルの使用

このユニットでは、追加のクエリを参照するようにワークフロー ファイルを編集する方法、クエリ パックからクエリを使用する方法、ワークフロー ファイルとカスタム構成ファイルからのクエリを結合する方法について説明します。

ワークフロー ファイルで追加のクエリを指定する

追加で実行したいクエリを指定するのに使用できるオプションは、次のとおりです。

  • packs。1 つまたは複数の CodeQL クエリパック (ベータ版) をインストールし、それらのパックに対して既定のクエリ スイートまたはクエリを実行します。
  • queries。1 つの .ql ファイル、複数の .ql ファイルを含むディレクトリ、.qls クエリ スイート定義ファイル、または任意の組み合わせを指定します。

パックとクエリの両方を同じワークフロー内で使用することができます。

github/codeql/cpp/ql/src@main のように、github/codeql リポジトリから直接クエリ スイートを参照することはお勧めしません。 このようなクエリは、他のクエリで使用されているものと同じバージョンの CodeQL を使用してコンパイルすることがきません。そのため、分析中にエラーが発生する可能性があります。

CodeQL クエリ パックを使用する

注意

CodeQL パックを含む CodeQL パッケージ管理機能は、現在ベータ版であり、変更される可能性があります。

1 つまたは複数の CodeQL クエリ パック (ベータ版) を追加するには、ワークフローの uses: github/codeql-action/init@v1 セクション内に with: packs: エントリを追加します。 パック内では、使用するパッケージを 1 つまたは複数指定し、必要に応じて、ダウンロードするバージョンを指定できます。 バージョンを指定しない場合は、最新バージョンがダウンロードされます。 公開されていないパッケージを使用する場合は、GITHUB_TOKEN 環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。

次の例では、スコープは、パッケージを公開した組織または個人のアカウントです。 ワークフローを実行すると、GitHub から 3 つの CodeQL クエリ パックがダウンロードされ、各パックの既定のクエリまたはクエリ スイートが実行されます。 次の例では、リスト内の各パックは、その仕様に基づいてダウンロードされます。

  • 最新バージョンの pack1 がダウンロードされ、すべてのデフォルトのクエリが実行されます。
  • バージョン 1.2.3 の pack2 がダウンロードされ、すべてのデフォルトのクエリが実行されます。
  • バージョン 3.2.1 と互換性のある最新バージョンの pack3 がダウンロードされ、すべてのクエリが実行されます。
  • pack4 のバージョン 4.5.6 がダウンロードされ、path/to/queries で見つかったクエリのみが実行されます。
- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Note

複数の言語に対して CodeQL データベースを生成するワークフローの場合は、代わりに、構成ファイル内に CodeQL クエリ パックを指定する必要があります。

QL パックでクエリを使用する

1 つまたは複数のクエリを追加するには、ワークフローの uses: github/codeql-action/init@v3 セクション内にエントリ with: queries: を追加します。 クエリがプライベート リポジトリ内にある場合は、external-repository-token パラメーターを使用して、プライベート リポジトリをチェックアウトするためのアクセス権を持つトークンを指定します。

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

queries の値でクエリ スイートを指定することもできます。 クエリ スイートは、通常、目的または言語別にグループ化されたクエリのコレクションです。

次のクエリ スイートは、CodeQL コード スキャンに組み込まれていて、使用することができます。

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

これらの各クエリ スイートには、その言語の組み込みの CodeQL クエリ パックに含まれるクエリの異なるサブセットが含まれています。 クエリ スイートは、各クエリのメタデータを使用して自動的に生成されます。

クエリ スイートを指定すると、既定のクエリ セットに加えて、スイート内に含まれるクエリが、CodeQL 分析エンジンによって自動的に実行されます。

ワークフロー ファイルとカスタム構成ファイルからのクエリを結合する

カスタム設定にも構成ファイルを使用する場合は、構成ファイル内に指定されたものではなく、ワークフロー内で指定された追加のパックまたはクエリが使用されます。 追加のパックまたはクエリの組み合わせセットを実行する場合は、ワークフロー内の packs または queries の値の前に + 記号を付けます。

次の例では、+ 記号を付けることで、指定した追加のパックとクエリが確実に、参照される構成ファイル内で指定したものと一緒に使用されるようになります。

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries