# SARIF reports

You can import [Static Analysis Results Interchange Format (SARIF)](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) reports into SonarQube. The issues will be taken into account by SonarQube in the analysis report, but the rules corresponding to these issues will not be visible on the **Rules** page nor reflected in quality profiles. This means that the rules that raise external issues must be managed in your third-party tool.

## Import process <a href="#import-process" id="import-process"></a>

SonarQube manages the import of a SARIF issue as follows:

* It assigns the `CONVENTIONAL` Coding attribute and the `SECURITY` software quality to the issue.
* For MQR Mode, it maps the issue's severity level on the SECURITY software quality using the following fields:
  * `runs[].tool.extensions.rules[].defaultConfiguration.level` is overridden by
  * `runs[].tool.driver.rules[].defaultConfiguration.level`
* For Standard Experience, it maps the issues severity level on the Vulnerability type
  * `runs[].tool.extensions.rules[].defaultConfiguration.level` is overridden by
  * `runs[].tool.driver.rules[].defaultConfiguration.level` is overridden by
  * `runs[].results[].level`

{% tabs %}
{% tab title="MULTI-QUALITY RULE MODE" %}

| **Severity field in SARIF 2.1.0** | **Impact level in SonarQube Server** |
| --------------------------------- | ------------------------------------ |
| error                             | HIGH                                 |
| warning                           | MEDIUM                               |
| note                              | LOW                                  |
| none                              | LOW                                  |

* Otherwise, the default MEDIUM impact level is applied.
  {% endtab %}

{% tab title="STANDARD EXPERIENCE" %}

| **Severity field in SARIF 2.1.0** | **Impact level in SonarQube Server** |
| --------------------------------- | ------------------------------------ |
| error                             | CRITICAL                             |
| warning                           | MAJOR                                |
| note                              | MINOR                                |
| none                              | LOW                                  |

* Otherwise, the default MAJOR impact level is applied.
  {% endtab %}
  {% endtabs %}

