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

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

People with write permissions to a repository can configure code scanning for the repository.

Code scanningは、GitHub Advanced Securityのライセンスを持っているなら利用できます。 詳しい情報については、「GitHub Advanced Security について」を参照してください。

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

code scanning の設定について

You can run code scanning on GitHub Enterprise Server, using GitHub Actions, or from your continuous integration (CI) system. For more information, see "About GitHub Actions" or "Running CodeQLランナー in your CI system."

This article is about running code scanning on GitHub Enterprise Server using actions.

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

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

CodeQL 解析は、GitHub で実行できる code scanning のほんの一例に過ぎません。 GitHub Marketplace on GitHub.com contains other code scanning workflows you can use. The specific examples given in this article relate to the CodeQL分析ワークフロー file.

Editing a code scanning workflow

GitHub は、リポジトリの .github/workflows ディレクトリにワークフローファイルを保存します。 ファイル名を検索して、追加済みのワークフローを見つけることができます。 For example, the default workflow file for CodeQL code scanning is called codeql-analysis.yml.

  1. リポジトリで、編集したいワークフローファイルにアクセスします。
  2. ファイルビューの右上隅の をクリックしてワークフローエディタを開きます。 ワークフローファイルの編集ボタン
  3. ファイルを編集したら、[Start commit] をクリックして、[Commit changes] フォームに入力します。 現在のブランチに直接コミットするか、新しいブランチを作成してプルリクエストを開始するかを選択できます。 codeql.yml ワークフローの更新をコミットする

ワークフローファイルの編集に関する詳しい情報については、「GitHub Actions を学ぶ」を参照してください。

頻度を設定する

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

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

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

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

If you scan on push, then the results appear in the Security tab for your repository. 詳しい情報については、「リポジトリの コードスキャンアラートを管理する」を参照してください。

Note: If you want code scanning alerts to appear as pull request checks, you must use the pull_request event, described below.

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

デフォルトの CodeQL分析ワークフロー は、pull_request イベントを使用して、デフォルトブランチに対するプルリクエストのコードスキャンをトリガーします。 The pull_request event is not triggered if the pull request was opened from a private fork.

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

If you scan pull requests, then the results appear as alerts in a pull request check. 詳しい情報については、「プルリクエストでコードスキャンアラートをトリアージする」を参照してください。

プルリクエストの不要なスキャンを回避する

どのファイルが変更されたかに関わらず、デフォルトブランチに対する特定のプルリクエストにコードスキャンがトリガーされることを避けたい場合もあるでしょう。 これを設定するには、code scanning ワークフローで on:pull_request:paths-ignore または on:pull_request:paths を指定します。 たとえば、プルリクエストにおける変更が、.md または .txt のファイル拡張子を持つファイルである場合、次の paths-ignore 配列を使用できます。

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

注釈

  • on:pull_request:paths-ignoreon:pull_request:paths は、ワークフローのアクションがプルリクエストで実行されるかどうかを決定する条件を設定します。 アクションが実行されたときにどのファイルが解析__されるかは決定しません。 プルリクエストに、on:pull_request:paths-ignore または on:pull_request:paths にマッチしないファイルが含まれている場合、ワークフローはそのアクションを実行し、on:pull_request:paths-ignore または on:pull_request:paths にマッチするものを含む、プルリクエストにおいて変更されたすべてのファイルをスキャンします。ただし、除外されているファイルは除きます。 ファイルを解析から除外する方法については、「スキャンするディレクトリを指定する」を参照してください。
  • For CodeQL code scanning ワークフローファイルに対しては、on:push イベントで paths-ignorepaths といったキーワードは使用しないでください。解析に漏れが生じる恐れがあります。 正確な結果を得るには、CodeQL code scanning が新しい変更を前回のコミットの解析と比較できる必要があります。

on:pull_request:paths-ignoreon:pull_request:paths を使用して、プルリクエストに対していつワークフローを実行するかを決定することに関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。

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

デフォルトの code scanning ワークフローは、pull_request イベントを使用して、プルリクエストの HEAD コミットでコードスキャンをトリガーします。 このスケジュールを調整するには、ワークフローで cron 値を編集します。 詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。

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

サンプル

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

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

このワークフローは、次をスキャンします。

  • デフォルトブランチと保護されたブランチに対する全てのプッシュ
  • デフォルトブランチに対する全てのプルリクエスト
  • The default branch every Monday at 14:20 UTC

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

コードのコンパイルに特定のオペレーティングシステムが必要な場合は、そのオペレーティングシステムを CodeQL分析ワークフロー で設定できます。 jobs.analyze.runs-on の値を編集して、code scanning のアクションを実行するマシンのオペレーティングシステムを指定します。 You specify the operating system by using an appropriate label as the second element in a two-element array, after self-hosted.

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

Code scanning は、macOS、Ubuntu、Windows の最新バージョンをサポートしています。 Typical values for this setting are therefore: ubuntu-latest, windows-latest, and macos-latest. For more information, see "Workflow syntax for GitHub Actions" and "Using labels with self-hosted runners."

You must ensure that Git is in the PATH variable on your self-hosted runners.

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

CodeQL code scanning automatically detects code written in the supported languages.

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

The default CodeQL分析ワークフロー file contains a build matrix called language which lists the languages in your repository that are analyzed. CodeQL automatically populates this matrix when you add code scanning to a repository. Using the language matrix optimizes CodeQL to run each analysis in parallel. We recommend that all workflows adopt this configuration due to the performance benefits of parallelizing builds. For more information about build matrices, see "Managing complex workflows."

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

