[Buildroot] [RFC PATCH 01/14] docs/manual: add vulnerability status and justification

[Thomas Perale via buildroot <buildroot@buildroot.org>]

In Buildroot, we can put the ignore CVEs entries in different
categories:

- Vulnerability fixed by a patch.
- Vulnerability ignored because the internal tooling detect it as a
  false positive
- Vulnerability ignored because the database is wrong or not up-to-date.
- Vulnerability ignored because it doesn't apply to Buildroot
  (platform/hardware specific, ...).
- Vulnerability ignored because Buildroot is using an upstream fixed
  version (based on a hash for instance) while the CPE metadata
  reference the latest known version.

Since the introduction of `_IGNORE_CVES` the justification for the
vulnerability were added as a comment on top of the ignored
vulnerability. With the introduction of the rule for the `CVE:` trailer
it's now possible to distinguish the vulnerabilities that are patched
from the one that are not-applicable for another unknown reason.

This commit add documentation to introduce two new variables:

- `<pkg>_<vuln-id>_STATUS`
- `<pkg>_<vuln-id>_DETAIL`

This allows to have machine readable variables that are exposed and
contains the reasons why a vulnerability is set as ignored instead of
storing this knowledge in a comment on top of the `_IGNORE_CVES` entry.

The `<pkg>_<vuln-id>_STATUS` syntax is based on OpenVex statuses syntax
[1][2]. This varialbe only needs to be used if a patch on the Buildroot
tree isn't present.

The `<pkg>_<vuln-id>_DETAIL` is a free text field that allows to add
more information to justify the status.

[1] https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-labels
[2] https://github.com/openvex/ospec/blob/main/OPENVEX-SPEC.md#status-justifications

Signed-off-by: Thomas Perale <thomas.perale@mind.be>
---
 docs/manual/adding-packages-generic.adoc | 35 ++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/docs/manual/adding-packages-generic.adoc b/docs/manual/adding-packages-generic.adoc
index e7547460fd..47b28adf4b 100644
--- a/docs/manual/adding-packages-generic.adoc
+++ b/docs/manual/adding-packages-generic.adoc
@@ -520,6 +520,41 @@ LIBFOO_IGNORE_CVES += CVE-2020-12345
 LIBFOO_IGNORE_CVES += CVE-2020-54321
 ----
 
+* +LIBFOO_<VULN-ID>_STATUS+ informs about the impact of the vulnerability
+  +<VULN-ID>+. This variable needs to be set only if the referenced +<VULN-ID>+
+  is not fixed by a patch present in the Buildroot tree. It support different
+  labels based on
+  https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-labels[OpenVex
+  statuses] and
+  https://github.com/openvex/spec/blob/main/OPENVEX-SPEC.md#status-justifications[justification]:
+  ** +fixed+: referenced by the package Makefile already includes the fix but
+     no new version has been issued by the upstream project. This typically
+     happens when the version is using an +hash+ and the CPE reference the
+     latest known version.
+  ** +not-affected-component-not-present+: the vulnerability is incorrect and
+     should reference another package. Or the package is not part of the final
+     image.
+  ** +not-affected-vulnerable-code-not-present+: the code affected by the
+     vulnerability is not included in the final image. Could be a not supported
+     architecture, flags that are disabled by the package configuration,
+     busybox commands not built, dependencies not supported, ...
+  ** +not-affected-vulnerable-code-not-in-execute-path+: the vulnerable code is
+     present in the generated image but cannot be reached because of the
+     system's runtime configuration.
+  ** +not-affected-vulnerable-code-cannot-be-controlled-by-adversary+: the
+     vulnerable code may be executed, but an attacker cannot control the inputs
+     required to trigger the vulnerability.
+* +LIBFOO_<VULN-ID>_DETAIL+ is an optional free text entry that add
+  additional information on the reason a +STATUS+ has been set for a
+  +<VULN-ID>+.
++
+----
+LIBFOO_IGNORE_CVES += CVE-2020-54321
+
+LIBFOO_CVE-2020-54321_STATUS = not-affected-vulnerable-code-not-present
+LIBFOO_CVE-2020-54321_DETAIL = Only when built with libbaz, which Buildroot doesn't support
+----
+
 * [[cpe-id]] +LIBFOO_CPE_ID_*+ variables is a set of variables that allows the
   package to define its https://nvd.nist.gov/products/cpe[CPE
   identifier]. The available variables are:
-- 
2.54.0

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot