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

code scanning の設定について

GitHub Actions を使用して、または CodeQLランナー を使用して継続的インテグレーション (CI) システムから code scanning を GitHub Enterprise Server 上で実行できます。 GitHub Actions に関する詳しい情報については、「GitHub Actions について」を参照してください。 For more information about the CodeQLランナー, see "Running code scanning in your CI system."

この記事は、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分析ワークフロー ファイルに関するものです。

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] フォームに入力します。 現在のブランチに直接コミットするか、新しいブランチを作成してプルリクエストを開始するかを選択できます。

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

頻度を設定する

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

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

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

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

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

デフォルトの CodeQL分析ワークフロー は、pull_request イベントを使用して、デフォルトブランチに対するプルリクエストのコードスキャンをトリガーします。 プルリクエストをプライベートフォークからオープンした場合、pull_request イベントはトリガーされません。

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

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

どのファイルが変更されたかに関わらず、デフォルトブランチに対する特定のプルリクエストにコードスキャンがトリガーされることを避けたい場合もあるでしょう。 これを設定するには、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-ignore と on:pull_request:paths を使用して、プルリクエストに対していつワークフローを実行するかを決定することに関する詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。

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

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

サンプル

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

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '40 7 * * 2'

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

• デフォルトブランチと保護されたブランチに対する全てのプッシュ
• デフォルトブランチに対する全てのプルリクエスト
• 毎週火曜日 7:40 (UTC) にデフォルトブランチ

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

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

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. 詳しい情報については、「GitHub Actions のワークフロー構文」および「セルフホストランナーでラベルを使用する」を参照してください。

セルフホストランナーの PATH 変数に Git が確実に含まれるようにしてください。

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

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

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

単一の .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-quality	security-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という構文が利用できます。 たとえば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.

追加のクエリを指定する

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'

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 にアップロードする」を参照してください。