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

Configuring code scanning

You can configure how GitHub scans the code in your project for vulnerabilities and errors.

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

Code scanning is available for organization-owned repositories where GitHub Advanced Security is enabled. 詳しい情報については、「GitHub Advanced Security について」を参照してください。

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

About code scanning configuration

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 "About CodeQL code scanning in your CI system."

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

Before you can configure code scanning for a repository, you must set up code scanning by adding a GitHub Actions workflow to the repository. For more information, see "Setting up code scanning for a repository."

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

CodeQL analysis is just one type of code scanning you can do in GitHub. 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 saves workflow files in the .github/workflows directory of your repository. You can find a workflow you have added by searching for its file name. For example, by default, the workflow file for CodeQL code scanning is called codeql-analysis.yml.

  1. In your repository, browse to the workflow file you want to edit.
  2. In the upper right corner of the file view, to open the workflow editor, click . Edit workflow file button
  3. After you have edited the file, click Start commit and complete the "Commit changes" form. You can choose to commit directly to the current branch, or create a new branch and start a pull request. Commit update to codeql.yml workflow

For more information about editing workflow files, see "Learn GitHub Actions."

Configuring frequency

You can configure the CodeQL分析ワークフロー to scan code on a schedule or when specific events occur in a repository.

Scanning code when someone pushes a change, and whenever a pull request is created, prevents developers from introducing new vulnerabilities and errors into the code. Scanning code on a schedule informs you about the latest vulnerabilities and errors that GitHub, security researchers, and the community discover, even when developers aren't actively maintaining the repository.

Scanning on push

By default, the CodeQL分析ワークフロー uses the on.push event to trigger a code scan on every push to the default branch of the repository and any protected branches. For code scanning to be triggered on a specified branch, the workflow must exist in that branch. For more information, see "Workflow syntax for GitHub Actions."

If you scan on push, then the results appear in the Security tab for your repository. For more information, see "Managing code scanning alerts for your repository."

Scanning pull requests

The default CodeQL分析ワークフロー uses the pull_request event to trigger a code scan on pull requests targeted against the default branch. The pull_request event is not triggered if the pull request was opened from a private fork.

For more information about the pull_request event, see "Workflow syntax for GitHub Actions."

If you scan pull requests, then the results appear as alerts in a pull request check. For more information, see "Triaging code scanning alerts in pull requests."

Defining the severities causing pull request check failure

By default, only alerts with the severity level of Error or security severity level of Critical or High will cause a pull request check failure, and a check will still succeed with alerts of lower severities. You can change the levels of alert severities and of security severities that will cause a pull request check failure in your repository settings. For more information about severity levels, see "Managing code scanning alerts for your repository."

  1. your GitHub Enterprise Server instanceで、リポジトリのメインページにアクセスしてください。
  2. リポジトリ名の下で Settings(設定)をクリックしてください。 リポジトリの設定ボタン
  3. 左のサイドバーで、Security & analysis(セキュリティと分析)をクリックしてください。 リポジトリ設定の"セキュリティと分析"タブ
  4. Under "Code scanning", to the right of "Check Failure", use the drop-down menu to select the level of severity you would like to cause a pull request check failure.

Check failure setting

Avoiding unnecessary scans of pull requests

You might want to avoid a code scan being triggered on specific pull requests targeted against the default branch, irrespective of which files have been changed. You can configure this by specifying on:pull_request:paths-ignore or on:pull_request:paths in the code scanning workflow. For example, if the only changes in a pull request are to files with the file extensions .md or .txt you can use the following paths-ignore array.

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

Notes

  • on:pull_request:paths-ignore and on:pull_request:paths set conditions that determine whether the actions in the workflow will run on a pull request. They don't determine what files will be analyzed when the actions are run. When a pull request contains any files that are not matched by on:pull_request:paths-ignore or on:pull_request:paths, the workflow runs the actions and scans all of the files changed in the pull request, including those matched by on:pull_request:paths-ignore or on:pull_request:paths, unless the files have been excluded. For information on how to exclude files from analysis, see "Specifying directories to scan."
  • For CodeQL code scanning workflow files, don't use the paths-ignore or paths keywords with the on:push event as this is likely to cause missing analyses. For accurate results, CodeQL code scanning needs to be able to compare new changes with the analysis of the previous commit.

For more information about using on:pull_request:paths-ignore and on:pull_request:paths to determine when a workflow will run for a pull request, see "Workflow syntax for GitHub Actions."

Scanning on a schedule

If you use the default CodeQL分析ワークフロー, the workflow will scan the code in your repository once a week, in addition to the scans triggered by events. To adjust this schedule, edit the cron value in the workflow. For more information, see "Workflow syntax for GitHub Actions."

Note: GitHub only runs scheduled jobs that are in workflows on the default branch. Changing the schedule in a workflow on any other branch has no effect until you merge the branch into the default branch.

Example

The following example shows a CodeQL分析ワークフロー for a particular repository that has a default branch called main and one protected branch called protected.

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

This workflow scans:

  • Every push to the default branch and the protected branch
  • Every pull request to the default branch
  • The default branch every Monday at 14:20 UTC

Specifying an operating system

If your code requires a specific operating system to compile, you can configure the operating system in your CodeQL分析ワークフロー. Edit the value of jobs.analyze.runs-on to specify the operating system for the machine that runs your code scanning actions. 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]

