dosc: move glossary and add some more details about vulnerabilities and advisories #1106
Conversation
|
@ctron : Thanks for tagging me for a review! I will try to review this before the end of the week. |
| xref:index.adoc#vulnerability[Vulnerabilities] are learned from ingesting advisories. During the ingestion process, | ||
| Trustify will extract and aggregate vulnerability information, grouped by their vulnerability identifier. | ||
|
|
||
| Advisories may contain multiple vulnerabilities and may scope the application of statements the advisories make to |
There was a problem hiding this comment.
We should avoid using the word "may" in technical documentation, unless you are using it to indicate permission. Consider replacing "may" with "can" or "might".
For example: Advisories might contain many vulnerabilities, and can scope the application of statements that advisories make to certain packages.
As a side note, the phrase, "... the application of statements ..." sounds like it doesn't fit when I read this sentence out loud. What do you mean by this phrase?
There was a problem hiding this comment.
My intention was so say that, statements this advisory makes about certain packages (like what the score of a vulnerability is) are limited to the scope of the advisory.
There was a problem hiding this comment.
Ah, okay, that makes more sense. Thank you!
| Advisories may contain multiple vulnerabilities and may scope the application of statements the advisories make to | ||
| certain packages. This means that trustify has an aggregated set of information for a vulnerability, where information | ||
| from the CVE project supersedes information from more specific advisories. And has "vulnerabilities of an advisory", | ||
| which contains the specific information provided by this advisory. |
There was a problem hiding this comment.
For the sentences starting on line 7 ending on line 9.
trustify --> Trustify
On the first use of an acronym, we should spell it out, then you can use the acronym elsewhere in the doc.
CVE --> Common Vulnerabilities and Exposures (CVE)
I would suggest ending this sentence a little earlier.
For example: This means that Trustify has an aggregated set of information for a vulnerability.
Then start the next sentence, for example: The information from the Common Vulnerabilities and Exposures (CVE) project supersedes the information from more specific advisories.
We should avoid starting a sentence with "And ...". I'm not sure what is meant by this last sentence. Does the CVE project contain the "vulnerabilities of an advisory" information, or does this information come from somewhere else? Consider rewriting this last sentence, or remove it completely.
For example: The CVE project tracks the vulnerabilities for a specific advisory.
Putting all three of my sentence suggestions together gives us this paragraph:
Advisories can contain many vulnerabilities, and can scope the application of statements that advisories make to certain packages. The information from the Common Vulnerabilities and Exposures (CVE) project supersedes the information from more specific advisories. The CVE project tracks the vulnerabilities for a specific advisory.
There was a problem hiding this comment.
Tried to rephrase the last sentence:
Trustify also has "vulnerabilities belonging to an advisory", which contain specific vulnerability information,
provided by that advisory.
| Given `log4j-1.2.3.jar`, seventeen different people could compile the same source with the same arguments, and still end | ||
| up with 17 distinct Java jars (due to non-reproducible builds). | ||
| Each is an artifact of the *same* package. | ||
| Each may (will probably) have its own SHA-256 related to it. |
There was a problem hiding this comment.
Drop the phrase "will propably" from the sentence.
For example: Each can have its own SHA-256 related to it.
There was a problem hiding this comment.
I think the idea was to state not only the possibility that it can, but also that, most likely, it actually will have.
Changed that into: Each might, and most likely will, have its own SHA-256 related to it.
ctron
force-pushed
the
feature/move_glossary_1
branch
2 times, most recently
from
31fd614 to
4de809b
Compare
|
@ritz303 thanks for the review, learned a few more things :) I pushed some changes, I hope I covered all of it. |
|
I marked it "merge when ready", so if you're ok with it, give a +1 and it should merge, even when I'm already in 🎄 mode 😉 |
|
@ctron : I just found one more minor nit-pick, regarding capitalization, but overall this doc looks much better. Thank you for making these updates. |
Co-authored-by: Aron Gunn <[email protected]>
ctron
force-pushed
the
feature/move_glossary_1
branch
from
4de809b to
a0be4b3
Compare
No description provided.