See [software-qualities](https://docs.sonarsource.com/sonarqube-community-build/quality-standards-administration/managing-rules/software-qualities "mention") and [standard-experience](https://docs.sonarsource.com/sonarqube-community-build/instance-administration/analysis-functions/instance-mode/standard-experience "mention") for more details.

## Setting up the import <a href="#setting-up" id="setting-up"></a>

To set up the import of SARIF reports into SonarQube:

1. Prepare your SARIF report files according to the import file specifications below.
2. Use on the scanner side the [analysis-parameters](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/analysis-parameters "mention") `sonar.sarifReportPaths` to define the list of SARIF report files to be imported during your project analysis. This parameter accepts a comma-delimited list of paths.

## Import file specifications <a href="#import-file-specifications" id="import-file-specifications"></a>

The SARIF files must:

* Be UTF-8 file encoded.
* Comply with the [official SARIF format, version 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html).

### Mandatory fields <a href="#mandatory-fields" id="mandatory-fields"></a>

| Field                           | Description                                                               |
| ------------------------------- | ------------------------------------------------------------------------- |
| `version`                       | Must be set to "2.1.0".                                                   |
| `runs[].tool.driver.name`       | Name of the tool that created the report.                                 |
| `runs[].results[].message.text` | Message of the external issue.                                            |
| `runs[].results[].ruleId`       | Identifier of the corresponding rule in the tool that created the report. |

{% hint style="info" %}
If a mandatory field is missing, the report is ignored (see the corresponding line in the logs).
{% endhint %}

### Optional fields <a href="#optional-fields" id="optional-fields"></a>

<table><thead><tr><th width="194.4609375">Field</th><th width="159.3125">Sub-field</th><th>Description</th></tr></thead><tbody><tr><td><code>runs[].tool.driver</code></td><td></td><td>The tool that generated the report.</td></tr><tr><td><code>runs[].tool.driver.rules[]</code></td><td><code>id</code></td><td>Identifier of the rule of the tool that created the report.</td></tr><tr><td></td><td><code>shortDescription.text</code></td><td>Short description is mapped as the name of the rule in SonarQube. If the field is empty, SonarQube constructs the name based on the driver <code>name</code> and <code>id</code> fields.</td></tr><tr><td></td><td><code>fullDescription.text</code></td><td>Full description of the rule.</td></tr><tr><td></td><td><code>defaultConfiguration.level</code></td><td>SonarQube uses this field to determine the issue's impact level on vulnerability for Standard Experience and security for MQR Mode.</td></tr><tr><td><code>runs[].tool.extensions.rules[]</code></td><td><code>defaultConfiguration.level</code></td><td>SonarQube uses this field to determine the issue's impact level on vulnerability for Standard Experience and security for MQR Mode, if the driver field <code>runs[].tool.driver.rules[].defaultConfiguration.level</code> above is not used.</td></tr><tr><td><code>runs[].results[]</code></td><td><code>level</code></td><td><p>Used to map the severity level for Standard Experience only. For severity levels for MQR mode see <code>runs[].tool.driver.rules[].defaultConfiguration.level</code> above.</p><p>If this field is not defined <code>runs[].tool.driver.rules[].defaultConfiguration</code> will be used instead.</p></td></tr><tr><td></td><td><code>stacks[]</code></td><td>The stacks are mapped to the issue flows.</td></tr><tr><td></td><td><code>stacks[].frames[]</code></td><td>Each frame of a stack represents one path of the whole issue flow.</td></tr><tr><td></td><td><code>stack.frames.location</code></td><td>Follows the same pattern as in locations indicated below.</td></tr><tr><td><code>runs[].results[].locations[]</code></td><td></td><td>SonarQube only uses the first item in the array. It must be a physical location.</td></tr><tr><td></td><td><code>physicalLocation.artifactLocation.uri</code></td><td><p>Path of the file concerned by the issue.</p><p>If no location is defined, the issue is raised at the project level.</p></td></tr><tr><td></td><td><code>physicalLocation.region</code></td><td><p>Text range concerned by the issue. Is defined by the following fields:</p><ul><li><code>startLine</code></li><li><code>startColumn</code>(optional)</li><li><code>endLine</code> (optional)</li><li><code>endColumn</code> (optional)</li></ul><p>If <code>startColumn</code>, <code>endLine</code>, <code>endColumn</code> are not specified,SonarQube automatically retrieves the full coordinates of the line.</p></td></tr><tr><td></td><td><code>relatedLocations</code></td><td>Contains the same fields as <code>physicalLocation</code>.</td></tr></tbody></table>

{% hint style="warning" %}
The `runs[].results[].level`field which defines the issue's severity will be ignored by SonarQube in MQR Mode.
{% endhint %}

### Import file example <a href="#import-file-example" id="import-file-example"></a>

```json
{
  "version": "2.1.0",
  "$schema": "http://json.schemastore.org/sarif-2.1.0-rtm.5",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "a test linter",
          "rules": [
            {
              "id": "rule1",
              "shortDescription": {
                "text": "XooLint rule 1"
              },
              "fullDescription": {
                "text": "XooLint rule 1 full description"
              }
            },
            {
              "id": "rule2",
              "shortDescription": {
                "text": "XooLint rule 2"
              }
            }
          ]
        }
      },
      "results": [
        {
          "level": "error",
          "message": {
            "text": "'toto' is assigned a value but never used."
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/File0.xoo"
                },
                "region": {
                  "startLine": 1,
                  "startColumn": 5,
                  "endLine": 1,
                  "endColumn": 9
                }
              }
            }
          ],
          "relatedLocations": [
            {
              "message": {
                "text": "Secondary location message."
              },
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/File0.xoo"
                },
                "region": {
                  "startLine": 2,
                  "startColumn": 1
                }
              }
            }
          ],
          "ruleId": "rule1"
        },
        {
          "level": "error",
          "message": {
            "text": "Issue with flow"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "src/File1.xoo"
                },
                "region": {
                  "startLine": 1,
                  "startColumn": 5,
                  "endLine": 1,
                  "endColumn": 9
                }
              }
            }
          ],
          "stacks": [
            {
              "frames": [
                {
                  "location": {
                    "message": {
                      "text": "Stack frame message."
                    },
                    "physicalLocation": {
                      "artifactLocation": {
                        "uri": "src/File1.xoo"
                      },
                      "region": {
                        "startLine": 3,
                        "startColumn": 1
                      }
                    }
                  }
                },
                {
                  "location": {
                    "message": {
                      "text": "Stack frame message 2."
                    },
                    "physicalLocation": {
                      "artifactLocation": {
                        "uri": "src/File1.xoo"
                      },
                      "region": {
                        "startLine": 4,
                        "startColumn": 1
                      }
                    }
                  }
                }
              ]
            }
          ],
          "ruleId": "rule2"
        }
      ]
    }
  ]
}
```

## Related pages

[about-external-issues](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/importing-external-issues/about-external-issues "mention")

[external-analyzer-reports](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/importing-external-issues/external-analyzer-reports "mention")

[generic-issue-import-format](https://docs.sonarsource.com/sonarqube-community-build/analyzing-source-code/importing-external-issues/generic-issue-import-format "mention")