From d63bf7489cb015c8894bd59d45ddfb620aa9b5be Mon Sep 17 00:00:00 2001 From: Jens Reimann Date: Tue, 17 Dec 2024 16:58:05 +0100 Subject: [PATCH] docs: add a section about advisories and vulnerabilities --- docs/book/modules/concepts/nav.adoc | 1 + docs/book/modules/concepts/pages/a_v.adoc | 11 +++++++++++ docs/book/modules/concepts/pages/index.adoc | 19 +++++++++---------- 3 files changed, 21 insertions(+), 10 deletions(-) create mode 100644 docs/book/modules/concepts/pages/a_v.adoc diff --git a/docs/book/modules/concepts/nav.adoc b/docs/book/modules/concepts/nav.adoc index 06b497d6..e720a269 100644 --- a/docs/book/modules/concepts/nav.adoc +++ b/docs/book/modules/concepts/nav.adoc @@ -1 +1,2 @@ * xref:concepts:index.adoc[Concepts] +** xref:concepts:a_v.adoc[Advisories & vulnerabilities] diff --git a/docs/book/modules/concepts/pages/a_v.adoc b/docs/book/modules/concepts/pages/a_v.adoc new file mode 100644 index 00000000..58a83e11 --- /dev/null +++ b/docs/book/modules/concepts/pages/a_v.adoc @@ -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. diff --git a/docs/book/modules/concepts/pages/index.adoc b/docs/book/modules/concepts/pages/index.adoc index 8229ade4..2af455ce 100644 --- a/docs/book/modules/concepts/pages/index.adoc +++ b/docs/book/modules/concepts/pages/index.adoc @@ -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,7 +47,7 @@ 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/log4j@1.2.3` may or may not refer to a unique artifact. @@ -56,7 +55,7 @@ With additional qualifiers, it is possible to produce a URI that asserts uniquen 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