ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

コードスキャンを設定する

GitHub がプロジェクトのコードをスキャンして脆弱性やエラーを検出する方法を設定できます。

リポジトリへの書き込み権限を持つユーザは、リポジトリの code scanning を設定できます。

ここには以下の内容があります:

ノート: Code scanningは現在ベータで、変更されることがあります。 ベータへのアクセスをリクエストするには、待ちリストに参加してください。

code scanning の設定について

Code scanning は GitHub Actions を使用します。 リポジトリに code scanning を設定する前に、リポジトリに GitHub Actions ワークフローを追加して code scanning を有効にする必要があります。 詳しい情報については、「code scanning を有効化する」を参照してください。

通常、code scanning のデフォルトのワークフローを編集する必要はありません。 ワークフローを編集して、スキャンの頻度、スキャンする言語またはディレクトリ、コードで code scanning が検索する内容を指定できます。 また、特定のコマンドを使用してコードをコンパイルする場合は、ワークフローを編集する必要があります。

ワークフローファイルの編集に関する詳細な情報については「ワークフローの設定」を参照してください。

頻度を設定する

スケジュール設定されているときや、リポジトリで特定のイベントが発生したときに、コードをスキャンできます。

たとえば、次の設定は、プッシュ時、プルリクエストの作成時、およびスケジュール設定に従ってスキャンします。

on:
  push:
  pull_request:
  schedule:
    - cron: '0 15 * * 0'

リポジトリへのプッシュごと、およびプルリクエストが作成されるたびにコードをスキャンすることで、開発者がコードに新しい脆弱性やエラーをもたらすことを防ぎます。 スケジュールに従ってコードをスキャンすると、開発者がリポジトリを積極的に維持していない場合でも、GitHub、セキュリティ研究者、コミュニティが発見した最新の脆弱性とエラーが通知されます。

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

デフォルトの code scanning ワークフローは、on.push イベントを使用して、ワークフローファイルを含むブランチへのプッシュごとにコードスキャンをトリガーします。 詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

特定のブランチに on.push を制限するために、branches キーワードを使用することはお勧めしません。 on.push にブランチを指定した場合、code scanning はワークフローで指定したブランチをプッシュしたときにのみ実行されます。

プルリクエストをスキャンする

デフォルトの code scanning ワークフローは、pull_request イベントを使用して、プルリクエストの HEAD コミットでコードスキャンをトリガーします。 プライベートフォークからプルリクエストをオープンした場合、pull_request イベントのスキャンは実行されません。

pull_request イベントに関する詳しい情報については、「"GitHub Actionsのためのワークフローの構文」を参照してください。

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

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

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

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

コードのコンパイルに特定のオペレーティングシステムが必要な場合は、ワークフローで設定できます。 jobs.<job_id>.runs-on の値を編集して、code scanning のアクションを実行するマシンのオペレーティングシステムを指定します。 Code scanning は、macOS、Ubuntu、Windows の最新バージョンをサポートしています。 詳しい情報については、「GitHub Actionsのワークフロー構文」を参照してください。

自動言語検出をオーバーライドする

Code scanning は、サポートされている言語で記述されたコードを自動的に検出してスキャンします。

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

リポジトリに複数の言語のコードが含まれている場合は、分析する言語を指定できます。 言語が分析されないようにする理由はいくつかあります。 たとえば、プロジェクトには、コードの本文とは異なる言語の依存関係があり、それらの依存関係のアラートを表示する必要がない場合があります。

自動言語検出をオーバーライドするには、ワークフローの init アクションに with:languages: を追加します。 サポートされている言語のキーワードは、cppcsharpgojavaJavaScript、および python です。

たとえば、次の設定では、code scanning をC/C++、C#、および Python に制限しています。

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

コンパイル言語のビルドステップを追加する

C/C++、C#、および Java の場合、デフォルトのワークフローの autobuild ステップは、アクションが CodeQL 分析を実行する前にコードをビルドしようとします。 他のコンパイル言語とは対照的に、CodeQL はコードをビルドせずに Go を分析します。

リポジトリ内の C/C++、C#、またはJava に非標準のビルドプロセスがある場合、 autobuild が失敗することがあります。 その場合は、ワークフローから autobuild アクションを削除し、 run ステップのコメントを解除します。

run ステップは、オペレーティングシステムのシェルを使用してコマンドラインプログラムを実行します。 これらのコマンドを変更し、さらにコマンドを追加して、ビルドプロセスをカスタマイズできます。

- run: |
  make bootstrap
  make release

run キーワードに関する詳しい情報については、「"GitHub Actionsのためのワークフローの構文」を参照してください。

プライベートリポジトリにアクセスする

code scanning のワークフローが GitHub のプライベートリポジトリにアクセスする場合は、個人アクセストークンを使用して認証するように Git を設定する必要があります。 CodeQL アクションの前にワークフローで jobs.<job_id>.steps.env を使用して、ランナー環境でシークレットを定義します。 詳しい情報については、「コマンドライン用の個人アクセストークンを作成する」および「暗号化されたシークレットの作成と保存」を参照してください。

たとえば、次の設定では、Git が GitHub.com の github/foogithub/bargithub/baz リポジトリへの完全な URL を、ACCESS_TOKEN 環境変数に保存した個人アクセストークンを含む URL に置き換えます。

steps:
- name: Configure access to private repository on GitHub.com
  env:
    TOKEN: ${{ secrets.ACCESS_TOKEN }}
  run: |
    git config --global url."https://${TOKEN}@github.com/github/foo".insteadOf "https://github.com/github/foo"
    git config --global url."https://${TOKEN}@github.com/github/bar".insteadOf "https://github.com/github/bar"
    git config --global url."https://${TOKEN}@github.com/github/baz".insteadOf "https://github.com/github/baz"

カスタム設定を使用する

code scanning 用の設定ファイルを作成できます。 設定ファイルでは、実行するクエリとスキャンするディレクトリを指定できます。

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

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

設定ファイルがローカルリポジトリ内に存在している必要があります。 設定ファイルの例については、「Example configuration files」を参照してください。

追加のクエリを実行する

code scanning を有効にすると、 GitHub の CodeQL 分析エンジンはコードからデータベースを生成し、その上でクエリを実行します。 詳しい情報については「code scanningについて」を参照してください。

設定ファイルでこれらを指定することで、追加のクエリを実行できます。 実行するクエリは、QL パックに属している必要があり、独自のリポジトリまたは任意のパブリックリポジトリに格納することができます。 詳しい情報については、「QL パックについて」を参照してください。

クエリは、標準ライブラリ(クエリの import LANGUAGE ステートメントで参照されるライブラリ)、またはクエリと同じ QL パック内のライブラリにのみ依存している必要があります。 標準ライブラリは github/codeql リポジトリにあります。 詳しい情報については「クエリファイルの概要」を参照してください。

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

1 つ以上のクエリを追加するには、設定ファイルに queries セクションを追加します。

queries:
  - name: DESCRIPTION OF YOUR CHOICE
    uses: PATH

設定ファイルでこれらを指定して、追加のクエリスイートを実行することもできます。 クエリスイートはクエリのコレクションであり、通常は目的または言語ごとにグループ化されています。

次のクエリスイートは code scanning に組み込まれており、設定ファイルで使用できます。

クエリスイート説明
security-extendedデフォルトのクエリよりも重要度と精度が低いクエリ
security-and-qualitysecurity-extended からのクエリ、および保守性と信頼性に関するクエリ

設定ファイルでクエリスイートを指定すると、CodeQL 分析エンジンは、デフォルトのクエリセットに加えて、スイートに含まれるクエリを実行します。

1つ以上のクエリスイートを追加するには、設定ファイルに queries セクションを追加します。

queries:
 - uses: security-and-quality

github/codeql/cpp/ql/src@master のように github/codeql リポジトリから直接 uses のクエリスイートを参照することはお勧めしません。 このようなクエリは、設定ファイルで使用されているものと同じバージョンの CodeQL でコンパイルされない場合があり、分析中にエラーが発生する可能性があります。

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

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

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

CodeQL がサポートするインタプリタ言語(Pythonおよび JavaScript/TypeScript)の場合、設定ファイルで paths キーワードを使用して、code scanning を特定のディレクトリのファイルに制限できます。 paths-ignore キーワードを使用して、特定のディレクトリのファイルをスキャンから除外できます。

注釈: code scanning 設定ファイルのコンテキストで使用される paths および paths-ignore キーワードを on.<push|pull_request>.paths で使用する場合、同じキーワードと混同しないでください。 ワークフローファイルの on.<push|pull_request> を変更するときに使用する場合、指定されたディレクトリのコードの変更時にアクションが実行されるかどうかを決定します。 詳細については、「GitHub Actionsのワークフロー構文」を参照してください。

C/C++、C#、および Java の場合、code scanning をプロジェクトの特定のディレクトリに制限するには、ワークフローで適切なビルドステップを指定する必要があります。 ビルドからディレクトリを除外するために使用するコマンドは、ビルドシステムによって異なります。 詳しい情報については、「コンパイル言語のビルドステップを追加する 」を参照してください。

特定のディレクトリのコードを変更すると、monorepo の一部をすばやく分析できます。 ビルドステップでディレクトリを除外し、ワークフローファイルで on.<push|pull_request>paths-ignore および paths キーワードを使用する必要があります。

設定ファイルの例

この設定ファイルは、コードのスキャン時に CodeQL によって実行されるクエリのリストに security-and-quality クエリスイートを追加します。 使用可能なクエリスイートの詳細については、「追加のクエリを実行する」を参照してください。

name: "My CodeQL config"

queries:
  - uses: security-and-quality

この設定ファイルはデフォルトのクエリを無効にし、代わりに実行するカスタムクエリのセットを指定します。 また、node_modules と呼ばれるものを除くすべてのサブディレクトリを含む、/src ディレクトリ内のファイルをスキャンするように CodeQL を設定します。

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@master
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@master
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths-ignore: 
  - '/node_modules/'
paths:
  - '/src' 

サードパーティのコードスキャンツールを使用する

ワークフローに upload-sarif アクションを追加することで、GitHub のサードパーティツールからのコード分析を表示できます。 詳しい情報については、「SARIF ファイルを GitHub にアップロードする」を参照してください。

担当者にお尋ねください

探しているものが見つからなかったでしょうか?

弊社にお問い合わせください