# コード スキャンのワークフロー構成オプション
ワークフロー ファイルを編集して、高度なセットアップでプロジェクト内のコードの脆弱性とエラーをスキャンする方法を構成します。
> \[!NOTE]
> この機能を使用するには、サイト管理者が code scanning を有効にする必要があります。 コードをスキャンするためにGitHub Actionsを使いなら、サイト管理者はGitHub Actionsの有効化と、必要なインフラストラクチャのセットアップもしなければなりません。 詳しくは、「[アプライアンス用コードスキャンの構成](/ja/enterprise-server@3.20/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance)」をご覧ください。
> \[!NOTE]
> この記事では、このバージョンの GitHub Enterprise Server の初期リリースに含まれる CodeQL アクションのバージョンおよび関連する CodeQL CLI バンドルで使用できる機能について説明します。 エンタープライズでより新しいバージョンの CodeQL アクションを使用する場合は、この記事の [GitHub Enterprise Cloud バージョン](/ja/enterprise-cloud@latest/code-security/reference/code-scanning/workflow-configuration-options)で最新の機能に関する情報を参照してください。
> 最新バージョンの使用方法については、「[アプライアンス用コードスキャンの構成](/ja/enterprise-server@3.20/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access)」を参照してください。
## \[前提条件]
```
code scanningの詳細設定を使用し、構成が定義されているワークフロー ファイルを編集できるようにする必要があります。
```
この記事で示す例は、 CodeQL 分析ワークフロー ファイルに関連しています。 既定では、このファイルは `.github/workflows/codeql-analysis.yml`で定義されます。
## スキャンの頻度
スケジュールに従って、またはリポジトリで特定のイベントが発生したときにコードをスキャンするように CodeQL 分析ワークフロー を構成できます。
リポジトリへのプッシュごと、およびプルリクエストが作成されるたびにコードをスキャンすることで、開発者がコードに新しい脆弱性やエラーをもたらすことを防ぎます。 スケジュールに従ってコードをスキャンすると、開発者がリポジトリを積極的に保守していない場合でも、 GitHub、セキュリティ研究者、コミュニティが検出した最新の脆弱性とエラーについて通知されます。
### プッシュ時にスキャンする
既定では、 CodeQL 分析ワークフロー は `on:push` イベントを使用して、リポジトリの既定のブランチと保護されたブランチへのすべてのプッシュでコード スキャンをトリガーします。 指定したブランチで code scanning をトリガーするには、そのブランチにワークフローが存在する必要があります。 詳しくは、「[GitHub Actions のワークフロー構文](/ja/enterprise-server@3.20/actions/using-workflows/workflow-syntax-for-github-actions#on)」をご覧ください。
プッシュ時にスキャンすると、リポジトリの \[ ** Security** ] タブに結果が表示されます。 詳しくは、「[リポジトリのコード スキャンのアラートの評価](/ja/enterprise-server@3.20/code-security/code-scanning/managing-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository#viewing-the-alerts-for-a-repository)」をご覧ください。
さらに、開かれた pull request にマップできる結果が `on:push` スキャンから返された場合、これらのアラートは他の pull request アラートと同じ場所にある pull request に自動的に表示されます。 これらのアラートは、ブランチのヘッドの既存の分析とターゲット ブランチの分析を比較することで特定します。 プル要求の code scanning アラートの詳細については、 [Pull RequestでCode scanningアラートをトリアージする](/ja/enterprise-server@3.20/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests) を参照してください。
### Pull Requestをスキャンする
既定の CodeQL 分析ワークフロー では、 `pull_request` イベントを使用して、既定のブランチを対象とするプル要求でコード スキャンをトリガーします。
プル要求がプライベート fork.`pull_request` から開かれた場合、
```
`pull_request` イベントについて詳しくは、「[AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request)」をご覧ください。
```
pull requests をスキャンすると、結果は pull request チェックのアラートとして表示されます。 詳しくは、「[Pull RequestでCode scanningアラートをトリアージする](/ja/enterprise-server@3.20/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests)」をご覧ください。
ヘッド コミットではなく pull request のマージ コミットをスキャンするように構成された `pull_request` トリガーを使用すると、各プッシュでブランチのヘッドをスキャンする場合より効果的で正確な結果が生成されます。 ただし、プル要求でトリガーするように構成できない CI/CD システムを使用する場合でも、 `on:push` トリガーを使用できます。 code scanning は結果をマップしてブランチでプル要求を開き、プル要求の注釈としてアラートを追加します。 詳細については、「[プッシュ時のスキャン](#scanning-on-push)」を参照してください。
### Pull Requestの不要なスキャンを回避する
変更されたファイルに関係なく、既定のブランチを対象とする特定の pull request でコード スキャンがトリガーされないようにしたい場合があります。 これを構成するには、`on:pull_request:paths-ignore` ワークフローで`on:pull_request:paths`またはcode scanningを指定します。 たとえば、pull request 内の変更がファイル拡張子 `.md` または `.txt` のファイルに対するものだけである場合、次の `paths-ignore` 配列を使用できます。
```yaml copy
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
paths-ignore:
- '**/*.md'
- '**/*.txt'
```
> \[!NOTE]
```
`on:pull_request:paths-ignore` と `on:pull_request:paths` で、ワークフロー内のアクションが pull request で実行されるかどうかを決定する条件を設定します。 アクションが実行 _される_ ときにどのファイルが解析されるかは決定されません。 pull request に `on:pull_request:paths-ignore` または `on:pull_request:paths` で一致しないファイルが含まれている場合、ワークフローによって、アクションが実行され、そのファイルが除外されていない限り、`on:pull_request:paths-ignore` または `on:pull_request:paths` で一致するファイルを含め、pull request で変更されたすべてのファイルがスキャンされます。 分析からファイルを除外する方法については、「[スキャンするディレクトリを指定する](#specifying-directories-to-scan)」を参照してください。
```
```
`on:pull_request:paths-ignore` と `on:pull_request:paths` を使って pull request に対してワークフローをいつ実行するかを決定する方法について詳しくは、「[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)」をご覧ください。
```
### スケジュールに従ってスキャンする
既定の CodeQL 分析ワークフローを使用すると、ワークフローは、イベントによってトリガーされるスキャンに加えて、週に 1 回リポジトリ内のコードをスキャンします。 このスケジュールを調整するには、ワークフロー内の `cron` イベントの `on.schedule` 値を編集します。 詳しくは、「[GitHub Actions のワークフロー構文](/ja/enterprise-server@3.20/actions/reference/workflows-and-actions/workflow-syntax#onschedule)」をご覧ください。
> \[!NOTE]
> ワークフロー ファイルが既定のブランチに存在する場合にのみ、このイベントによってワークフローの実行がトリガーされます。
### 例
次の例は、CodeQL 分析ワークフロー という名前の既定のブランチと、`main`という 1 つの保護されたブランチを持つ特定のリポジトリの`protected`を示しています。
```yaml copy
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
schedule:
- cron: '20 14 * * 1'
```
このワークフローでは以下をスキャンします。
* 既定のブランチと保護されたブランチへのすべてのプッシュ
* 既定のブランチへのすべての pull request
* 毎週月曜日 14 時 20 分 (UTC) に既定のブランチ
## オペレーティング システム
> \[!NOTE]
>
> * Swift コードのコード スキャンでは、既定で macOS ランナーが使用されます。
> * Swift コードの Code scanning は、Actions Runner Controller (ARC) の一部であるランナーではサポートされていません。ARC をキャプチャするランナーでは Linux のみが使用されるため、Swift には macOS ランナーが必要です。 ただし、ARC をキャプチャする ランナーとセルフホストの macOS ランナーの両方を組み合わせることもできます。 詳しくは、「[アクション ランナー コントローラー](/ja/enterprise-server@3.20/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller)」をご覧ください。
コードでコンパイルに特定のオペレーティング システムが必要な場合は、 CodeQL 分析ワークフローでオペレーティング システムを構成できます。
`jobs.analyze.runs-on`の値を編集して、code scanningアクションを実行するマシンのオペレーティング システムを指定します。
オペレーティングシステムを指定するには、`self-hosted`の後に2要素配列の2番目の要素として適切なラベルを使用します。
```yaml copy
jobs:
analyze:
name: Analyze
runs-on: [self-hosted, ubuntu-latest]
```
```
CodeQL
code scanning は、Ubuntu、Windows、および macOS の最新バージョンをサポートしています。 したがって、この設定の一般的な値は、`ubuntu-latest`、`windows-latest`、`macos-latest` です。 詳細については、「[AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job)」および「[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners)」を参照してください。
Git がセルフホステッド ランナーの PATH 変数にあることを確認する必要があります。 詳細については、「[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners)」および「[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners)」を参照してください。
```
セルフホステッド マシンで CodeQL 分析を実行するための推奨仕様 (RAM、CPU コア、ディスク[CodeQL を実行するための推奨ハードウェア リソース](/ja/enterprise-server@3.20/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql) を参照してください。
##
```
CodeQL データベースの場所
```
一般に、後の手順では前の手順で作成されたデータベースが自動的に検索されるため、 CodeQL 分析ワークフロー がデータベース CodeQL 配置する場所について心配する必要はありません。 ただし、CodeQL データベースを特定のディスクの場所に配置する必要があるカスタム ワークフロー ステップを作成する場合 (たとえば、データベースをワークフロー 成果物としてアップロードする場合)、`db-location` アクションの下で `init` パラメーターを使用してその場所を指定できます。
```yaml copy
- uses: github/codeql-action/init@v4
with:
db-location: '${{ github.runner_temp }}/my_location'
```
```
CodeQL 分析ワークフローでは、`db-location`で指定されたパスは書き込み可能であり、存在しないか、空のディレクトリであることが想定されます。 セルフホストランナー上で動作するか、Dockerコンテナを使うジョブでこのパラメータを使う場合、選択されたディレクトリが実行間でクリアされること、あるいは不要になったらデータベースが削除されることを保証するのはユーザの責任です。 これは、 GitHubホストランナーで実行されているジョブでは必要ありません。これにより、実行されるたびに新しいインスタンスとクリーンなファイルシステムが取得されます。 詳しくは、「[AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners)」をご覧ください。
```
このパラメーターを使用しない場合、 CodeQL 分析ワークフロー は独自に選択した一時的な場所にデータベースを作成します。 現在、既定値は `${{ github.runner_temp }}/codeql_databases` です。
## 分析する言語
```
CodeQL
code scanning では、次の言語で記述されたコードがサポートされています。
```
* C/C++
* C#
* Go
* Java/Kotlin
* JavaScript/TypeScript
* Python
* Ruby
* Rust
* Swift \* GitHub Actions ワークフロー
> \[!NOTE]
>
> * Java、Kotlin、またはその両方で記述されたコードを分析するには `java-kotlin` を使用します。
> * JavaScript、TypeScript、またはその両方で記述されたコードを分析するには `javascript-typescript` を使用します。
詳細については、CodeQL Web サイトのドキュメント「[サポートされている言語とフレームワーク](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/)」を参照してください。
```
CodeQL では、次の言語識別子が使用されます。
```
| Language | 識別子 | オプションの代替識別子 (存在する場合) |
| -------- | ------- | -------------------- |
| C/C++ | `c-cpp` | |
```
`c` または `cpp` |
```
\| C# | `csharp` |
\| |
GitHub Actionsのワークフロー | `actions`
|
\| Go | `go` |
\| Java/Kotlin | `java-kotlin` |
`java` または `kotlin` |
\| JavaScript/TypeScript | `javascript-typescript` |
`javascript` または `typescript` |
\| Python | `python` |
\| Ruby | `ruby` |
\| |
Rust | `rust`
|
\| Swift | `swift` |
> \[!NOTE]
> 代替識別子の 1 つを指定した場合、これは標準の言語識別子の使用と同じです。 たとえば、`javascript` の代わりに `javascript-typescript` を指定した場合、TypeScript コードの分析は除外されません。 代わりに、カスタム構成ファイルを使って、`paths-ignore` 設定でファイルを分析対象から除外できます。 詳細については、「[カスタム構成ファイルの使用](/ja/enterprise-server@3.20/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#custom-configuration-files)」と「[スキャンするディレクトリを指定する](/ja/enterprise-server@3.20/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#specifying-directories-to-scan)」を参照してください。
これらの言語識別子は、`languages` アクションの `init` 入力に対する引数として使用できます。 引数として指定する言語は 1 つに限定することをお勧めします。
```yaml copy
- uses: github/codeql-action/init@v4
with:
languages: javascript-typescript
```
CodeQL を使用したCodeQL 分析ワークフローした後に作成された既定の[](/ja/enterprise-server@3.20/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql) ファイルでは、分析されるリポジトリ内の言語を一覧表示する `language` という名前のプロパティを含むマトリックスが定義されます。 このマトリックスには、リポジトリで検出されたサポート対象の言語が自動的に事前設定されています。
`language`マトリックスを使用すると、CodeQLは各言語分析を並列で実行し、各言語の分析をカスタマイズできます。 個々の分析では、マトリックスから取得した言語名が `init` 入力の引数として `languages` アクションに渡されます。 すべてのワークフローでこの構成を採用することをお勧めします。 マトリックスの詳細については、「[ワークフローでのジョブのバリエーションの実行](/ja/enterprise-server@3.20/actions/using-jobs/using-a-matrix-for-your-jobs)」を参照してください。
```yaml copy
- uses: github/codeql-action/init@v4
with:
languages: ${{ matrix.language }}
```
ワークフローで `language` マトリックスを使用している場合、 CodeQL はマトリックス内の言語のみを分析します。 分析対象の言語を変更するには、マトリックス構成を編集します。 分析対象から除外する言語は削除できます。 言語が分析されないようにする理由は、いくつかあります。 たとえば、プロジェクトで、コードの本体に対する依存関係が別の言語の中にあり、それらの依存関係のアラートを表示したくない場合が考えられます。
code scanningの構成時にリポジトリに存在しなかった言語を追加することもできます。 たとえば、 code scanning の構成時にリポジトリに最初は JavaScript のみが含まれ、後で Python コードを追加した場合は、マトリックスに `python` を追加する必要があります。
```yaml copy
jobs:
analyze:
name: Analyze
...
strategy:
fail-fast: false
matrix:
include:
- language: javascript-typescript
build-mode: none
- language: python
build-mode: none
```
コンパイル済み言語の場合、マトリックスを使って、`build-mode` プロパティの値を変更することで、分析に使うビルド モードを構成することもできます。 ビルド モードの詳細については、「[コンパイル済み言語の CodeQL コード スキャン](/ja/enterprise-server@3.20/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#about-build-mode-none-for-codeql)」を参照してください。
ワークフローが`languages` アクションの`init`入力に引数を指定しない場合、CodeQLは分析を順番に実行するように構成されます。 この場合、 CodeQL はリポジトリでサポートされている言語を自動的に検出し、分析を試みます。 リポジトリのサイズと言語の数によっては、この処理に長時間かかる場合があります。 このモードでは、1 つの言語の分析が失敗すると、すべての言語の分析が失敗します。 そのため、この構成はお勧めしません。
> \[!NOTE]
> 言語を順番に分析するときは、すべての言語の既定のビルド モードが使われます。 または、`autobuild` ステップを明示的に指定した場合は、`autobuild` モードをサポートするすべての言語ではそれが使われ、それ以外の言語では既定のモードが使われます。 これよりも複雑なビルドモード構成が必要な場合は、マトリックスを構成する必要があります。
## チェック失敗時のアラートの重大度
ルールセットを使用すると、次のいずれかの条件が満たされたときにプル要求がマージされないようにできます。
* 必要なツールは、ルール セットで定義されている重大度の code scanning アラートを検索します。
* 必要なツールの分析はまだ進行中です。
* リポジトリに必要なツールが構成されていません。
詳しくは、「[コード スキャンのマージ保護を設定します](/ja/enterprise-server@3.20/code-security/code-scanning/managing-your-code-scanning-configuration/set-code-scanning-merge-protection)」をご覧ください。 ルールセットの一般情報については、[「AUTOTITLE」](/ja/enterprise-server@3.20/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)を参照してください。
## 分析カテゴリ
```
`category` を使用して、同じツールとコミットに対して、異なる言語またはコードの異なる部分に対して実行される複数の解析を区別します。 ワークフロー中で指定したカテゴリは、SARIF結果ファイルに含まれます。
```
このパラメータは、特に単一リポジトリで作業をしていて、単一リポジトリの様々なコンポーネントに対して複数のSARIFファイルがある場合に有益です。
```yaml copy
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v4
with:
# Optional. Specify a category to distinguish between multiple analyses
# for the same tool and ref. If you don't use `category` in your workflow,
# GitHub will generate a default category name for you
category: "my_category"
```
ワークフローで `category` パラメーターを指定しない場合、アクションをトリガーするワークフロー ファイルの名前、アクション名、およびマトリックス変数に基づいて、 GitHub によってカテゴリ名が生成されます。 例えば次が挙げられます。
\*
`.github/workflows/codeql-analysis.yml`ワークフローと `analyze` アクションによって、カテゴリ `.github/workflows/codeql.yml:analyze` が生成されます。
\*
`.github/workflows/codeql-analysis.yml` ワークフロー、`analyze` アクション、`{language: javascript-typescript, os: linux}` マトリックス変数によって、カテゴリ `.github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux` が生成されます。
```
`category` 値は、SARIF v2.1.0 の `.automationDetails.id` プロパティとして表示されます。 詳しくは、「[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#runautomationdetails-object)」をご覧ください。
```
指定したカテゴリは、SARIF ファイルに `runAutomationDetails` オブジェクトの詳細が含まれている場合、上書きされることはありません。
##
```
CodeQL モデル パック
```
コードベースが、CodeQLの標準クエリで認識されないライブラリまたはフレームワークに依存している場合は、発行されたCodeQLモデル パックを指定することで、code scanning ワークフローのCodeQLカバレッジを拡張できます。 独自のモデル パックの作成の詳細については、「[CodeQL パックの作成と操作](/ja/enterprise-server@3.20/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-and-working-with-codeql-packs#creating-a-model-pack)」を参照してください。
> \[!NOTE]
> CodeQL モデル パックは現在 パブリック プレビュー 段階であり、変更される可能性があります。 モデル パックは C/C++、C#、Java/Kotlin、Python、Ruby、Rust 分析でサポートされます。
>
> Visual Studio Code 用 CodeQL 拡張機能の CodeQL モデル エディターでは、C#、Java/Kotlin、Python、Ruby に対する依存関係のモデリングがサポートされています。
###
```
CodeQL モデル パックの使用
```
1 つ以上の発行済みCodeQLモデル パックを追加するには、ワークフローの `with: packs:` セクション内の `uses: github/codeql-action/init@v4` エントリ内でそれらを指定します。
`packs` 内で、使用するパッケージを 1 つ以上指定し、必要に応じて、ダウンロードするバージョンを指定します。 バージョンを指定しない場合は、最新バージョンがダウンロードされます。 公開されていないパッケージを使用する場合は、`GITHUB_TOKEN` 環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。 詳細については、「[ワークフローでの認証に GITHUB\_TOKEN を使用する](/ja/enterprise-server@3.20/actions/security-guides/automatic-token-authentication)」および「[GitHub Actions でのシークレットの使用](/ja/enterprise-server@3.20/actions/security-guides/encrypted-secrets)」を参照してください。
```yaml copy
- uses: github/codeql-action/init@v4
with:
config-file: ./.github/codeql/codeql-config.yml
queries: security-extended
packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack
```
この例では、既定のクエリは、Java、およびクエリ パック `7.8.9` の `7.9.0` 以下のバージョンからのクエリ`my-company/my-java-queries`に対して実行されます。 最新バージョンのモデル パック `my-repo/my-java-model-pack` でモデル化された依存関係により、デフォルトのクエリと `my-company/my-java-queries` のクエリ両方が使用できます。
## 既定以外のクエリ
コードをスキャンするためにCodeQLを使う場合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。
> \[!TIP]
> また、分析から除外するクエリを指定したり、分析に含めたりすることもできます。 これには、カスタム構成ファイルを使用する必要があります。 詳細については、以下の「 [カスタム構成ファイル](#custom-configuration-files) 」および「 [特定のクエリを分析から除外する](#excluding-specific-queries-from-analysis) 」を参照してください。
GitHub Container registry に公開されている CodeQL パックまたはリポジトリに格納されている CodeQL パックの一部である場合に、追加のクエリを実行できます。 詳しくは、「[CodeQL によるコード スキャンについて](/ja/enterprise-server@3.20/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-codeql-queries)」をご覧ください。
追加で実行したいクエリを指定するのに使用できるオプションは、次のとおりです。
* ```
`packs` 1 つまたは複数の CodeQL クエリ パックをインストールし、それらのパックに対して既定のクエリ スイートまたはクエリを実行します。
```
* ```
`queries` 1 つの _.ql_ ファイル、複数の _.ql_ ファイルを含むディレクトリ、 _.qls_ クエリ スイート定義ファイル、または任意の組み合わせを指定します。 クエリ スイート定義の詳細については、「[CodeQL クエリ スイートの作成](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/)」を参照してください。
```
同じワークフローで `packs` と `queries` の両方を使用できます。
### クエリ パックの使用
1 つ以上のCodeQLクエリ パックを追加するには、ワークフローの `with: packs:` セクション内に`uses: github/codeql-action/init@v4` エントリを追加します。
`packs` 内で、使用するパッケージを 1 つ以上指定し、必要に応じて、ダウンロードするバージョンを指定します。 バージョンを指定しない場合は、最新バージョンがダウンロードされます。 公開されていないパッケージを使用する場合は、`GITHUB_TOKEN` 環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。 詳細については、「[ワークフローでの認証に GITHUB\_TOKEN を使用する](/ja/enterprise-server@3.20/actions/security-guides/automatic-token-authentication)」および「[GitHub Actions でのシークレットの使用](/ja/enterprise-server@3.20/actions/security-guides/encrypted-secrets)」を参照してください。
> \[!NOTE]
> 複数の言語の CodeQL データベースを生成するワークフローの場合は、代わりに構成ファイルで CodeQL クエリ パックを指定する必要があります。 詳細については、以下の [「クエリ パック CodeQL 指定する](#specifying-codeql-query-packs) 」を参照してください。
次の例では、`scope` は、パッケージを公開した Organaization または個人アカウントです。 ワークフローを実行すると、4 つの CodeQL クエリ パックが GitHub からダウンロードされ、各パックの既定のクエリまたはクエリ スイートが実行されます。
* 最新バージョンの `pack1` がダウンロードされ、すべての既定のクエリが実行されます。
* バージョン 1.2.3 の `pack2` がダウンロードされ、すべての既定のクエリが実行されます。
* バージョン 3.2.1 と互換性のある最新バージョンの `pack3` がダウンロードされ、すべてのクエリが実行されます。
* バージョン 4.5.6 の `pack4` がダウンロードされ、`path/to/queries` 内で見つかったクエリのみが実行されます。
```yaml copy
- uses: github/codeql-action/init@v4
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 エンジンで効率的に使用できなくなる可能性があります。 最適なパフォーマンスを確保するために、特定のバージョンのクエリ パックを指定する必要がある場合は、ピン留めされたバージョンのクエリ パックをバージョンアップする必要があるかどうかを定期的に確認することを検討してください。
>
> パックの互換性について詳しくは、「[CodeQL クエリパック参照](/ja/enterprise-server@3.20/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility)」をご覧ください。
###
```
CodeQLパックをGitHub Enterprise Serverからダウンロードする
```
ワークフローで、 GitHub Enterprise Server インストールで公開されているパックを使用している場合は、ワークフローに検索先を指定する必要があります。 これを行うには、`registries` アクションのgithub/codeql-action/init\@v4入力を使用します。 この入力は、次に示すように、`url`、`packages`、`token` の各プロパティのリストを受け入れます。
```yaml copy
- uses: github/codeql-action/init@v4
with:
registries: |
# URL to the container registry, usually in this format
- url: https://containers.GHEHOSTNAME1/v2/
# List of package glob patterns to be found at this registry
packages:
- my-company/*
- my-company2/*
# Token, which should be stored as a secret
token: ${{ secrets.GHEHOSTNAME1_TOKEN }}
# URL to the default container registry
- url: https://ghcr.io/v2/
# Packages can also be a string
packages: "*/*"
token: ${{ secrets.GHCR_TOKEN }}
```
レジストリ リストのパッケージ パターンは順番に調べられるので、通常、最も具体的なパッケージ パターンを最初に置く必要があります。 `token` の値は、ダウンロード元のGitHubインスタンスによって生成された、 personal access token (classic) であり、 `read:packages` 権限を持つものでなければなりません。
```
`|` プロパティ名の後の `registries` に注意してください。
GitHub Actions入力は文字列のみを受け取ることができるため、これは重要です。
`|`を使用すると、後続のテキストが文字列に変換され、後で github/codeql-action/init@v4 アクションによって解析されます。
```
### QL パックでクエリを使用する
1 つまたは複数のクエリを追加するには、ワークフローの `with: queries:` セクション内にエントリ `uses: github/codeql-action/init@v4` を追加します。 クエリがプライベート リポジトリ内にある場合は、`external-repository-token` パラメーターを使用して、プライベート リポジトリをチェックアウトするためのアクセス権を持つトークンを指定します。
```
`queries` の値でクエリ スイートを指定することもできます。 クエリ スイートは、通常、目的または言語別にグループ化されたクエリのコレクションです。
```
```yaml copy
- uses: github/codeql-action/init@v4
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 }}
```
以下のクエリスイートはCodeQL code scanningに組み込まれており、利用可能です。
| クエリ スイート | 説明 |
| :--------------------- | :------------------------------------------- |
| `security-extended` | 既定のスイートからのクエリ、および重要度と精度の低いクエリ |
| `security-and-quality` | `security-extended` からのクエリに加え、保守性および信頼性のクエリ。 |
詳細については、「[CodeQL クエリ セット](/ja/enterprise-server@3.20/code-security/code-scanning/managing-your-code-scanning-configuration/built-in-codeql-query-suites)」を参照してください。
これらの各クエリ スイートには、その言語の組み込みの CodeQL クエリ パックに含まれるクエリの異なるサブセットが含まれています。 クエリ スイートは、各クエリのメタデータを使用して自動的に生成されます。 詳細については、「[CodeQL クエリのメタデータ](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/)」を参照してください。
クエリ スイートを指定すると、CodeQL の分析エンジンでは、既定の一連のクエリと、追加のクエリ スイートで定義されている追加クエリが実行されます。
### カスタム構成ファイルの処理
カスタム設定にも構成ファイルを使用する場合は、構成ファイル内に指定されたものではなく、ワークフロー内で指定された追加のパックまたはクエリが使用されます。 追加のパックまたはクエリの組み合わせセットを実行する場合は、ワークフロー内の `packs` または `queries` の値にプレフィックスとして `+` 記号を付けます。 詳細については、「 [カスタム構成ファイル](#custom-configuration-files)」を参照してください。
次の例では、`+` 記号を付けることで、指定した追加のパックとクエリが確実に、参照される構成ファイル内で指定したものと一緒に使用されるようになります。
```yaml copy
- uses: github/codeql-action/init@v4
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
```
## カスタム構成ファイル
カスタム構成ファイルは、実行する追加のパックとクエリを指定するときの代替的な方法です。 また、このファイルを使用して、既定のクエリを無効にしたり、特定のクエリを除外または含めたり、分析中にスキャンするディレクトリを指定したりすることもできます。
ワークフロー ファイルでは、`config-file` アクションの `init` パラメーターを使用して、使用する構成ファイルへのパスを指定します。 この例では、構成ファイル *./.github/codeql/codeql-config.yml* を読み込みます。
```yaml copy
- uses: github/codeql-action/init@v4
with:
config-file: ./.github/codeql/codeql-config.yml
```
構成ファイルは、分析するリポジトリ内、または外部リポジトリ内に格納できます。 外部リポジトリを使用すると、1 つの場所の複数のリポジトリに対して構成オプションを指定できます。 外部リポジトリにある構成ファイルを参照する場合は、 *OWNER/REPOSITORY/FILENAME\@BRANCH* 構文を使用できます。 たとえば、 *octo-org/shared/codeql-config.yml\@main* です。
構成ファイルが外部のプライベート リポジトリにある場合は、`external-repository-token` アクションの `init` パラメーターを使用して、そのプライベート リポジトリへのアクセス権を持つトークンを指定します。
```yaml copy
- uses: github/codeql-action/init@v4
with:
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
```
構成ファイルの設定は、YAML 形式で記述します。
### クエリ パック CodeQL 指定する
```
CodeQL クエリパックを配列で指定します。 形式は、ワークフロー ファイルで使用される形式とは異なるので注意してください。
```
```yaml copy
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 バージョンの範囲です。 指定しない場合は、最新バージョンが使われます。 semver の範囲の詳細については、[npm の semver ドキュメント](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges)を参照してください。
複数の CodeQL データベースを生成するワークフローがある場合は、パックの入れ子になったマップを使用して、カスタム構成ファイルで実行する任意の CodeQL クエリ パックを指定できます。
```yaml copy
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
```
### 脅威モデルを活用したCodeQLのカバレッジ拡張
> \[!NOTE]
> 脅威モデルは現在 パブリック プレビュー 段階であり、変更される可能性があります。 パブリック プレビュー 期間中、脅威モデルは Java/Kotlin と C# 解析でのみサポートされます。
デフォルトの脅威モデルには、信頼されていないデータのリモート ソースが含まれます。 カスタム構成ファイルでCodeQLを指定することで、`threat-models: local`脅威モデルを拡張して、信頼されていないデータのローカル ソース (コマンド ライン引数、環境変数、ファイル システム、データベースなど) を含めることができます。 脅威モデルを拡張すると、デフォルトの脅威モデルも使用されます。
### 追加のクエリを指定する
追加のクエリは `queries` 配列に指定します。 配列の各要素に、単一のクエリ ファイル、クエリ ファイルを含むディレクトリ、またはクエリ スイート定義ファイルを識別する値を持つ `uses`パラメーターを含めます。
```yaml copy
queries:
- uses: ./my-basic-queries/example-query.ql
- uses: ./my-advanced-queries
- uses: ./query-suites/my-security-queries.qls
```
あるいは、以下の設定ファイルの例にあるように、配列の各要素に名前を与えることもできます。 その他のクエリの詳細については、上記 [の既定以外のクエリ](#non-default-queries) を参照してください。
### デフォルトのクエリを無効にする
カスタム クエリのみを実行する場合は、`disable-default-queries: true` を使用して既定のセキュリティ クエリを無効にすることができます。
### 分析からの特定のクエリの除外
カスタム構成ファイルに `exclude` および `include` フィルターを追加して、分析から除外また分析に含めるクエリを指定できます。
たとえば、これは、次のように除外する場合に便利です。
* 既定のスイート (`security`、`security-extended`、および `security-and-quality`) からの特定のクエリ。
* 結果に関心がない特定のクエリ。
* 警告と推奨事項を生成するすべてのクエリ。
以下の構成ファイルと同様の `exclude` フィルターを使用して、既定の分析から削除するクエリを除外できます。 次の構成ファイルの例では、`js/redundant-assignment` および `js/useless-assignment-to-local` クエリの両方が分析から除外されています。
```yaml copy
query-filters:
- exclude:
id: js/redundant-assignment
- exclude:
id: js/useless-assignment-to-local
```
クエリの ID を見つけるには、\[ ** Security** ] タブのアラートの一覧でアラートをクリックします。これにより、アラートの詳細ページが開きます。
`Rule ID` フィールドにはクエリ ID が含まれています。アラート詳細ページについて詳しくは、「[Code scanningアラートについて](/ja/enterprise-server@3.20/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-details)」をご覧ください。
> \[!TIP]
>
> * フィルターの順序が重要です。 クエリとクエリ パックに関する命令の後に表示される最初のフィルター命令によって、既定でクエリを含めるか除外するかが決まります。
> * 後続の命令は順番に実行され、ファイル内で後にある命令の方が前にある命令よりも優先されます。
これらのフィルターの使用方法を示す別の例については、「[サンプル構成ファイル](#example-configuration-files)」セクションを参照してください。
カスタム構成ファイルでの `exclude` および `include` フィルターの使用について詳しくは、「[CodeQL クエリ スイートの作成](/ja/enterprise-server@3.20/code-security/codeql-cli/using-the-advanced-functionality-of-the-codeql-cli/creating-codeql-query-suites#filtering-the-queries-in-a-query-suite)」をご覧ください。 フィルター処理できるクエリ メタデータについて詳しくは、「[CodeQL クエリのメタデータ](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/)」を参照してください。
### スキャンするディレクトリを指定する
コードをビルドせずにコードベースを分析する場合は、構成ファイルにcode scanning配列を追加することで、特定のディレクトリ内のファイルに`paths`を制限できます。
`paths-ignore` 配列を追加して、特定のディレクトリ内のファイルを分析から除外することもできます。 このオプションは、解釈された言語 (Python、Ruby、JavaScript/TypeScript) で CodeQL アクションを実行する場合、またはコードをビルドせずにコンパイル済み言語を分析する場合 (現在 C/C++、 C#、 Java および Rustでサポートされています) に使用できます。
```yaml copy
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
```
> \[!NOTE]
> \*
> `paths`構成ファイルのコンテキストで使用される`paths-ignore`キーワードとcode scanningキーワードは、ワークフロー内の`on..paths`に使用する場合と同じキーワードと混同しないでください。 これらをワークフロー内の `on.` の変更に使用すると、指定されたディレクトリ内のコードが変更されたときにアクションを実行するかどうかが決定されます。 詳しくは、「[GitHub Actions のワークフロー構文](/ja/enterprise-server@3.20/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)」をご覧ください。
>
> * フィルター パターン文字 `?`、`+`、`[`、`]`、`!` はサポートされていないため、文字どおりに照合されます。
> *
```
`**` 文字は、行の先頭または末尾にのみ指定するか、スラッシュで囲むことができます。また、`**` と他の文字を一緒に使用できます。 たとえば `foo/**`、`**/foo`、`foo/**/bar` は、すべて許容される構文ですが、`**foo` は許容されません。 ただし、例に示すように、1 つの星印を他の文字と一緒に使用できます。
```
```
`*` 文字を含むものはすべて引用符で囲む必要があります。
```
コードがビルドされる分析では、プロジェクト内の特定のディレクトリに code scanning を制限する場合は、ワークフローで適切なビルド 手順を指定する必要があります。 ビルドからディレクトリを除外するために使用するコマンドは、ビルド システムによって異なります。 詳しくは、「[コンパイル済み言語の CodeQL コード スキャン](/ja/enterprise-server@3.20/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#adding-build-steps-for-a-compiled-language)」をご覧ください。
特定のディレクトリ内のコードを変更した場合、モノリポの小さな部分をすばやく分析できます。 ビルド ステップでディレクトリを除外すること、およびワークフローで `paths-ignore` の `paths` および `on.` キーワードを使用することが、どちらも必要になります。
### サンプル構成ファイル
この構成ファイルは、コードのスキャン時に CodeQL によって実行されるクエリのリストに `security-and-quality` クエリ スイートを追加します。 使用できるクエリ スイートの詳細については、「 [既定以外のクエリ](#non-default-queries)」を参照してください。
```yaml
name: "My CodeQL config"
queries:
- uses: security-and-quality
```
以下の設定ファイルはデフォルトのクエリを無効化し、その代わりに実行するカスタムクエリのセットを指定します。 また、CodeQL が、*src/node\_modules* ディレクトリと *.test.js* で名前が終わるファイルを除く、*src* ディレクトリ (ルートに対する相対) 内のファイルをスキャンするようにも設定します。
*src/node\_modules* 内のファイルと末尾が *.test.js* で終わる名前のファイルは、分析から除外されます。
```yaml
name: "My CodeQL config"
disable-default-queries: true
queries:
- name: Use an in-repository CodeQL pack (run queries in the my-queries directory)
uses: ./my-queries
- name: Use an external JavaScript CodeQL pack (run queries from an external repo)
uses: octo-org/javascript-codeql-pack@main
- name: Use an external query (run a single query from an external CodeQL pack)
uses: octo-org/python-codeql-pack/show_ifs.ql@main
- name: Use a query suite file (run queries from a query suite in this repo)
uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
```
次の構成ファイルを使用すると、重大度エラーのアラートを生成するクエリのみが実行されます。 構成では、最初にすべての既定のクエリ、`./my-queries` 内のすべてのクエリ、および `codeql/java-queries` 内の既定のスイートを選んでから、警告または推奨事項を生成するすべてのクエリを除外します。
```yaml
queries:
- name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
uses: ./my-queries
packs:
- codeql/java-queries
query-filters:
- exclude:
problem.severity:
- warning
- recommendation
```
## 構成の詳細
ワークフロー ファイルで追加の構成の詳細を指定する場合は、`config` アクションの `init` コマンドのCodeQL入力を使用できます。 この入力の値は、上記の [カスタム構成](#custom-configuration-files) ファイルに記載されている構成ファイル形式に従う YAML 文字列である必要があります。
### 構成例
```
GitHub Actions ワークフロー ファイルのこの手順では、`config`入力を使用して既定のクエリを無効にし、`security-extended`クエリ スイートを追加し、`cwe-020`でタグ付けされたクエリを除外します。
```
```yaml
- uses: github/codeql-action/init@v4
with:
languages: ${{ matrix.language }}
config: |
disable-default-queries: true
threat-models: local
queries:
- uses: security-extended
query-filters:
- exclude:
tags: /cwe-020/
```
同じ方法を使用して、ワークフロー ファイル内の有効な構成オプションを指定できます。
> \[!TIP]
```
GitHub Actions変数を使用して、複数のリポジトリ間で 1 つの構成を共有できます。 この方法の利点の 1 つは、ワークフロー ファイルを編集せずに 1 か所で構成を更新できることです。
```
> 次の例では、 `vars.CODEQL_CONF` は GitHub Actions 変数です。 その値には、有効な構成ファイルの内容を指定できます。 詳しくは、「[変数に情報を格納する](/ja/enterprise-server@3.20/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows)」をご覧ください。
>
> ```yaml
> - uses: github/codeql-action/init@v4
> with:
> languages: ${{ matrix.language }}
> config: ${{ vars.CODEQL_CONF }}
> ```
## コンパイル済み言語
コンパイル済み言語の場合、 CodeQL アクションで分析用の CodeQL データベースを作成する方法を決定できます。 利用可能なビルド オプションについては、「[コンパイル済み言語の CodeQL コード スキャン](/ja/enterprise-server@3.20/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages)」をご覧ください。
## データのアップロード
```
GitHub では、サード パーティ製ツールによって外部から生成されたコード分析データを表示できます。
`upload-sarif` アクションを使用してコード分析データをアップロードできます。 詳しくは、「[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)」をご覧ください。
```