#381: threadFlowLocation "helper rules"

["Larry Golding (Myriad Consulting Inc)" <v-lgold@microsoft.com>]

I created and merged a change draft for Yekaterina’s Issue #381, “Associate descriptor metadata with thread flow locations”:

 

https://github.com/oasis-tcs/sarif-spec/blob/master/Documents/ChangeDrafts/Accepted/sarif-v2.0-issue-381-helper-rules.docx

 

Please take a look. The entire change is pasted below.

 

Yekaterina and Michael: There is a subtle point that I want to discuss in a separate email. It might result in a small change to what I wrote.

 

Next is Issue #387: “anyOf externalPropertyFileReference location or guid is required”.

 

Thanks,

Larry

 

3.37.14 taxa property

A threadFlowLocation MAY contain a property named taxa whose value is an array of zero or more unique (§3.7.3) reportingDescriptorReference objects each of which specifies a category into which this threadFlowLocation falls.

NOTE: The motivation for this property is a tool that uses a set of rules to guide its analysis as it traces tainted data from a source to a sink. For example, at one location, the tool might apply a rule that says: “If the input to String.Substr is tainted, then so is the return value.” Such a tool can represent these “helper rules” as a custom taxonomy (§3.19.3), an array of reportingDescriptor objects (§3.48). Each member of threadFlowLocation.taxa can reference one of these helper rules.

EXAMPLE: This example illustrates the scenario in the above note.

{                                # A run object (§3.14).

  "tool": {                      # See §3.14.6.

    "driver": {

      "name": "TaintDetector",

      "rules": [

        {

          "id": "TD0001",

          "name": "UntrustedDataStoredInDatabase",

          "shortDescription": {

            "text": "Data from an untrusted source was stored in a database."

          }

        },

        ...

      ],

      "taxa": [                  # Custom taxonomy (§3.19.3) for helper rules.

        {                        # A reportingDescriptor object (§3.48).

          "id": "HR0001",

          "name": "SubstrPropogatesTaint",

          "shortDescription": {

            "text": "If the input to String.Substr is tainted,

                     so is the return value."

          }

        },

        ...

      ]

    }

  },

 

  "results": [                   # See §3.14.22.

    {                            # A result object §3.26.

      "ruleId": "TD0001",

      ...

      "codeFlows": [             # See §3.26.18.

        {                        # A codeFlow object (§3.35).

          "threadFlows": [       # See §3.35.3.

            {                    # A threadFlow object (§3.36).

              "locations": [     # See §3.36.6.

                ...

                {                # A threadFlowLocation object.

                  "location": {  # See §3.37.3.

                    "physicalLocation": {

                      "artifactLocation": {

                        "uri": "io/input.c",

                        "uriBaseId": "SRCROOT"

                      },

                      "region": {

                        "startLine": 32

                      }

                    }

                  },

                  "taxa": [

                    {        # A reportingDescriptorReference object (§3.51).

                      "id": "TD0001",

                      "index": 0

                    }

                  ]

                },

                ...

              ]

            }

          ]

        }

      ]

    }

  ]

}