CodeQL クエリスイートの作成

CodeQL クエリスイートの作成について

CodeQL クエリスイートでは、ファイル名、ディスク上または CodeQL パック内の場所、またはメタデータプロパティに基づいてクエリを選択することができます。 CodeQL 分析で頻繁に使用するクエリのクエリスイートを作成します。

クエリスイートを使用すると、各クエリファイルへのパスを個別に指定せずに、複数のクエリを CodeQL に渡すことができます。クエリスイートの定義は、拡張子が .qls の YAML ファイルに格納されます。スイートの定義は一連の命令であり、各命令は、(通常は) 1 つのキーを持つ YAML マッピングです。これらの命令は、クエリスイートの定義に指定された順序で実行されます。スイートの定義の命令がすべて実行されると、結果は、選択されたクエリのセットになります。

注: クエリスイートに追加するカスタムクエリは "CodeQL パック" 内にあり、正しいクエリメタデータを含んでいる必要があります。詳しくは、「CodeQL CLI でのカスタムクエリの使用」をご覧ください。

クエリスイートに追加するクエリの場所指定

クエリスイートを作成するときは、選びたいクエリの場所を最初に指定する必要があります。次を使用して、1 つ以上のクエリの場所を定義できます。

query 命令 — CodeQL に、指定された 1 つ以上の .ql ファイルを検索するように指示します。
```
- query: <path-to-query>
```
引数は、スイート定義を含む CodeQL パックを基準にした 1 つ以上のファイルパスである必要があります。
queries 命令 — CodeQL に、.ql ファイルのディレクトリを再帰的にスキャンするように指示します。
```
- queries: <path-to-subdirectory>
```
ディレクトリのパスは、スイート定義ファイルを含む CodeQL パックのルートを基準にする必要があります。別の CodeQL パックに対するクエリを検索するには、from フィールドを追加します。
```
- queries: <path-to-subdirectory>
  from: <ql-pack-name>
  version: ^x.y.z
```
version フィールドは省略可能であり、この CodeQL パックの互換性のあるバージョンの範囲を指定するものです。バージョンを指定しない場合は、パックの最新バージョンが使用されます。
qlpack 命令 — CodeQL に、名前付き CodeQL パックの既定のスイートでクエリを解決するように指示します。
```
- qlpack: <qlpack-name>
  version: ^x.y.z
```
クエリパックの既定のスイートには、そのクエリパック内で推奨されるクエリのセットが含まれています。すべてのクエリパックに既定のスイートがあるわけではありません。指定されたクエリパックで既定のスイートが定義されていない場合、qlpack 命令はパック内のすべてのクエリに解決されます。

version フィールドは省略可能であり、この CodeQL パックの互換性のあるバージョンの範囲を指定するものです。バージョンを指定しない場合は、パックの最新バージョンが使用されます。

注: パス名がクエリスイート定義に表示される場合は、常にスラッシュ / をディレクトリ区切りとして指定する必要があります。これにより、クエリスイート定義がすべてのオペレーティングシステムで確実に機能します。

スイート定義には少なくとも 1 つの query、queries、または qlpack 命令を追加する必要があります。それ以外の場合、クエリは選ばれません。スイートにこれ以上の命令が含まれない場合は、ファイルの一覧、指定されたディレクトリ、または名前付き CodeQL パックで見つかったすべてのクエリが選ばれます。さらにフィルター処理命令がある場合は、それらの命令によって課される制約に一致するクエリのみが選ばれます。

クエリスイートでのクエリのフィルター処理

query、queries、または qlpack 命令を指定してスイートに追加するクエリの初期セットを定義した後、include と exclude の命令を追加できます。次の命令では、特定のプロパティに基づいて選択条件が定義されます。

クエリのセットに対して include 命令を実行すると、条件に一致するすべてのクエリが選択に保持され、一致しないクエリは削除されます。
クエリのセットに対して exclude 命令を実行すると、条件に一致するすべてのクエリが選択から削除され、一致しないクエリは保持されます。

