コードスキャンのワークフロー構成オプション

メモ

この機能を使用するには、サイト管理者が code scanning を有効にする必要があります。コードをスキャンするためにGitHub Actionsを使いなら、サイト管理者はGitHub Actionsの有効化と、必要なインフラストラクチャのセットアップもしなければなりません。詳しくは、「アプライアンス用コードスキャンの構成」をご覧ください。

メモ

この記事では、このバージョンの GitHub Enterprise Server の初期リリースに含まれる CodeQL アクションのバージョンおよび関連する CodeQL CLI バンドルで使用できる機能について説明します。エンタープライズでより新しいバージョンの CodeQL アクションを使用する場合は、この記事の GitHub Enterprise Cloud バージョンで最新の機能に関する情報を参照してください。最新バージョンの使用方法については、「アプライアンス用コードスキャンの構成」を参照してください。

[前提条件]

          code scanningの詳細設定を使用し、構成が定義されているワークフロー ファイルを編集できるようにする必要があります。

この記事で示す例は、 CodeQL 分析ワークフローファイルに関連しています。既定では、このファイルは .github/workflows/codeql-analysis.ymlで定義されます。

スキャンの頻度

スケジュールに従って、またはリポジトリで特定のイベントが発生したときにコードをスキャンするように CodeQL 分析ワークフローを構成できます。

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

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

既定では、 CodeQL 分析ワークフローは on:push イベントを使用して、リポジトリの既定のブランチと保護されたブランチへのすべてのプッシュでコードスキャンをトリガーします。指定したブランチで code scanning をトリガーするには、そのブランチにワークフローが存在する必要があります。詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。

プッシュ時にスキャンすると、リポジトリの [ Security ] タブに結果が表示されます。詳しくは、「リポジトリのコードスキャンのアラートの評価」をご覧ください。

さらに、開かれた pull request にマップできる結果が on:push スキャンから返された場合、これらのアラートは他の pull request アラートと同じ場所にある pull request に自動的に表示されます。これらのアラートは、ブランチのヘッドの既存の分析とターゲットブランチの分析を比較することで特定します。プル要求の code scanning アラートの詳細については、 Pull RequestでCode scanningアラートをトリアージするを参照してください。

Pull Requestをスキャンする

既定の CodeQL 分析ワークフローでは、 pull_request イベントを使用して、既定のブランチを対象とするプル要求でコードスキャンをトリガーします。プル要求がプライベート fork.pull_request から開かれた場合、

          `pull_request` イベントについて詳しくは、「[AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request)」をご覧ください。

pull requests をスキャンすると、結果は pull request チェックのアラートとして表示されます。詳しくは、「Pull RequestでCode scanningアラートをトリアージする」をご覧ください。

ヘッドコミットではなく pull request のマージコミットをスキャンするように構成された pull_request トリガーを使用すると、各プッシュでブランチのヘッドをスキャンする場合より効果的で正確な結果が生成されます。ただし、プル要求でトリガーするように構成できない CI/CD システムを使用する場合でも、 on:push トリガーを使用できます。 code scanning は結果をマップしてブランチでプル要求を開き、プル要求の注釈としてアラートを追加します。詳細については、「プッシュ時のスキャン」を参照してください。

Pull Requestの不要なスキャンを回避する

変更されたファイルに関係なく、既定のブランチを対象とする特定の pull request でコードスキャンがトリガーされないようにしたい場合があります。これを構成するには、on:pull_request:paths-ignore ワークフローでon:pull_request:pathsまたはcode scanningを指定します。たとえば、pull request 内の変更がファイル拡張子 .md または .txt のファイルに対するものだけである場合、次の paths-ignore 配列を使用できます。

YAML

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

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