If your workflow uses the language matrix then CodeQL is hardcoded to analyze only the languages in the matrix. To change the languages you want to analyze, edit the value of the matrix variable. You can remove a language to prevent it being analyzed or you can add a language that was not present in the repository when code scanning was set up. For example, if the repository initially only contained JavaScript when code scanning was set up, and you later added Python code, you will need to add python to the matrix.

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

If your workflow does not contain a matrix called language, then CodeQL is configured to run analysis sequentially. If you don't specify languages in the workflow, CodeQL automatically detects, and attempts to analyze, any supported languages in the repository. If you want to choose which languages to analyze, without using a matrix, you can use the languages parameter under the init action.

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

追加のクエリを実行する

コードをスキャンするためにCodeQLを使う場合、CodeQL分析エンジンはコードからデータベースを生成し、それに対してクエリを実行します。 詳しい情報については「code scanningについて」を参照してください。

CodeQLの分析はデフォルトのクエリセットを使いますが、デフォルトのクエリに加えてもっと多くのクエリを実行するよう指定することもできます。 実行したいクエリは、リポジトリ内のQLパックに属していなければなりません。 詳しい情報については、「QL パックについて」を参照してください。

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

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

1つ以上のクエリスイートを追加するには、設定ファイルに queries セクションを追加します。 If the queries are in a private repository, use the external-repository-token parameter to specify a token that has access to the private repository.

- uses: github/codeql-action/init@v1
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Provide a token to access private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

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

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

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

If you are also using a configuration file for custom settings, any additional queries specified in your workflow are used instead of any specified in the configuration file. If you want to run the combined set of additional queries specified here and in the configuration file, prefix the value of queries in the workflow with the + symbol. 設定ファイルの例については、「Example configuration files」を参照してください。

In the following example, the + symbol ensures that the specified additional queries are used together with any queries specified in the referenced configuration file.

- uses: github/codeql-action/init@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

As an alternative to specifying which queries to run in the workflow file, you can do this in a separate configuration file. You can also use a configuration file to disable the default queries and to specify which directories to scan during analysis.

In the workflow file, use the config-file parameter of the init action to specify the path to the configuration file you want to use. この例では、設定ファイル ./.github/codeql/codeql-config.yml を読み込みます。

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

設定ファイルは、分析しようとしているリポジトリ内、あるいは外部のリポジトリに配置できます。 外部リポジトリを利用すると、複数のリポジトリに対する設定オプションを一カ所で指定できます。 外部リポジトリにある設定ファイルを参照する際には、OWNER/REPOSITORY/FILENAME@BRANCHという構文が利用できます。 たとえばmonacorp/shared/codeql-config.yml@mainといったようにします。

If the configuration file is located in an external private repository, use the external-repository-token parameter of the init action to specify a token that has access to the private repository.

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

The settings in the configuration file are written in YAML format.

追加のクエリを指定する

You specify additional queries in a queries array. Each element of the array contains a uses parameter with a value that identifies a single query file, a directory containing query files, or a query suite definition file.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

Optionally, you can give each array element a name, as shown in the example configuration files below.

For more information about additional queries, see "Running additional queries" above.

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

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

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

For the interpreted languages that CodeQL supports (Python and JavaScript/TypeScript), you can restrict code scanning to files in specific directories by adding a paths array to the configuration file. You can exclude the files in specific directories from analysis by adding a paths-ignore array.

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

ノート:

  • The paths and paths-ignore keywords, used in the context of the code scanning configuration file, should not be confused with the same keywords when used for on.<push|pull_request>.paths in a workflow. When they are used to modify on.<push|pull_request> in a workflow, they determine whether the actions will be run when someone modifies code in the specified directories. 詳細については、「GitHub Actionsのワークフロー構文」を参照してください。
  • The filter pattern characters ?, +, [, ], and ! are not supported and will be matched literally.
  • ** Note: ** characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix ** and other characters. たとえば、foo/****/foo、および foo/**/bar はすべて使用できる構文ですが、**foo は使用できません。 ただし、例に示すように、単一の を他の文字と一緒に使用できます。 You'll need to quote anything that contains a `` character.

For compiled languages, if you want to limit code scanning to specific directories in your project, you must specify appropriate build steps in the workflow. ビルドからディレクトリを除外するために使用するコマンドは、ビルドシステムによって異なります。 詳しい情報については、「コンパイル型言語の CodeQL ワークフローを設定する」を参照してください。

特定のディレクトリのコードを変更すると、monorepo の一部をすばやく分析できます。 ビルドステップでディレクトリを除外し、ワークフローファイルで 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は、プロジェクトをセットアップするためにGoのプロジェクトのビルドも実行します。 ただし、他のコンパイル言語とは対照的に、リポジトリ内のGoのファイルはビルドされるものだけでなく、すべてが展開されます。 ビルドが処理しないGoのファイルの展開をスキップするために、カスタムのビルドコマンドを使うこともできます。

リポジトリ内の C/C++、C#、またはJava のコードに非標準のビルドプロセスがある場合、 autobuild が失敗することがあります。 ワークフローからautobuildステップを取り除き、手動でビルドのステップを追加する必要があるでしょう。 リポジトリのGoのファイルで展開するものを指定したい場合には、ビルドのステップを追加しなければなりません。コンパイルされた言語で CodeQL code scanning を設定する方法に関する詳しい情報については、「コンパイルされた言語の CodeQL を設定する」を参照してください。

code scanning 用の設定ファイルを作成できます。

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

このドキュメントは役立ちましたか?プライバシーポリシー

これらのドキュメントを素晴らしいものにするのを手伝ってください!

GitHubのすべてのドキュメントはオープンソースです。間違っていたり、はっきりしないところがありましたか?Pull Requestをお送りください。

コントリビューションを行う

OR, コントリビューションの方法を学んでください。

問題がまだ解決していませんか?

GitHubコミュニティで質問するサポートへの連絡