Skip to main content

コード スキャン用の高度なセットアップのカスタマイズ

高度なセットアップでどのようにプロジェクト内のコードの脆弱性とエラーをスキャンするかをカスタマイズできます。

この機能を使用できるユーザーについて

書き込み アクセスを持つユーザー if advanced setup is already enabled

code scanning の設定について

GitHub Actionsを使って、あるいは継続的インテグレーション(CI)システムから、GitHub上でcode scanningを実行できます。 詳細については、「ワークフローの書き込み」または「既存の CI システムでコード スキャンを使用する」を参照してください。

code scanning の高度なセットアップにより、code scanning ワークフローをカスタマイズして、構成をきめ細かく制御できます。 詳しくは、「コード スキャンの高度なセットアップの構成」を参照してください。

CodeQL 解析は、GitHub で実行できる code scanning のほんの一例に過ぎません。 GitHub Marketplace には、使用できる他の code scanning ワークフローが含まれます。 これらの選択肢は、 [ セキュリティ] タブからアクセスできる「code scanning を開始する」ページにあります。 この記事で示す例は、CodeQL 分析ワークフロー ファイルに関連しています。

code scanningワークフローの編集

GitHub によって、リポジトリの .github/workflows ディレクトリにワークフロー ファイルが保存されます。 追加したワークフローは、そのファイル名を検索して見つけることができます。 たとえば、デフォルトでは、CodeQL code scanning のワークフロー ファイルは、codeql-analysis.yml という名前です。

  1. リポジトリで、編集したいワークフローファイルにアクセスします。
  2. ファイル ビューの右上隅の をクリックして、ワークフロー エディターを開きます。
  3. ファイルを編集したら、[コミットの開始] をクリックし、[変更のコミット] フォームに入力します。 現在のブランチに直接コミットするか、新しいブランチを作成して 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 に追加されます。 詳細については、「プッシュ時のスキャン」を参照してください。

注: リポジトリがマージ キューで構成されている場合は、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 配列を使用できます。

YAML
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

注: on:pull_request:paths-ignoreon: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-ignoreon:pull_request:paths を使って pull request に対してワークフローをいつ実行するかを決定する方法について詳しくは、「GitHub Actions のワークフロー構文」をご覧ください。

スケジュールに従ってスキャンする

デフォルトの CodeQL 分析ワークフローを使用すると、このワークフローではイベントによってトリガーされるスキャンに加えて、リポジトリ内のコードが週に 1 回スキャンされます。 このスケジュールを調整するには、ワークフローの cron 値を編集します。 詳しくは、「GitHub Actions のワークフロー構文」を参照してください。

メモ: GitHub では、デフォルトのブランチのワークフロー内にあるスケジュール設定されたジョブのみが実行されます。 他のブランチのワークフローでスケジュールを変更しても、ブランチをデフォルトブランチにマージするまで影響はありません。

次の例は、デフォルトのブランチの名前が main で、protected という名前の保護されたブランチがある特定のリポジトリの CodeQL 分析ワークフローを示しています。

YAML
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

このワークフローでは以下をスキャンします。

  • デフォルトのブランチと保護されたブランチへのすべてのプッシュ
  • デフォルトのブランチへのすべての pull request
  • 毎週月曜日 14 時 20 分 (UTC) にデフォルトのブランチ

オペレーティングシステムを指定する

注:

  • 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 アクションを実行するコンピューターのオペレーティング システムを指定します。

YAML
jobs:
  analyze:
    name: Analyze
    runs-on: [ubuntu-latest]

Code Scanning にセルフホスト ランナーを使うことにした場合は、2 つの要素からなる配列の 2 番目の要素として、self-hosted の後に、適切なラベルを使用して、オペレーティング システムを指定できます。

YAML
jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

CodeQL code scanning は、Ubuntu、Windows、および macOS の最新バージョンをサポートしています。 したがって、この設定の一般的な値は、ubuntu-latestwindows-latestmacos-latest です。 詳細については、「ジョブのランナーを選択する」および「セルフホストランナーとのラベルの利用」を参照してください。

