CodeQL パックを使った分析のカスタマイズ

CodeQL パックについて

CodeQL パックを使用して、CodeQL クエリとライブラリを作成、共有、実行したり、これらに依存したりすることができます。 CodeQL パックには、クエリ、ライブラリ ファイル、クエリ スイート、メタデータが含まれます。 他のユーザーが作成したパックをダウンロードし、コードベースで実行することで、CodeQL 分析をカスタマイズできます。

CodeQL パックの 、二つの タイプがあります。 クエリ パックとライブラリ パック。

• クエリ パックには、CodeQL データベースで評価できる事前コンパイル済みクエリのセットが含まれています。 クエリ パックは、実行するように設計されています。 クエリ パックが発行されると、バンドルにはすべての推移的な依存関係とコンパイル キャッシュが含まれます。 これにより、パック内のクエリの一貫した効率的な実行が保証されます。

• ライブラリ パックは、クエリ パック (またはその他のライブラリ パック) で使用するように設計されており、クエリ自体は含まれません。 ライブラリはにコンパイルされません。パックが発行されたときにコンパイル キャッシュが含まれません。

サポートされているすべての言語の標準 CodeQL パックは、Container registry で公開されています。 CodeQL CLI バンドルを使用して、標準的な方法で CodeQL CLI をインストールした場合、コア クエリ パックはすでにダウンロードされており、使用できるようになります。 これらは次のとおりです。

• codeql/cpp-queries
• codeql/csharp-queries
• codeql/go-queries
• codeql/java-queries
• codeql/javascript-queries
• codeql/python-queries
• codeql/ruby-queries

CodeQL CLI を使用して、独自の CodeQL パックを作成したり、パックに依存関係を追加したり、依存関係をインストールまたは更新したりできます。 詳しくは、「CodeQL パックの作成と操作」を参照してください。

CodeQL CLI を使用して作成した CodeQL パックを発行できます。 CodeQL パックの公開とダウンロードの詳細については、「CodeQL パックを発行して使用する」をご覧ください。

CodeQL クエリ パックのダウンロードと使用

CodeQL CLI バンドルには、GitHub の専門家、セキュリティ研究者、コミュニティの共同作成者によって管理されるクエリが含まれます。 他の組織によって開発されたクエリを実行する場合、CodeQL クエリ パックを使用すると、クエリ 。 クエリ パックについて詳しくは、「CodeQL によるコード スキャンについて」をご覧ください。

CodeQL クエリ パックを使ってデータベースを分析する前に、GitHub Container registry から必要なパッケージをすべてダウンロードする必要があります。 これは、codeql database analyze コマンドの一部として --download フラグを使うこと、または codeql pack download を実行することにより行うことができます。 パッケージが一般公開されていない場合は、認証に GitHub App または personal access token を使う必要があります。 詳細と例については、「CodeQL 分析結果を GitHub にアップロードする」をご覧ください。

オプション	必須	使用法
<scope/name@version:path>		コンマ区切りリストを使って、ダウンロードする 1 つまたは複数の CodeQL クエリ パックのスコープと名前を指定します。 必要に応じて、ダウンロードして解凍するバージョンを含めます。 既定では、このパックの最新バージョンがダウンロードされます。 必要に応じて、実行するクエリ、ディレクトリ、またはクエリ スイートへのパスを含めます。 パスが含まれていない場合、このパックの既定のクエリを実行します。
--github-auth-stdin		GitHub の REST API での認証用に作成された GitHub App または personal access token を標準入力でシークレット ストアから CLI に渡します。 このトークンを使用して設定された GITHUB_TOKEN 環境変数にコマンドがアクセスできる場合、これは必要ありません。

クエリ パックのダウンロードと使用の基本的な例

この例では、codeql database analyze コマンドに --download オプションを付けて実行しています。

1. 最新バージョンの octo-org/security-queries パックをダウンロードします。
2. バージョン 1.0.1 とocto-org/optional-security-queries互換性のある_バージョンの_パックをダウンロードします (この場合はバージョン 1.0.2 です)。 semver の互換性については、npm のセマンティック バージョンの範囲に関するドキュメントを参照してください。
3. octo-org/security-queries の既定のクエリをすべて実行します。
4. octo-org/optional-security-queries のクエリ queries/csrf.ql だけを実行します

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

CodeQL パックの直接ダウンロード

CodeQL パックをダウンロードしてすぐに実行しない場合、codeql pack download コマンドを使用できます。 これは、CodeQL クエリを実行するとき、インターネットへのアクセスをしないようにする場合、便利です。 CodeQL 分析を実行するとき、前の例と同じ方法でパック、バージョン、パスを指定できます。

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

複数の GitHub コンテナー レジストリから CodeQL パックをダウンロードする

CodeQL パックが複数のコンテナー レジストリに存在する場合は、各パックを検索する場所を CodeQL CLI に示す必要があります。 詳しくは、「コード スキャンの詳細設定を行う」を参照してください。

CodeQL パックで実行するクエリの指定

クエリ指定子は、一連のクエリに対して動作する codeql database analyze やその他のコマンドによって使用されます。 クエリ指定子の完全な形式は scope/name@range:path です。各値は次のとおりです。

• scope/name は、CodeQL パックの修飾名です。
• range は semver 範囲です。
• path は、単一のクエリ、クエリを含むディレクトリ、またはクエリ スイート ファイルへのファイル システム パスです。

scope/name を指定する場合は、range と path を省略できます。 range を省略すると、指定したパックの最新バージョンが使用されます。 path を省略すると、指定したパックの既定のクエリ スイートが使用されます。

path は、.ql クエリ ファイル、1 つまたは複数のクエリを含むディレクトリ、または .qls クエリ スイート ファイルにすることができます。 パック名を省略する場合は、path を指定する必要があります。これは、現在のプロセスの作業ディレクトリに対して相対的であると解釈されます。 glob パターンはサポートされていません。

scope/name と path の両方を指定した場合は、path を絶対にすることはできません。 これは、CodeQL パックのルートに対して相対的であると見なされます。

クエリ指定子の例

• codeql/python-queries - 最新バージョンの codeql/python-queries パックの既定のクエリ スイート内のすべてのクエリ。

• codeql/python-queries@1.2.3 - バージョン 1.2.3 の codeql/python-queries パックの既定のクエリ スイート内のすべてのクエリ。

• codeql/python-queries@~1.2.3 - 最新バージョン (1.2.3 以上、1.3.0 未満) の codeql/python-queries パックの既定のクエリ スイート内のすべてのクエリ。

• codeql/python-queries:Functions - 最新バージョンの codeql/python-queries パックの Functions ディレクトリ内のすべてのクエリ。

• codeql/python-queries@1.2.3:Functions - バージョン 1.2.3 の codeql/python-queries パックの Functions ディレクトリ内のすべてのクエリ。

• codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls - バージョン 1.2.3 の codeql/python-queries パックの codeql-suites/python-code-scanning.qls ディレクトリ内のすべてのクエリ。

• suites/my-suite.qls - 現在の作業ディレクトリに対して相対的な suites/my-suite.qls ファイル内のすべてのクエリ。