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

コードスキャンの SARIF サポート

To display results from a third-party static analysis tool in your repository on GitHub, you'll need your results stored in a SARIF file that supports a specific subset of the SARIF 2.1.0 JSON schema for code scanning. デフォルトの CodeQL 静的分析エンジンを使用すると、結果は GitHub のリポジトリに自動的に表示されます。

Code scanning is available if you have an Advanced Security license.

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

ノート: Code scanningは現在ベータで、変更されることがあります。 For more information about taking part in the beta, sign up here.

SARIF サポートについて

SARIF(Static Analysis Results Interchange Format)は、出力ファイル形式を定義する OASIS 標準です。 SARIF 標準は、静的分析ツールが結果を共有する方法を合理化するために使用されます。 Code scanning は、SARIF 2.1.0 JSON スキーマのサブセットをサポートしています。

サードパーティの静的コード分析エンジンから SARIF ファイルをアップロードするには、アップロードされたファイルが SARIF 2.1.0 バージョンを使用していることを確認する必要があります。 GitHub will parse the SARIF file and show alerts using the results in your repository as a part of the code scanning experience. 詳しい情報については、「SARIF ファイルを GitHub にアップロードする」を参照してください。 SARIF 2.1.0 JSON スキーマの詳細については、「sarif-schema-2.1.0.json」を参照してください。

SARIF ファイルに partialFingerprints が含まれていない場合、GitHub Actions を使用して SARIF ファイルをアップロードすると、partialFingerprints フィールドが計算されます。 For more information, see "Enabling code scanning" or "Running CodeQL code scanning in your CI system."

GitHub は、SARIF ファイルのプロパティを使用してアラートを表示します。 たとえば、shortDescriptionfullDescription は、code scanning アラートの上部に表示されます。 location により、GitHub がコードファイルに注釈を表示できるようになります。 For more information, see "Managing code scanning alerts for your repository."

SARIF の使用が初めてで、詳細を確認する必要がある場合は、Microsoft の SARIF tutorials リポジトリを参照してください。

フィンガープリントを使用してアラートの重複を防止する

GitHub Actions ワークフローが新しいコードスキャンを実行するたびに、それぞれの実行結果が処理され、アラートがリポジトリに追加されます。 同じ問題に対するアラートの重複を防ぐために、code scanning はフィンガープリントを使用してさまざまな実行結果を照合し、選択したブランチの最新の実行で 1 回だけ表示されるようにします。 This makes it possible to match alerts to the right line of code when files are edited.

GitHub は、OASIS 標準の partialFingerprints プロパティを使用して、2 つの結果が論理的に同一の場合に検出します。 詳しい情報については、OASIS ドキュメントの「"partialFingerprints プロパティ」エントリを参照してください。

id は SARIF ファイルの他の部分から参照され、code scanning が GitHub に URL を表示するために使用できます。 If you upload a SARIF file using the upload-sarif action and this data is missing, GitHub attempts to populate the partialFingerprints field from the source files. For more information about uploading results, see "Uploading a SARIF file to GitHub."

If you upload a SARIF file without fingerprint data using the /code-scanning/sarifs API endpoint, the code scanning alerts will be processed and displayed, but users may see duplicate alerts. To avoid seeing duplicate alerts, you should calculate fingerprint data and populate the partialFingerprints property before you upload the SARIF file. You may find the script that the upload-sarif action uses a helpful starting point: https://github.com/github/codeql-action/blob/main/src/fingerprints.ts. For more information about the API, see "Upload a SARIF file."

Validating your SARIF file

You can check a SARIF file is compatible with code scanning by testing it against the GitHub ingestion rules. For more information, visit the Microsoft SARIF validator.

サポートされている SARIF 出力ファイルのプロパティ

CodeQL 以外のコード分析エンジンを使用する場合、サポートされている SARIF プロパティを確認して、GitHub での分析結果の表示方法を最適化できます。

有効な SARIF 2.1.0 出力ファイルはすべてアップロードできますが、code scanning は以下のサポートされているプロパティのみを使用します。

sarifLog オブジェクト

名前説明
$schema必須。バージョン 2.1.0 の SARIF JSON スキーマの URI。 例: https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json
version必須。Code scanning は、SARIF バージョン 2.1.0 のみをサポートしています。
runs[]必須。SARIF ファイルには、1 つ以上の実行の配列が含まれています。 各実行は、分析ツールの 1 回の実行を表します。 run の詳細については、「run オブジェクト」を参照してください。