セルフホステッド ランナーを使う場合は、Git が PATH 変数内にあることを確認する必要があります。詳しくは、「自己ホスト ランナーの概要」と「自己ホストランナーの追加」をご覧ください。

セルフホステッド マシンで CodeQL 分析を実行するための推奨仕様 (RAM、CPU コア数、ディスク) については、「CodeQL を実行するための推奨ハードウェア リソース」をご覧ください。

CodeQLデータベースの場所の指定

一般に、CodeQL 分析ワークフローで CodeQL データベースが配置される場所について気にする必要はありません。これは、前のステップで作成されたデータベースが後のステップで自動的に検出されるためです。 ただし、カスタムのワークフロー ステップを記述していて、CodeQL データベースをワークフロー成果物としてアップロードするなど、そのデータベースが特定のディスクの場所にあることが必要な場合は、init アクションの db-location パラメーターを使ってその場所を指定できます。

YAML
- 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

注:

  • java-kotlin を使用して、Java、Kotlin、またはその両方で記述されたコードを分析します。
  • javascript-typescript を使用して、JavaScript、TypeScript、またはその両方で記述されたコードを分析します。

詳細については、CodeQL Web サイトのドキュメント「サポートされている言語とフレームワーク」を参照してください。

CodeQL では、次の言語識別子が使用されます。

言語識別子オプションの代替識別子 (存在する場合)
C/C++c-cppc または cpp
C#csharp
Gogo
Java/Kotlinjava-kotlinjava または kotlin
JavaScript/TypeScriptjavascript-typescriptjavascript または typescript
Pythonpython
Rubyruby
Swiftswift

注: 代替識別子の 1 つを指定した場合、これは標準の言語識別子の使用と同じです。 たとえば、javascript-typescript の代わりに javascript を指定した場合、TypeScript コードの分析は除外されません。 これは、--paths-ignore オプションを使用して高度なセットアップ ワークフローで行うことができます。 詳しくは、「コード スキャン用の高度なセットアップのカスタマイズ」を参照してください。

デフォルトの CodeQL 分析ワークフロー ファイルには、language というマトリックスが含まれ、リポジトリ内の分析対象の言語が一覧表示されています。 CodeQLは、code scanningがリポジトリに追加されたときにこのマトリクスを自動的に作成します。 language マトリックスを使用すると、CodeQL で各解析が並行して実行されるように最適化されます。 ビルドを並列化するとパフォーマンスが向上するため、すべてのワークフローでこの構成を採用することをお勧めします。 マトリックスについて詳しくは、「ワークフローでのジョブのバリエーションの実行」をご覧ください。

サポートされている 1 つ以上の言語のコードがリポジトリに含まれている場合は、分析する言語を選択できます。 言語が分析されないようにする理由は、いくつかあります。 たとえば、プロジェクトで、コードの本体に対する依存関係が別の言語の中にあり、それらの依存関係のアラートを表示したくない場合が考えられます。

ワークフローで language マトリックスを使用する場合、CodeQL はマトリックス内の言語だけを分析するようにハードコードされています。 分析する言語を変更するには、マトリックス変数の値を編集します。 解析されないように言語を削除したり、code scanning を構成したときにはリポジトリに存在しなかった言語を追加したりできます。 たとえば、code scanning が構成されたとき、リポジトリには当初 JavaScript しか含まれておらず、後で Python のコードを追加した場合は、マトリックスに python を追加する必要があります。

YAML
jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript-typescript', 'python']

ワークフローに language という名前のマトリックスが含まれていない場合は、CodeQL は解析を順次実行するように設定されます。 ワークフロー中で言語を指定していない場合、CodeQLはリポジトリ中のサポートされている言語を検出し、分析しようとします。 マトリックスは使用せず、分析する言語を選択する場合は、init アクションの下の languages パラメーターを使用できます。

