Re: [sarif] Alternatives for embedding links

</fact>

</fact>

</fact>

Cheers,

Nick

On Nov 9, 2017, at 7:02 PM, Larry Golding (Comcast) <larrygolding@comcast.net> wrote:

Hello all,

Yesterday, I took an action to describe to you the two options we have discussed for embedding links to source files within SARIF message properties. Both options will work whether the message is plain text or contains formatting markup such as Markdown; that is, the “embedded links” proposal is independent of the “messages with formatting” proposal.

Both options involve using a syntax borrowed from Markdown to specify the link: [link text](link target). They differ in how link target is expressed.
Option 1: Mini-language
The first option expresses the properties of the link target using a string in a “mini-language”. To understand this option, you need to know that SARIF defines a “physicalLocation” object (see Section 3.19 of the spec), with three properties:

A uri property, which is what it sounds like: the URI of the source file.

A region property, which specifies a region within the source file, using properties such as startLine and startColumn. For a full explanation of region, see Section 3.20 – but you don’t need to understand those details to understand this option.

A uriBaseId property, which, if the URI is relative, indirectly specifies an absolute path upon which the relative URI is based. This is subtle; please see Section 3.3 for a full explanation, although you don’t really need to understand the details to understand this option.

This option looks like this:

{
"version": "1.0.0",
"runs": [
    {
      "tool": {
        "name": "TaintTracker"
      },

      "results": [
        {
          "ruleId": "CA2001",
          "locations": [
            {
                     "analysisTarget": {
                       "uriBaseId": "SRCROOT",
                       "uri": "src/db/sql.cs",
                       "region": {
                         "startLine": 63,
                         "startColumn": 12,
                         "endColumn": 18
                       }
              }
            }
          ],
          "message": "Tainted data is used to execute a SQL command. The data entered the system [here]($(SRCROOT)src/ui/input.cs#startLine=20,startColumn=4,message='source of tainted data')"
        }
      ]
    }
]
}

The link text is “here”, and the link target is expressed in the mini-language as follows:

$(SRCROOT)src/ui/input.cs#startLine=20,startColumn=4,message='source of tainted data',

$(SRCROOT) refers to the uriBaseId, src/ui/input.cs is the uri, and the thing that looks like a URI fragment (starting with “#”) specifies the region, along with a “hover message”. The idea of the hover message is that if you click the link, your SARIF viewer application would open the specified file and highlight the region. Then, if you hovered your mouse over the region, the specified message would appear as the hover text.

This design has an interesting consequence: since the mini-language specifies everything that a physicalLocation object specifies, we could consider removing the physicalLocation object from the standard, and replacing it with a string in that format. Then the example above would appear as follows:

{
"version": "1.0.0",
"runs": [
    {
      "tool": {
        "name": "TaintTracker"
      },

      "results": [
        {
          "ruleId": "CA2001",
          "locations": [
            {
                     "analysisTarget": "$(SRCROOT)/src/db/sql.cs#startLine=63,startColumn=12,endColumn=18"
            }
          ],
          "message": "Tainted data is used to execute a SQL command. The data entered the system [here]($(SRCROOT)src/ui/input.cs#startLine=20,startColumn=4,message='source of tainted data')"
        }
      ]
    }
]
}

The analysisTarget property, whose value was previously a physicalLocation object, is now a string expressed in the mini-language. The introduction of the mini-language does not require us to remove the physicalLocation object, but Michael has argued that the spec should not have two different ways to express the same thing (the physicalLocation object on the one hand, and the mini-language on the other).
Option 2: Index into relatedLocations
The second option expresses the link target as an index into the result.relatedLocations array. To understand this option, you need to know that SARIF defines a property relatedLocations on the result object. Section 3.17.12 explains that this property contains:

… an array of one or more unique (§3.9) annotatedCodeLocation objects (§3.25), each of which represents a location relevant to understanding the result.

In this example, the location where the tainted data entered the system is “relevant to understanding the result”, so it makes sense in SARIF to express it as a “related location”. This option looks like this:

{
"version": "1.0.0",
"runs": [
    {
      "tool": {
        "name": "TaintTracker"
      },

      "results": [
        {
          "ruleId": "CA2001",
          "locations": [
            {
              "analysisTarget": {
                "uriBaseId": "SRCROOT",
                "uri": "src/db/sql.cs",
                "region": {
                  "startLine": 63,
                  "startColumn": 12,
                  "endColumn": 18
                }
              }
            }
          ],
          "message": "Tainted data is used to execute a SQL command. The data entered the system [here](0)",
          "relatedLocations": [
            {
              "message": "source of tainted data",
              "physicalLocation": {
                "uriBaseId": "SRCROOT",
                "uri": "src/ui/input.cs",
                "region": {
                  "startLine": 20,
                  "startColumn": 4
                }
              }
            }
          ]
        }
      ]
    }
]
}

The link text is “here”, and the link target is expressed as an index into the relatedLocations array. Note that in this option, the “hover message” (“source of tainted data”) appears as the message property of the annotatedCodeLocation object in the relatedLocations array. In this example, there is only one related location, so the index is 0.
Comparison of the options
Option 1 (mini-language) has these advantages:
It makes the SARIF file more compact (although that isn’t actually a design goal for SARIF).
It enables someone reading the raw SARIF file to see the link target directly in the context of the message.

Option 2 (index into relatedLocations) has these advantages:
It does not introduce a mini-language (except for the “embedded link” syntax itself, but that occurs in both options). It retains physicalLocation as a structured JSON object. It’s generally undesirable to introduce mini-languages. After all, SARIF consumers already use a (presumably) highly reliable JSON parser to read the SARIF file; why should consumers need an additional parser to crack the mini-language?
It takes advantage of an existing SARIF facility (relatedLocations) which has exactly the semantics we need here (a location “relevant to understanding the result”).
It avoids the need to define an escaping mechanism for characters (such as ‘#’ or ‘(‘) which, in the mini-language version, might appear in the “message” parameter of the “fragment”.
It avoids the parsing needed to identify the “fragment” that specifies the region (as opposed to the “real” fragment; see #5).
It avoids depending on the constraint that the “real” fragment in a URI specifying a nested file begin with a “/”.

#4 and #5 in this list require you to understand how SARIF represents locations within “nested files” (for example, files within a ZIP archive). I can explain this in more detail if necessary, but if you find #1 through #3 persuasive in themselves, I won’t bother. If you’re interested, you can see Section 3.12.9, which describes the run.files property. Look for the paragraph that starts “In some cases, a file might be nested within another file”.

We will discuss this further at the next TC meeting.

Thanks for reading all of this!
Larry

sarif message

Option 1: Mini-language

Option 2: Index into relatedLocations

Comparison of the options