フィルター命令の順序は重要です。命令の場所指定後に表示される最初のフィルター命令によって、既定でクエリを含めるか除外するかが決まります。最初のフィルターが include の場合、最初に場所指定されたクエリは、明示的な include フィルターと一致する場合にのみスイートの一部になります。最初のフィルターが exclude の場合、最初に場所指定されたクエリは、明示的に除外されている場合にのみスイートの一部になります。

後続の命令は順番に実行され、ファイル内で後にある命令の方が前にある命令よりも優先されます。そのため、include 命令は、同じクエリに一致する後の exclude 命令によってオーバーライドできます。同様に、exclude は後の includeによってオーバーライドできます。

どちらの命令でも、引数は制約ブロックです。つまり、制約を表す YAML マップです。各制約はマップエントリであり、この場合のキーは通常、クエリメタデータプロパティです。次の値が考えられます。

1 つの文字列。
/ で囲まれた正規表現。
文字列、正規表現、またはその両方を含むリスト。

制約に一致させるには、メタデータ値が文字列または正規表現のいずれかに一致する必要があります。複数のメタデータキーがある場合は、各キーを一致させる必要があります。照合に使用できる標準メタデータキーは description、id、kind、name、tags、precision、および problem.severity です。クエリメタデータプロパティについて詳しくは、「CodeQL クエリのメタデータ」をご覧ください。

メタデータタグに加えて、制約ブロック内のキーは次の場合もあります。

query filename — クエリファイル名の最後のパスコンポーネントと照合します。
query path — 外側の CodeQL パックを基準にした、クエリファイルのパスと照合します。
tags contain — 指定された照合文字列の 1 つが、@tags メタデータプロパティの値のスペース区切りコンポーネントのいずれかに一致する必要があります。
tags contain all — 指定されたそれぞれの照合文字列が、@tags メタデータプロパティのコンポーネントのいずれかに一致する必要があります。

実行するクエリのフィルター処理の例

一般的なユースケースは、ユーザーが実行したくない特定のクエリを除き、CodeQL パックですべてのクエリを実行するクエリスイートを作成することです。一般的には、クエリごとに一意で安定した識別子であるクエリ id でフィルター処理することをお勧めします。次の 3 つのクエリスイート定義は、意味的に同一であり、クエリ id でフィルター処理されます。

このフィルターは、除外された識別子を持つ 2 つのクエリを除き、codeql/cpp-queries の既定のスイート内のすべてのクエリと一致します。

- qlpack: codeql/cpp-queries
- exclude:
    id:
      - cpp/cleartext-transmission
      - cpp/cleartext-storage-file

この例では、クエリごとに個別の exclude 命令が使用されます。

- qlpack: codeql/cpp-queries
- exclude:
    id: cpp/cleartext-transmission
- exclude:
    id: cpp/cleartext-storage-file

この例では、正規表現によって同じ 2 つのクエリが除外されます。また、cpp/cleartext- で始まる識別子を持つスイートに追加される今後のクエリも除外されます。

- qlpack: codeql/cpp-queries
- exclude:
    id:
      - /^cpp\/cleartext-.*/

codeql/cpp-queries CodeQL パックの既定のスイート内のすべてのクエリを選び、セキュリティクエリのみを含むように絞り込むスイートを定義するには、次を使用します。

- qlpack: codeql/cpp-queries
- include:
    tags contain: security

my-custom-queries ディレクトリから @kind problem と @precision high のすべてのクエリが選ばれるスイートを定義するには、次を使用します。

- queries: my-custom-queries
- include:
    kind: problem
    precision: very-high

次のクエリスイート定義は、上記の定義とは異なる動作をします。この定義は、@kind problem "または" @precision very-high であるクエリが選ばれます。__

- queries: my-custom-queries
- include:
    kind: problem
- include:
    precision: very-high

@problem.severity recommendation を含むものを除き、my-custom-queries ディレクトリから @kind problem のすべてのクエリが選ばれるスイートを作成するには、次を使用します。

- queries: my-custom-queries
- include:
    kind: problem
- exclude:
    problem.severity: recommendation

