# CodeQL パックを使った分析のカスタマイズ CodeQL パックを使用して、他のユーザーが管理している CodeQL クエリを実行したり、自分が開発した CodeQL クエリを共有したりすることができます。 他のユーザーが作成したパックをダウンロードし、コードベースで実行することで、CodeQL 分析をカスタマイズできます。 詳しくは、「[CodeQL クエリ パック](/ja/code-security/concepts/code-scanning/codeql/codeql-query-packs)」をご覧ください。 ## CodeQL クエリ パックのダウンロードと使用 CodeQL クエリ パックを使ってデータベースを分析する前に、GitHub Container registry から必要なパッケージをすべてダウンロードする必要があります。 これは、`--download` コマンドの一部として `codeql database analyze` フラグを使うか、`codeql pack download` を実行することで可能です。 パッケージが一般公開されていない場合は、認証に GitHub App または personal access token を使う必要があります。 詳細と例については、「[CodeQL 分析結果をGitHubにアップロードする](/ja/code-security/codeql-cli/getting-started-with-the-codeql-cli/uploading-codeql-analysis-results-to-github#uploading-results-to-github)」をご覧ください。 | Option | 必須 | Usage | | ---------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \ | | コンマ区切りリストを使用して、ダウンロードする 1 つまたは複数の CodeQL クエリ パックのスコープと名前を指定します。 必要に応じて、ダウンロードして解凍するバージョンを含めます。 既定では、このパックの最新バージョンがダウンロードされます。 必要に応じて、実行するクエリ、ディレクトリ、またはクエリ スイートへのパスを含めます。 パスが含まれていない場合、このパックの既定のクエリを実行します。 | | --github-auth-stdin | | GitHub App の REST API での認証用に作成された personal access token または GitHub を標準入力でシークレット ストアから CLI に渡します。 このトークンを使用して設定された `GITHUB_TOKEN` 環境変数にコマンドがアクセスできる場合、これは必要ありません。 | > \[!NOTE] > 特定のバージョンのクエリ パックを使用するよう指定する場合は、指定したバージョンが、最新バージョンの CodeQL では最終的に古くなりすぎて効率的に使用できなくなる可能性があることに注意してください。 最適なパフォーマンスを確保するために、特定のバージョンのクエリ パックを指定する必要がある場合は、使用している CodeQL CLI CLI をアップグレードするたびに、ピン留めするバージョンを再評価する必要があります。 > > パックの互換性について詳しくは、「[CodeQL クエリパック参照](/ja/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility)」をご覧ください。 ### クエリ パックのダウンロードと使用の基本的な例 この例では、`codeql database analyze` コマンドに `--download` オプションを付けて実行しています。 1. 最新バージョンの `octo-org/security-queries` パックをダウンロードします。 2. バージョン 1.0.1 と`octo-org/optional-security-queries`互換性のある\_バージョンの\_パックをダウンロードします (この場合はバージョン 1.0.2 です)。 semver の互換性については、[npm のセマンティック バージョンの範囲に関するドキュメント](https://github.com/npm/node-semver#ranges)を参照してください。 3. ``` `octo-org/security-queries` の既定のクエリをすべて実行します。 ``` 4. ``` `queries/csrf.ql` のクエリ `octo-org/optional-security-queries` だけを実行します ``` ```shell $ 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 分析を実行するとき、前の例と同じ方法でパック、バージョン、パスを指定できます。 ```shell echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download ... ``` ### 複数の CodeQL コンテナー レジストリから GitHub パックをダウンロードする CodeQL パックが複数のコンテナー レジストリに存在する場合は、各パックを検索する場所を CodeQL CLI に示す必要があります。 詳しくは、「[コード スキャンのワークフロー構成オプション](/ja/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#downloading-codeql-packs-from-github-enterprise-server)」をご覧ください。 ## CodeQL パックで実行するクエリの指定 クエリ指定子は、一連のクエリに対して動作する `codeql database analyze` やその他のコマンドによって使用されます。 クエリ指定子の完全な形式は `scope/name@range:path` です。各値は次のとおりです。 * `scope/name` は、CodeQL パックの修飾名です。 * `range` は [semver 範囲](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges)です。 * `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` - 最新バージョン (`codeql/python-queries` 以上、`1.2.3` 未満) の `1.3.0` パックの既定のクエリ スイート内のすべてのクエリ。 * `codeql/python-queries:Functions` - 最新バージョンの `Functions` パックの `codeql/python-queries` ディレクトリ内のすべてのクエリ。 * `codeql/python-queries@1.2.3:Functions` - バージョン 1.2.3 の `Functions` パックの `codeql/python-queries` ディレクトリ内のすべてのクエリ。 * `codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls` - バージョン 1.2.3 の `codeql-suites/python-code-scanning.qls` パックの `codeql/python-queries` ディレクトリ内のすべてのクエリ。 * `suites/my-suite.qls` - 現在の作業ディレクトリに対して相対的な `suites/my-suite.qls` ファイル内のすべてのクエリ。 > \[!TIP] > 標準の CodeQL クエリ パックの既定のクエリ スイートは `codeql-suites/-code-scanning.qls` です。 その他の便利なクエリ スイートも、各パックの `codeql-suites` ディレクトリにあります。 たとえば、`codeql/cpp-queries` パックには次のクエリ スイートが含まれています。 > > * ``` `cpp-code-scanning.qls` - C++ の標準コード スキャン クエリ。 このパックの既定のクエリ スイート。 ``` > * ``` `cpp-security-extended.qls` - C++ の既定の `cpp-code-scanning.qls` スイートからのクエリに加え、重要度と精度の低いクエリ。 ``` > * ``` `cpp-security-and-quality.qls` - `cpp-security-extended.qls` からのクエリに加え、保守性および信頼性のクエリ。 ``` > これらのクエリ スイートのソースは、[CodeQL リポジトリ](https://github.com/github/codeql/tree/main/cpp/ql/src/codeql-suites)で確認できます。 他の言語のクエリ スイートも同様です。 ## モデル パックを使用して、依存関係をカスタムする呼び出しを分析する 公開されたモデル パックは、`--model-packs` オプションを使用して code scanning 分析に含めることができます。 例えば次が挙げられます。 ```shell $ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \ --model-packs my-repo/my-java-model-pack \ --output=/temp/my-company.sarif codeql/java-queries ``` この例では、標準クエリ パック `codeql/java-queries` の関連するクエリは、モデル パック、`my-repo/my-java-model-pack` の依存関係情報を使用して、それらの依存関係を呼び出すコードの脆弱性をチェックします。 1 つの分析で複数の公開済みモデル パックを指定できます。 独自のモデル パックの記述の詳細については、「[CodeQL パックの作成と操作](/ja/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack)」を参照してください。 ### 発行済みパックについて パックが分析で使用するために発行されると、`codeql pack create` または `codeql pack publish` コマンドによって、コンテンツが完全であることが確認され、コンテンツのいくつかの部分が追加されます。 * クエリ パックの場合、それが依存する各ライブラリ パックのコピーであり、開発に使用された正確なバージョンです。 クエリ パックのユーザーは、これらのライブラリ パックを個別にダウンロードする必要はありません。 * クエリ パックの場合、各クエリのプリコンパイル済み表現。 これらは、分析ごとにクエリの QL ソースをコンパイルするよりも高速に実行できます。 このデータのほとんどは、発行済みパック内の `.codeql` という名前のディレクトリにありますが、プリコンパイル済みクエリは、各クエリの `.qlx` ソースの後にサフィックス `.ql` が付いたファイル内にあります。 発行済みパックのクエリを使用してデータベースを分析する場合、CodeQL は、`.ql` ソースの代わりにこれらのファイルをロードします。 "発行済み" パックのコンテンツを変更する必要がある場合、必ず \_\_ ファイルをすべて削除してください。これらによって、`.qlx` ファイルの変更を有効にできなくなる可能性があります。`.ql`