CodeQL code scanning supports the latest versions of Ubuntu, Windows, and macOS. 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.

Specifying the location for CodeQL databases

In general, you do not need to worry about where the CodeQL分析ワークフロー places CodeQL databases since later steps will automatically find databases created by previous steps. However, if you are writing a custom workflow step that requires the CodeQL database to be in a specific disk location, for example to upload the database as a workflow artifact, you can specify that location using the db-location parameter under the init action.

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

The CodeQL分析ワークフロー will expect the path provided in db-location to be writable, and either not exist, or be an empty directory. When using this parameter in a job running on a self-hosted runner or using a Docker container, it's the responsibility of the user to ensure that the chosen directory is cleared between runs, or that the databases are removed once they are no longer needed. This is not necessary for jobs running on GitHub-hosted runners, which obtain a fresh instance and a clean filesystem each time they run. For more information, see "About GitHub-hosted runners."

If this parameter is not used, the CodeQL分析ワークフロー will create databases in a temporary location of its own choice.

Changing the languages that are analyzed

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

Configuring a category for the analysis

Use category to distinguish between multiple analyses for the same tool and commit, but performed on different languages or different parts of the code. The category you specify in your workflow will be included in the SARIF results file.

This parameter is particularly useful if you work with monorepos and have multiple SARIF files for different components of the monorepo.

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze
      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"

If you don't specify a category parameter in your workflow, GitHub Enterprise Server will generate a category name for you, based on the name of the workflow file triggering the action, the action name, and any matrix variables. For example:

  • The .github/workflows/codeql-analysis.yml workflow and the analyze action will produce the category .github/workflows/codeql.yml:analyze.
  • The .github/workflows/codeql-analysis.yml workflow, the analyze action, and the {language: javascript, os: linux} matrix variables will produce the category .github/workflows/codeql-analysis.yml:analyze/language:javascript/os:linux.

The category value will appear as the <run>.automationDetails.id property in SARIF v2.1.0. For more information, see "SARIF support for code scanning."

Your specified category will not overwrite the details of the runAutomationDetails object in the SARIF file, if included.

Running additional queries

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

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About code scanning with CodeQL."

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

To add one or more queries, add a with: queries: entry within the uses: github/codeql-action/init@v1 section of the workflow. If the queries are in a private repository, use the external-repository-token parameter to specify a token that has access to checkout the private repository.

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

You can also specify query suites in the value of queries. Query suites are collections of queries, usually grouped by purpose or language.

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

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

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

If you also use a configuration file for custom settings, any additional queries specified in your workflow are used instead of those specified in the configuration file. If you want to run the combined set of additional queries, prefix the value of queries in the workflow with the + symbol. For more information, see "Using a custom configuration file."

In the following example, the + symbol ensures that the specified additional queries are used together with any 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

Using a custom configuration file

A custom configuration file is an alternative way to specify additional queries to run. You can also use the 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. This example loads the configuration file ./.github/codeql/codeql-config.yml.

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

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

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: ./query-suites/my-security-queries.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.

Disabling the default queries

If you only want to run custom queries, you can disable the default security queries by using disable-default-queries: true.

Specifying directories to scan

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'

Note:

  • 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. For more information, see "Workflow syntax for GitHub Actions."
  • The filter pattern characters ?, +, [, ], and ! are not supported and will be matched literally.
  • ** characters can only be at the start or end of a line, or surrounded by slashes, and you can't mix ** and other characters. For example, foo/**, **/foo, and foo/**/bar are all allowed syntax, but **foo isn't. However you can use single stars along with other characters, as shown in the example. 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. The commands you need to use to exclude a directory from the build will depend on your build system. For more information, see "Configuring the CodeQL workflow for compiled languages."

You can quickly analyze small portions of a monorepo when you modify code in specific directories. You'll need to both exclude directories in your build steps and use the paths-ignore and paths keywords for on.<push|pull_request> in your workflow.

Example configuration files

この設定ファイルは、コードのスキャン時に 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'

Configuring code scanning for compiled languages

サポートされているコンパイル言語では、コードをビルドするためにCodeQL分析ワークフロー内でautobuildアクションを使うことができます。 これによって、C/C++、C#、Javaでは明示的にビルドコマンドを指定する必要がなくなります。 CodeQLは、プロジェクトをセットアップするためにGoのプロジェクトのビルドも実行します。 ただし、他のコンパイル言語とは対照的に、リポジトリ内のGoのファイルはビルドされるものだけでなく、すべてが展開されます。 ビルドが処理しないGoのファイルの展開をスキップするために、カスタムのビルドコマンドを使うこともできます。

リポジトリ内の C/C++、C#、またはJava のコードに非標準のビルドプロセスがある場合、 autobuild が失敗することがあります。 ワークフローからautobuildステップを取り除き、手動でビルドのステップを追加する必要があるでしょう。 リポジトリのGoのファイルで展開するものを指定したい場合には、ビルドのステップを追加しなければなりません。 For more information about how to configure CodeQL code scanning for compiled languages, see "Configuring the CodeQL workflow for compiled languages."

Uploading code scanning data to GitHub

GitHub can display code analysis data generated externally by a third-party tool. You can upload code analysis data with the upload-sarif action. For more information, see "Uploading a SARIF file to GitHub."

このドキュメントは役立ちましたか?

プライバシーポリシー

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

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

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

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

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