run オブジェクト

Code scanning は run オブジェクトを使用して、ツールで結果をフィルタし、結果のソースに関する情報を提供します。 run オブジェクトには、結果を生成したツールに関する情報を含む tool.driver ツールコンポーネントオブジェクトが含まれます。 run ごとに、1 つの分析ツールの結果のみを取得できます。

名前説明
tool.driver.name必須。分析ツールの名前。 Code scanning は、GitHub に名前を表示して、ツールで結果をフィルタできるようにします。
tool.driver.version任意。分析ツールのバージョン。 Code scanning は、バージョン番号を使用して、分析されているコードでの変更ではなく、ツールのバージョン変更により結果が変更された可能性がある場合に追跡します。 SARIF ファイルに semanticVersion フィールドが含まれている場合、version は code scanning で使用されません。
tool.driver.semanticVersion任意。セマンティックバージョニング 2.0 形式で指定された分析ツールのバージョン。 Code scanning は、バージョン番号を使用して、分析されているコードでの変更ではなく、ツールのバージョン変更により結果が変更された可能性がある場合に追跡します。 SARIF ファイルに semanticVersion フィールドが含まれている場合、version は code scanning で使用されません。 詳しい情報については、セマンティックバージョニングのドキュメントの「セマンティックバージョニング 2.0.0」を参照してください。
tool.driver.rules[]必須。ルールを表す reportingDescriptor オブジェクトの配列。 分析ツールはルールを使用して、分析対象のコードの問題を見つけます。 詳しい情報については、「reportingDescriptor オブジェクト」を参照してください。
results[]必須。分析ツールの結果。 Code scanning は GitHub に結果を表示します。 詳しい情報については、「result オブジェクト」を参照してください。

reportingDescriptor オブジェクト

名前説明
id必須。ルールの一意の識別子。 id は SARIF ファイルの他の部分から参照され、code scanning が GitHub に URL を表示するために使用できます。
name任意。ルールの名前。 Code scanning は、GitHub のルールで結果をフィルタできるように名前を表示します。
shortDescription.text必須。ルールの簡単な説明。 Code scanning は、関連する結果の横にある GitHub の簡単な説明を表示します。
fullDescription.text必須。ルールの説明。 Code scanning は、関連する結果の横にある GitHub の説明全体を表示します。 文字数は最大 1000 文字に制限されています。
defaultConfiguration.level任意。ルールのデフォルトの重要度レベル。 Code scanning は、特定のルールの結果がどの程度重要であるかを理解するために、重要度レベルを使用します。 この値は、result オブジェクトの level 属性でオーバーライドできます。 詳しい情報については、「result オブジェクト」を参照してください。 デフォルト: Warning
help.text必須。テキスト形式を使用したルールのドキュメント。 Code scanning は、関連する結果の横にこのヘルプドキュメントを表示します。
help.markdown推奨。Markdown 形式を使用したルールのドキュメント。 Code scanning は、関連する結果の横にこのヘルプドキュメントを表示します。 When help.markdown is available, it is displayed instead of help.text.
properties.tags[]任意。文字列の配列。 Code scanning は、tags を使用して、GitHub の結果をフィルタできます。 たとえば、security タグを含むすべての結果をフィルタすることができます。
properties.precision推奨。このルールで示される結果が true である頻度を示す文字列。 たとえば、ルールに既知の高誤検知率がある場合、精度は low である必要があります。 Code scanning は、GitHub の精度で結果を並べ替えるため、最高 level の精度と最高 precision の結果が最初に表示されます。 Can be one of: very-high, high, medium, or low.

result オブジェクト

