code scanning の設定について
GitHub Actionsを使って、あるいは継続的インテグレーション(CI)システムから、GitHub上でcode scanningを実行できます。 詳細については、GitHub Actions に関するページまたは「CI システムの CodeQL code scanning について」を参照してください。
code scanning の場合、既定の設定も詳細設定も両方 GitHub Actions で実行されます。 既定の設定では、お使いのリポジトリに最適な code scanning 構成が自動的に検出されます。一方、詳細設定では、code scanning ワークフローをカスタマイズできます。 詳細については、「リポジトリの code scanning の構成」を参照してください。この記事では、code scanning の詳細設定を構成する方法について説明します。
詳細設定では、GitHub の CodeQL 分析ワークフロー などのワークフローを編集し、スキャンの頻度、スキャンする言語やディレクトリ、code scanning を使ったコード内での検索対象を指定できます。 また、特定のコマンド セットを使ってコードをコンパイルする場合は、ワークフローを編集する必要もあるかもしれません。
CodeQL 解析は、GitHub で実行できる code scanning のほんの一例に過ぎません。 GitHub Marketplace には、使用できる他の code scanning ワークフローが含まれます。 これらの選択肢は、 [ セキュリティ] タブからアクセスできる「code scanning を開始する」ページにあります。 この記事で示す例は、CodeQL 分析ワークフロー ファイルに関連しています。
code scanningワークフローの編集
GitHub によって、リポジトリの .github/workflows ディレクトリにワークフロー ファイルが保存されます。 追加したワークフローは、そのファイル名を検索して見つけることができます。 たとえば、既定では、CodeQL code scanning のワークフロー ファイルは、codeql-analysis.yml という名前です。
- リポジトリで、編集したいワークフローファイルにアクセスします。
- ファイル ビューの右上隅の をクリックして、ワークフロー エディターを開きます。
- ファイルを編集したら、[コミットの開始] をクリックし、[変更のコミット] フォームに入力します。 現在のブランチに直接コミットするか、新しいブランチを作成して pull request を開始するかを選択できます。
ワークフロー ファイルの編集の詳細については、「GitHub Actions について学ぶ」を参照してください。
頻度を設定する
スケジュール設定されているときや、リポジトリで特定のイベントが発生したときに、コードをスキャンするように CodeQL 分析ワークフローを構成できます。
リポジトリへのプッシュごと、およびプルリクエストが作成されるたびにコードをスキャンすることで、開発者がコードに新しい脆弱性やエラーをもたらすことを防ぎます。 スケジュールに従ってコードをスキャンすると、開発者がリポジトリを積極的に維持していない場合でも、GitHub、セキュリティ研究者、コミュニティが発見した最新の脆弱性とエラーが通知されます。
プッシュ時にスキャンする
既定では、CodeQL 分析ワークフローで、リポジトリの既定のブランチと保護されたブランチへのプッシュごとにコード スキャンをトリガーするのに on.push
イベントが使用されます。 指定したブランチで code scanning がトリガーされるようにするには、ワークフローがそのブランチに存在している必要があります。 詳細については、GitHub Actions のワークフロー構文に関するページを参照してください。
プッシュ時にスキャンすると、結果がリポジトリの [セキュリティ] タブに表示されます。 詳細については、「リポジトリの code scanning アラートの管理」を参照してください。
さらに、開かれた 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 に追加されます。 詳細については、「プッシュ時のスキャン」を参照してください。
pull request チェック エラーの原因となる重大度を定義する
既定では、重大度レベルが Error
または セキュリティの重大度レベルが Critical
か High
であるアラートの場合にのみ、pull request チェック エラーが発生し、重大度が低いアラートではチェックは成功します pull request チェック エラーを引き起こすアラートの重大度とセキュリティの重大度のレベルは、リポジトリの設定で変更できます。 重大度レベルの詳細については、Code Scanning アラートについてのページを参照してください。
-
GitHub.com で、リポジトリのメイン ページへ移動します。 1. リポジトリ名の下の [ 設定] をクリックします。
-
サイドバーの [セキュリティ] セクションで、 [コードのセキュリティと分析] をクリックします。
-
"Code scanning"の下で、"Check Failure(チェックの失敗)"の右のドロップダウンメニューを使い、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: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 で変更されたすべてのファイルがスキャンされます。 分析からファイルを除外する方法については、「スキャンするディレクトリを指定する」を参照してください。- CodeQL code scanning ワークフロー ファイルの場合、
on:push
イベントでpaths-ignore
またはpaths
キーワードを使用しないでください。解析に漏れが生じるおそれがあります。 正確な結果を得るには、CodeQL code scanning が新しい変更を前回のコミットの解析と比較できる必要があります。
on:pull_request:paths-ignore
と on:pull_request:paths
を使用して pull request に対してワークフローをいつ実行するかを決定する方法については、「GitHub Actions のワークフロー構文」を参照してください。
スケジュールに従ってスキャンする
既定の CodeQL 分析ワークフローを使用すると、このワークフローではイベントによってトリガーされるスキャンに加えて、リポジトリ内のコードが週に 1 回スキャンされます。 このスケジュールを調整するには、ワークフローの cron
値を編集します。 詳細については、GitHub Actions のワークフロー構文に関するページを参照してください。
メモ: GitHub では、既定のブランチのワークフロー内にあるスケジュール設定されたジョブのみが実行されます。 他のブランチのワークフローでスケジュールを変更しても、ブランチをデフォルトブランチにマージするまで影響はありません。
例
次の例は、既定のブランチの名前が main
で、protected
という名前の保護されたブランチがある特定のリポジトリの CodeQL 分析ワークフローを示しています。
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
schedule:
- cron: '20 14 * * 1'
このワークフローでは以下をスキャンします。
- 既定のブランチと保護されたブランチへのすべてのプッシュ
- 既定のブランチへのすべての pull request
- 毎週月曜日 14 時 20 分 (UTC) に既定のブランチ
オペレーティングシステムを指定する
コードのコンパイルに特定のオペレーティング システムが必要な場合は、そのオペレーティング システムを CodeQL 分析ワークフローで構成できます。 jobs.analyze.runs-on
の値を編集して、code scanning アクションを実行するコンピューターのオペレーティング システムを指定します。
jobs:
analyze:
name: Analyze
runs-on: [ubuntu-latest]
Code Scanning にセルフホスト ランナーを使うことにした場合は、2 つの要素からなる配列の 2 番目の要素として、self-hosted
の後に、適切なラベルを使用して、オペレーティング システムを指定できます。
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@v2
with:
db-location: '${{ github.workspace }}/codeql_dbs'
CodeQL 分析ワークフローでは、db-location
に指定されるパスが書き込み可能であり、存在しないか空のディレクトリであると想定されています。 セルフホストランナー上で動作するか、Dockerコンテナを使うジョブでこのパラメータを使う場合、選択されたディレクトリが実行間でクリアされること、あるいは不要になったらデータベースが削除されることを保証するのはユーザの責任です。 これは、実行のたびに新しいインスタンスとクリーンなファイルシステムが取得される GitHub ホスト ランナー上で動作するジョブには必要ありません。 詳細については、「GitHub ホスト ランナーの概要」を参照してください。
このパラメーターが使われていない場合、CodeQL 分析ワークフローでは、データベースが任意の一時的な場所に作成されます。
解析される言語を変更する
CodeQL code scanningは、自動的にサポートする言語で書かれたコードを検出します。
- C/C++
- C#
- Go
- Java/Kotlin
- JavaScript/TypeScript
- Python
- Ruby
注:
- Kotlin の CodeQL 分析は、現在ベータ版です。 ベータ版の間、Kotlin の分析は他の言語の CodeQL 分析ほど包括的ではありません。
- Java、Kotlin、またはその両方で記述されたコードを分析するには
java
を使用します。 - JavaScript、TypeScript、またはその両方で記述されたコードを分析するには
javascript
を使用します。
詳細については、CodeQL Web サイトのドキュメント「サポートされている言語とフレームワーク」を参照してください。
既定の 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', 'python']
ワークフローに language
という名前のマトリックスが含まれていない場合は、CodeQL は解析を順次実行するように設定されます。 ワークフロー中で言語を指定していない場合、CodeQLはリポジトリ中のサポートされている言語を検出し、分析しようとします。 マトリックスは使用せず、分析する言語を選択する場合は、init
アクションの下の languages
パラメーターを使用できます。
- uses: github/codeql-action/init@v2
with:
languages: cpp, csharp, python
追加のクエリを実行する
Linux だけを使う GitHub でホストされているランナーの場合、CodeQL 分析ワークフローでは、CodeQL 分析でさらに結果を得るためにために Python 依存関係の自動インストールが試みられます。 この動作は、"Initialize CodeQL" ステップで呼び出されるアクションに setup-python-dependencies
パラメーターを指定することで制御できます。 既定では、このパラメーターは true
に設定されます。
-
リポジトリがPythonで書かれたコードを含むなら、"Initialize CodeQL"ステップは必要な依存関係をGitHubがホストするランナーにインストールします。 また、自動インストールが成功すると、このアクションによって、環境変数
CODEQL_PYTHON
が、依存関係が含まれる Python 実行可能ファイルに設定されます。 -
リポジトリがPythonの依存関係を持たない場合、あるいは依存関係が予想外の方法で指定されている場合、警告が示されてアクションは残りのジョブを継続します。 依存関係の解釈に問題があってもアクションの実行は成功することがありますが、結果は不完全かも知れません。
あるいは、任意のオペレーティングシステムにおいて手動でPythonの依存関係をインストールできます。 このワークフローの抜粋に示されるように、setup-python-dependencies
を追加して false
に設定し、さらに CODEQL_PYTHON
を、依存関係が含まれる Python 実行可能ファイルに設定する必要があります。
jobs:
CodeQL-Build:
runs-on: ubuntu-latest
permissions:
security-events: write
actions: read
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.x'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
if [ -f requirements.txt ];
then pip install -r requirements.txt;
fi
# Set the `CODEQL-PYTHON` environment variable to the Python executable
# that includes the dependencies
echo "CODEQL_PYTHON=$(which python)" >> $GITHUB_ENV
- name: Initialize CodeQL
uses: github/codeql-action/init@v2
with:
languages: python
# Override the default behavior so that the action doesn't attempt
# to auto-install Python dependencies
setup-python-dependencies: false
分析のカテゴリの設定
category
を使用して、同じツールとコミットに対して、異なる言語またはコードの異なる部分に対して実行される複数の解析を区別します。 ワークフロー中で指定したカテゴリは、SARIF結果ファイルに含まれます。
このパラメータは、特に単一リポジトリで作業をしていて、単一リポジトリの様々なコンポーネントに対して複数のSARIFファイルがある場合に有益です。
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v2
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, os: linux}
マトリックス変数によって、カテゴリ.github/workflows/codeql-analysis.yml:analyze/language:javascript/os:linux
が生成されます。
category
値は、SARIF v2.1.0 の <run>.automationDetails.id
プロパティとして表示されます。 詳細については、「code scanning の SARIF サポート」を参照してください。
指定したカテゴリは、SARIF ファイルに runAutomationDetails
オブジェクトの詳細が含まれている場合、上書きされることはありません。
追加のクエリを実行する
コードをスキャンするためにCodeQLを使う場合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。
また、分析から除外するクエリを指定したり、分析に含めたりすることもできます。 これには、カスタム構成ファイルを使用する必要があります。 詳しくは、以下の「カスタム構成ファイルの使用」および「分析からの特定のクエリの除外」を参照してください。
追加のクエリは、GitHub Container registry に公開される CodeQL パック (ベータ版)、またはリポジトリに格納される QL の一部である場合に、実行できます。 詳細については、「code scanning と CodeQL について」を参照してください。
追加で実行したいクエリを指定するのに使用できるオプションは、次のとおりです。
packs
。1 つまたは複数の CodeQL クエリ パック (ベータ版) をインストールし、それらのパックに対して既定のクエリ スイートまたはクエリを実行します。queries
。1 つの .ql ファイル、複数の .ql ファイルを含むディレクトリ、 .qls クエリ スイート定義ファイル、または任意の組み合わせを指定します。 クエリ スイート定義の詳細については、「CodeQL クエリ スイートの作成」を参照してください。
同じワークフローで packs
と queries
の両方を使用できます。
github/codeql/cpp/ql/src@main
のように、github/codeql
リポジトリから直接クエリ スイートを参照することはお勧めしません。 このようなクエリは再コンパイルする必要があり、現在 GitHub Actions でアクティブになっている CodeQL のバージョンと互換性がないため、分析中にエラーが発生する可能性があります。
CodeQL クエリ パックを使用する
注: CodeQL パッケージ管理機能 (CodeQL パックを含む) は現在ベータ版であり、変更される可能性があります。
1 つ以上の CodeQL クエリ パック (ベータ版) を追加するには、ワークフローの uses: github/codeql-action/init@v2
セクション内に with: packs:
エントリを追加します。 packs
内で、使用するパッケージを 1 つ以上指定し、必要に応じて、ダウンロードするバージョンを指定します。 バージョンを指定しない場合は、最新バージョンがダウンロードされます。 公開されていないパッケージを使用する場合は、GITHUB_TOKEN
環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。 詳細については、ワークフローでの認証に関するページと「暗号化されたシークレット」を参照してください。
メモ: 複数の言語の CodeQL データベースを生成するワークフローでは、構成ファイルで CodeQL クエリ パックを代わりに指定する必要があります。 詳細については、以下の「CodeQL クエリ パックの指定」を参照してください。
次の例では、scope
は、パッケージを公開した Organaization または個人アカウントです。 ワークフローを実行すると、4 つの CodeQL クエリ パックが GitHub からダウンロードされ、各パックの既定のクエリまたはクエリ スイートが実行されます。
- 最新バージョンの
pack1
がダウンロードされ、すべての既定のクエリが実行されます。 - バージョン 1.2.3 の
pack2
がダウンロードされ、すべての既定のクエリが実行されます。 - バージョン 3.2.1 と互換性のある最新バージョンの
pack3
がダウンロードされ、すべてのクエリが実行されます。 - バージョン 4.5.6 の
pack4
がダウンロードされ、path/to/queries
内で見つかったクエリのみが実行されます。
- uses: github/codeql-action/init@v2
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
メモ: 特定のバージョンのクエリ パックを使用するよう指定する場合は、指定したバージョンが、CodeQL アクションで使用される既定の CodeQL エンジンでは最終的に古くなりすぎて効率的に使用できなくなる可能性があることに注意してください。 最適なパフォーマンスを確保するために、特定のバージョンのクエリ パックを指定する必要がある場合は、ピン留めされたバージョンのクエリ パックをバージョンアップする必要があるかどうかを定期的に確認することを検討してください。
パックの互換性について詳しくは、「CodeQL パックの互換性について」を参照してください。
GitHub Enterprise Server から CodeQL パックをダウンロードする
GitHub Enterprise Server のインストールで発行されたパックがワークフローで使われている場合は、それを見つける場所をワークフローに指示する必要があります。 これを行うには、github/codeql-action/init@v2 アクションの registries
入力を使います。 この入力は、次に示すように、url
、packages
、token
の各プロパティのリストを受け入れます。
- uses: github/codeql-action/init@v2
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@v2 アクションによって解析されます。
QL パックでクエリを使用する
1 つ以上のクエリを追加するには、ワークフローの uses: github/codeql-action/init@v2
セクション内に with: queries:
エントリを追加します。 クエリがプライベート リポジトリ内にある場合は、external-repository-token
パラメーターを使用して、プライベート リポジトリをチェックアウトするためのアクセス権を持つトークンを指定します。
- uses: github/codeql-action/init@v2
with:
queries: COMMA-SEPARATED LIST OF PATHS
# Optional. Provide a token to access queries stored in private repositories.
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
queries
の値でクエリ スイートを指定することもできます。 クエリ スイートは、通常、目的または言語別にグループ化されたクエリのコレクションです。
以下のクエリスイートはCodeQL code scanningに組み込まれており、利用可能です。
クエリ スイート | 説明 |
---|---|
security-extended | 既定のスイートからのクエリ、および重要度と精度の低いクエリ |
security-and-quality | security-extended からのクエリに加え、保守性および信頼性のクエリ。 |
クエリ スイートを指定すると、CodeQL の分析エンジンでは、既定の一連のクエリと、追加のクエリ スイートで定義されている追加クエリが実行されます。 JavaScript の security-extended
クエリ スイートと security-and-quality
クエリ スイートには、試験的なクエリが含まれています。 詳細については、「code scanning アラートについて」を参照してください。
カスタム構成ファイルの処理
カスタム設定にも構成ファイルを使用する場合、構成ファイル内に指定されているものではなく、ワークフロー内で指定した追加のパックまたはクエリが使用されます。 追加のパックまたはクエリの組み合わせセットを実行する場合は、ワークフロー内の packs
または queries
の値の前に +
記号を付けます。 詳細については、「カスタム構成の使用」を参照してください。
次の例では、+
記号を付けることで、指定した追加のパックとクエリが、参照される構成ファイル内で指定したものと一緒に確実に使用されます。
- uses: github/codeql-action/init@v2
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@v2
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@v2
with:
external-repository-token: ${{ secrets.ACCESS_TOKEN }}
構成ファイルの設定は、YAML 形式で記述します。
CodeQL クエリ パックを指定する
注: CodeQL パッケージ管理機能 (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
クエリ パックを指定する完全な書式は 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
追加のクエリを指定する
追加のクエリは queries
配列に指定します。 配列の各要素に、単一のクエリ ファイル、クエリ ファイルを含むディレクトリ、またはクエリ スイート定義ファイルを識別する値を持つ uses
パラメーターを含めます。
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
クエリの ID を見つけるには、 [Security] タブのアラートの一覧でアラートをクリックします。これにより、アラートの詳細ページが開きます。 フィールドには Rule ID
クエリ ID が含まれています。アラートの詳細ページについて詳しくは、「code scanning アラートについて」を参照してください。
ヒント:
- フィルターの順序が重要です。 クエリとクエリ パックに関する命令の後に表示される最初のフィルター命令によって、既定でクエリを含めるか除外するかが決まります。
- 後続の命令は順番に実行され、ファイル内で後にある命令の方が前にある命令よりも優先されます。
これらのフィルターの使用方法を示す別の例については、「サンプル構成ファイル」セクションを参照してください。
カスタム構成ファイルでの exclude
および include
フィルターの使用について詳しくは、「CodeQL クエリ スイートの作成」を参照してください。 フィルター処理できるクエリ メタデータについて詳しくは、「CodeQL クエリのメタデータ」を参照してください。
スキャンするディレクトリを指定する
CodeQL がサポートするインタプリタ型言語 (Python、Ruby、JavaScript/TypeScript) では、構成ファイルに paths
配列を追加することで、code scanning を特定のディレクトリのファイルに限定できます。 paths-ignore
配列を追加すると、特定のディレクトリ内のファイルを分析から除外できます。
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
注:
- 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 QL pack (run queries in the my-queries directory)
uses: ./my-queries
- name: Use an external JavaScript QL pack (run queries from an external repo)
uses: octo-org/javascript-qlpack@main
- name: Use an external query (run a single query from an external QL pack)
uses: octo-org/python-qlpack/show_ifs.ql@main
- name: Use a query suite file (run queries from a query suite in this repo)
uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
次の構成ファイルを使用すると、重大度エラーのアラートを生成するクエリのみが実行されます。 構成では、最初にすべての既定のクエリ、./my-queries
内のすべてのクエリ、および codeql/java-queries
内の既定のスイートを選んでから、警告または推奨事項を生成するすべてのクエリを除外します。
queries:
- name: Use an in-repository QL pack (run queries in the my-queries directory)
uses: ./my-queries
packs:
- codeql/java-queries
query-filters:
- exclude:
problem.severity:
- warning
- recommendation
コンパイルされた言語の code scanning を設定する
サポートされているコンパイル言語の場合、CodeQL 分析ワークフローの autobuild
アクションを使ってコードをビルドできます。 これにより、C/C++、C#、Go、Kotlin、Java の明示的なビルド コマンドを指定する必要がなくなります。 これらの言語では、CodeQL は、ビルドされたリポジトリ内のソース ファイルを分析します。 これらの言語の場合は、autobuild
を無効にし、その代わりにカスタム ビルド コマンドによってビルドされたファイルのみを分析するためにこれらのカスタム コマンドを使用できます。
autobuild
が失敗した場合、または autobuild
プロセスによってビルドされたものとは異なるソース ファイルのセットを分析する場合は、ワークフローから autobuild
ステップを削除し、ビルド ステップを手動で追加する必要があります。 C/C++、C#、Go、Kotlin、Java プロジェクトの場合、CodeQL では、指定したビルド ステップによってビルドされたソース コードを分析します。 コンパイル型言語の CodeQL code scanning を構成する方法の詳細については、「コンパイル型言語の CodeQL ワークフローの構成」を参照してください。
code scanning データを GitHub にアップロードする
GitHubは、サードパーティのツールによって外部で生成されたコード分析データを表示できます。 upload-sarif
アクションを使用してコード分析データをアップロードできます。 詳細については、「SARIF ファイルを GitHub にアップロードする」を参照してください。