Define result taxonomies

[michaelcfanning]

No description provided.

[michaelcfanning]

1. Remove properties.tags.
2. Add result.tags.
3. Add rules.tags -- they always flow to result.tags.
4. Add rule.optionalTags -- any subset of these might flow to the result.tags for a specific result.
5. Add taxonomies, an array of descriptors at the sarif log level.
6. Define a look up object comprising the id and index into taxonomies.

Driving scenario: taxonomy: I detect CWE/851

tags are hierarchical

[michaelcfanning]

The TC thinks this proposal makes sense as it stands. But it suggests the possibility of expanding this idea so that the CWE tag references can provide linkage to comprehensive metadata on the related CWE/other classification.

It would be helpful to review this broader issue. Please review #3 and take look.

[michaelcfanning]

Let's commit to having this closed by TC#32.

[michaelcfanning]

We propose to create a set of reporting descriptors at the sarif log level 'taxonomies'. The tags associated with a result or a rule would be an array of objects that locate data in the taxonomies array. Each item would consist of an id and an index into the taxonomies data, if it exists. The array index would be optional, so that users could simply mark items with the readable id.

[michaelcfanning]

TC accepts this change.

[michaelcfanning]

EBALLOT PROPOSAL: provide a mechanism for persisting arbitrary categorization (i.e., 'taxonomies') metadata to log files. Rules and notifications can describe all tags that are consistently and/or optionally reported by each.

API IMPACT
Schema changes PR: microsoft/sarif-sdk#1318

• Add run.taxonomies, an array of reportingDescriptor objects (so a taxonomy entry can have an id, a name, shortDescription, longDescription, etc.).
• Add externalPropertyFiles.taxonomies so that the data can be persisted to an external file.
• Add reportingDescriptor.taxonomyReferences, an array of reportingDescriptorReference objects. (these are taxonomy items that always apply to the result implicated by this rule).
• Add reportingDescriptor.optionalTaxonomyReferences, an array of reportingDescriptorReference objects (these are taxonomy items that can optionally apply to a result implicated by this rule).
• Add result.taxonomyReferences, an array of reportingDescriptorReferences that point into run.taxonomies. The pointer property of each of these reference objects is simply a stringified integer (for example, "42" refers to the item at index 42 in run.taxonomies).

NOTES

1. This ballot item depends on the reportingDescriptorReference object defined in Define a reportingDescriptorReference object #324, so if that one is rejected, this one would have to be modified. See Define a reportingDescriptorReference object #324 for more on reportingDescriptorReference. Note especially the proposed sarif URI scheme that allows us to specify the location of an item within a SARIF log file.

2. This change will not remove the reserved property bag tags value (as suggested in earlier discussion on this issue).

[kupsch]

The design for result and reportingDescriptor is good, but I think how the taxonomy data is stored needs changes that are going to be discuss soon with Michael and Larry. I also think that the toolComponent should declare the taxonomies that it uses.

[michaelcfanning]

Per offline discussion, result.ruleExtensionIndex s/be renamed to ruleComponent, the type of which is a componentIdentity.

[ghost]

E-BALLOT #3 PROPOSAL

Represent standard taxonomies by reusing the existing toolComponent and reportingDescriptor types. A standard taxonomy is a toolComponent that contains taxonomyDescriptors (an array of reportingDescriptors), but does not contain ruleDescriptors or notificationDescriptors.

Allow tool components to define their own custom taxonomies by including taxonomyDescriptors along with their ruleDescriptors and notificationDescriptors.

SCHEMA CHANGES

• In the toolComponent object:

  • Add a property taxonDescriptors of type reportingDescriptor[], optional, default: []: allows definition of both standard and per-tool taxonomies.
  • Add a property supportedTaxonomies of type toolComponentReference[], optional, default: []: allows a tool to declare the taxonomies it supports.
  • Add a property localizedDataSemanticVersion
  • Add a property minimumRequiredLocalizedDataSemanticVersion
  • Add a property reportingConfigurationOverrides, which an array of reporting descriptors

• In the reportingDescriptor object:

  • Add a property taxonReferences of type reportingDescriptorReference[], optional, default: []: the set of taxa that apply to all results implicated by this rule.
  • Add a property optionalTaxonReferences of type reportingDescriptorReference[], optional, default: []: a set of taxa that can optionally apply to results implicated by this rule.

• In the result object:

  • Add a property taxonReferences of type reportingDescriptorReference[], optional, default: []: the set of optional taxa into which this result falls (the "required" taxonomy references apply implicitly).

• Add new roles: taxonomy, extension, translation, reportingConfigurationOverride

NOTE: Unlike in the previous proposal, it is not necessary to explicitly declare "taxonomies" as externalizable, since they are toolComponents, which are already externalizable through the driver and extensions properties of the externalPropertyFile and externalPropertyFileReferences objects.

[ghost]

Approved in e-ballot-3 (as modified by #338).