名前説明
ruleId任意。ルールの一意の識別子(reportingDescriptor.id)。 詳しい情報については、「reportingDescriptor オブジェクト」を参照してください。 Code scanning は、ルール識別子を使用して、GitHub のルールで結果をフィルタします。
ruleIndex任意。ツールコンポーネントの rules 配列内の関連するルール(reportingDescriptor オブジェクト)のインデックス。 詳しい情報については、「run オブジェクト」を参照してください。
rule任意。この結果のルール(レポート記述子)を見つけるために使用される参照。 詳しい情報については、「reportingDescriptor オブジェクト」を参照してください。
level任意。結果の重要度。 このレベルは、ルールで定義されているデフォルトの重要度をオーバーライドします。 Code scanning は、レベルを使用して、GitHub の重要度で結果をフィルタします。
message.text必須。結果を説明するメッセージ。 Code scanning は、結果のタイトルとしてメッセージテキストを表示します。 表示スペースが限られている場合、メッセージの最初の文のみが表示されます。
locations[]必須。結果が検出された場所。 指定された場所ごとに変更を加えることでのみ問題を修正できる場合を除き、1 つの場所のみを含める必要があります。 注釈: code scanning が結果を表示するには、少なくとも 1 つの場所が必要です。 Code scanning は、このプロパティを使用して、結果を注釈するファイルを決定します。 この配列の最初の値のみが使用されます。 他のすべての値は無視されます。
partialFingerprints必須。結果の一意の ID を追跡するために使用される文字列。 Code scanning は、partialFingerprints を使用して、コミットとブランチで同じ結果であるものを正確に識別します。 Code scanning は、partialFingerprints がある場合、それを使用しようとします。 upload-action を使用してサードパーティの SARIF ファイルをアップロードする場合、SARIF ファイルに含まれていないときに、アクションによって partialFingerprints が作成されます。 詳しい情報については、「フィンガープリントを使用してアラートの重複を防止する」を参照してください。 注釈: Code scanning は、primaryLocationLineHash のみを使用します。
codeFlows[].threadFlows[].locations[]任意。threadFlow オブジェクトに対する location オブジェクトの配列。実行スレッドを通してプログラムの進行状況を記述します。 codeFlow オブジェクトは、結果の検出に使用されるコード実行パターンを記述します。 コードフローが入力されている場合、code scanning は、関連する結果の GitHub のコードフローを拡張します。 詳しい情報については、「location オブジェクト」を参照してください。
relatedLocations[]この結果に関連する場所。 結果メッセージに埋め込まれている場合、Code scanning は、関連する場所にリンクします。 詳しい情報については、「location オブジェクト」を参照してください。
suppressions[].state任意。stateaccepted に設定されている場合、code scanning は GitHub の状態を Closed に更新します。

location オブジェクト

プログラミングアーティファクト内の場所(リポジトリ内のファイルやビルド中に生成されたファイルなど)。

名前説明
location.id任意。この場所を単一の結果オブジェクト内の他のすべての場所と区別する一意の識別子。
location.physicalLocation必須。アーティファクトとリージョンを識別します。 詳しい情報については、「physicalLocation」を参照してください。
location.message.text任意。場所に関連するメッセージ。

physicalLocation オブジェクト

名前説明
artifactLocation.uri必須。アーティファクトの場所を示す URI(通常はリポジトリ内のファイル、またはビルド中に生成されたファイル)。 URI が相対の場合、分析されている GitHub リポジトリのルートに相対である必要があります。 たとえば、main.js または src/script.js は、リポジトリのルートを基準にしています。 URI が絶対の場合、code scanning は URI を使用してアーティファクトをチェックアウトし、リポジトリ内のファイルを照合できます。 例: https://github.com/github/example/blob/00/src/promiseUtils.js
region.startLine必須。リージョンの最初の文字の行番号。
region.startColumn必須。リージョンの最初の文字の列番号。
region.endLine必須。リージョンの最後の文字の行番号。
region.endColumn必須。リージョンの末尾に続く文字の列番号。

SARIF 出力ファイルの例

次の例の SARIF 出力ファイルは、サポートされているプロパティと値の例を示しています。

最低限必要なプロパティの例

次の SARIF 出力ファイルには、code scanning の結果が期待どおりに機能するために最低限必要なプロパティを示す値の例が示されています。 プロパティを削除したり、値を含めていない場合、このデータは正しく表示されないか、GitHub で同期されません。

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Tool Name",
          "rules": [
            {
              "id": "R01"
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "R01",
          "message": {
            "text": "Result text. This result does not have a rule associated."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "fileURI"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 7,
                  "endColumn": 10
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "39fa2ee980eb94b0:1"
          }
        }
      ]
    }
  ]
}

サポートされているすべての SARIF プロパティを示す例

次の SARIF 出力ファイルには、code scanning でサポートされているすべての SARIF プロパティを示す値の例が示されています。

