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

Note

この機能を使用するには、サイト管理者が code scanning を有効にする必要があります。コードをスキャンするためにGitHub Actionsを使いなら、サイト管理者はGitHub Actionsの有効化と、必要なインフラストラクチャのセットアップもしなければなりません。詳しくは、「アプライアンス用コードスキャンの構成」を参照してください。

Note

この記事では、このバージョンの GitHub Enterprise Server の初期リリースに含まれる CodeQL アクションのバージョンおよび関連する CodeQL CLI バンドルで使用できる機能について説明します。エンタープライズでより新しいバージョンの CodeQL アクションを使用する場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。最新バージョンの使用については、「アプライアンス用コードスキャンの構成」を参照してください。

code scanning の設定について

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

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

CodeQL 解析は、GitHub で実行できる code scanning のほんの一例に過ぎません。 GitHub.com 上の GitHub Marketplace には、使用できる他の code scanning ワークフローが含まれます。この記事で示す具体的な例は、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 イベントの詳細については、「ワークフローをトリガーするイベント」を参照してください。

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の不要なスキャンを回避する

変更されたファイルに関係なく、デフォルトのブランチを対象とする特定の 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'

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 分析ワークフローを示しています。

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) にデフォルトのブランチ

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

Note

Swift コードのコードスキャンでは、デフォルトで macOS ランナーが使用されます。
Swift コードの Code scanning は、Actions Runner Controller (ARC) の一部であるランナーではサポートされていません。ARC をキャプチャするランナーでは Linux のみが使用されるため、Swift には macOS ランナーが必要です。ただし、ARC をキャプチャするランナーとセルフホストの macOS ランナーの両方を組み合わせることもできます。詳しくは、「Actions Runner Controller について」を参照してください。

コードのコンパイルに特定のオペレーティングシステムが必要な場合は、そのオペレーティングシステムを CodeQL 分析ワークフローで構成できます。 jobs.analyze.runs-on の値を編集して、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

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 を追加する必要があります。

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

.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 モデルエディターは現在ベータであり、変更される可能性があります。モデルパックは Java/Kotlin 分析でサポートされます。

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の分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。

Tip

また、分析から除外するクエリを指定したり、分析に含めたりすることもできます。これには、カスタム構成ファイルを使用する必要があります。詳しくは、以下の「カスタム構成ファイルの使用」および「分析からの特定のクエリの除外」を参照してください。

追加のクエリは、GitHub Container registry に公開される CodeQL パック、またはリポジトリに格納される CodeQL パックの一部である場合に実行できます。詳しくは、「CodeQL によるコードスキャンについて」を参照してください。

追加で実行したいクエリを指定するのに使用できるオプションは、次のとおりです。

packs 1 つまたは複数の CodeQL クエリパックをインストールし、それらのパックに対して既定のクエリスイートまたはクエリを実行します。
queries 1 つの .ql ファイル、複数の .ql ファイルを含むディレクトリ、 .qls クエリスイート定義ファイル、または任意の組み合わせを指定します。クエリスイート定義の詳細については、「CodeQL クエリスイートの作成」を参照してください。

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

クエリパックの使用

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 Server からダウンロードされ、各パックのデフォルトのクエリまたはクエリスイートが実行されます。

最新バージョンの 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

Note

特定のバージョンのクエリパックを使用するよう指定する場合は、指定したバージョンが、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 クエリパックを指定します。形式は、ワークフローファイルで使用される形式とは異なるので注意してください。

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

追加のクエリを指定する

追加のクエリは 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アラートについて」を参照してください。

Tip

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

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

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

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

コードをビルドせずにコードベースを分析する場合は、構成ファイルに paths 配列を追加することで、code scanning を特定のディレクトリ内のファイルに制限できます。 paths-ignore 配列を追加すると、特定のディレクトリ内のファイルを分析から除外することもできます。このオプションは、インタープリタ型言語でサポートされている)。

YAML

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 は、コードベースの最も可能性の高いビルドメソッドを識別する autobuild ステップに従います。 autobuild が失敗した場合、または autobuild プロセスによってビルドされたソースファイルとは異なるソースファイルのセットを分析する場合は、次の操作を行う必要があります。ワークフローの autobuild ステップを削除するかコメントにします。次に、run ステップをコメント解除し、使用するビルドプロセスを手動で指定します。 C/C++、C#、Go、Java、Kotlin、および Swift の場合、CodeQL は、指定したビルドステップによってビルドされたソースコードを分析します。コンパイル型言語に対する CodeQL code scanning の構成方法の詳細については、「コンパイル済み言語の CodeQL コードスキャン」を参照してください。

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

GitHubは、サードパーティのツールによって外部で生成されたコード分析データを表示できます。 upload-sarif アクションを使用してコード分析データをアップロードできます。詳しくは、「SARIF ファイルを GitHub にアップロードする」をご覧ください。

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

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

この記事の内容

code scanning の設定について

code scanningワークフローの編集

頻度を設定する

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

Pull Requestをスキャンする

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

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

例

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

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

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

pull request チェックエラーの原因となるアラートの重大度を定義する

分析のカテゴリの設定

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

追加のクエリを実行する

クエリパックの使用

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

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

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

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

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

追加のクエリを指定する

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

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

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

サンプル構成ファイル

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

構成例

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

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

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

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

この記事の内容

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