From 0d4900e02ab42139ff79fed81fc3d0389723737b Mon Sep 17 00:00:00 2001 From: Jens Reimann Date: Tue, 17 Dec 2024 16:43:32 +0100 Subject: [PATCH 1/3] docs: move glossary into the book --- docs/book/antora.yml | 1 + .../admin/examples/trustify/database.tf | 2 + docs/book/modules/concepts/nav.adoc | 1 + docs/book/modules/concepts/pages/index.adoc | 89 +++++++++++++++++++ docs/glossary.md | 89 +------------------ 5 files changed, 94 insertions(+), 88 deletions(-) create mode 100644 docs/book/modules/concepts/nav.adoc create mode 100644 docs/book/modules/concepts/pages/index.adoc diff --git a/docs/book/antora.yml b/docs/book/antora.yml index eb2a76364..514c9b708 100644 --- a/docs/book/antora.yml +++ b/docs/book/antora.yml @@ -5,3 +5,4 @@ start_page: ROOT:index.adoc nav: - modules/ROOT/nav.adoc - modules/admin/nav.adoc + - modules/concepts/nav.adoc diff --git a/docs/book/modules/admin/examples/trustify/database.tf b/docs/book/modules/admin/examples/trustify/database.tf index fe3032983..86c122cd5 100644 --- a/docs/book/modules/admin/examples/trustify/database.tf +++ b/docs/book/modules/admin/examples/trustify/database.tf @@ -122,4 +122,6 @@ resource "aws_db_instance" "trustify" { skip_final_snapshot = true availability_zone = var.availability-zone + + performance_insights_enabled = true } diff --git a/docs/book/modules/concepts/nav.adoc b/docs/book/modules/concepts/nav.adoc new file mode 100644 index 000000000..06b497d60 --- /dev/null +++ b/docs/book/modules/concepts/nav.adoc @@ -0,0 +1 @@ +* xref:concepts:index.adoc[Concepts] diff --git a/docs/book/modules/concepts/pages/index.adoc b/docs/book/modules/concepts/pages/index.adoc new file mode 100644 index 000000000..8229ade40 --- /dev/null +++ b/docs/book/modules/concepts/pages/index.adoc @@ -0,0 +1,89 @@ += Concepts + +The following sections explain a few concepts of Trustify. + +== Entities + +=== 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`. + +Within the database, generally a vulnerability is added as a side effect of an advisory mentioning it. + +A *CVE Record* from NIST/NVD is a low-value advisory that is generally the first discovered advisory that mentions a vulnerability. + +=== Advisory + +An advisory is an opinion about a vulnerability. + +These opinions include the context to which the opinions apply. +These opinions include evaluation of the severity and scoring of a vulnerability within that context, such as CVSS scores. + +As mentioned above, a *CVE Record* from the CVE Project is a low-value advisory that mentions the vulnerability and provides a base opinion about it. +It may include CVSS scores, within the context of the abstract origin containing the vulnerability. +This may be simply in reference to the vulnerability *as it exists in source-code form*. + +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 + +An SBOM is a source-of-someone's-truth about "what's inside it?", so +everything in our DB is ultimately sourced from some +source-of-truth. We can't really say definitively "product X is +composed of A1, A2 + A3". Instead, we can have multiple simultaneous +statements -- SBOM's -- from multiple people saying "product X is +claimed by Bob to be A1 + A2" and "product X is claimed by Jim to be +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 + +A package is an atomic artifact or component. +Packages may be addressed using pURLs. +A package may be described by an SBOM describing how it is created and its contents. +A package may certainly contain other packages (e.g. shading one Java jar into another). +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 + +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. +With additional qualifiers, it is possible to produce a URI that asserts uniqueness, such as `pkg:maven/org.apache/log4j@1.2.3?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 + +A product is a *named collection of 1 or more packages* for a concrete shippable thing. + +Products may be addressed using CPEs or some other future identification method. +A product may be described by an SBOM describing its components, which may be other products or packages, or their SBOMs. + +NOTE: Given Red Hat ProdSec definitions, grouping of Products may need to occur within some sense of Product Versions, or Product Streams. + +`RHEL8` may be a *product stream*. +`RHEL 8.2.03 PowerPC` may be a concrete *product* distinct from `RHEL 8.2.03 AArch64`. + +==== CPE + +A CPE is a "Common Product Enumeration" from the NIST organization. +CPEs are self-assigned but registered occasionally with NIST. +CPEs describe the vendor, the product, the version, target architecture, etc. +CPEs may also be non-fully specified, to use as pattern-matching. +For instance, "All versions of RHEL 8.2.013, regardless of platform", or if more fully-specified, could imply "All versions of RHEL 8.x on AArch64". + +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 + +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 +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. + +Consider an *artifact* to be a concrete *instance* of a package. diff --git a/docs/glossary.md b/docs/glossary.md index 9f9c0c3ff..795c4941d 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,88 +1 @@ -# Glossary of Understanding - -## Entities - -### 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`. - -Within the database, generally a vulnerability is added as a side effect of an advisory mentioning it. - -A *CVE Record* from NIST/NVD is a low-value advisory that is generally the first discovered advisory that mentions a vulnerability. - -### Advisory - -An advisory is an opinion about a vulnerability. - -These opinions include the context to which the opinions apply. -These opinions include evaluation of the severity and scoring of a vulnerability within that context, such as CVSS scores. - -As mentioned above, a *CVE Record* from the CVE Project is a low-value advisory that mentions the vulnerability and provide a base opinion about it. -It may include CVSS scores, within the context of the abstract origin containing the vulnerability. -This may be simply in reference to the vulnerability *as it exists in source-code form*. - -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 - -An SBOM is a source-of-someone's-truth about "what's inside it?", so -everything in our DB is ultimately sourced from some -source-of-truth. We can't really say definitively "product X is -composed of A1, A2 + A3". Instead, we can have multiple simultaneous -statements -- SBOM's -- from multiple people saying "product X is -claimed by Bob to be A1 + A2" and "product X is claimed by Jim to be -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 - -A package is an atomic artifact or component. -Packages may be addressed using pURLs. -A package may be described by an SBOM describing how it is created and its contents. -A package may certainly contain other packages (e.g. shading one Java jar into another). -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 - -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. -With additional qualifiers, it is possible to produce a URI that asserts uniqueness, such as `pkg:maven/org.apache/log4j@1.2.3?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 - -A product is a *named collection of 1 or more packages* for a concrete shippable thing. - -Products may be addressed using CPEs or some other future identification method. -A product may be described by an SBOM describing its components, which may be other products or packages, or their SBOMs. - -> [!NOTE] -> Given ProdSec definitions, grouping of Products may need to occur within some sense of Product Versions, or Product Streams. - -`RHEL8` may be a *product stream*. -`RHEL 8.2.03 PowerPC` may be a concrete *product* distinct from `RHEL 8.2.03 AArch64`. - -#### CPE - -A CPE is a "Common Product Enumeration" from the NIST organization. -CPEs are self-assigned, but registered occasionally with NIST. -CPEs describe the vendor, the product, the version, target architecture, etc. -CPEs may also be non-fully specified, to use as pattern-matching. -For instance, "All versions of RHEL 8.2.013, regardless of platform", or if more fully-specified, could imply "All versions of RHEL 8.x on AArch64". - -> [!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 - -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 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. - -Consider an *artifact* to be a concrete *instance* of a package. +See [book/modules/concepts/pages/index.adoc](book/modules/concepts/pages/index.adoc). From e6adcefe52e7690f1ae06520931f4bdc3cfc43a3 Mon Sep 17 00:00:00 2001 From: Jens Reimann Date: Tue, 17 Dec 2024 16:58:05 +0100 Subject: [PATCH 2/3] 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 06b497d60..e720a2691 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 000000000..58a83e116 --- /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 8229ade40..2af455cea 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 From dce932981e632d80920d5b79b288e2224e9fa56e Mon Sep 17 00:00:00 2001 From: Jens Reimann Date: Fri, 20 Dec 2024 09:43:09 +0100 Subject: [PATCH 3/3] docs: incorporated feedback from docs review Co-authored-by: Aron Gunn --- docs/book/modules/concepts/pages/a_v.adoc | 2 +- docs/book/modules/concepts/pages/index.adoc | 57 +++++++++++---------- 2 files changed, 32 insertions(+), 27 deletions(-) diff --git a/docs/book/modules/concepts/pages/a_v.adoc b/docs/book/modules/concepts/pages/a_v.adoc index 58a83e116..6250bb68f 100644 --- a/docs/book/modules/concepts/pages/a_v.adoc +++ b/docs/book/modules/concepts/pages/a_v.adoc @@ -1,6 +1,6 @@ = Advisories & vulnerabilities -Trustify learns about xref:index.adoc#vulnerability[Vulnerabilities] by ingesting advisories. During the ingestion +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 diff --git a/docs/book/modules/concepts/pages/index.adoc b/docs/book/modules/concepts/pages/index.adoc index 2af455cea..90e7b8343 100644 --- a/docs/book/modules/concepts/pages/index.adoc +++ b/docs/book/modules/concepts/pages/index.adoc @@ -5,32 +5,35 @@ The following sections explain a few concepts of Trustify. [#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`. +A vulnerability is primarily a *name* for ensuring all advisories are discussing the same thing. +Generally, most vulnerabilities come from the CVE Project, with the format of `CVE-2024-1234`. -Within the database, generally a vulnerability is added as a side effect of an advisory mentioning it. +Within the database, Trustify adds the vulnerability when discovering an advisory mentioning it. -A *CVE Record* from NIST/NVD is a low-value advisory that is generally the first discovered advisory that mentions a vulnerability. +A *CVE Record* from National Institute of Standards and Technology (NIST)/National Vulnerabilities Database (NVD) is a +low-value advisory that is generally the first discovered advisory that mentions a vulnerability. == Advisory An advisory is an opinion about a vulnerability. These opinions include the context to which the opinions apply. -These opinions include evaluation of the severity and scoring of a vulnerability within that context, such as CVSS scores. +These opinions include evaluation of the severity and scoring of a vulnerability within that context, such as +Common Vulnerability Scoring System (CVSS) scores. As mentioned above, a *CVE Record* from the CVE Project is a low-value advisory that mentions the vulnerability and provides a base opinion about it. -It may include CVSS scores, within the context of the abstract origin containing the vulnerability. -This may be simply in reference to the vulnerability *as it exists in source-code form*. +It might include CVSS scores, within the context of the abstract origin containing the vulnerability. +This might be simply in reference to the vulnerability *as it exists in source-code form*. -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*. +Other, more-involved stakeholders, such as, product vendors, upstream project owners, might issue *additional* +advisories. +These opinions might be in reference to *concrete*, shipped products, contextualized to how the vulnerable code is *actually used*. == 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 -source-of-truth. We can't really say definitively "product X is +source-of-truth. We cannot really say definitively "product X is composed of A1, A2 + A3". Instead, we can have multiple simultaneous statements -- SBOM's -- from multiple people saying "product X is claimed by Bob to be A1 + A2" and "product X is claimed by Jim to be @@ -41,48 +44,50 @@ packages... about vulnerabilities... == Package A package is an atomic artifact or component. -Packages may be addressed using pURLs. -A package may be described by an SBOM describing how it is created and its contents. -A package may certainly contain other packages (e.g. shading one Java jar into another). -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). +Packages can be addressed using pURLs. +A package can be described by an SBOM describing how it is created and its contents. +A package can certainly contain other packages. For example, shading one Java jar into another. +A package can also be the sole member of a product. For example `UBI-8.0.13-x86.oci` can be the singular package within the "UBI 8.0.13-x86" product. A package is one step more abstract than an *artifact*. === 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. +A simple pURL such as `pkg:maven/org.apache/log4j@1.2.3` can or cannot refer to a unique artifact. With additional qualifiers, it is possible to produce a URI that asserts uniqueness, such as `pkg:maven/org.apache/log4j@1.2.3?repository_url=repo.jboss.com`. -Without additional qualifiers, the implicit aspects (such as `repository_url`) must be taken into account. +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 A product is a *named collection of 1 or more packages* for a concrete shippable thing. -Products may be addressed using CPEs or some other future identification method. -A product may be described by an SBOM describing its components, which may be other products or packages, or their SBOMs. +Products can be addressed using Common Platform Enumerations (CPE) or some other future identification method. +A product can be described by an SBOM describing its components, which might be other products or packages, or their SBOMs. -NOTE: Given Red Hat ProdSec definitions, grouping of Products may need to occur within some sense of Product Versions, or Product Streams. +NOTE: Given Red Hat Product Security definitions, grouping of products might need to occur within some sense of product +versions, or product streams. -`RHEL8` may be a *product stream*. -`RHEL 8.2.03 PowerPC` may be a concrete *product* distinct from `RHEL 8.2.03 AArch64`. +`Red Hat Enterprise Linux 8` might be a *product stream*. +`Red Hat Enterprise Linux 8.2.03 PowerPC` might be a concrete *product* distinct from `Red Hat Enterprise Linux 8.2.03 AArch64`. === CPE A CPE is a "Common Product Enumeration" from the NIST organization. CPEs are self-assigned but registered occasionally with NIST. CPEs describe the vendor, the product, the version, target architecture, etc. -CPEs may also be non-fully specified, to use as pattern-matching. -For instance, "All versions of RHEL 8.2.013, regardless of platform", or if more fully-specified, could imply "All versions of RHEL 8.x on AArch64". +CPEs can also be non-fully specified, to use as pattern-matching. +For instance, "All versions of Red Hat Enterprise Linux 8.2.013, regardless of platform", or if more fully-specified, +could imply "All versions of Red Hat Enterprise Linux 8.x on AArch64". 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 -For a given *package*, there may be zero or more instances of that package. +For a given *package*, there can 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 -up with 17 distinct Java jars (due to non-reproducible builds). +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. +Each might, and most likely will, have its own SHA-256 related to it. Consider an *artifact* to be a concrete *instance* of a package.