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

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 という名前です。

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 イベントについて詳しくは、「ワークフローをトリガーするイベント」をご覧ください。

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 配列を使用できます。

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

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

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

例

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

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

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

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

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

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

コードのコンパイルに特定のオペレーティング システムが必要な場合は、そのオペレーティング システムを CodeQL 分析ワークフローで構成できます。 jobs.analyze.runs-on の値を編集して、code scanning アクションを実行するコンピューターのオペレーティング システムを指定します。 2 つの要素からなる配列の 2 番目の要素として、self-hosted の後に、適切なラベルを使用して、オペレーティング システムを指定します。

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

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

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

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

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

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

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

- uses: github/codeql-action/init@v3
  with:
    db-location: '${{ github.runner_temp }}/my_location'

- uses: github/codeql-action/init@v3
  with:
    db-location: '${{ github.runner_temp }}/my_location'

CodeQL 分析ワークフローでは、db-location に指定されるパスが書き込み可能であり、存在しないか空のディレクトリであると想定されています。 セルフホストランナー上で動作するか、Dockerコンテナを使うジョブでこのパラメーターを使う場合、選択されたディレクトリが実行間でクリアされること、あるいは不要になったらデータベースが削除されることを保証するのはユーザーの責任です。 これは、実行のたびに新しいインスタンスとクリーンなファイルシステムが取得される GitHub ホスト ランナー上で動作するジョブには必要ありません。 詳しくは、「GitHub ホステッド ランナーの使用」を参照してください。

このパラメーターが使われていない場合、CodeQL 分析ワークフローでは、データベースが任意の一時的な場所に作成されます。 現在、デフォルト値は ${{ github.runner_temp }}/codeql_databases です。

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

CodeQL code scanningは、自動的にサポートする言語で書かれたコードを検出します。

• C/C++
• C#
• Go
• Java/Kotlin
• JavaScript/TypeScript
• Python
• Ruby
• Swift

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

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

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

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

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

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

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

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

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

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

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

pull request で code scanning を有効にすると、チェックは、重大度 errorのアラートが 1 つまたは複数検出された場合、またはセキュリティの重大度criticalまたはhigh が検出された場合のみ失敗します。 重大度が低いアラートまたはセキュリティ重大度のアラートが検出された場合、チェックは成功します。 重要なコードベースの場合は、コード変更をマージする前にアラートを修正または無視するようにするために、アラートが検出された場合に code scanning チェックを失敗させることができます。 重大度レベルの詳細については、「アラートの重大度とセキュリティの重大度レベルについて」を参照してください。

チェック エラーを発生させる重大度とセキュリティの重大度アラート レベルを編集できます。 詳しくは、「既定のセットアップの構成を編集する」を参照してください。

分析のカテゴリの設定

category を使用して、同じツールとコミットに対して、異なる言語またはコードの異なる部分に対して実行される複数の解析を区別します。 ワークフロー中で指定したカテゴリは、SARIF結果ファイルに含まれます。

このパラメーターは、特に単一リポジトリで作業をしていて、単一リポジトリの様々なコンポーネントに対して複数のSARIFファイルがある場合に有益です。

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v3
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v3
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

ワークフローで category パラメーターを指定しない場合、GitHub Enterprise 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 パックの作成と操作」を参照してください。

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

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

この例では、デフォルトのクエリは Java に対して実行され、クエリ パックmy-company/my-java-queries の 7.8.9 より大きいか、7.9.0 より小さいバージョンからのクエリも実行されます。 最新バージョンのモデル パック my-repo/my-java-model-pack でモデル化された依存関係により、デフォルトのクエリと my-company/my-java-queries のクエリ両方が使用できます。

追加のクエリを実行する

コードをスキャンするためにCodeQLを使う場合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。

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

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

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

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

クエリ パックの使用

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

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

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

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

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

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

- uses: github/codeql-action/init@v3
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

    

- uses: github/codeql-action/init@v3
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

    

レジストリ リストのパッケージ パターンは順番に調べられるので、通常、最も具体的なパッケージ パターンを最初に置く必要があります。 token の値は、read:packages アクセス許可でのダウンロード元の GitHub インスタンスによって生成された personal access token (classic) にする必要があります。

registries プロパティ名の後の | に注意してください。 GitHub Actions の入力は文字列のみを受け取ることができるため、これは重要です。 | を使うと、後続のテキストが文字列に変換され、それが後で github/codeql-action/init@v3 アクションによって解析されます。

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

1 つまたは複数のクエリを追加するには、ワークフローの uses: github/codeql-action/init@v3 セクション内にエントリ with: queries: を追加します。 クエリがプライベート リポジトリ内にある場合は、external-repository-token パラメーターを使用して、プライベート リポジトリをチェックアウトするためのアクセス権を持つトークンを指定します。

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

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

以下のクエリスイートはCodeQL code scanningに組み込まれており、利用可能です。

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

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

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

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

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

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

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

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

カスタム構成ファイルは、実行する追加のパックとクエリを指定するときの代替的な方法です。 また、このファイルを使用して、既定のクエリを無効にしたり、特定のクエリを除外または含めたり、分析中にスキャンするディレクトリを指定したりすることもできます。

ワークフロー ファイルでは、init アクションの config-file パラメーターを使用して、使用する構成ファイルへのパスを指定します。 この例では、構成ファイル ./.github/codeql/codeql-config.yml を読み込みます。

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

構成ファイルは、分析するリポジトリ内、または外部リポジトリ内に格納できます。 外部リポジトリを使用すると、1 つの場所の複数のリポジトリに対して構成オプションを指定できます。 外部リポジトリにある構成ファイルを参照する場合は、 OWNER/REPOSITORY/FILENAME@BRANCH 構文を使用できます。 たとえば、 octo-org/shared/codeql-config.yml@main です。

構成ファイルが外部のプライベート リポジトリにある場合は、init アクションの external-repository-token パラメーターを使用して、そのプライベート リポジトリへのアクセス権を持つトークンを指定します。

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

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

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

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

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

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

クエリ パックを指定する完全な書式は scope/name[@version][:path] です。 version と path はどちらも省略可能です。 version は semver バージョンの範囲です。 指定しない場合は、最新バージョンが使われます。 semver の範囲の詳細については、npm の semver ドキュメントを参照してください。

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

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

追加のクエリを指定する

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

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

あるいは、以下の設定ファイルの例にあるように、配列の各要素に名前を与えることもできます。 追加のクエリの詳細については、前述の「追加のクエリを実行する」を参照してください。

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

カスタム クエリのみを実行する場合は、disable-default-queries: true を使用してデフォルトのセキュリティ クエリを無効にすることができます。

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

カスタム構成ファイルに exclude および include フィルターを追加して、分析から除外また分析に含めるクエリを指定できます。

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

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

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

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

クエリの ID を見つけるには、 [Security] タブのアラートの一覧でアラートをクリックします。これにより、アラートの詳細ページが開きます。 Rule ID フィールドにはクエリ ID が含まれています。アラート詳細ページについて詳しくは、「Code scanningアラートについて」をご覧ください。

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

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

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

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

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

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

コードがビルドされる分析で、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/

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

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