codeql/cpp-queries CodeQL パックから @tag security と @precision high または very-high のすべてのクエリが選ばれるスイートを作成するには、次を使用します。

- queries: .
  from: codeql/cpp-queries
- include:
    tags contain: security
    precision:
    - high
    - very-high

注: codeql resolve queries /path/to/suite.qls コマンドを使用すると、クエリスイート定義で選ばれているクエリを確認できます。詳しくは、「クエリを解決する」を参照してください。

既存のクエリスイート定義の再利用

既存のクエリスイート定義は、次を指定することで再利用できます。

import 命令 — 以前に定義した .qls ファイルによって選ばれたクエリを現在のスイートに追加します。
```
- import: <path-to-query-suite>
```
インポートされたスイートのパスは、現在のスイート定義を含む CodeQL パックを基準にする必要があります。インポートされたクエリスイートが別の QL パックにある場合は、次を使用できます。
```
- import: <path-to-query-suite>
  from: <ql-pack>
  version: ^x.y.z
```
version フィールドは省略可能であり、この CodeQL パックの互換性のあるバージョンの範囲を指定するものです。バージョンを指定しない場合は、パックの最新バージョンが使用されます。

import 命令を使用して追加されたクエリは、後続の exclude 命令を使用してフィルター処理できます。
apply 命令 — 以前に定義した .qls ファイルのすべての命令を現在のスイートに追加します。適用された .qls ファイル内の命令が、apply の代わりに表示されたかのようにして実行されます。適用されたスイートの include と exclude の命令は、以前の命令によって追加されたクエリにも作用します。
```
- apply: <path-to-query-suite>
```
apply 命令を使用して、.yml ファイルに保存された一連の再利用可能な条件を複数のクエリ定義に適用することもできます。詳しくは、下記の例をご覧ください。

再利用性の例

複数のクエリスイート定義で同じ条件を使用するには、命令を含む別の .yml ファイルを作成します。たとえば、reusable-instructions.yml という名前のファイルに次を保存します。

- include:
    kind:
    - problem
    - path-problem
    tags contain: security
    precision:
    - high
    - very-high

現在のクエリスイートと同じ CodeQL パックに reusable-instructions.yml を追加します。次に、1 つ以上のクエリスイートで、apply 命令を使用して、再利用可能な命令を現在のスイートに適用します。次に例を示します。

- queries: queries/cpp/custom
- apply: reusable-instructions.yml

これにより、queries/cpp/custom のクエリがフィルター処理され、再利用可能な条件に一致するもののみが含まれるようになります。

別の CodeQL パックのクエリで reusable-instructions.yml を使用してスイート定義を作成することもできます。 .qls ファイルがクエリと同じ CodeQL パックにある場合は、apply 命令の直後に from フィールドを追加できます。

# load queries from the default suite of my-org/my-other-custom-queries
- qlpack: my-org/my-other-custom-queries

# apply the reusable instructions from the my-org/my-custom-instructions CodeQL pack
- apply: reusable-instructions.yml
  from: my-org/my-custom-instructions
  version: ^1.2.3 # optional

import 命令の一般的なユースケースは、別のクエリスイートのクエリにさらにフィルターを適用することです。たとえば、このスイートでは、cpp-security-and-quality スイートをさらにフィルター処理し、low と medium の有効桁数クエリが除外されます。

- import: codeql-suites/cpp-security-and-quality.qls
  from: codeql/cpp-queries
- exclude:
    precision:
      - low
      - medium

別のスイートからインポートされたクエリを include する場合、構文は少し異なります。

- import: codeql-suites/cpp-security-and-quality.qls
  from: codeql/cpp-queries
- exclude: {}
- include:
    precision:
      - very-high
      - high

空の exclude 命令に注目してください。これは、後続の include 命令がインポートされたスイートからのクエリをフィルター処理できるようにするために必要です。

クエリスイートの名前付け

クエリスイートの名前を指定するには、description 命令を指定します。

- description: <name-of-query-suite>

「CodeQL クエリ」

CodeQL クエリスイートの作成

この機能を使用できるユーザーについて

この記事の内容