メモ

          `on:pull_request:paths-ignore` と `on:pull_request:paths` で、ワークフロー内のアクションが pull request で実行されるかどうかを決定する条件を設定します。 アクションが実行 _される_ ときにどのファイルが解析されるかは決定されません。 pull request に `on:pull_request:paths-ignore` または `on:pull_request:paths` で一致しないファイルが含まれている場合、ワークフローによって、アクションが実行され、そのファイルが除外されていない限り、`on:pull_request:paths-ignore` または `on:pull_request:paths` で一致するファイルを含め、pull request で変更されたすべてのファイルがスキャンされます。 分析からファイルを除外する方法については、「[スキャンするディレクトリを指定する](#specifying-directories-to-scan)」を参照してください。

          `on:pull_request:paths-ignore` と `on:pull_request:paths` を使って pull request に対してワークフローをいつ実行するかを決定する方法について詳しくは、「[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore)」をご覧ください。

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

既定の CodeQL 分析ワークフローを使用すると、ワークフローは、イベントによってトリガーされるスキャンに加えて、週に 1 回リポジトリ内のコードをスキャンします。このスケジュールを調整するには、ワークフロー内の cron イベントの on.schedule 値を編集します。詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。

メモ

ワークフローファイルが既定のブランチに存在する場合にのみ、このイベントによってワークフローの実行がトリガーされます。

例

次の例は、CodeQL 分析ワークフローという名前の既定のブランチと、mainという 1 つの保護されたブランチを持つ特定のリポジトリのprotectedを示しています。

YAML

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

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

このワークフローでは以下をスキャンします。

既定のブランチと保護されたブランチへのすべてのプッシュ
既定のブランチへのすべての pull request
毎週月曜日 14 時 20 分 (UTC) に既定のブランチ

オペレーティングシステム

メモ

Swift コードのコードスキャンでは、既定で macOS ランナーが使用されます。

Swift コードの Code scanning は、Actions Runner Controller (ARC) の一部であるランナーではサポートされていません。ARC をキャプチャするランナーでは Linux のみが使用されるため、Swift には macOS ランナーが必要です。ただし、ARC をキャプチャするランナーとセルフホストの macOS ランナーの両方を組み合わせることもできます。詳しくは、「アクションランナーコントローラー」をご覧ください。

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

YAML

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

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

          CodeQL
          code scanning は、Ubuntu、Windows、および macOS の最新バージョンをサポートしています。 したがって、この設定の一般的な値は、`ubuntu-latest`、`windows-latest`、`macos-latest` です。 詳細については、「[AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job)」および「[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners)」を参照してください。

          Git がセルフホステッド ランナーの PATH 変数にあることを確認する必要があります。 詳細については、「[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners)」および「[AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners)」を参照してください。

セルフホステッドマシンで CodeQL 分析を実行するための推奨仕様 (RAM、CPU コア、ディスクCodeQL を実行するための推奨ハードウェアリソースを参照してください。

          CodeQL データベースの場所

一般に、後の手順では前の手順で作成されたデータベースが自動的に検索されるため、 CodeQL 分析ワークフローがデータベース CodeQL 配置する場所について心配する必要はありません。ただし、CodeQL データベースを特定のディスクの場所に配置する必要があるカスタムワークフローステップを作成する場合 (たとえば、データベースをワークフロー成果物としてアップロードする場合)、db-location アクションの下で init パラメーターを使用してその場所を指定できます。

YAML

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

          CodeQL 分析ワークフローでは、`db-location`で指定されたパスは書き込み可能であり、存在しないか、空のディレクトリであることが想定されます。 セルフホストランナー上で動作するか、Dockerコンテナを使うジョブでこのパラメータを使う場合、選択されたディレクトリが実行間でクリアされること、あるいは不要になったらデータベースが削除されることを保証するのはユーザの責任です。 これは、 GitHubホストランナーで実行されているジョブでは必要ありません。これにより、実行されるたびに新しいインスタンスとクリーンなファイルシステムが取得されます。 詳しくは、「[AUTOTITLE](/actions/using-github-hosted-runners/about-github-hosted-runners)」をご覧ください。

このパラメーターを使用しない場合、 CodeQL 分析ワークフローは独自に選択した一時的な場所にデータベースを作成します。現在、既定値は ${{ github.runner_temp }}/codeql_databases です。

分析する言語

          CodeQL
          code scanning では、次の言語で記述されたコードがサポートされています。

C/C++
C#
Go
Java/Kotlin
JavaScript/TypeScript
Python
Ruby
Rust (パブリックプレビュー)
Swift

メモ

Java、Kotlin、またはその両方で記述されたコードを分析するには java-kotlin を使用します。
JavaScript、TypeScript、またはその両方で記述されたコードを分析するには javascript-typescript を使用します。

詳細については、CodeQL Web サイトのドキュメント「サポートされている言語とフレームワーク」を参照してください。

          CodeQL では、次の言語識別子が使用されます。

Language	識別子	オプションの代替識別子 (存在する場合)
C/C++	`c-cpp`

          `c` または `cpp` |

メモ

代替識別子の 1 つを指定した場合、これは標準の言語識別子の使用と同じです。たとえば、javascript の代わりに javascript-typescript を指定した場合、TypeScript コードの分析は除外されません。代わりに、カスタム構成ファイルを使って、paths-ignore 設定でファイルを分析対象から除外できます。詳細については、「カスタム構成ファイルの使用」と「スキャンするディレクトリを指定する」を参照してください。

これらの言語識別子は、languages アクションの init 入力に対する引数として使用できます。引数として指定する言語は 1 つに限定することをお勧めします。

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

CodeQL を使用したCodeQL 分析ワークフローした後に作成された既定のファイルでは、分析されるリポジトリ内の言語を一覧表示する language という名前のプロパティを含むマトリックスが定義されます。このマトリックスには、リポジトリで検出されたサポート対象の言語が自動的に事前設定されています。 languageマトリックスを使用すると、CodeQLは各言語分析を並列で実行し、各言語の分析をカスタマイズできます。個々の分析では、マトリックスから取得した言語名が init 入力の引数として languages アクションに渡されます。すべてのワークフローでこの構成を採用することをお勧めします。マトリックスの詳細については、「ワークフローでのジョブのバリエーションの実行」を参照してください。

YAML

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

ワークフローで language マトリックスを使用している場合、 CodeQL はマトリックス内の言語のみを分析します。分析対象の言語を変更するには、マトリックス構成を編集します。分析対象から除外する言語は削除できます。言語が分析されないようにする理由は、いくつかあります。たとえば、プロジェクトで、コードの本体に対する依存関係が別の言語の中にあり、それらの依存関係のアラートを表示したくない場合が考えられます。 code scanningの構成時にリポジトリに存在しなかった言語を追加することもできます。たとえば、 code scanning の構成時にリポジトリに最初は JavaScript のみが含まれ、後で Python コードを追加した場合は、マトリックスに python を追加する必要があります。

YAML

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

コンパイル済み言語の場合、マトリックスを使って、build-mode プロパティの値を変更することで、分析に使うビルドモードを構成することもできます。ビルドモードの詳細については、「コンパイル済み言語の CodeQL コードスキャン」を参照してください。

ワークフローがlanguages アクションのinit入力に引数を指定しない場合、CodeQLは分析を順番に実行するように構成されます。この場合、 CodeQL はリポジトリでサポートされている言語を自動的に検出し、分析を試みます。リポジトリのサイズと言語の数によっては、この処理に長時間かかる場合があります。このモードでは、1 つの言語の分析が失敗すると、すべての言語の分析が失敗します。そのため、この構成はお勧めしません。

メモ

言語を順番に分析するときは、すべての言語の既定のビルドモードが使われます。または、autobuild ステップを明示的に指定した場合は、autobuild モードをサポートするすべての言語ではそれが使われ、それ以外の言語では既定のモードが使われます。これよりも複雑なビルドモード構成が必要な場合は、マトリックスを構成する必要があります。

チェック失敗時のアラートの重大度

ルールセットを使用すると、次のいずれかの条件が満たされたときにプル要求がマージされないようにできます。

必要なツールは、ルールセットで定義されている重大度の code scanning アラートを検索します。
必要なツールの分析はまだ進行中です。
リポジトリに必要なツールが構成されていません。

詳しくは、「コードスキャンのマージ保護を設定します」をご覧ください。ルールセットの一般情報については、「AUTOTITLE」を参照してください。

分析カテゴリ

          `category` を使用して、同じツールとコミットに対して、異なる言語またはコードの異なる部分に対して実行される複数の解析を区別します。 ワークフロー中で指定したカテゴリは、SARIF結果ファイルに含まれます。

このパラメータは、特に単一リポジトリで作業をしていて、単一リポジトリの様々なコンポーネントに対して複数のSARIFファイルがある場合に有益です。

YAML

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

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

ワークフローで category パラメーターを指定しない場合、アクションをトリガーするワークフローファイルの名前、アクション名、およびマトリックス変数に基づいて、 GitHub によってカテゴリ名が生成されます。例えば次が挙げられます。 * .github/workflows/codeql-analysis.ymlワークフローと analyze アクションによって、カテゴリ .github/workflows/codeql.yml:analyze が生成されます。 * .github/workflows/codeql-analysis.yml ワークフロー、analyze アクション、{language: javascript-typescript, os: linux} マトリックス変数によって、カテゴリ .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux が生成されます。

          `category` 値は、SARIF v2.1.0 の `<run>.automationDetails.id` プロパティとして表示されます。 詳しくは、「[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#runautomationdetails-object)」をご覧ください。

指定したカテゴリは、SARIF ファイルに runAutomationDetails オブジェクトの詳細が含まれている場合、上書きされることはありません。

          CodeQL モデル パック

コードベースが、CodeQLの標準クエリで認識されないライブラリまたはフレームワークに依存している場合は、発行されたCodeQLモデルパックを指定することで、code scanning ワークフローのCodeQLカバレッジを拡張できます。独自のモデルパックの作成の詳細については、「CodeQL パックの作成と操作」を参照してください。

メモ

CodeQL モデルパックは現在ベータ段階であり、変更される可能性があります。モデルパックは C/C++、C#、Java/Kotlin、Python、および Ruby 分析でサポートされます。

Visual Studio Code 用 CodeQL 拡張機能の CodeQL モデルエディターでは、C#、Java/Kotlin、Python、Ruby に対する依存関係のモデリングがサポートされています。

          CodeQL モデル パックの使用

1 つ以上の発行済みCodeQLモデルパックを追加するには、ワークフローの with: packs: セクション内の uses: github/codeql-action/init@v4 エントリ内でそれらを指定します。 packs 内で、使用するパッケージを 1 つ以上指定し、必要に応じて、ダウンロードするバージョンを指定します。バージョンを指定しない場合は、最新バージョンがダウンロードされます。公開されていないパッケージを使用する場合は、GITHUB_TOKEN 環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。詳細については、「ワークフローでの認証に GITHUB_TOKEN を使用する」および「GitHub Actions でのシークレットの使用」を参照してください。

YAML

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

この例では、既定のクエリは、Java、およびクエリパック 7.8.9 の 7.9.0 以下のバージョンからのクエリmy-company/my-java-queriesに対して実行されます。最新バージョンのモデルパック my-repo/my-java-model-pack でモデル化された依存関係により、デフォルトのクエリと my-company/my-java-queries のクエリ両方が使用できます。

既定以外のクエリ

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

ヒント

また、分析から除外するクエリを指定したり、分析に含めたりすることもできます。これには、カスタム構成ファイルを使用する必要があります。詳細については、以下の「カスタム構成ファイル」および「特定のクエリを分析から除外する」を参照してください。

GitHub Container registry に公開されている CodeQL パックまたはリポジトリに格納されている CodeQL パックの一部である場合に、追加のクエリを実行できます。詳しくは、「CodeQL によるコードスキャンについて」をご覧ください。

追加で実行したいクエリを指定するのに使用できるオプションは、次のとおりです。

        `packs` 1 つまたは複数の CodeQL クエリ パックをインストールし、それらのパックに対して既定のクエリ スイートまたはクエリを実行します。

        `queries` 1 つの _.ql_ ファイル、複数の _.ql_ ファイルを含むディレクトリ、 _.qls_ クエリ スイート定義ファイル、または任意の組み合わせを指定します。 クエリ スイート定義の詳細については、「[CodeQL クエリ スイートの作成](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/)」を参照してください。

同じワークフローで packs と queries の両方を使用できます。

クエリパックの使用

1 つ以上のCodeQLクエリパックを追加するには、ワークフローの with: packs: セクション内にuses: github/codeql-action/init@v4 エントリを追加します。 packs 内で、使用するパッケージを 1 つ以上指定し、必要に応じて、ダウンロードするバージョンを指定します。バージョンを指定しない場合は、最新バージョンがダウンロードされます。公開されていないパッケージを使用する場合は、GITHUB_TOKEN 環境変数を、パッケージにアクセスできるシークレットに設定する必要があります。詳細については、「ワークフローでの認証に GITHUB_TOKEN を使用する」および「GitHub Actions でのシークレットの使用」を参照してください。

メモ

複数の言語の CodeQL データベースを生成するワークフローの場合は、代わりに構成ファイルで CodeQL クエリパックを指定する必要があります。詳細については、以下の「クエリパック CodeQL 指定する」を参照してください。

次の例では、scope は、パッケージを公開した Organaization または個人アカウントです。ワークフローを実行すると、4 つの CodeQL クエリパックが GitHub からダウンロードされ、各パックの既定のクエリまたはクエリスイートが実行されます。

最新バージョンの pack1 がダウンロードされ、すべての既定のクエリが実行されます。
バージョン 1.2.3 の pack2 がダウンロードされ、すべての既定のクエリが実行されます。
バージョン 3.2.1 と互換性のある最新バージョンの pack3 がダウンロードされ、すべてのクエリが実行されます。
バージョン 4.5.6 の pack4 がダウンロードされ、path/to/queries 内で見つかったクエリのみが実行されます。

YAML

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

メモ

使用するクエリパックの特定のバージョンを指定する場合は、指定したバージョンが最終的に古すぎて、CodeQL アクションで使用される既定のCodeQL エンジンで効率的に使用できなくなる可能性があります。最適なパフォーマンスを確保するために、特定のバージョンのクエリパックを指定する必要がある場合は、ピン留めされたバージョンのクエリパックをバージョンアップする必要があるかどうかを定期的に確認することを検討してください。

パックの互換性について詳しくは、「CodeQL クエリパック参照」をご覧ください。

          CodeQLパックをGitHub Enterprise Serverからダウンロードする

ワークフローで、 GitHub Enterprise Server インストールで公開されているパックを使用している場合は、ワークフローに検索先を指定する必要があります。これを行うには、registries アクションのgithub/codeql-action/init@v4入力を使用します。この入力は、次に示すように、url、packages、token の各プロパティのリストを受け入れます。

YAML

- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

レジストリリストのパッケージパターンは順番に調べられるので、通常、最も具体的なパッケージパターンを最初に置く必要があります。 tokenの値は、personal access token (classic)アクセス許可を使用してダウンロードする GitHub インスタンスによって生成されるread:packagesである必要があります。

          `|` プロパティ名の後の `registries` に注意してください。 
          GitHub Actions入力は文字列のみを受け取ることができるため、これは重要です。 
          `|`を使用すると、後続のテキストが文字列に変換され、後で github/codeql-action/init@v4 アクションによって解析されます。

QL パックでクエリを使用する

1 つまたは複数のクエリを追加するには、ワークフローの with: queries: セクション内にエントリ uses: github/codeql-action/init@v4 を追加します。クエリがプライベートリポジトリ内にある場合は、external-repository-token パラメーターを使用して、プライベートリポジトリをチェックアウトするためのアクセス権を持つトークンを指定します。

          `queries` の値でクエリ スイートを指定することもできます。 クエリ スイートは、通常、目的または言語別にグループ化されたクエリのコレクションです。

YAML

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

- uses: github/codeql-action/init@v4
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

クエリスイート	説明
`security-extended`	既定のスイートからのクエリ、および重要度と精度の低いクエリ
`security-and-quality`	`security-extended` からのクエリに加え、保守性および信頼性のクエリ。

詳細については、「CodeQL クエリセット」を参照してください。

これらの各クエリスイートには、その言語の組み込みの CodeQL クエリパックに含まれるクエリの異なるサブセットが含まれています。クエリスイートは、各クエリのメタデータを使用して自動的に生成されます。詳細については、「CodeQL クエリのメタデータ」を参照してください。

クエリスイートを指定すると、CodeQL の分析エンジンでは、既定の一連のクエリと、追加のクエリスイートで定義されている追加クエリが実行されます。

カスタム構成ファイルの処理

カスタム設定にも構成ファイルを使用する場合は、構成ファイル内に指定されたものではなく、ワークフロー内で指定された追加のパックまたはクエリが使用されます。追加のパックまたはクエリの組み合わせセットを実行する場合は、ワークフロー内の packs または queries の値にプレフィックスとして + 記号を付けます。詳細については、「カスタム構成ファイル」を参照してください。

次の例では、+ 記号を付けることで、指定した追加のパックとクエリが確実に、参照される構成ファイル内で指定したものと一緒に使用されるようになります。

YAML

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

カスタム構成ファイル

カスタム構成ファイルは、実行する追加のパックとクエリを指定するときの代替的な方法です。また、このファイルを使用して、既定のクエリを無効にしたり、特定のクエリを除外または含めたり、分析中にスキャンするディレクトリを指定したりすることもできます。

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

YAML

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

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

構成ファイルは、分析するリポジトリ内、または外部リポジトリ内に格納できます。外部リポジトリを使用すると、1 つの場所の複数のリポジトリに対して構成オプションを指定できます。外部リポジトリにある構成ファイルを参照する場合は、 OWNER/REPOSITORY/FILENAME@BRANCH 構文を使用できます。たとえば、 octo-org/shared/codeql-config.yml@main です。

構成ファイルが外部のプライベートリポジトリにある場合は、external-repository-token アクションの init パラメーターを使用して、そのプライベートリポジトリへのアクセス権を持つトークンを指定します。

YAML

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

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

構成ファイルの設定は、YAML 形式で記述します。

クエリパック CodeQL 指定する

          CodeQL クエリパックを配列で指定します。 形式は、ワークフロー ファイルで使用される形式とは異なるので注意してください。

YAML

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

クエリパックを指定する完全な書式は scope/name[@version][:path] です。 version と path はどちらも省略可能です。 version は semver バージョンの範囲です。指定しない場合は、最新バージョンが使われます。 semver の範囲の詳細については、npm の semver ドキュメントを参照してください。

複数の CodeQL データベースを生成するワークフローがある場合は、パックの入れ子になったマップを使用して、カスタム構成ファイルで実行する任意の CodeQL クエリパックを指定できます。

YAML

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

脅威モデルを活用したCodeQLのカバレッジ拡張

メモ

脅威モデルは現在ベータ段階であり、変更される可能性があります。ベータ期間中、脅威モデルは Java/Kotlin と C# 解析でのみサポートされます。

デフォルトの脅威モデルには、信頼されていないデータのリモートソースが含まれます。カスタム構成ファイルでCodeQLを指定することで、threat-models: local脅威モデルを拡張して、信頼されていないデータのローカルソース (コマンドライン引数、環境変数、ファイルシステム、データベースなど) を含めることができます。脅威モデルを拡張すると、デフォルトの脅威モデルも使用されます。

追加のクエリを指定する

追加のクエリは queries 配列に指定します。配列の各要素に、単一のクエリファイル、クエリファイルを含むディレクトリ、またはクエリスイート定義ファイルを識別する値を持つ usesパラメーターを含めます。

YAML

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

あるいは、以下の設定ファイルの例にあるように、配列の各要素に名前を与えることもできます。その他のクエリの詳細については、上記の既定以外のクエリを参照してください。

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

カスタムクエリのみを実行する場合は、disable-default-queries: true を使用して既定のセキュリティクエリを無効にすることができます。

分析からの特定のクエリの除外

カスタム構成ファイルに exclude および include フィルターを追加して、分析から除外また分析に含めるクエリを指定できます。

たとえば、これは、次のように除外する場合に便利です。

既定のスイート (security、security-extended、および security-and-quality) からの特定のクエリ。
結果に関心がない特定のクエリ。
警告と推奨事項を生成するすべてのクエリ。

以下の構成ファイルと同様の exclude フィルターを使用して、既定の分析から削除するクエリを除外できます。次の構成ファイルの例では、js/redundant-assignment および js/useless-assignment-to-local クエリの両方が分析から除外されています。

YAML

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

クエリの ID を見つけるには、[ Security ] タブのアラートの一覧でアラートをクリックします。これにより、アラートの詳細ページが開きます。 Rule ID フィールドにはクエリ ID が含まれています。アラート詳細ページについて詳しくは、「Code scanningアラートについて」をご覧ください。

ヒント

フィルターの順序が重要です。クエリとクエリパックに関する命令の後に表示される最初のフィルター命令によって、既定でクエリを含めるか除外するかが決まります。
後続の命令は順番に実行され、ファイル内で後にある命令の方が前にある命令よりも優先されます。

これらのフィルターの使用方法を示す別の例については、「サンプル構成ファイル」セクションを参照してください。

カスタム構成ファイルでの exclude および include フィルターの使用について詳しくは、「CodeQL クエリスイートの作成」をご覧ください。フィルター処理できるクエリメタデータについて詳しくは、「CodeQL クエリのメタデータ」を参照してください。

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

コードをビルドせずにコードベースを分析する場合は、構成ファイルにcode scanning配列を追加することで、特定のディレクトリ内のファイルにpathsを制限できます。 paths-ignore 配列を追加して、特定のディレクトリ内のファイルを分析から除外することもできます。このオプションは、解釈された言語 (Python、Ruby、JavaScript/TypeScript) で CodeQL アクションを実行する場合、またはコードをビルドせずにコンパイル済み言語を分析する場合 (現在 C# および Javaでサポートされています) に使用できます。

YAML

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

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

メモ

* paths構成ファイルのコンテキストで使用されるpaths-ignoreキーワードとcode scanningキーワードは、ワークフロー内のon.<push|pull_request>.pathsに使用する場合と同じキーワードと混同しないでください。これらをワークフロー内の on.<push|pull_request> の変更に使用すると、指定されたディレクトリ内のコードが変更されたときにアクションを実行するかどうかが決定されます。詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。

フィルターパターン文字 ?、+、[、]、! はサポートされていないため、文字どおりに照合されます。

          `**` 文字は、行の先頭または末尾にのみ指定するか、スラッシュで囲むことができます。また、`**` と他の文字を一緒に使用できます。 たとえば `foo/**`、`**/foo`、`foo/**/bar` は、すべて許容される構文ですが、`**foo` は許容されません。 ただし、例に示すように、1 つの星印を他の文字と一緒に使用できます。

          `*` 文字を含むものはすべて引用符で囲む必要があります。

コードがビルドされる分析では、プロジェクト内の特定のディレクトリに code scanning を制限する場合は、ワークフローで適切なビルド手順を指定する必要があります。ビルドからディレクトリを除外するために使用するコマンドは、ビルドシステムによって異なります。詳しくは、「コンパイル済み言語の CodeQL コードスキャン」をご覧ください。

特定のディレクトリ内のコードを変更した場合、モノリポの小さな部分をすばやく分析できます。ビルドステップでディレクトリを除外すること、およびワークフローで paths-ignore の paths および on.<push|pull_request> キーワードを使用することが、どちらも必要になります。

サンプル構成ファイル

この構成ファイルは、コードのスキャン時に 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 CodeQL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript CodeQL pack (run queries from an external repo)
    uses: octo-org/javascript-codeql-pack@main
  - name: Use an external query (run a single query from an external CodeQL pack)
    uses: octo-org/python-codeql-pack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls

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

次の構成ファイルを使用すると、重大度エラーのアラートを生成するクエリのみが実行されます。構成では、最初にすべての既定のクエリ、./my-queries 内のすべてのクエリ、および codeql/java-queries 内の既定のスイートを選んでから、警告または推奨事項を生成するすべてのクエリを除外します。

queries:
  - name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

構成の詳細

ワークフローファイルで追加の構成の詳細を指定する場合は、config アクションの init コマンドのCodeQL入力を使用できます。この入力の値は、上記のカスタム構成ファイルに記載されている構成ファイル形式に従う YAML 文字列である必要があります。

構成例

          GitHub Actions ワークフロー ファイルのこの手順では、`config`入力を使用して既定のクエリを無効にし、`security-extended`クエリ スイートを追加し、`cwe-020`でタグ付けされたクエリを除外します。

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

同じ方法を使用して、ワークフローファイル内の有効な構成オプションを指定できます。

ヒント

          GitHub Actions変数を使用して、複数のリポジトリ間で 1 つの構成を共有できます。 この方法の利点の 1 つは、ワークフロー ファイルを編集せずに 1 か所で構成を更新できることです。

次の例では、 vars.CODEQL_CONF は GitHub Actions 変数です。その値には、有効な構成ファイルの内容を指定できます。詳しくは、「変数に情報を格納する」をご覧ください。
- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

コンパイル済み言語

コンパイル済み言語の場合、 CodeQL アクションで分析用の CodeQL データベースを作成する方法を決定できます。利用可能なビルドオプションについては、「コンパイル済み言語の CodeQL コードスキャン」をご覧ください。

データのアップロード

          GitHub では、サード パーティ製ツールによって外部から生成されたコード分析データを表示できます。 
          `upload-sarif` アクションを使用してコード分析データをアップロードできます。 詳しくは、「[AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github)」をご覧ください。

コード スキャンのワークフロー構成オプション

この機能を使用できるユーザーについて

この記事で

コードスキャンのワークフロー構成オプション