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

8 分

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

このユニットでは、カスタム構成ファイルで追加のクエリを参照する方法を確認します。

カスタム構成ファイルの追加のクエリ

カスタム構成ファイルは、実行する追加のパックとクエリを指定するときの代替的な方法です。また、このファイルを使用すると、既定のクエリを無効にしたり、分析時にスキャンするディレクトリを指定したりすることもできます。

ワークフローファイルでは、init アクションの config-file パラメーターを使用して、使用する構成ファイルへのパスを指定します。この例では、構成ファイル ./.github/codeql/codeql-config.yml を読み込みます。

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

構成ファイルは、分析するリポジトリ内、または外部リポジトリ内に格納できます。外部リポジトリを使用すると、1 つの場所の複数のリポジトリに対して構成オプションを指定できます。外部リポジトリにある構成ファイルを参照する場合は、OWNER/REPOSITORY/FILENAME@BRANCH 構文を使用できます。 (例: octo-org/shared/codeql-config.yml@main)。

構成ファイルが外部のプライベートリポジトリにある場合は、init アクションの external-repository-token パラメーターを使用して、そのプライベートリポジトリへのアクセス権を持つトークンを指定します。

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

構成ファイルの設定は、YAML 形式で記述します。

カスタム構成ファイルで CodeQL クエリパックを指定する

Note

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

CodeQL クエリパックは配列内に指定できます。この形式は、ワークフローファイルで使用される形式とは異なります。

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

クエリパックを指定する完全な書式は scope/name[@version][:path] です。 version と path はどちらも省略可能です。 version は semver バージョンの範囲です。指定しない場合は、最新バージョンが使われます。

複数の CodeQL データベースを生成するワークフローでは、入れ子になったパックのマップを使用して、カスタム構成ファイルで実行する CodeQL クエリパックを指定できます。

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

カスタム構成で追加のクエリを指定する

queries 配列に追加のクエリを指定できます。配列の各要素に、単一のクエリファイル、クエリファイルを含むディレクトリ、またはクエリスイート定義ファイルを識別する値を持つ usesパラメーターを含めます。

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

必要に応じて、次の構成ファイルの例に示すように、各配列要素に名前を付けることができます。

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'

既定のクエリを無効にする

カスタムクエリのみを実行する場合は、disable-default-queries: true を使用して既定のセキュリティクエリを無効にすることができます。このフラグは、特定の規則を除外するカスタムクエリスイートを作成する場合にも使用してください。これによって、すべてのクエリが 2 回実行されるのを防止できます。

分析からの特定のクエリの除外

カスタム構成ファイルに exclude と include のフィルターを追加して、分析で除外または含める次のようなクエリを指定できます。

デフォルトのスイート (security、security-extended、および security-and-quality) からの特定のクエリ。
結果に関心がない特定のクエリ。
警告と推奨事項を生成するすべてのクエリ。

次のファイルの構成にあるものと同様の exclude フィルターを使用して、既定の分析から削除するクエリを除外できます。次の構成ファイルの例では、js/redundant-assignment および js/useless-assignment-to-local クエリの両方が分析から除外されています。

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

クエリの ID を見つけるには、[セキュリティ] タブのアラートのリストでアラートをクリックします。これにより、[アラートの詳細] ページが開きます。 [ルール ID] フィールドにはクエリ ID が含まれています。

excludes フィルターを使用する場合は、次の点に注意してください。

フィルターの順序が重要です。クエリとクエリパックに関する命令の後に表示される最初のフィルター命令によって、デフォルトでクエリを含めるか除外するかが決まります。
後続の命令は順番に実行され、ファイル内で後にある命令の方が前にある命令よりも優先されます。

スキャンするディレクトリを指定する

CodeQL でサポートされているインタープリター言語 (Python、Ruby、JavaScript/TypeScript) では、構成ファイルに paths 配列を追加して、コードスキャンを特定のディレクトリ内のファイルに制限できます。 paths-ignore 配列を追加すると、特定のディレクトリ内のファイルを分析から除外できます。

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Note

コードスキャン構成ファイルのコンテキストで使用される paths および paths-ignore キーワードを、ワークフローの on.<push|pull_request>.paths で使用するときの同じキーワードと混同しないでください。これらをワークフロー内の on.<push|pull_request> の変更に使用すると、指定されたディレクトリ内のコードが変更されたときにアクションを実行するかどうかが決定されます。
フィルターパターン文字 ?、+、[、]、! はサポートされていないため、文字どおりに照合されます。
** 文字は、行の先頭または末尾にのみ指定するか、スラッシュで囲むことができます。また、** と他の文字を一緒に使用できます。たとえば foo/**、**/foo、foo/**/bar は、すべて許容される構文ですが、**foo は許容されません。ただし、例に示すように、1 つの星印を他の文字と一緒に使用できます。 * 文字を含むものはすべて引用符で囲む必要があります。

コンパイル済み言語では、コードスキャンをプロジェクト内の特定のディレクトリに制限する場合、ワークフローに適切なビルドステップを指定する必要があります。ビルドからディレクトリを除外するために使用するコマンドは、ビルドシステムによって異なります。

特定のディレクトリ内のコードを変更した場合、モノリポの小さな部分をすばやく分析できます。ビルドステップでディレクトリを除外すること、およびワークフローで on.<push|pull_request> の paths-ignore および paths キーワードを使用することが、どちらも必要になります。

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