Add support for `relatedLocations` in SARIF format

[jamacku]

Description

SARIF format allows specifying related locations to the root defect. GitHub is able to parse this location data and show them in a semi-usable way (examples below).

relatedLocations[] - A set of locations relevant to this result. Code scanning will link to related locations when they are embedded in the result message. For more information, see the location object.

Note: This feature requires the support for region data to be implemented first: #136

Example of relatedLocations used in SARIF

I'm using ShellCheck as an example, but I believe that this might be useful also for other static analyzers.

The shell script used in the example:

#!/bin/bash

echo "I'm innocent script, just pass the name of the directory as parameter and I'll remove it for you..."

DIR_SUFFIX="*"
UNUSED_VAR=""

echo "I'm going to remove directory $1/$DIR_SUFFIX"

#! FIXME - Call rm -rf $1/$DIR_SUFFIX

echo "<img src="foo.png" />" > file.html

files='file1 file2'
combined_file=`cat ${files}`
echo "${combined_file}"

rm $1

echo $1 # Unquoted variables
find . -name *.ogg # Unquoted find/grep patterns
rm "~/my file.txt" # Quoted tilde expansion
v='--verbose="true"'; cmd $v # Literal quotes in variables

{
 "ruleId": "SHELLCHECK_WARNING: style[SC2006]",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 15
 }
 }
 }
 ],
 "message": {
 "text": "Use $(...) notation instead of legacy backticks `...`."
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 15
 }
 },
 "message": {
 "text": "Use $(...) notation instead of legacy backticks `...`. Suggestions: use [`$(`](1), use [`)`](2)"
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "style[SC2006]"
 ]
 }
 ]
 }
 ]
 }
 ],
 "relatedLocations": [
 {
 "id": 1,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "endColumn": 16,
 "endLine": 15,
 "startColumn": 15,
 "startLine": 15
 }
 },
 "message": {
 "text": "$("
 }
 },
 {
 "id": 2,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "endColumn": 29,
 "endLine": 15,
 "startColumn": 28,
 "startLine": 15
 }
 },
 "message": {
 "text": ")"
 }
 }
 ]
},

The GitHub requires links torelatedLocations directly in the message.text string. Otherwise, it doesn't show them in UI.

{
 "text": "Use $(...) notation instead of legacy backticks `...`. Suggestions: use [`$(`](1), use [`)`](2)"
}

Data for relatedLocations can be gathered when using ShellCheck JSON1 format.

{
 "file": "innocent-script.sh",
 "line": 15,
 "endLine": 15,
 "column": 15,
 "endColumn": 29,
 "level": "style",
 "code": 2006,
 "message": "Use $(...) notation instead of legacy backticks `...`.",
 "fix": {
 "replacements": [
 {
 "column": 15,
 "endColumn": 16,
 "endLine": 15,
 "insertionPoint": "afterEnd",
 "line": 15,
 "precedence": 8,
 "replacement": "$("
 },
 {
 "column": 28,
 "endColumn": 29,
 "endLine": 15,
 "insertionPoint": "beforeStart",
 "line": 15,
 "precedence": 8,
 "replacement": ")"
 }
 ]
 }
}

Full ShellCheck JSON1

{
 "comments": [
 {
 "file": "innocent-script.sh",
 "line": 6,
 "endLine": 6,
 "column": 1,
 "endColumn": 11,
 "level": "warning",
 "code": 2034,
 "message": "UNUSED_VAR appears unused. Verify use (or export if used externally).",
 "fix": null
 },
 {
 "file": "innocent-script.sh",
 "line": 12,
 "endLine": 12,
 "column": 17,
 "endColumn": 24,
 "level": "warning",
 "code": 2140,
 "message": "Word is of the form \"A\"B\"C\" (B indicated). Did you mean \"ABC\" or \"A\\\"B\\\"C\"?",
 "fix": null
 },
 {
 "file": "innocent-script.sh",
 "line": 15,
 "endLine": 15,
 "column": 15,
 "endColumn": 29,
 "level": "style",
 "code": 2006,
 "message": "Use $(...) notation instead of legacy backticks `...`.",
 "fix": {
 "replacements": [
 {
 "column": 15,
 "endColumn": 16,
 "endLine": 15,
 "insertionPoint": "afterEnd",
 "line": 15,
 "precedence": 8,
 "replacement": "$("
 },
 {
 "column": 28,
 "endColumn": 29,
 "endLine": 15,
 "insertionPoint": "beforeStart",
 "line": 15,
 "precedence": 8,
 "replacement": ")"
 }
 ]
 }
 },
 {
 "file": "innocent-script.sh",
 "line": 21,
 "endLine": 21,
 "column": 14,
 "endColumn": 19,
 "level": "warning",
 "code": 2061,
 "message": "Quote the parameter to -name so the shell won't interpret it.",
 "fix": null
 },
 {
 "file": "innocent-script.sh",
 "line": 21,
 "endLine": 21,
 "column": 14,
 "endColumn": 15,
 "level": "info",
 "code": 2035,
 "message": "Use ./*glob* or -- *glob* so names with dashes won't become options.",
 "fix": null
 },
 {
 "file": "innocent-script.sh",
 "line": 22,
 "endLine": 22,
 "column": 5,
 "endColumn": 18,
 "level": "warning",
 "code": 2088,
 "message": "Tilde does not expand in quotes. Use $HOME.",
 "fix": null
 },
 {
 "file": "innocent-script.sh",
 "line": 23,
 "endLine": 23,
 "column": 3,
 "endColumn": 21,
 "level": "warning",
 "code": 2089,
 "message": "Quotes/backslashes will be treated literally. Use an array.",
 "fix": null
 },
 {
 "file": "innocent-script.sh",
 "line": 23,
 "endLine": 23,
 "column": 27,
 "endColumn": 29,
 "level": "warning",
 "code": 2090,
 "message": "Quotes/backslashes in this variable will not be respected.",
 "fix": null
 }
 ]
}