YAML
- 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ファイルがある場合に有益です。

YAML
    - 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 によって、アクションをトリガーするワークフロー ファイルの名前、アクション名、任意のマトリックス変数に基づいて、カテゴリ名が生成されます。 たとえば次のような点です。

  • .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 パックの作成と操作」を参照してください。

注: CodeQL モデル パックと CodeQL モデル エディターは現在 パブリック プレビュー であり、変更される可能性があります。 モデル パックは C#、Java/Kotlin、Python、および Ruby 分析でサポートされます。

CodeQL モデル パックを使用する

1 つ以上の CodeQL モデル パックを追加するには、ワークフローの uses: github/codeql-action/init@v3 セクションをもつ with: packs: エントリ内のモデル パックを追加します。 packs 内で、使用するパッケージを 1 つ以上指定し、必要に応じて、ダウンロードするバージョンを指定します。 バージョンを指定しない場合は、最新バージョンがダウンロードされます。 公開されていないパッケージを使用する場合は、GITHUB_TOKEN 環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。 詳細については、「自動トークン認証」および「GitHub Actions でのシークレットの使用」を参照してください。

YAML
- 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-queries7.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 クエリ スイートの作成」を参照してください。

同じワークフローで packsqueries の両方を使用できます。

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 でのシークレットの使用」を参照してください。

メモ: 複数の言語の CodeQL データベースを生成するワークフローでは、構成ファイルで CodeQL クエリ パックを代わりに指定する必要があります。 詳細については、以下の「CodeQL クエリ パックの指定」を参照してください。

次の例では、scope は、パッケージを公開した Organaization または個人アカウントです。 ワークフローを実行すると、4 つの CodeQL クエリ パックが GitHub からダウンロードされ、各パックのデフォルトのクエリまたはクエリ スイートが実行されます。

  • 最新バージョンの pack1 がダウンロードされ、すべてのデフォルトのクエリが実行されます。
  • バージョン 1.2.3 の pack2 がダウンロードされ、すべてのデフォルトのクエリが実行されます。
  • バージョン 3.2.1 と互換性のある最新バージョンの pack3 がダウンロードされ、すべてのクエリが実行されます。
  • バージョン 4.5.6 の pack4 がダウンロードされ、path/to/queries 内で見つかったクエリのみが実行されます。
YAML
- 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

メモ: 特定のバージョンのクエリ パックを使用するよう指定する場合は、指定したバージョンが、CodeQL アクションで使用されるデフォルトの CodeQL エンジンでは最終的に古くなりすぎて効率的に使用できなくなる可能性があることに注意してください。 最適なパフォーマンスを確保するために、特定のバージョンのクエリ パックを指定する必要がある場合は、ピン留めされたバージョンのクエリ パックをバージョンアップする必要があるかどうかを定期的に確認することを検討してください。

パックの互換性について詳しくは、「CodeQL パックを発行して使用する」をご覧ください。

GitHub Enterprise Server から CodeQL パックをダウンロードする

GitHub Enterprise Server のインストールで発行されたパックがワークフローで使われている場合は、それを見つける場所をワークフローに指示する必要があります。 これを行うには、github/codeql-action/init@v3 アクションの registries 入力を使います。 この入力は、次に示すように、urlpackagestoken の各プロパティのリストを受け入れます。

YAML
- 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 の値でクエリ スイートを指定することもできます。 クエリ スイートは、通常、目的または言語別にグループ化されたクエリのコレクションです。

YAML
- 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-qualitysecurity-extended からのクエリに加え、保守性および信頼性のクエリ。

詳細については、「CodeQL クエリ スイート」を参照してください。

これらの各クエリ スイートには、その言語の組み込みの CodeQL クエリ パックに含まれるクエリの異なるサブセットが含まれています。 クエリ スイートは、各クエリのメタデータを使用して自動的に生成されます。 詳しくは、「CodeQL クエリのメタデータ」をご覧ください。