{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Tool Name",
          "semanticVersion": "2.0.0",
          "rules": [
            {
              "id": "3f292041e51d22005ce48f39df3585d44ce1b0ad",
              "name": "js/unused-local-variable",
              "shortDescription": {
                "text": "Unused variable, import, function or class"
              },
              "fullDescription": {
                "text": "Unused variables, imports, functions or classes may be a symptom of a bug and should be examined carefully."
              },
              "defaultConfiguration": {
                "level": "note"
              },
              "properties": {
                "tags": [
                  "maintainability"
                ],
                "precision": "very-high"
              }
            },
            {
              "id": "d5b664aefd5ca4b21b52fdc1d744d7d6ab6886d0",
              "name": "js/inconsistent-use-of-new",
              "shortDescription": {
                "text": "Inconsistent use of 'new'"
              },
              "fullDescription": {
                "text": "If a function is intended to be a constructor, it should always be invoked with 'new'. Otherwise, it should always be invoked as a normal function, that is, without 'new'."
              },
              "properties": {
                "tags": [
                  "reliability",
                  "correctness",
                  "language-features"
                ],
                "precision": "very-high"
              }
            },
            {
              "id": "R01"
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "3f292041e51d22005ce48f39df3585d44ce1b0ad",
          "ruleIndex": 0,
          "message": {
            "text": "Unused variable foo."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "main.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 7,
                  "endColumn": 10
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "39fa2ee980eb94b0:1",
            "primaryLocationStartColumnFingerprint": "4"
          }
        },
        {
          "ruleId": "d5b664aefd5ca4b21b52fdc1d744d7d6ab6886d0",
          "ruleIndex": 1,
          "message": {
            "text": "Function resolvingPromise is sometimes invoked as a constructor (for example [here](1)), and sometimes as a normal function (for example [here](2))."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/promises.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2
                }
              }
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "5061c3315a741b7d:1",
            "primaryLocationStartColumnFingerprint": "7"
          },
          "relatedLocations": [
            {
              "id": 1,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/ParseObject.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 2281,
                  "startColumn": 33,
                  "endColumn": 55
                }
              },
              "message": {
                "text": "here"
              }
            },
            {
              "id": 2,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/LiveQueryClient.js",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 166
                }
              },
              "message": {
                "text": "here"
              }
            }
          ]
        },
        {
          "ruleId": "R01",
          "message": {
            "text": "Specifying both [ruleIndex](1) and [ruleID](2) might lead to inconsistencies."
          },
          "level": "error",
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif",
                  "uriBaseId": "%SRCROOT%"
                },
                "region": {
                  "startLine": 54,
                  "startColumn": 10,
                  "endLine": 55,
                  "endColumn": 25
                }
              }
            }
          ],
          "relatedLocations": [
            {
              "id": 1,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif"
                },
                "region": {
                  "startLine": 81,
                  "startColumn": 10,
                  "endColumn": 18
                }
              },
              "message": {
                "text": "here"
              }
            },
            {
              "id": 2,
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "full.sarif"
                },
                "region": {
                  "startLine": 82,
                  "startColumn": 10,
                  "endColumn": 21
                }
              },
              "message": {
                "text": "here"
              }
            }
          ],
          "codeFlows": [
            {
              "threadFlows": [
                {
                  "locations": [
                    {
                      "location": {
                        "physicalLocation": {
                          "region": {
                            "startLine": 11,
                            "endLine": 29,
                            "startColumn": 10,
                            "endColumn": 18
                          },
                          "artifactLocation": {
                            "uriBaseId": "%SRCROOT%",
                            "uri": "full.sarif"
                          }
                        },
                        "message": {
                          "text": "Rule has index 0"
                        }
                      }
                    },
                    {
                      "location": {
                        "physicalLocation": {
                          "region": {
                            "endColumn": 47,
                            "startColumn": 12,
                            "startLine": 12
                          },
                          "artifactLocation": {
                            "uriBaseId": "%SRCROOT%",
                            "uri": "full.sarif"
                          }
                        }
                      }
                    }
                  ]
                }
              ]
            }
          ],
          "partialFingerprints": {
            "primaryLocationLineHash": "ABC:2"
          }
        }
      ],
      "columnKind": "utf16CodeUnits"
    }
  ]
}

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.