Add Appendix 'Displaying results in a viewer'. (#25)
* Add Appendix 'Displaying results in a viewer'. * Fix broken link in TOC. * Add a footnote. * Fix backwards explanation of suppressions. * Fix two punctuation errors. * Amplify the summary. * Describe the effective level calculation. * Remove unnecessary sentence. * Generalize "CI" to "incremental". * Add a missing word. * Minor rephrasing Co-authored-by: Larry Golding <lgolding@comcast.net> Co-authored-by: Michael C. Fanning <michael.fanning@microsoft.com>
This commit is contained in:
Larry Golding
GitHub
Родитель
32f15e51b0
Коммит
ed94457459
289
README.md
289
README.md
|
|
@ -1,144 +1,145 @@
|
|||
# SARIF Tutorials
|
||||
|
||||
## Introduction
|
||||
|
||||
SARIF, the Static Analysis Results Interchange Format, defines a standard format for the output of static analysis tools.
|
||||
It is a powerful and sophisticated format suited to the needs of a wide variety of tools.
|
||||
For this reason — and because the format is defined in a 220-plus page specification written in formal language!
|
||||
— it can be hard to learn SARIF and to figure out what parts of it you need to use.
|
||||
|
||||
These tutorials aim to present SARIF in a more approachable way.
|
||||
We'll start with some background:
|
||||
Why do we need SARIF? Where did it come from? What can it do?
|
||||
Then we'll dive into the format, exploring the most basic concepts first, then moving on to more advanced concepts.
|
||||
|
||||
The advanced concepts usually apply to only a subset of SARIF producers and consumers,
|
||||
so you don't to read everything.
|
||||
Just read the introductory material, then pick and choose the additional topics that interest you.
|
||||
|
||||
## Sample files
|
||||
|
||||
You can find the sample files displayed in the tutorials under the `samples` directory.
|
||||
They are all valid SARIF files unless I say otherwise.
|
||||
|
||||
## Links to the specification
|
||||
|
||||
At times, the tutorials link to a section of the SARIF specification for more detailed information
|
||||
or descriptions of advanced scenarios.
|
||||
These links look like this: [§3.13: sarifLog object](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012434)
|
||||
and they point into the
|
||||
[HTML version](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html) of the spec.
|
||||
There are also PDF and .docx versions in the [SARIF 2.1.0 CS01](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/)
|
||||
(Committee Specification 1) folder on the OASIS web site.
|
||||
|
||||
The specification is definitive (and if we want to get really technical, the .docx version of the specification is
|
||||
definitive, but let's assume there are no bugs in the PDF or HTML converters).
|
||||
If it seems like something in these tutorials disagrees with the spec,
|
||||
let me know and I'll either fix the tutorials or make sure that a bug is filed against the spec.
|
||||
|
||||
## Disclaimer
|
||||
|
||||
The [SARIF specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/)
|
||||
is a [Committee Specification](https://www.oasis-open.org/news/announcements/static-analysis-results-interchange-format-sarif-v2-1-0-from-the-sarif-tc-is-an-a)
|
||||
from [OASIS](https://www.oasis-open.org/).
|
||||
But despite the fact that I'm the co-Editor (with Michael Fanning) and primary wordsmith of the specification,
|
||||
these tutorials are _not_ an OASIS work product or endorsed by OASIS in any way.
|
||||
They represent my personal interpretation and explanation of the standard.
|
||||
|
||||
## Status
|
||||
|
||||
These tutorials now contain enough information to give you a solid background in SARIF.
|
||||
As you will see from the "TODO" entries in the table of contents, there's much more I'd like to write about.
|
||||
But these are advanced topics that I will address when I have time.
|
||||
|
||||
If you'd like an explanation of a SARIF feature that I haven't covered,
|
||||
please let me know by filing an issue in this repo
|
||||
|
||||
## <a id="contents"></a>Table of contents
|
||||
|
||||
- [Introduction](docs/1-Introduction.md)
|
||||
- [What is SARIF?](docs/1-Introduction.md#what-is-sarif)
|
||||
- [About static analysis tools](docs/1-Introduction.md#tools)
|
||||
- [Why SARIF?](docs/1-Introduction.md#why-sarif)
|
||||
- [A simple example](docs/1-Introduction.md#simple-example)
|
||||
- [The plan for these tutorials](docs/1-Introduction.md#plan)
|
||||
- [The basics](docs/2-Basics.md)
|
||||
- [The log file and the object model](docs/2-Basics.md#log-file-and-om)
|
||||
- [Logs and runs](docs/2-Basics.md#logs-runs)
|
||||
- [Tools: driver and extensions](docs/2-Basics.md#tools)
|
||||
- [Property bags](docs/2-Basics.md#property-bags)
|
||||
- [Results](docs/2-Basics.md#results)
|
||||
- [Message](docs/2-Basics.md#message)
|
||||
- [Rule identifier](docs/2-Basics.md#rule-id)
|
||||
- [Level](docs/2-Basics.md#level)
|
||||
- [Locations](docs/2-Basics.md#locations)
|
||||
- [The `locations` array](docs/2-Basics.md#loc-array)
|
||||
- [Physical and logical locations](docs/2-Basics.md#phys-log-loc)
|
||||
- [Artifacts](docs/2-Basics.md#artifacts)
|
||||
- [Defining artifacts](docs/2-Basics.md#defining-artifacts)
|
||||
- [Linking results to artifacts](docs/2-Basics.md#linking-artifacts)
|
||||
- [Rule metadata](docs/2-Basics.md#rule-metadata)
|
||||
- [Beyond the basics](docs/3-Beyond-basics.md)
|
||||
- [Related locations](docs/3-Beyond-basics.md#related-locations)
|
||||
- [More about messages](docs/3-Beyond-basics.md#more-about-messages)
|
||||
- [Markdown messages](docs/3-Beyond-basics.md#msg-markdown)
|
||||
- [Messages from metadata](docs/3-Beyond-basics.md#msg-metadata)
|
||||
- [Messages with arguments](docs/3-Beyond-basics.md#msg-args)
|
||||
- [Messages with embedded links](docs/3-Beyond-basics.md#msg-links)
|
||||
- [Links in text and Markdown](docs/3-Beyond-basics.md#msg-links-text-markdown)
|
||||
- [Links to locations](docs/3-Beyond-basics.md#msg-links-location)
|
||||
- [Invocations](docs/3-Beyond-basics.md#invocations)
|
||||
- [Notifications](docs/3-Beyond-basics.md#notifications)
|
||||
- [Tool execution notification and tool configuration notifications](docs/3-Beyond-basics.md#exec-config-notif)
|
||||
- [Notifications _vs._ results](docs/3-Beyond-basics.md#notif-result)
|
||||
- [Taxonomies](docs/3-Beyond-basics.md#taxonomies)
|
||||
- [Code flows](docs/3-Beyond-basics.md#code-flows)
|
||||
- [Automation](docs/3-Beyond-basics.md#automation)
|
||||
- [The `id` and `guid` properties](docs/3-Beyond-basics.md#run-id-and-guid)
|
||||
- [The `correlationGuid` property](docs/3-Beyond-basics.md#run-correlationGuid)
|
||||
- Advanced topics
|
||||
- Tool extensions (TODO)
|
||||
- Translations (TODO)
|
||||
- Handling large files (TODO)
|
||||
- Result matching (TODO)
|
||||
- The `sarif:` URI scheme (TODO)
|
||||
- Appendices
|
||||
- [Fitness for purpose: An overview](docs/Fitness-for-purpose-overview.md)
|
||||
- [Fitness for purpose: Automatic bug filing](docs/Fitness-for-purpose-automatic-bug-filing.md)
|
||||
- [Authoring rule metadata and result messages](docs/Authoring-rule-metadata-and-result-messages.md)
|
||||
- [The SARIF Multitool](docs/Multitool.md)
|
||||
- The history of SARIF (TODO)
|
||||
- [Glossary](docs/Glossary.md)
|
||||
- [Resources](docs/Resources.md)
|
||||
|
||||
## Contributing
|
||||
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
||||
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
||||
the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com.>
|
||||
|
||||
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
|
||||
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
|
||||
provided by the bot. You will only need to do this once across all repos using our CLA.
|
||||
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
|
||||
## Legal Notices
|
||||
|
||||
Microsoft and any contributors grant you a license to the Microsoft documentation and other content
|
||||
in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode),
|
||||
see the [LICENSE](LICENSE) file, and grant you a license to any code in the repository under the
|
||||
[MIT License](https://opensource.org/licenses/MIT), see the
|
||||
[LICENSE-CODE](LICENSE-CODE) file.
|
||||
|
||||
Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation
|
||||
may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries.
|
||||
The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks.
|
||||
Microsoft's general trademark guidelines can be found at <http://go.microsoft.com/fwlink/?LinkID=254653.>
|
||||
|
||||
Privacy information can be found at <https://privacy.microsoft.com/en-us/>
|
||||
|
||||
Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents,
|
||||
or trademarks, whether by implication, estoppel or otherwise.
|
||||
# SARIF Tutorials
|
||||
|
||||
## Introduction
|
||||
|
||||
SARIF, the Static Analysis Results Interchange Format, defines a standard format for the output of static analysis tools.
|
||||
It is a powerful and sophisticated format suited to the needs of a wide variety of tools.
|
||||
For this reason — and because the format is defined in a 220-plus page specification written in formal language!
|
||||
— it can be hard to learn SARIF and to figure out what parts of it you need to use.
|
||||
|
||||
These tutorials aim to present SARIF in a more approachable way.
|
||||
We'll start with some background:
|
||||
Why do we need SARIF? Where did it come from? What can it do?
|
||||
Then we'll dive into the format, exploring the most basic concepts first, then moving on to more advanced concepts.
|
||||
|
||||
The advanced concepts usually apply to only a subset of SARIF producers and consumers,
|
||||
so you don't to read everything.
|
||||
Just read the introductory material, then pick and choose the additional topics that interest you.
|
||||
|
||||
## Sample files
|
||||
|
||||
You can find the sample files displayed in the tutorials under the `samples` directory.
|
||||
They are all valid SARIF files unless I say otherwise.
|
||||
|
||||
## Links to the specification
|
||||
|
||||
At times, the tutorials link to a section of the SARIF specification for more detailed information
|
||||
or descriptions of advanced scenarios.
|
||||
These links look like this: [§3.13: sarifLog object](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html#_Toc16012434)
|
||||
and they point into the
|
||||
[HTML version](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/sarif-v2.1.0-cs01.html) of the spec.
|
||||
There are also PDF and .docx versions in the [SARIF 2.1.0 CS01](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/)
|
||||
(Committee Specification 1) folder on the OASIS web site.
|
||||
|
||||
The specification is definitive (and if we want to get really technical, the .docx version of the specification is
|
||||
definitive, but let's assume there are no bugs in the PDF or HTML converters).
|
||||
If it seems like something in these tutorials disagrees with the spec,
|
||||
let me know and I'll either fix the tutorials or make sure that a bug is filed against the spec.
|
||||
|
||||
## Disclaimer
|
||||
|
||||
The [SARIF specification](https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/)
|
||||
is a [Committee Specification](https://www.oasis-open.org/news/announcements/static-analysis-results-interchange-format-sarif-v2-1-0-from-the-sarif-tc-is-an-a)
|
||||
from [OASIS](https://www.oasis-open.org/).
|
||||
But despite the fact that I'm the co-Editor (with Michael Fanning) and primary wordsmith of the specification,
|
||||
these tutorials are _not_ an OASIS work product or endorsed by OASIS in any way.
|
||||
They represent my personal interpretation and explanation of the standard.
|
||||
|
||||
## Status
|
||||
|
||||
These tutorials now contain enough information to give you a solid background in SARIF.
|
||||
As you will see from the "TODO" entries in the table of contents, there's much more I'd like to write about.
|
||||
But these are advanced topics that I will address when I have time.
|
||||
|
||||
If you'd like an explanation of a SARIF feature that I haven't covered,
|
||||
please let me know by filing an issue in this repo
|
||||
|
||||
## <a id="contents"></a>Table of contents
|
||||
|
||||
- [Introduction](docs/1-Introduction.md)
|
||||
- [What is SARIF?](docs/1-Introduction.md#what-is-sarif)
|
||||
- [About static analysis tools](docs/1-Introduction.md#tools)
|
||||
- [Why SARIF?](docs/1-Introduction.md#why-sarif)
|
||||
- [A simple example](docs/1-Introduction.md#simple-example)
|
||||
- [The plan for these tutorials](docs/1-Introduction.md#plan)
|
||||
- [The basics](docs/2-Basics.md)
|
||||
- [The log file and the object model](docs/2-Basics.md#log-file-and-om)
|
||||
- [Logs and runs](docs/2-Basics.md#logs-runs)
|
||||
- [Tools: driver and extensions](docs/2-Basics.md#tools)
|
||||
- [Property bags](docs/2-Basics.md#property-bags)
|
||||
- [Results](docs/2-Basics.md#results)
|
||||
- [Message](docs/2-Basics.md#message)
|
||||
- [Rule identifier](docs/2-Basics.md#rule-id)
|
||||
- [Level](docs/2-Basics.md#level)
|
||||
- [Locations](docs/2-Basics.md#locations)
|
||||
- [The `locations` array](docs/2-Basics.md#loc-array)
|
||||
- [Physical and logical locations](docs/2-Basics.md#phys-log-loc)
|
||||
- [Artifacts](docs/2-Basics.md#artifacts)
|
||||
- [Defining artifacts](docs/2-Basics.md#defining-artifacts)
|
||||
- [Linking results to artifacts](docs/2-Basics.md#linking-artifacts)
|
||||
- [Rule metadata](docs/2-Basics.md#rule-metadata)
|
||||
- [Beyond the basics](docs/3-Beyond-basics.md)
|
||||
- [Related locations](docs/3-Beyond-basics.md#related-locations)
|
||||
- [More about messages](docs/3-Beyond-basics.md#more-about-messages)
|
||||
- [Markdown messages](docs/3-Beyond-basics.md#msg-markdown)
|
||||
- [Messages from metadata](docs/3-Beyond-basics.md#msg-metadata)
|
||||
- [Messages with arguments](docs/3-Beyond-basics.md#msg-args)
|
||||
- [Messages with embedded links](docs/3-Beyond-basics.md#msg-links)
|
||||
- [Links in text and Markdown](docs/3-Beyond-basics.md#msg-links-text-markdown)
|
||||
- [Links to locations](docs/3-Beyond-basics.md#msg-links-location)
|
||||
- [Invocations](docs/3-Beyond-basics.md#invocations)
|
||||
- [Notifications](docs/3-Beyond-basics.md#notifications)
|
||||
- [Tool execution notification and tool configuration notifications](docs/3-Beyond-basics.md#exec-config-notif)
|
||||
- [Notifications _vs._ results](docs/3-Beyond-basics.md#notif-result)
|
||||
- [Taxonomies](docs/3-Beyond-basics.md#taxonomies)
|
||||
- [Code flows](docs/3-Beyond-basics.md#code-flows)
|
||||
- [Automation](docs/3-Beyond-basics.md#automation)
|
||||
- [The `id` and `guid` properties](docs/3-Beyond-basics.md#run-id-and-guid)
|
||||
- [The `correlationGuid` property](docs/3-Beyond-basics.md#run-correlationGuid)
|
||||
- Advanced topics
|
||||
- Tool extensions (TODO)
|
||||
- Translations (TODO)
|
||||
- Handling large files (TODO)
|
||||
- Result matching (TODO)
|
||||
- The `sarif:` URI scheme (TODO)
|
||||
- Appendices
|
||||
- [Fitness for purpose: An overview](docs/Fitness-for-purpose-overview.md)
|
||||
- [Fitness for purpose: Automatic bug filing](docs/Fitness-for-purpose-automatic-bug-filing.md)
|
||||
- [Authoring rule metadata and result messages](docs/Authoring-rule-metadata-and-result-messages.md)
|
||||
- [Displaying results in a viewer](docs/Displaying-results-in-a-viewer.md)
|
||||
- [The SARIF Multitool](docs/Multitool.md)
|
||||
- The history of SARIF (TODO)
|
||||
- [Glossary](docs/Glossary.md)
|
||||
- [Resources](docs/Resources.md)
|
||||
|
||||
## Contributing
|
||||
|
||||
This project welcomes contributions and suggestions. Most contributions require you to agree to a
|
||||
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
|
||||
the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com.>
|
||||
|
||||
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
|
||||
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
|
||||
provided by the bot. You will only need to do this once across all repos using our CLA.
|
||||
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
|
||||
## Legal Notices
|
||||
|
||||
Microsoft and any contributors grant you a license to the Microsoft documentation and other content
|
||||
in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode),
|
||||
see the [LICENSE](LICENSE) file, and grant you a license to any code in the repository under the
|
||||
[MIT License](https://opensource.org/licenses/MIT), see the
|
||||
[LICENSE-CODE](LICENSE-CODE) file.
|
||||
|
||||
Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation
|
||||
may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries.
|
||||
The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks.
|
||||
Microsoft's general trademark guidelines can be found at <http://go.microsoft.com/fwlink/?LinkID=254653.>
|
||||
|
||||
Privacy information can be found at <https://privacy.microsoft.com/en-us/>
|
||||
|
||||
Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents,
|
||||
or trademarks, whether by implication, estoppel or otherwise.
|
||||
|
|
|
|||
1262
docs/2-Basics.md
1262
docs/2-Basics.md
Разница между файлами не показана из-за своего большого размера
Загрузить разницу
Разница между файлами не показана из-за своего большого размера
Загрузить разницу
|
|
@ -0,0 +1,107 @@
|
|||
[Table of contents](../README.md#contents)
|
||||
|
||||
# Displaying results in a viewer
|
||||
|
||||
Many SARIF viewers display a list of the results contained in the log file or files being viewed. Since log files can contain thousands of results, it is important for the viewer to display by default just those results that are most useful, while still giving the user a way to see all available results.
|
||||
|
||||
Having decided which results to display, most viewers have a way to indicate the relative importance of each result. The viewer should direct the user's attention to the most important of the displayed results.
|
||||
|
||||
This document describes how a viewer should decide which results to show by default,
|
||||
and how it should convey their relative importance. The viewer should provide some UI gesture to allow the user to see results that are not shown by default.
|
||||
|
||||
## Determining which results to display
|
||||
|
||||
Four properties of the SARIF `result` object interact to determine which results to show by default:
|
||||
|
||||
- `suppressions`
|
||||
- `baselineState`
|
||||
- `kind` and `level`, combined as described in the section <a href="#importance">Determining importance</a> to produce an `importance` value.
|
||||
|
||||
In addition, results can be hidden by _policies_.<sup><a href="#note-1">1</a></sup>
|
||||
|
||||
Proceed through the algorithm below. If at any point the algorithm states that the result should not be shown by default, there is no need to proceed any further (you will see the word "STOP"). If at any point the algorithm states that the result _should_ be shown by default, it is possible that a subsequent decision point in the algorithm might still decide not to show the result. Proceed until you come to the end of the algorithm or you encounter a STOP.
|
||||
|
||||
1. If a policy is in effect (for example, because the user has selected a policy in the viewer's UI, or because the viewer is part of a workflow that specifies a policy), and if the policy states that the rule violated by this result is disabled, then the result should not be shown by default. STOP.
|
||||
|
||||
2. `result.suppressions`: If the result is suppressed as described in the section <a href="#suppression-status">Determining suppression status</a>, it should not be shown by default. STOP.
|
||||
|
||||
3. `result.baselineState`:
|
||||
|
||||
- If the baseline state is `"absent"` (meaning that the result appeared in the previous run but no longer appears in the current run) then it should not be shown by default. STOP.
|
||||
|
||||
- If the baseline state is `"new"` (meaning that the result did not appear in the previous run but has appeared for the first time (or perhaps reappeared) in this run) then it should be shown by default.
|
||||
|
||||
- If the baseline state is `"unchanged"` (meaning that the result has not changed since the previous run) or `"updated"` (meaning that some aspects of the result have changed since the previous run, but it is nonetheless still identifiably the same result), then whether or not to show the result by default depends on the usage scenario.
|
||||
|
||||
If the viewer is operating in an "incremental" scenario (a scenario where the developer wants to focus on the problems introduced by her most recent commits, for example, examining the results of a continuous integration (CI) build) then `"unchanged"` and `"updated"` results should not be shown by default. STOP.
|
||||
|
||||
Otherwise, `"unchanged"` and `"updated"` results should be shown by default.
|
||||
|
||||
- If `result.baselineState` is absent (meaning that this run has not been "baselined" -- compared to a previous run -- and therefore there is no way for the viewer to know if the result is new or pre-existing) then the result should be shown by default.
|
||||
|
||||
4. `importance`:
|
||||
|
||||
- If `importance` is `"note"`, the result should not be shown by default. STOP.
|
||||
- If `importance` is `"warning"` or `"error"`, the result should be shown by default.
|
||||
|
||||
## <a id="suppression-status"></a>Determining suppression status
|
||||
|
||||
The `result.suppressions` property is an array each of whose elements represents a request to suppress the result. Each array element has an optional `"status"` property that describes the review status of the suppression request: `"accepted"`, `"underReview"`, or `"rejected"`.<sup><a href="#note-2">2</a></sup>
|
||||
|
||||
If the status of _any_ of the suppressions is `"underReview"` or `"rejected"`, then the result should _not_ be considered suppressed. Otherwise, the result _should_ be considered suppressed.
|
||||
|
||||
## <a id="importance"></a>Determining importance
|
||||
|
||||
The SARIF `result` object's `level` and `kind` properties together determine the result's overall importance. For clarity, we refer to the result of this importance calculation as `importance`, set in code font, even though the `result` object does not have an "importance" property. `importance` is always one of `"error"`, `"warning"`, or `"note"`.
|
||||
|
||||
In general, results whose `importance` is `"error"` are blocking and must be fixed, results whose `importance` is `"warning"` are non-blocking but should still be fixed, and results whose `importance` is `"note"` represent either optional opportunities to improve code quality, or purely informational messages.
|
||||
|
||||
By the SARIF spec, only certain combinations of `kind` and `level` are valid. If `level` is `"error"`, `"warning"`, or `"note"`, then the result describes a failure of some kind, and therefore `"kind"` must be `"fail"`. Conversely, if `"kind"` is anything other than `"fail"` (for example `"pass"` or `"open"`), then the result does _not_ describe a failure, so `"level"` must be `"none"`.<sup><a href="#note-3">3</a></sup>
|
||||
|
||||
To complicate matters still further, a result's effective "level" is determined by a combination of factors in addition to the result's own `level` property. For the remainder of this section, when we refer to `level`, we really mean the result's effective level as explained in the section <a href="#effective-level">Determining effective level</a>.
|
||||
|
||||
With that background, `importance` is calculated as follows:
|
||||
|
||||
If `level` is `"error"`, `"warning"`, or `"none"`, then `importance` is equal to `level`.
|
||||
|
||||
If `level` is `"none"`, `importance` depends upon `kind` as follows:
|
||||
|
||||
| `kind` | Meaning | `importance` |
|
||||
| --- | --- | --- |
|
||||
| `"informational"` | The result represents a purely informational observation about the code (for example, "This file was compiled with C++ Compiler Version 7.1.2") | `"note"` |
|
||||
| `"notApplicable"` | The analysis rule was not applicable to this analysis target. | `"note"` |
|
||||
| `"open"` | The analysis tool did not have enough information to determine whether there was a problem.<sup><a href="#note-4">4</a></sup> | `"warning"` |
|
||||
| `"pass"` | The analysis rule was evaluated, and no problem was found. | `"note"`<sup><a href="#note-5">5</a></sup> |
|
||||
| `"review"` | The result requires human review | `"warning"` |
|
||||
|
||||
## <a id="effective-level"></a>Determining effective level
|
||||
|
||||
The effective level calculation is present in the SARIF spec, but it's a little hard to dig out because it is spread across sections that describe results, rule metadata, and policies. The algorithm is as follows:
|
||||
|
||||
1. If a policy is in effect, and if the policy specifies a `level` for the rule violated by this result, then that is the effective level. STOP.
|
||||
|
||||
2. If `result.level` is present, then that is the effective level. STOP.
|
||||
|
||||
3. If rule metadata is available for the rule violated by this result, and if the metadata specifies `defaultConfiguration.level`, then that is the effective level. STOP.
|
||||
|
||||
4. Otherwise, since the result does not specify a level, and since there is no default configuration or policy to turn to, the effective level is `"warning"`.
|
||||
|
||||
## Summary
|
||||
|
||||
To ensure a uniform experience across the SARIF ecosystem, it is important that viewers implement a standard algorithm for determining which results to display by default, and for conveying the relative importance of the results it does display. We recommend the algorithms described here.
|
||||
|
||||
In addition, viewers should provide UI gestures to allow users to see results that are not displayed by default.
|
||||
|
||||
## Notes
|
||||
|
||||
<a id="note-1"></a>1. See [§3.19.5](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317538) in the SARIF spec for details.
|
||||
|
||||
<a id="note-2"></a>2. See [§3.35](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317733) and [§3.35.3](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317736) in the SARIF spec for details.
|
||||
|
||||
<a id="note-3"></a>3. See [§3.27.9](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317647) and [§3.27.10](https://docs.oasis-open.org/sarif/sarif/v2.1.0/os/sarif-v2.1.0-os.html#_Toc34317648) in the SARIF spec for details.
|
||||
|
||||
<a id="note-4"></a>4. This value is used by program correctness provers. If, for example, a prover doesn't know if a particular function can throw an exception, it might not be able to decide whether a code path is safe.
|
||||
|
||||
<a id="note-5"></a>5. If possible, a viewer should represent a `"pass"` result with an icon distinct from the typical "blue information" icon used for other `"note"`s, for example, a green check mark.
|
||||
|
||||
[Table of contents](../README.md#contents)
|
||||
Загрузка…
Ссылка в новой задаче