Full edited csgrep SARIF

{
 "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
 "version": "2.1.0",
 "runs": [
 {
 "tool": {
 "driver": {
 "name": "csdiff",
 "version": "3.0.3",
 "informationUri": "https://github.com/csutils/csdiff",
 "rules": [
 {
 "id": "SHELLCHECK_WARNING: info[SC2035]",
 "name": "SC2035",
 "properties": {
 "tags": [
 "ShellCheck"
 ]
 },
 "help": {
 "text": "Defect reference: https://github.com/koalaman/shellcheck/wiki/SC2035",
 "markdown": "Defect reference: [SC2035](https://github.com/koalaman/shellcheck/wiki/SC2035)"
 }
 },
 {
 "id": "SHELLCHECK_WARNING: style[SC2006]",
 "name": "SC2006",
 "properties": {
 "tags": [
 "ShellCheck"
 ]
 },
 "help": {
 "text": "Defect reference: https://github.com/koalaman/shellcheck/wiki/SC2006",
 "markdown": "Defect reference: [SC2006](https://github.com/koalaman/shellcheck/wiki/SC2006)"
 }
 },
 {
 "id": "SHELLCHECK_WARNING: warning[SC2034]",
 "name": "SC2034",
 "properties": {
 "tags": [
 "ShellCheck"
 ]
 },
 "help": {
 "text": "Defect reference: https://github.com/koalaman/shellcheck/wiki/SC2034",
 "markdown": "Defect reference: [SC2034](https://github.com/koalaman/shellcheck/wiki/SC2034)"
 }
 },
 {
 "id": "SHELLCHECK_WARNING: warning[SC2061]",
 "name": "SC2061",
 "properties": {
 "tags": [
 "ShellCheck"
 ]
 },
 "help": {
 "text": "Defect reference: https://github.com/koalaman/shellcheck/wiki/SC2061",
 "markdown": "Defect reference: [SC2061](https://github.com/koalaman/shellcheck/wiki/SC2061)"
 }
 },
 {
 "id": "SHELLCHECK_WARNING: warning[SC2088]",
 "name": "SC2088",
 "properties": {
 "tags": [
 "ShellCheck"
 ]
 },
 "help": {
 "text": "Defect reference: https://github.com/koalaman/shellcheck/wiki/SC2088",
 "markdown": "Defect reference: [SC2088](https://github.com/koalaman/shellcheck/wiki/SC2088)"
 }
 },
 {
 "id": "SHELLCHECK_WARNING: warning[SC2089]",
 "name": "SC2089",
 "properties": {
 "tags": [
 "ShellCheck"
 ]
 },
 "help": {
 "text": "Defect reference: https://github.com/koalaman/shellcheck/wiki/SC2089",
 "markdown": "Defect reference: [SC2089](https://github.com/koalaman/shellcheck/wiki/SC2089)"
 }
 },
 {
 "id": "SHELLCHECK_WARNING: warning[SC2090]",
 "name": "SC2090",
 "properties": {
 "tags": [
 "ShellCheck"
 ]
 },
 "help": {
 "text": "Defect reference: https://github.com/koalaman/shellcheck/wiki/SC2090",
 "markdown": "Defect reference: [SC2090](https://github.com/koalaman/shellcheck/wiki/SC2090)"
 }
 },
 {
 "id": "SHELLCHECK_WARNING: warning[SC2140]",
 "name": "SC2140",
 "properties": {
 "tags": [
 "ShellCheck"
 ]
 },
 "help": {
 "text": "Defect reference: https://github.com/koalaman/shellcheck/wiki/SC2140",
 "markdown": "Defect reference: [SC2140](https://github.com/koalaman/shellcheck/wiki/SC2140)"
 }
 }
 ]
 }
 },
 "results": [
 {
 "ruleId": "SHELLCHECK_WARNING: warning[SC2034]",
 "level": "warning",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 6
 }
 }
 }
 ],
 "message": {
 "text": "UNUSED_VAR appears unused. Verify use (or export if used externally)."
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 6
 }
 },
 "message": {
 "text": "UNUSED_VAR appears unused. Verify use (or export if used externally)."
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "warning[SC2034]"
 ]
 }
 ]
 }
 ]
 }
 ]
 },
 {
 "ruleId": "SHELLCHECK_WARNING: warning[SC2140]",
 "level": "warning",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 12
 }
 }
 }
 ],
 "message": {
 "text": "Word is of the form \"A\"B\"C\" (B indicated). Did you mean \"ABC\" or \"A\\\"B\\\"C\"?"
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 12
 }
 },
 "message": {
 "text": "Word is of the form \"A\"B\"C\" (B indicated). Did you mean \"ABC\" or \"A\\\"B\\\"C\"?"
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "warning[SC2140]"
 ]
 }
 ]
 }
 ]
 }
 ]
 },
 {
 "ruleId": "SHELLCHECK_WARNING: style[SC2006]",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 15
 }
 }
 }
 ],
 "message": {
 "text": "Use $(...) notation instead of legacy backticks `...`. Suggestions: use [`$(`](1), use [`)`](2)"
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 15
 }
 },
 "message": {
 "text": "Use $(...) notation instead of legacy backticks `...`."
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "style[SC2006]"
 ]
 }
 ]
 }
 ]
 }
 ],
 "relatedLocations": [
 {
 "id": 1,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "endColumn": 16,
 "endLine": 15,
 "startColumn": 15,
 "startLine": 15
 }
 },
 "message": {
 "text": "$("
 }
 },
 {
 "id": 2,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "endColumn": 29,
 "endLine": 15,
 "startColumn": 28,
 "startLine": 15
 }
 },
 "message": {
 "text": ")"
 }
 }
 ]
 },
 {
 "ruleId": "SHELLCHECK_WARNING: warning[SC2061]",
 "level": "warning",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 21
 }
 }
 }
 ],
 "message": {
 "text": "Quote the parameter to -name so the shell won't interpret it."
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 21
 }
 },
 "message": {
 "text": "Quote the parameter to -name so the shell won't interpret it."
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "warning[SC2061]"
 ]
 }
 ]
 }
 ]
 }
 ]
 },
 {
 "ruleId": "SHELLCHECK_WARNING: info[SC2035]",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 21
 }
 }
 }
 ],
 "message": {
 "text": "Use ./*glob* or -- *glob* so names with dashes won't become options."
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 21
 }
 },
 "message": {
 "text": "Use ./*glob* or -- *glob* so names with dashes won't become options."
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "info[SC2035]"
 ]
 }
 ]
 }
 ]
 }
 ]
 },
 {
 "ruleId": "SHELLCHECK_WARNING: warning[SC2088]",
 "level": "warning",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 22
 }
 }
 }
 ],
 "message": {
 "text": "Tilde does not expand in quotes. Use $HOME."
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 22
 }
 },
 "message": {
 "text": "Tilde does not expand in quotes. Use $HOME."
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "warning[SC2088]"
 ]
 }
 ]
 }
 ]
 }
 ]
 },
 {
 "ruleId": "SHELLCHECK_WARNING: warning[SC2089]",
 "level": "warning",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 23
 }
 }
 }
 ],
 "message": {
 "text": "Quotes/backslashes will be treated literally. Use an array."
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 23
 }
 },
 "message": {
 "text": "Quotes/backslashes will be treated literally. Use an array."
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "warning[SC2089]"
 ]
 }
 ]
 }
 ]
 }
 ]
 },
 {
 "ruleId": "SHELLCHECK_WARNING: warning[SC2090]",
 "level": "warning",
 "locations": [
 {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 23
 }
 }
 }
 ],
 "message": {
 "text": "Quotes/backslashes in this variable will not be respected."
 },
 "codeFlows": [
 {
 "threadFlows": [
 {
 "locations": [
 {
 "location": {
 "id": 0,
 "physicalLocation": {
 "artifactLocation": {
 "uri": "innocent-script.sh"
 },
 "region": {
 "startLine": 23
 }
 },
 "message": {
 "text": "Quotes/backslashes in this variable will not be respected."
 }
 },
 "nestingLevel": 0,
 "kinds": [
 "warning[SC2090]"
 ]
 }
 ]
 }
 ]
 }
 ]
 }
 ]
 }
 ]
}

GitHub UI

Upon clicking on the link with suggestions, the pop-up box shows the location (not visible enough IMHO):

The data can be used to show suggestions in console output as well. For example sarif-fmt tool shows:

Related to:

• Shown alerts should include a possible solution (if available) redhat-plumbers-in-action/differential-shellcheck#88