code scanning の設定について
GitHub Actionsを使って、あるいは継続的インテグレーション(CI)システムから、GitHub Enterprise Cloud上でcode scanningを実行できます。 詳細については、「ワークフローの書き込み」または「既存の CI システムでコード スキャンを使用する」を参照してください。
code scanning の高度なセットアップにより、code scanning ワークフローをカスタマイズして、構成をきめ細かく制御できます。 詳しくは、「コード スキャンの高度なセットアップの構成」を参照してください。
CodeQL 解析は、GitHub で実行できる code scanning のほんの一例に過ぎません。 GitHub Marketplace には、使用できる他の code scanning ワークフローが含まれます。 これらの選択肢は、[Get started with code scanning] ページにあります。これには [ Security] タブからアクセスできます。この記事で示す具体的な例は、CodeQL 分析ワークフロー ファイルに関連しています。
code scanningワークフローの編集
GitHub によって、リポジトリの .github/workflows ディレクトリにワークフロー ファイルが保存されます。 追加したワークフローは、そのファイル名を検索して見つけることができます。 たとえば、デフォルトでは、CodeQL code scanning のワークフロー ファイルは、codeql-analysis.yml という名前です。
- リポジトリで、編集したいワークフローファイルにアクセスします。
- ファイル ビューの右上隅の をクリックして、ワークフロー エディターを開きます。
- ファイルを編集したら、[コミットの開始] をクリックし、[変更のコミット] フォームに入力します。 現在のブランチに直接コミットするか、新しいブランチを作成して pull request を開始するかを選択できます。
ワークフロー ファイルの編集について詳しくは、「ワークフローの書き込み」をご覧ください。
頻度を設定する
スケジュール設定されているときや、リポジトリで特定のイベントが発生したときに、コードをスキャンするように CodeQL 分析ワークフローを構成できます。
リポジトリへのプッシュごと、およびプルリクエストが作成されるたびにコードをスキャンすることで、開発者がコードに新しい脆弱性やエラーをもたらすことを防ぎます。 スケジュールに従ってコードをスキャンすると、開発者がリポジトリを積極的に維持していない場合でも、GitHub、セキュリティ研究者、コミュニティが発見した最新の脆弱性とエラーが通知されます。
プッシュ時にスキャンする
デフォルトでは、CodeQL 分析ワークフローで、リポジトリのデフォルトのブランチと保護されたブランチへのプッシュごとにコード スキャンをトリガーするのに on:push
イベントが使用されます。 指定したブランチで code scanning がトリガーされるようにするには、ワークフローがそのブランチに存在している必要があります。 詳しくは、「GitHub Actions のワークフロー構文」を参照してください。
プッシュ時にスキャンすると、結果がリポジトリの [セキュリティ] タブに表示されます。 詳しくは、「リポジトリのコード スキャンのアラートの評価」を参照してください。
さらに、開かれた pull request にマップできる結果が on:push
スキャンから返された場合、これらのアラートは他の pull request アラートと同じ場所にある pull request に自動的に表示されます。 これらのアラートは、ブランチのヘッドの既存の分析とターゲット ブランチの分析を比較することで特定します。 pull request での code scanning アラートについて詳しくは、「pull request で Code scanning アラートをトリアージする」をご覧ください。
Pull Requestをスキャンする
デフォルトの CodeQL 分析ワークフローでは、デフォルトのブランチをターゲットとする pull request のコード スキャンをトリガーするのに pull_request
イベントが使用されます。 pull request がプライベート フォークからのものである場合、pull_request
イベントは、リポジトリの設定で [フォークの pull request からワークフローを実行] オプションを選択している場合にのみトリガーされます。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」をご覧ください。
pull_request
イベントについて詳しくは、「ワークフローをトリガーするイベント」をご覧ください。
pull requests をスキャンすると、結果は pull request チェックのアラートとして表示されます。 詳しくは、「pull request で Code scanning アラートをトリアージする」を参照してください。
ヘッド コミットではなく pull request のマージ コミットをスキャンするように構成された pull_request
トリガーを使用すると、各プッシュでブランチのヘッドをスキャンする場合より効果的で正確な結果が生成されます。 ただし、使用している CI/CD システムで、pull request でトリガーするように構成できない場合でも、on:push
トリガーは引き続き使用できます。また、code scanning により、結果がブランチの開いている pull request にマッピングされ、アラートが注釈としてその pull request に追加されます。 詳細については、「プッシュ時のスキャン」を参照してください。
Note
ご利用のリポジトリがマージ キューで構成されている場合は、code scanning に対する追加トリガーとして merge_group
イベントを含める必要があります。 これにより、pull request がマージ キューに追加されたときにもスキャンされます。 詳しくは、「マージキューの管理」を参照してください。
Pull Requestの不要なスキャンを回避する
変更されたファイルに関係なく、デフォルトのブランチを対象とする特定の pull request でコード スキャンがトリガーされないようにしたい場合があります。 これを構成するには、code scanning ワークフローで on:pull_request:paths-ignore
または on:pull_request:paths
を指定します。 たとえば、pull request 内の変更がファイル拡張子 .md
または .txt
のファイルに対するものだけである場合、次の paths-ignore
配列を使用できます。
on: push: branches: [main, protected] pull_request: branches: [main] paths-ignore: - '**/*.md' - '**/*.txt'
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 で変更されたすべてのファイルがスキャンされます。 分析からファイルを除外する方法については、「スキャンするディレクトリを指定する」を参照してください。
on:pull_request:paths-ignore
と on:pull_request:paths
を使って pull request に対してワークフローをいつ実行するかを決定する方法について詳しくは、「GitHub Actions のワークフロー構文」をご覧ください。
スケジュールに従ってスキャンする
デフォルトの CodeQL 分析ワークフローを使用すると、このワークフローではイベントによってトリガーされるスキャンに加えて、リポジトリ内のコードが週に 1 回スキャンされます。 このスケジュールを調整するには、ワークフローの cron
値を編集します。 詳しくは、「GitHub Actions のワークフロー構文」を参照してください。
Note
GitHub では、既定のブランチのワークフロー内にあるスケジュール設定されたジョブのみが実行されます。 他のブランチのワークフローでスケジュールを変更しても、ブランチをデフォルトブランチにマージするまで影響はありません。
例
次の例は、デフォルトのブランチの名前が main
で、protected
という名前の保護されたブランチがある特定のリポジトリの CodeQL 分析ワークフローを示しています。
on: push: branches: [main, protected] pull_request: branches: [main] schedule: - cron: '20 14 * * 1'
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
schedule:
- cron: '20 14 * * 1'
このワークフローでは以下をスキャンします。
- デフォルトのブランチと保護されたブランチへのすべてのプッシュ
- デフォルトのブランチへのすべての pull request
- 毎週月曜日 14 時 20 分 (UTC) にデフォルトのブランチ
オペレーティングシステムを指定する
Note
-
Swift コードのコード スキャンでは、デフォルトで macOS ランナーが使用されます。 GitHub でホストされている macOS ランナーは Linux や Windows ランナーよりも高価であるため、ビルド ステップのスキャンのみを検討する必要があります。 Swift のコード スキャンの構成の詳細については、「AUTOTITLE」を参照してください。 GitHub でホストされているランナーの料金の詳細については、「GitHub Actions の課金について」を参照してください。
-
Swift コードの Code scanning は、Actions Runner Controller (ARC) の一部であるランナーではサポートされていません。ARC をキャプチャするランナーでは Linux のみが使用されるため、Swift には macOS ランナーが必要です。 ただし、ARC をキャプチャする ランナーとセルフホストの macOS ランナーの両方を組み合わせることもできます。 詳しくは、「Actions Runner Controller について」を参照してください。
コードのコンパイルに特定のオペレーティング システムが必要な場合は、そのオペレーティング システムを CodeQL 分析ワークフローで構成できます。 jobs.analyze.runs-on
の値を編集して、code scanning アクションを実行するコンピューターのオペレーティング システムを指定します。
jobs: analyze: name: Analyze runs-on: [ubuntu-latest]
jobs:
analyze:
name: Analyze
runs-on: [ubuntu-latest]
Code Scanning にセルフホスト ランナーを使うことにした場合は、2 つの要素からなる配列の 2 番目の要素として、self-hosted
の後に、適切なラベルを使用して、オペレーティング システムを指定できます。
jobs: analyze: name: Analyze runs-on: [self-hosted, ubuntu-latest]
jobs:
analyze:
name: Analyze
runs-on: [self-hosted, ubuntu-latest]
CodeQL code scanning は、Ubuntu、Windows、および macOS の最新バージョンをサポートしています。 したがって、この設定の一般的な値は、ubuntu-latest
、windows-latest
、macos-latest
です。 詳細については、「ジョブのランナーを選択する」および「セルフホストランナーとのラベルの利用」を参照してください。
セルフホステッド ランナーを使う場合は、Git が PATH 変数内にあることを確認する必要があります。詳しくは、「自己ホスト ランナーの概要」と「自己ホストランナーの追加」をご覧ください。
セルフホステッド マシンで CodeQL 分析を実行するための推奨仕様 (RAM、CPU コア数、ディスク) については、「CodeQL を実行するための推奨ハードウェア リソース」をご覧ください。
CodeQLデータベースの場所の指定
一般に、CodeQL 分析ワークフローで CodeQL データベースが配置される場所について気にする必要はありません。これは、前のステップで作成されたデータベースが後のステップで自動的に検出されるためです。 ただし、カスタムのワークフロー ステップを記述していて、CodeQL データベースをワークフロー成果物としてアップロードするなど、そのデータベースが特定のディスクの場所にあることが必要な場合は、init
アクションの db-location
パラメーターを使ってその場所を指定できます。
- uses: github/codeql-action/init@v3 with: db-location: '${{ github.runner_temp }}/my_location'
- uses: github/codeql-action/init@v3
with:
db-location: '${{ github.runner_temp }}/my_location'
CodeQL 分析ワークフローでは、db-location
に指定されるパスが書き込み可能であり、存在しないか空のディレクトリであると想定されています。 セルフホストランナー上で動作するか、Dockerコンテナを使うジョブでこのパラメーターを使う場合、選択されたディレクトリが実行間でクリアされること、あるいは不要になったらデータベースが削除されることを保証するのはユーザーの責任です。 これは、実行のたびに新しいインスタンスとクリーンなファイルシステムが取得される GitHub ホスト ランナー上で動作するジョブには必要ありません。 詳しくは、「GitHub ホステッド ランナーの使用」を参照してください。
このパラメーターが使われていない場合、CodeQL 分析ワークフローでは、データベースが任意の一時的な場所に作成されます。 現在、デフォルト値は ${{ github.runner_temp }}/codeql_databases
です。
解析される言語を変更する
CodeQL code scanningは、自動的にサポートする言語で書かれたコードを検出します。
- C/C++
- C#
- Go
- Java/Kotlin
- JavaScript/TypeScript
- Python
- Ruby
- Swift
Note
java-kotlin
を使用して、Java、Kotlin、またはその両方で記述されたコードを分析します。javascript-typescript
を使用して、JavaScript、TypeScript、またはその両方で記述されたコードを分析します。
詳細については、CodeQL Web サイトのドキュメント「サポートされている言語とフレームワーク」を参照してください。
CodeQL では、次の言語識別子が使用されます。
言語 | 識別子 | オプションの代替識別子 (存在する場合) |
---|---|---|
C/C++ | c-cpp | c または cpp |
C# | csharp | |
Go | go | |
Java/Kotlin | java-kotlin | java または kotlin |
JavaScript/TypeScript | javascript-typescript | javascript または typescript |
Python | python | |
Ruby | ruby | |
Swift | swift |
Note
代替識別子の 1 つを指定した場合、これは標準の言語識別子の使用と同じです。 たとえば、javascript-typescript
の代わりに javascript
を指定した場合、TypeScript コードの分析は除外されません。 これは、--paths-ignore
オプションを使用して高度なセットアップ ワークフローで行うことができます。 詳しくは、「コード スキャン用の高度なセットアップのカスタマイズ」を参照してください。
デフォルトの CodeQL 分析ワークフロー ファイルには、language
というマトリックスが含まれ、リポジトリ内の分析対象の言語が一覧表示されています。 CodeQLは、code scanningがリポジトリに追加されたときにこのマトリクスを自動的に作成します。 language
マトリックスを使用すると、CodeQL で各解析が並行して実行されるように最適化されます。 ビルドを並列化するとパフォーマンスが向上するため、すべてのワークフローでこの構成を採用することをお勧めします。 マトリックスについて詳しくは、「ワークフローでのジョブのバリエーションの実行」をご覧ください。
サポートされている 1 つ以上の言語のコードがリポジトリに含まれている場合は、分析する言語を選択できます。 言語が分析されないようにする理由は、いくつかあります。 たとえば、プロジェクトで、コードの本体に対する依存関係が別の言語の中にあり、それらの依存関係のアラートを表示したくない場合が考えられます。
ワークフローで language
マトリックスを使用する場合、CodeQL はマトリックス内の言語だけを分析するようにハードコードされています。 分析する言語を変更するには、マトリックス変数の値を編集します。 解析されないように言語を削除したり、code scanning を構成したときにはリポジトリに存在しなかった言語を追加したりできます。 たとえば、code scanning が構成されたとき、リポジトリには当初 JavaScript しか含まれておらず、後で Python のコードを追加した場合は、マトリックスに python
を追加する必要があります。
jobs: analyze: name: Analyze ... strategy: fail-fast: false matrix: language: ['javascript-typescript', 'python']
jobs:
analyze:
name: Analyze
...
strategy:
fail-fast: false
matrix:
language: ['javascript-typescript', 'python']
ワークフローに language
という名前のマトリックスが含まれていない場合は、CodeQL は解析を順次実行するように設定されます。 ワークフロー中で言語を指定していない場合、CodeQLはリポジトリ中のサポートされている言語を検出し、分析しようとします。 マトリックスは使用せず、分析する言語を選択する場合は、init
アクションの下の languages
パラメーターを使用できます。
- uses: github/codeql-action/init@v3 with: languages: c-cpp, csharp, python
- uses: github/codeql-action/init@v3
with:
languages: c-cpp, csharp, python
pull request チェック エラーの原因となるアラートの重大度を定義する
ルールセットを使用すると、次のいずれかの条件が満たされたときに pull request がマージされないようにできます。
-
必要なツールで、ルール セットで定義している重大度の code scanning アラートが見つかりました。
-
必要な code scanning ツールはまだ分析中です。
-
必要な code scanning ツールはリポジトリ用に構成されていません。
詳しくは、「コード スキャンのマージ保護を設定します」を参照してください。 ルールセットについて一般的な情報は、「ルールセットについて」をご覧ください。
分析のカテゴリの設定
category
を使用して、同じツールとコミットに対して、異なる言語またはコードの異なる部分に対して実行される複数の解析を区別します。 ワークフロー中で指定したカテゴリは、SARIF結果ファイルに含まれます。
このパラメーターは、特に単一リポジトリで作業をしていて、単一リポジトリの様々なコンポーネントに対して複数のSARIFファイルがある場合に有益です。
- name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v3 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"
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v3
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 Enterprise Cloud によって、アクションをトリガーするワークフロー ファイルの名前、アクション名、任意のマトリックス変数に基づいて、カテゴリ名が生成されます。 たとえば次のような点です。
.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 の <run>.automationDetails.id
プロパティとして表示されます。 詳しくは、「Code scanningの SARIF サポート」を参照してください。
指定したカテゴリは、SARIF ファイルに runAutomationDetails
オブジェクトの詳細が含まれている場合、上書きされることはありません。
CodeQL モデル パックを使用した CodeQL カバレッジの拡張
コードベースが CodeQL の標準クエリで認識されないライブラリまたはフレームワークに依存している場合は、発行された CodeQL モデル パックを指定することで、code scanning ワークフローの CodeQL カバレッジを拡張できます。 独自のモデル パックの作成に関する詳細については、「CodeQL パックの作成と操作」を参照してください。
Note
CodeQL モデル パックと CodeQL モデル エディターは現在 パブリック プレビュー であり、変更される可能性があります。 モデル パックは C#、Java/Kotlin、Python、および Ruby 分析でサポートされます。
CodeQL モデル パックを使用する
1 つ以上の CodeQL モデル パックを追加するには、ワークフローの uses: github/codeql-action/init@v3
セクションをもつ with: packs:
エントリ内のモデル パックを追加します。 packs
内で、使用するパッケージを 1 つ以上指定し、必要に応じて、ダウンロードするバージョンを指定します。 バージョンを指定しない場合は、最新バージョンがダウンロードされます。 公開されていないパッケージを使用する場合は、GITHUB_TOKEN
環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。 詳細については、「自動トークン認証」および「GitHub Actions でのシークレットの使用」を参照してください。
- uses: github/codeql-action/init@v3 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
- uses: github/codeql-action/init@v3
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 に対して実行され、クエリ パックmy-company/my-java-queries
の 7.8.9
より大きいか、7.9.0
より小さいバージョンからのクエリも実行されます。 最新バージョンのモデル パック my-repo/my-java-model-pack
でモデル化された依存関係により、デフォルトのクエリと my-company/my-java-queries
のクエリ両方が使用できます。
追加のクエリを実行する
コードをスキャンするためにCodeQLを使う場合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。
また、分析から除外するクエリを指定したり、分析に含めたりすることもできます。 これには、カスタム構成ファイルを使用する必要があります。 詳しくは、以下の「カスタム構成ファイルの使用」および「分析からの特定のクエリの除外」を参照してください。
追加のクエリは、GitHub Container registry に公開される CodeQL パック、またはリポジトリに格納される CodeQL パックの一部である場合に実行できます。 詳しくは、「CodeQL によるコード スキャンについて」を参照してください。
追加で実行したいクエリを指定するのに使用できるオプションは、次のとおりです。
packs
1 つまたは複数の CodeQL クエリ パックをインストールし、それらのパックに対して既定のクエリ スイートまたはクエリを実行します。queries
1 つの .ql ファイル、複数の .ql ファイルを含むディレクトリ、 .qls クエリ スイート定義ファイル、または任意の組み合わせを指定します。 クエリ スイート定義の詳細については、「CodeQL クエリ スイートの作成」を参照してください。
同じワークフローで packs
と queries
の両方を使用できます。
github/codeql/cpp/ql/src@main
のように、github/codeql
リポジトリから直接クエリ スイートを参照することはお勧めしません。 このようなクエリは再コンパイルする必要があり、現在 GitHub Actions でアクティブになっている CodeQL のバージョンと互換性がないため、分析中にエラーが発生する可能性があります。
クエリ パックの使用
1 つ以上の CodeQL クエリ パックを追加するには、ワークフローの uses: github/codeql-action/init@v3
セクション内に with: packs:
エントリを追加します。 packs
内で、使用するパッケージを 1 つ以上指定し、必要に応じて、ダウンロードするバージョンを指定します。 バージョンを指定しない場合は、最新バージョンがダウンロードされます。 公開されていないパッケージを使用する場合は、GITHUB_TOKEN
環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。 詳細については、「自動トークン認証」および「GitHub Actions でのシークレットの使用」を参照してください。
Note
複数の言語の CodeQL データベースを生成するワークフローでは、構成ファイルで CodeQL クエリ パックを代わりに指定する必要があります。 詳細については、以下の「CodeQL クエリ パックの指定」を参照してください。
次の例では、scope
は、パッケージを公開した Organaization または個人アカウントです。 ワークフローを実行すると、4 つの CodeQL クエリ パックが GitHub Enterprise Cloud からダウンロードされ、各パックのデフォルトのクエリまたはクエリ スイートが実行されます。
- 最新バージョンの
pack1
がダウンロードされ、すべてのデフォルトのクエリが実行されます。 - バージョン 1.2.3 の
pack2
がダウンロードされ、すべてのデフォルトのクエリが実行されます。 - バージョン 3.2.1 と互換性のある最新バージョンの
pack3
がダウンロードされ、すべてのクエリが実行されます。 - バージョン 4.5.6 の
pack4
がダウンロードされ、path/to/queries
内で見つかったクエリのみが実行されます。
- uses: github/codeql-action/init@v3 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
- uses: github/codeql-action/init@v3
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 パックを発行して使用する」をご覧ください。
GitHub Enterprise Server から CodeQL パックをダウンロードする
GitHub Enterprise Server のインストールで発行されたパックがワークフローで使われている場合は、それを見つける場所をワークフローに指示する必要があります。 これを行うには、github/codeql-action/init@v3 アクションの registries
入力を使います。 この入力は、次に示すように、url
、packages
、token
の各プロパティのリストを受け入れます。
- uses: github/codeql-action/init@v3 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 }}
- uses: github/codeql-action/init@v3
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
の値は、read:packages
アクセス許可でのダウンロード元の GitHub インスタンスによって生成された personal access token (classic) にする必要があります。
registries
プロパティ名の後の |
に注意してください。 GitHub Actions の入力は文字列のみを受け取ることができるため、これは重要です。 |
を使うと、後続のテキストが文字列に変換され、それが後で github/codeql-action/init@v3 アクションによって解析されます。
QL パックでクエリを使用する
1 つまたは複数のクエリを追加するには、ワークフローの uses: github/codeql-action/init@v3
セクション内にエントリ with: queries:
を追加します。 クエリがプライベート リポジトリ内にある場合は、external-repository-token
パラメーターを使用して、プライベート リポジトリをチェックアウトするためのアクセス権を持つトークンを指定します。
queries
の値でクエリ スイートを指定することもできます。 クエリ スイートは、通常、目的または言語別にグループ化されたクエリのコレクションです。
- uses: github/codeql-action/init@v3 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 }}
- uses: github/codeql-action/init@v3
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 クエリ スイート」を参照してください。
これらの各クエリ スイートには、その言語の組み込みの CodeQL クエリ パックに含まれるクエリの異なるサブセットが含まれています。 クエリ スイートは、各クエリのメタデータを使用して自動的に生成されます。 詳しくは、「CodeQL クエリのメタデータ」をご覧ください。
クエリ スイートを指定すると、CodeQL の分析エンジンでは、既定の一連のクエリと、追加のクエリ スイートで定義されている追加クエリが実行されます。
カスタム構成ファイルの処理
カスタム設定にも構成ファイルを使用する場合は、構成ファイル内に指定されたものではなく、ワークフロー内で指定された追加のパックまたはクエリが使用されます。 追加のパックまたはクエリの組み合わせセットを実行する場合は、ワークフロー内の packs
または queries
の値の前に +
記号を付けます。 詳細については、「カスタム構成ファイルの使用」を参照してください。
次の例では、+
記号を付けることで、指定した追加のパックとクエリが確実に、参照される構成ファイル内で指定したものと一緒に使用されるようになります。
- uses: github/codeql-action/init@v3 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
- uses: github/codeql-action/init@v3
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
カスタム構成ファイルの使用
カスタム構成ファイルは、実行する追加のパックとクエリを指定するときの代替的な方法です。 また、このファイルを使用して、既定のクエリを無効にしたり、特定のクエリを除外または含めたり、分析中にスキャンするディレクトリを指定したりすることもできます。
ワークフロー ファイルでは、init
アクションの config-file
パラメーターを使用して、使用する構成ファイルへのパスを指定します。 この例では、構成ファイル ./.github/codeql/codeql-config.yml を読み込みます。
- uses: github/codeql-action/init@v3 with: 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 }}
- uses: github/codeql-action/init@v3
with:
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
構成ファイルの設定は、YAML 形式で記述します。
CodeQL クエリ パックを指定する
配列に CodeQL クエリ パックを指定します。 形式は、ワークフロー ファイルで使用される形式とは異なるので注意してください。
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
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 ドキュメントを参照してください。
複数の 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
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# 解析でのみサポートされます。
デフォルトの脅威モデルには、信頼されていないデータのリモート ソースが含まれます。 カスタム構成ファイルで threat-models: local
を指定することで、信頼されていないデータのローカル ソース (コマンド ライン引数、環境変数、ファイル システム、データベースなど) を含むように、CodeQL 脅威モデルを 拡張できます。 脅威モデルを拡張すると、デフォルトの脅威モデルも使用されます。
追加のクエリを指定する
追加のクエリは queries
配列に指定します。 配列の各要素に、単一のクエリ ファイル、クエリ ファイルを含むディレクトリ、またはクエリ スイート定義ファイルを識別する値を持つ uses
パラメーターを含めます。
queries: - uses: ./my-basic-queries/example-query.ql - uses: ./my-advanced-queries - uses: ./query-suites/my-security-queries.qls
queries:
- uses: ./my-basic-queries/example-query.ql
- uses: ./my-advanced-queries
- uses: ./query-suites/my-security-queries.qls
あるいは、以下の設定ファイルの例にあるように、配列の各要素に名前を与えることもできます。 追加のクエリの詳細については、前述の「追加のクエリを実行する」を参照してください。
デフォルトのクエリを無効にする
カスタム クエリのみを実行する場合は、disable-default-queries: true
を使用してデフォルトのセキュリティ クエリを無効にすることができます。
分析からの特定のクエリの除外
カスタム構成ファイルに 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
query-filters:
- exclude:
id: js/redundant-assignment
- exclude:
id: js/useless-assignment-to-local
クエリの ID を見つけるには、 [Security] タブのアラートの一覧でアラートをクリックします。これにより、アラートの詳細ページが開きます。 Rule ID
フィールドにはクエリ ID が含まれています。アラート詳細ページについて詳しくは、「Code scanningアラートについて」をご覧ください。
Tip
- フィルターの順序が重要です。 クエリとクエリ パックに関する命令の後に表示される最初のフィルター命令によって、デフォルトでクエリを含めるか除外するかが決まります。
- 後続の命令は順番に実行され、ファイル内で後にある命令の方が前にある命令よりも優先されます。
これらのフィルターの使用方法を示す別の例については、「サンプル構成ファイル」セクションを参照してください。
カスタム構成ファイルでの exclude
および include
フィルターの使用について詳しくは、「CodeQL クエリ スイートの作成」をご覧ください。 フィルター処理できるクエリ メタデータについて詳しくは、「CodeQL クエリのメタデータ」を参照してください。
スキャンするディレクトリを指定する
コードをビルドせずにコードベースを分析する場合は、構成ファイルに paths
配列を追加することで、code scanning を特定のディレクトリ内のファイルに制限できます。 paths-ignore
配列を追加すると、特定のディレクトリ内のファイルを分析から除外することもできます。 このオプションは、インタープリタ型言語 で CodeQL アクションを実行する場合、またはコードをビルドせずにコンパイル済み言語を分析する場合に使用できます (現在 C# および Java) でサポートされている)。
paths: - src paths-ignore: - src/node_modules - '**/*.test.js'
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
Note
- code scanning 構成ファイルのコンテキストで使用される
paths
およびpaths-ignore
キーワードを、ワークフローのon.<push|pull_request>.paths
で使用する同じキーワードと混同しないでください。 これらをワークフロー内のon.<push|pull_request>
の変更に使用すると、指定されたディレクトリ内のコードが変更されたときにアクションを実行するかどうかが決定されます。 詳しくは、「GitHub Actions のワークフロー構文」を参照してください。 - フィルター パターン文字
?
、+
、[
、]
、!
はサポートされていないため、文字どおりに照合されます。 **
文字は、行の先頭または末尾にのみ指定するか、スラッシュで囲むことができます。また、**
と他の文字を一緒に使用できます。 たとえばfoo/**
、**/foo
、foo/**/bar
は、すべて許容される構文ですが、**foo
は許容されません。 ただし、例に示すように、1 つの星印を他の文字と一緒に使用できます。*
文字を含むものはすべて引用符で囲む必要があります。
コードがビルドされる分析で、code scanning をプロジェクト内の特定のディレクトリに制限する場合は、ワークフローで適切なビルド ステップを指定する必要があります。 ビルドからディレクトリを除外するために使用するコマンドは、ビルド システムによって異なります。 詳しくは、「コンパイル済み言語の CodeQL コード スキャン」を参照してください。
特定のディレクトリ内のコードを変更した場合、モノリポの小さな部分をすばやく分析できます。 ビルド ステップでディレクトリを除外することと、ワークフローで on.<push|pull_request>
の paths-ignore
および paths
キーワードを使用することの両方が必要になります。
サンプル構成ファイル
この構成ファイルは、コードのスキャン時に CodeQL によって実行されるクエリのリストに security-and-quality
クエリ スイートを追加します。 使用できるクエリ スイートの詳細については、「追加のクエリを実行する」を参照してください。
name: "My CodeQL config"
queries:
- uses: security-and-quality
以下の設定ファイルはデフォルトのクエリを無効化し、その代わりに実行するカスタムクエリのセットを指定します。 また、CodeQL が、src/node_modules ディレクトリと .test.js で名前が終わるファイルを除く、src ディレクトリ (ルートに対する相対) 内のファイルをスキャンするようにも設定します。 src/node_modules 内のファイルと末尾が .test.js で終わる名前のファイルは、分析から除外されます。
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
内の既定のスイートを選んでから、警告または推奨事項を生成するすべてのクエリを除外します。
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
入力を使用した構成の詳細の指定
ワークフロー ファイルで追加の構成詳細を指定したい場合は、CodeQL アクションの init
コマンドのconfig
入力を使用できます。 この入力の値は、上記の「カスタム構成ファイルの使用」に記載されている構成ファイル形式に従う YAML 文字列である必要があります。
構成例
GitHub Actions ワークフロー ファイルのこのステップでは、config
入力を使用してデフォルトのクエリを無効にし、security-extended
クエリ スイートを追加し、cwe-020
でタグ付けされたクエリを除外します。
- uses: github/codeql-action/init@v3
with:
languages: ${{ matrix.language }}
config: |
disable-default-queries: true
queries:
- uses: security-extended
query-filters:
- exclude:
tags: /cwe-020/
同じ方法を使用して、ワークフロー ファイル内の有効な構成オプションを指定できます。
Tip
GitHub Actions 変数を使用して、複数のリポジトリ間で 1 つの構成を共有できます。 この方法の利点の 1 つは、ワークフロー ファイルを編集せずに 1 か所で構成を更新できることです。
次の例では、vars.CODEQL_CONF
は GitHub Actions 変数です。 その値には、有効な構成ファイルの内容を指定できます。 詳しくは、「変数に情報を格納する」を参照してください。
- uses: github/codeql-action/init@v3
with:
languages: ${{ matrix.language }}
config: ${{ vars.CODEQL_CONF }}
コンパイルされた言語の code scanning を設定する
コンパイル言語の場合、CodeQL アクションで分析用の CodeQL データベースを作成する方法を決定できます。 利用可能なビルド オプションについては、「コンパイル済み言語の CodeQL コード スキャン」を参照してください。
code scanning データを GitHub にアップロードする
GitHubは、サードパーティのツールによって外部で生成されたコード分析データを表示できます。 upload-sarif
アクションを使用してコード分析データをアップロードできます。 詳しくは、「SARIF ファイルを GitHub にアップロードする」を参照してください。