Skip to content

Commit

Permalink
docs: add a section about advisories and vulnerabilities
Browse files Browse the repository at this point in the history
  • Loading branch information
ctron committed Dec 20, 2024
1 parent ec51cac commit d63bf74
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 10 deletions.
1 change: 1 addition & 0 deletions docs/book/modules/concepts/nav.adoc
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]
11 changes: 11 additions & 0 deletions docs/book/modules/concepts/pages/a_v.adoc
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.
19 changes: 9 additions & 10 deletions docs/book/modules/concepts/pages/index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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.

Expand All @@ -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.
Expand All @@ -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
Expand Down

0 comments on commit d63bf74

Please sign in to comment.