-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add a section about advisories and vulnerabilities
- Loading branch information
Showing
3 changed files
with
21 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,2 @@ | ||
* xref:concepts:index.adoc[Concepts] | ||
** xref:concepts:a_v.adoc[Advisories & vulnerabilities] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
= Advisories & vulnerabilities | ||
|
||
Trustify learns about xref:index.adoc#vulnerability[Vulnerabilities] by ingesting advisories. During the ingestion | ||
process, Trustify extracts and aggregates vulnerability information, grouped by their vulnerability identifier. | ||
|
||
Advisories can contain multiple vulnerabilities and can 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 Common Vulnerabilities and Exposures (CVE) project supersedes information from more specific advisories. | ||
|
||
Trustify also has "vulnerabilities belonging to an advisory", which contain specific vulnerability information, | ||
provided by that advisory. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,9 +2,8 @@ | |
|
||
The following sections explain a few concepts of Trustify. | ||
|
||
== Entities | ||
|
||
=== Vulnerability | ||
[#vulnerability] | ||
== Vulnerability | ||
|
||
A vulnerability is mostly, primarily a *name* that is used to ensure all advisories are discussing the same thing. | ||
Generally, to this point, most vulnerabilities come from the CVE Project, with the format of `CVE-2024-1234`. | ||
|
@@ -13,7 +12,7 @@ Within the database, generally a vulnerability is added as a side effect of an a | |
|
||
A *CVE Record* from NIST/NVD is a low-value advisory that is generally the first discovered advisory that mentions a vulnerability. | ||
|
||
=== Advisory | ||
== Advisory | ||
|
||
An advisory is an opinion about a vulnerability. | ||
|
||
|
@@ -27,7 +26,7 @@ This may be simply in reference to the vulnerability *as it exists in source-cod | |
Other, more-involved stakeholders (product vendors, upstream project owners) may issue *additional* advisories. | ||
These opinions may be in reference to *concrete* shipped products, contextualized to how the vulnerable code is *actually used*. | ||
|
||
=== SBOM | ||
== SBOM | ||
|
||
An SBOM is a source-of-someone's-truth about "what's inside it?", so | ||
everything in our DB is ultimately sourced from some | ||
|
@@ -39,7 +38,7 @@ A1 + A97". So an SBOM is the entity to track the origin of the | |
supposed "evidence" of assertional statements about products... about | ||
packages... about vulnerabilities... | ||
|
||
=== Package | ||
== Package | ||
|
||
A package is an atomic artifact or component. | ||
Packages may be addressed using pURLs. | ||
|
@@ -48,15 +47,15 @@ A package may certainly contain other packages (e.g. shading one Java jar into a | |
A package may also be the sole member of a Product (`UBI-8.0.13-x86.oci` may be the singular package within the "UBI 8.0.13-x86" product). | ||
A package is one step more abstract than an *artifact*. | ||
|
||
==== pURL | ||
=== pURL | ||
|
||
Package URLs (pURLs) are possibly ambiguous names applied to packages. | ||
A simple pURL such as `pkg:maven/org.apache/[email protected]` may or may not refer to a unique artifact. | ||
With additional qualifiers, it is possible to produce a URI that asserts uniqueness, such as `pkg:maven/org.apache/[email protected]?repository_url=repo.jboss.com`. | ||
Without additional qualifiers, the implicit aspects (such as `repository_url`) must be taken into account. | ||
For instance, an unqualified `pkg:maven` pURL *implies* "the jar from Maven Central, and none other". | ||
|
||
=== Product | ||
== Product | ||
|
||
A product is a *named collection of 1 or more packages* for a concrete shippable thing. | ||
|
||
|
@@ -68,7 +67,7 @@ NOTE: Given Red Hat ProdSec definitions, grouping of Products may need to occur | |
`RHEL8` may be a *product stream*. | ||
`RHEL 8.2.03 PowerPC` may be a concrete *product* distinct from `RHEL 8.2.03 AArch64`. | ||
|
||
==== CPE | ||
=== CPE | ||
|
||
A CPE is a "Common Product Enumeration" from the NIST organization. | ||
CPEs are self-assigned but registered occasionally with NIST. | ||
|
@@ -78,7 +77,7 @@ For instance, "All versions of RHEL 8.2.013, regardless of platform", or if more | |
|
||
NOTE: CPEs are somewhat contentious, and used enough for us to not ignore, but not used enough to be a pivotal definition of "product" for any users of Trustify. | ||
|
||
=== Artifact | ||
== Artifact | ||
|
||
For a given *package*, there may be zero or more instances of that package. | ||
Given `log4j-1.2.3.jar`, seventeen different people could compile the same source with the same arguments, and still end | ||
|