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

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

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

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

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

Did this doc help you?

ノート: Code scanningは現在ベータで、変更されることがあります。 To request access to the beta, join the waitlist.

code scanning の設定について

You can run code scanning within GitHub, using GitHub Actions, or from your continuous integration (CI) system, using the CodeQL runner. GitHub Actions に関する詳しい情報については、「GitHub Actions について」を参照してください。 For more information about the CodeQL runner, see "Running code scanning in your CI system."

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

リポジトリに code scanning を設定する前に、リポジトリに GitHub Actions ワークフローを追加して code scanning を有効にする必要があります。 デフォルトの code scanning ワークフローは、on.push イベントを使用して、ワークフローファイルを含むブランチへのプッシュごとにコードスキャンをトリガーします。

通常、code scanning のデフォルトのワークフローを編集する必要はありません。 However, if required, you can edit the workflow to customize some of the settings. For example, you can edit GitHub's CodeQL Analysis workflow to specify the frequency of scans, the languages or directories to scan, and what CodeQL code scanning looks for in your code. You might also need to edit the workflow if you use a specific set of commands to compile your code or if there is more than one compiled language in your repository.

CodeQL analysis is just one type of code scanning you can do in GitHub. GitHub Marketplace contains other code scanning workflows you can use. You can find a selection of these on the "Get started with code scanning" page, which you can access from the Security tab. The specific examples given in this article relate to the CodeQL Analysis workflow file.

Editing a code scanning workflow

GitHub は、リポジトリの .github/workflows ディレクトリにワークフローファイルを保存します。 You can find the workflow by searching for its file name. 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、セキュリティ研究者、コミュニティが発見した最新の脆弱性とエラーが通知されます。

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

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

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

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

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

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

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

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

サンプル

The following example shows a CodeQL Analysis workflow for a particular repository that has a default branch called main and one protected branch called protected.

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

This workflow scans:

  • Every push to the default branch and the protected branch
  • Every pull request to the default branch
  • The default branch at 3 P.M. every Sunday

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

If your code requires a specific operating system to compile, you can configure the operating system in your CodeQL Analysis workflow. jobs.<job_id>.runs-on の値を編集して、code scanning のアクションを実行するマシンのオペレーティングシステムを指定します。

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."

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

If the C/C++, C#, or Java code in your repository has a non-standard build process or if it's written in more than one compiled language, autobuild may fail. You will need to remove the autobuild step from the workflow, and manually add build steps. For more information about how to configure code scanning for compiled languages, see "Configuring code scanning for compiled languages."

  • 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

追加のクエリを実行する

When you use CodeQL to scan code, the CodeQL analysis engine generates a database from the code and runs queries on it. 詳しい情報については、「code scanning について」を参照してください。

CodeQL analysis uses a default set of queries, but you can specify more queries to run, in addition to the default queries. 実行するクエリは、QL パックに属している必要があり、独自のリポジトリまたは任意のパブリックリポジトリに格納することができます。 詳しい情報については、「QL パックについて」を参照してください。

クエリは、標準ライブラリ(クエリの import LANGUAGE ステートメントで参照されるライブラリ)、またはクエリと同じ QL パック内のライブラリにのみ依存している必要があります。 標準ライブラリは github/codeql リポジトリにあります。 For more information, see "About CodeQL queries."

単一の .ql ファイル、複数の .ql ファイルを含むディレクトリ、.qls クエリスイート定義ファイル、または任意の組み合わせを指定できます。 For more information about query suite definitions, see "Creating CodeQL query suites."

We don't recommend referencing query suites directly from the github/codeql repository, like github/codeql/cpp/ql/src@main. Such queries may not be compiled with the same version of CodeQL as used for your other queries, which could lead to errors during analysis.

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

- uses: github/codeql-action/init@v1
  with:
    - queries: COMMA-SEPARATED LIST OF PATHS

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

The following query suites are built into CodeQL code scanning and are available for use.

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

When you specify a query suite, the CodeQL analysis engine will run the queries contained within the suite for you, in addition to the default set of queries.

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.

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

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

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

The configuration file can be located within the local repository, or in a public, remote repository. リモートリポジトリの場合は、owner/repository/file.yml@branch 構文を使用できます。 The settings in the file are written in YAML format.

Specifying additional queries

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 scans by adding a paths-ignore array.

paths: 
  - src 
paths-ignore: 
  - 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のワークフロー構文」を参照してください。
  • ** 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.

C/C++、C#、および Java の場合、code scanning をプロジェクトの特定のディレクトリに制限するには、ワークフローで適切なビルドステップを指定する必要があります。 ビルドからディレクトリを除外するために使用するコマンドは、ビルドシステムによって異なります。 For more information, see "Configuring the CodeQL action for compiled languages."

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

設定ファイルの例

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

name: "My CodeQL config"

queries:
  - uses: security-and-quality

The following configuration file disables the default queries and specifies a set of custom queries to run instead. It also configures CodeQL to scan files in the src directory (relative to the root), and to exclude the node_modules directory (also relative to the root), as well as any file whose name ends in .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-ignore: 
  - node_modules
  - '**/*.test.js'
paths:
  - src 

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

For compiled languages like C/C++, C#, and Java, the autobuild step in the default workflow attempts to build code before the action performs CodeQL analysis. 他のコンパイル言語とは対照的に、CodeQL はコードをビルドせずに Go を分析します。

The autobuild process only ever attempts to build one compiled language for a repository. The language automatically selected for analysis is the language with most files.

If the C/C++, C#, or Java code in your repository has a non-standard build process or if it's written in more than one compiled language, autobuild may fail. You will need to remove the autobuild step from the workflow, and manually add build steps. For more information about how to configure CodeQL code scanning for compiled languages, see "Configuring the CodeQL action for compiled languages."

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

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 用の設定ファイルを作成できます。

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

Did this doc help you?