code scanning のカスタマイズ

code scanning の設定について

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

この記事は、アクションを使った GitHub Enterprise Server での code scanning の実行に関するものです。

リポジトリの code scanning をカスタマイズする前に、リポジトリに GitHub Actions ワークフローを追加して code scanning を構成する必要があります。 詳しくは、「リポジトリの code scanning を構成する」をご覧ください。

通常、code scanning の既定のワークフロー ファイルを編集する必要はありません。 ただし、必要な場合にはワークフローを編集して設定の一部をカスタマイズできます。 たとえば、GitHub の CodeQL 分析ワークフローを編集すると、スキャンの頻度、スキャンする言語やディレクトリ、CodeQL code scanning を使ったコード内での検索対象を指定できます。 コードのコンパイルに特定のコマンド セットを使う場合にも、CodeQL 分析ワークフローの編集が必要となる場合があります。

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 を開始するかを選択できます。

ワークフロー ファイルの編集について詳しくは、「GitHub Actions について」をご覧ください。

頻度を設定する

スケジュール設定されているときや、リポジトリで特定のイベントが発生したときに、コードをスキャンするように 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 に追加されます。 詳しくは、「code scanning のカスタマイズ」を参照してください。

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

変更されたファイルに関係なく、既定のブランチを対象とする特定の pull request でコード スキャンがトリガーされないようにしたい場合があります。 これを構成するには、code scanning ワークフローで on:pull_request:paths-ignore または on:pull_request:paths を指定します。 たとえば、pull request 内の変更がファイル拡張子 .md または .txt のファイルに対するものだけである場合、次の paths-ignore 配列を使用できます。

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

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

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

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

例

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

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

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

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

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

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

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

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

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

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

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

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

- uses: github/codeql-action/init@v2
  with:
    db-location: '${{ github.workspace }}/codeql_dbs'

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

このパラメーターが使われていない場合、CodeQL 分析ワークフローでは、データベースが任意の一時的な場所に作成されます。

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

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

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

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

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

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

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

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

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

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

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

既定では、重大度レベルが Error または セキュリティの重大度レベルが Critical か High であるアラートの場合にのみ、pull request チェック エラーが発生し、重大度が低いアラートではチェックは成功します pull request チェック エラーを引き起こすアラートの重大度とセキュリティの重大度のレベルは、リポジトリの設定で変更できます。 重大度レベルについて詳しくは、「Code scanningアラートについて」をご覧ください。

1. お使いの GitHub Enterprise Server インスタンス で、リポジトリのメイン ページへ移動します。 1. リポジトリ名の下にある [設定] をクリックします。 [設定] タブが表示されない場合は、 [] ドロップダウン メニューを選び、 [設定] をクリックします。

   

2. サイドバーの [セキュリティ] セクションで、 [コードのセキュリティと分析] をクリックします。

3. "Code scanning"の下で、"チェックエラー"の右のドロップダウンメニューを使い、pull request のチェックの失敗を引き起こさせる重大度のレベルを選んでください。

分析のカテゴリの設定

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

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

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

ワークフローで category パラメーターを指定しない場合、GitHub Enterprise Server によって、アクションをトリガーするワークフロー ファイルの名前、アクション名、任意のマトリックス変数に基づいて、カテゴリ名が生成されます。 たとえば次のような点です。

• .github/workflows/codeql-analysis.ymlワークフローと analyze アクションによって、カテゴリ .github/workflows/codeql.yml:analyze が生成されます。
• .github/workflows/codeql-analysis.yml ワークフロー、analyze アクション、{language: javascript, os: linux} マトリックス変数によって、カテゴリ .github/workflows/codeql-analysis.yml:analyze/language:javascript/os:linux が生成されます。

category 値は、SARIF v2.1.0 の <run>.automationDetails.id プロパティとして表示されます。 詳しくは、「Code scanningの SARIF サポート」を参照してください。

指定したカテゴリは、SARIF ファイルに runAutomationDetails オブジェクトの詳細が含まれている場合、上書きされることはありません。

追加のクエリを実行する

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

実行したいクエリが他にあれば、リポジトリ内の QL パックに属していなければなりません。 詳しくは、「CodeQL によるコード スキャンについて」を参照してください。

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

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

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

- uses: github/codeql-action/init@v2
  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 クエリ ヘルプのドキュメントを参照することで、クエリがどのクエリ スイートに含まれるかを特定できます。 クエリごとに、含まれているスイートがクエリ メタデータと共にページの上部に表示されます。 例: 「Zip 解凍時の任意のファイル書き込み ("Zip Slip")」と「クライアント側リクエスト フォージェリ」。

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

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

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

- uses: github/codeql-action/init@v2
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

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

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

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

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

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

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

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

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

追加のクエリを指定する

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

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

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

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

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

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

CodeQL がサポートするインタープリター言語 (Python、Ruby、JavaScript/TypeScript) の場合、構成ファイルに paths 配列を追加することで、特定のディレクトリ内のファイルに code scanning を制限できます。 paths-ignore 配列を追加すると、特定のディレクトリ内のファイルを分析から除外できます。

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

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

サポートされているコンパイル言語の場合、CodeQL 分析ワークフローの autobuild アクションを使ってコードをビルドできます。 これにより、C/C++、C#、Java の明示的なビルド コマンドを指定する必要がなくなります。 これらの言語では、CodeQL は、ビルドされたリポジトリ内のソース ファイルを分析します。 これらの言語の場合は、autobuild を無効にし、その代わりにカスタム ビルド コマンドによってビルドされたファイルのみを分析するためにこれらのカスタム コマンドを使用できます。

autobuild が失敗した場合、または autobuild プロセスによってビルドされたものとは異なるソース ファイルのセットを分析する場合は、ワークフローから autobuild ステップを削除し、ビルド ステップを手動で追加する必要があります。 C/C++、C#、Go、Java プロジェクトの場合、CodeQL では、指定したビルド ステップによってビルドされたソース コードを分析します。コンパイル型言語に対する CodeQL code scanning の構成方法について詳しくは、「コンパイル済み言語の CodeQL ワークフローを構成する」をご覧ください。

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

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