をカスタマイズして、コードスキャンの詳細設定を行う

code scanning の設定について

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

code scanning の詳細設定を使用すると、code scanning ワークフローをカスタマイズして、構成をきめ細かく制御できます。詳細については、「AUTOTITLE」を参照してください。

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 がトリガーされるようにするには、ワークフローがそのブランチに存在している必要があります。詳しくは、「ギットハブ　アクション　のワークフロー構文」を参照してください。

プッシュ時にスキャンすると、結果がリポジトリの [セキュリティ] タブに表示されます。詳しくは、「リポジトリのコードスキャンのアラートを管理する」を参照してください。

さらに、開かれた 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:
  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 で変更されたすべてのファイルがスキャンされます。ファイルを分析対象から除外する方法の詳細については、「スキャンするディレクトリの指定」を参照してください。

on:pull_request:paths-ignore と on:pull_request:paths を使って pull request に対してワークフローをいつ実行するかを決定する方法について詳しくは、「ギットハブ　アクション　のワークフロー構文」をご覧ください。

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

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

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

例

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

YAML

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) に既定のブランチ

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

注:

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]

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]

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 パラメーターを使ってその場所を指定できます。

YAML

- 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

注:

Swift の CodeQL 分析は、現在ベータ版です。ベータ版の間、Swift の分析は他の言語の CodeQL 分析ほど包括的ではありません。加えて、Swift 5.8 はまだサポートされていません。
Kotlin の CodeQL 分析は、現在ベータ版です。ベータ版の間、Kotlin の分析は他の言語の CodeQL 分析ほど包括的ではありません。
java-kotlin を使用して、Java、Kotlin、またはその両方で記述されたコードを分析します。
javascript-typescript を使用して、JavaScript、TypeScript、またはその両方で記述されたコードを分析します。

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

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

Language	識別子	オプションの代替識別子 (存在する場合)
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`

注: 代替識別子の 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']

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

- uses: github/codeql-action/init@v3
  with:
    languages: c-cpp, csharp, python

pull request のチェックエラーを発生させるアラート重大度を定義する

pull request で code scanning を有効にすると、チェックは、重大度 error のアラートが 1 つまたは複数検出された場合か、critical または high が検出された場合のみ失敗します。重大度が低いアラートまたはセキュリティ重大度のアラートが検出された場合、チェックは成功します。重要なコードベースの場合は、コード変更をマージする前にアラートを修正または無視するようにするために、アラートが検出された場合に 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"

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

注: モデルパックは現在ベータ版で、変更される可能性があります。ベータ期間中、モデルパックは Java/Kotlin と C# 分析でのみサポートされます。

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

- 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 パック (ベータ版)、またはリポジトリに格納される QL の一部である場合に、実行できます。詳しくは、「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 パックを含む) は現在ベータ版であり、変更される可能性があります。

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

メモ: 複数の言語の 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 内で見つかったクエリのみが実行されます。

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

- 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 入力を使います。この入力は、次に示すように、url、packages、token の各プロパティのリストを受け入れます。

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

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

- 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 の値の前に + 記号を付けます。詳細については、「カスタム構成の使用」を参照してください。

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

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

- 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

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

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

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

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

注: CodeQL パッケージ管理機能 (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

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 クエリパックを指定できます。

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

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

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 クエリの両方が分析から除外されています。

YAML

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アラートについて」をご覧ください。

ヒント:

フィルターの順序が重要です。クエリとクエリパックに関する命令の後に表示される最初のフィルター命令によって、既定でクエリを含めるか除外するかが決まります。
後続の命令は順番に実行され、ファイル内で後にある命令の方が前にある命令よりも優先されます。

これらのフィルターの使用方法を示す別の例については、「サンプル構成ファイル」セクションを参照してください。

カスタム構成ファイルでの exclude および include フィルターの使用について詳しくは、「CodeQL クエリスイートの作成」をご覧ください。フィルター処理できるクエリメタデータについて詳しくは、「CodeQL クエリのメタデータ」を参照してください。

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

コードをビルドせずにコードベースを分析すると、構成ファイルに paths 配列を追加することにより、code scanningを特定のディレクトリのファイルに制限できます。 paths-ignore 配列を追加することにより、特定のディレクトリのファイルを分析から除外できます。このオプションは、解釈された言語 (Python、Ruby、JavaScript/TypeScript) で CodeQL アクションを実行するとき、またはコード (現在は Java をサポート)をビルドせずにコンパイル済み言語を分析するときに使用できます。

YAML

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

注:

code scanning 構成ファイルのコンテキストで使用される paths および paths-ignore キーワードを、ワークフローの on.<push|pull_request>.paths で使用する同じキーワードと混同しないでください。これらをワークフロー内の on.<push|pull_request> の変更に使用すると、指定されたディレクトリ内のコードが変更されたときにアクションを実行するかどうかが決定されます。詳しくは、「ギットハブ　アクション　のワークフロー構文」を参照してください。
フィルターパターン文字 ?、+、[、]、! はサポートされていないため、文字どおりに照合されます。
** 文字は、行の先頭または末尾にのみ指定するか、スラッシュで囲むことができます。また、** と他の文字を一緒に使用できます。たとえば 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

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

をカスタマイズして、コードスキャンの詳細設定を行う

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

GitHub Actions で Code Scanning を実行する

この記事の内容

code scanning の設定について

code scanningワークフローの編集

頻度を設定する

プッシュ時にスキャンする

Pull Requestをスキャンする

Pull Requestの不要なスキャンを回避する

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

例

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

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

解析される言語を変更する

pull request のチェックエラーを発生させるアラート重大度を定義する

分析のカテゴリの設定

CodeQL モデルパックを使用した CodeQL カバレッジの拡張

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

追加のクエリを実行する

クエリパックの使用

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

QL パックでクエリを使用する

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

カスタム構成ファイルの使用

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

脅威モデルを使用した CodeQL カバレッジの拡張

追加のクエリを指定する

デフォルトのクエリを無効にする

分析からの特定のクエリの除外

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

サンプル構成ファイル

`config` 入力を使用した構成の詳細の指定

構成例

コンパイルされた言語の code scanning を設定する

code scanning データを GitHub にアップロードする

をカスタマイズして、コード スキャンの詳細設定を行う

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

この記事の内容

をカスタマイズして、コードスキャンの詳細設定を行う