クエリ スイートを指定すると、CodeQL の分析エンジンでは、既定の一連のクエリと、追加のクエリ スイートで定義されている追加クエリが実行されます。

カスタム構成ファイルの処理

カスタム設定にも構成ファイルを使用する場合は、構成ファイル内に指定されたものではなく、ワークフロー内で指定された追加のパックまたはクエリが使用されます。 追加のパックまたはクエリの組み合わせセットを実行する場合は、ワークフロー内の packs または queries の値の前に + 記号を付けます。 詳細については、「カスタム構成ファイルの使用」を参照してください。

次の例では、+ 記号を付けることで、指定した追加のパックとクエリが確実に、参照される構成ファイル内で指定したものと一緒に使用されるようになります。

YAML
- 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 を読み込みます。

YAML
- 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 パラメーターを使用して、そのプライベート リポジトリへのアクセス権を持つトークンを指定します。

YAML
- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

構成ファイルの設定は、YAML 形式で記述します。

CodeQL クエリ パックを指定する

配列に CodeQL クエリ パックを指定します。 形式は、ワークフロー ファイルで使用される形式とは異なるので注意してください。

YAML
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] です。 versionpath はどちらも省略可能です。 version は semver バージョンの範囲です。 指定しない場合は、最新バージョンが使われます。 semver の範囲の詳細については、npm の semver ドキュメントを参照してください。

複数の CodeQL データベースを生成するワークフローがある場合、入れ子になったパックのマップを使用して、カスタム構成ファイル内に、実行する任意の CodeQL クエリ パックを指定できます。

YAML
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 カバレッジの拡張

注: 脅威モデルは現在 パブリック プレビュー 段階であり、変更される可能性があります。 パブリック プレビュー 期間中、脅威モデルは Java/Kotlin および C# 解析でのみサポートされます。

デフォルトの脅威モデルには、信頼されていないデータのリモート ソースが含まれます。 カスタム構成ファイルで threat-models: local を指定することで、信頼されていないデータのローカル ソース (コマンド ライン引数、環境変数、ファイル システム、データベースなど) を含むように、CodeQL 脅威モデルを 拡張できます。 脅威モデルを拡張すると、デフォルトの脅威モデルも使用されます。

追加のクエリを指定する

追加のクエリは queries 配列に指定します。 配列の各要素に、単一のクエリ ファイル、クエリ ファイルを含むディレクトリ、またはクエリ スイート定義ファイルを識別する値を持つ usesパラメーターを含めます。

YAML
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 フィルターを追加して、分析から除外また分析に含めるクエリを指定できます。

たとえば、これは、次のように除外する場合に便利です。

  • デフォルトのスイート (securitysecurity-extended、および security-and-quality) からの特定のクエリ。
  • 結果に関心がない特定のクエリ。
  • 警告と推奨事項を生成するすべてのクエリ。

以下の構成ファイルと同様の exclude フィルターを使用して、デフォルトの分析から削除するクエリを除外できます。 次の構成ファイルの例では、js/redundant-assignment および js/useless-assignment-to-local クエリの両方が分析から除外されています。

YAML
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 クエリのメタデータ」を参照してください。

スキャンするディレクトリを指定する

コードをビルドせずにコードベースを分析する場合は、構成ファイルに paths 配列を追加することで、code scanning を特定のディレクトリ内のファイルに制限できます。 paths-ignore 配列を追加すると、特定のディレクトリ内のファイルを分析から除外することもできます。 このオプションは、インタープリタ型言語 で CodeQL アクションを実行する場合、またはコードをビルドせずにコンパイル済み言語を分析する場合に使用できます (現在 C# および Java) でサポートされている)。

YAML
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/****/foofoo/**/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/

同じ方法を使用して、ワークフロー ファイル内の有効な構成オプションを指定できます。

ヒント:

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 にアップロードする」を参照してください。