ref-manual: document CVE_STATUS and CVE_CHECK_STATUSMAP

Deprecate CVE_CHECK_IGNORE with CVE_STATUS

(From yocto-docs rev: 8b8054977f31e2d6090521a0102f066b6d563733)

Signed-off-by: Andrej Valek <andrej.valek@siemens.com>
Signed-off-by: Peter Marko <peter.marko@siemens.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 32 insertions, 8 deletions

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 4577baba3e..a7819d5b60 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -517,10 +517,10 @@ The ``Patched`` state of a CVE issue is detected from patch files with the forma
 ``CVE-ID.patch``, e.g. ``CVE-2019-20633.patch``, in the :term:`SRC_URI` and using
 CVE metadata of format ``CVE: CVE-ID`` in the commit message of the patch file.
 
-If the recipe lists the ``CVE-ID`` in :term:`CVE_CHECK_IGNORE` variable, then the CVE state is reported
-as ``Ignored``. Multiple CVEs can be listed separated by spaces. Example::
+If the recipe adds ``CVE-ID`` as flag of the :term:`CVE_STATUS` variable with status
+mapped to ``Ignored``, then the CVE state is reported as ``Ignored``::
 
-   CVE_CHECK_IGNORE += "CVE-2020-29509 CVE-2020-29511"
+   CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows"
 
 If CVE check reports that a recipe contains false positives or false negatives, these may be
 fixed in recipes by adjusting the CVE product name using :term:`CVE_PRODUCT` and :term:`CVE_VERSION` variables.
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index ac5b97a526..def98de307 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1653,11 +1653,7 @@ system and gives an overview of their function and contents.
          and kernel module recipes).
 
    :term:`CVE_CHECK_IGNORE`
-      The list of CVE IDs which are ignored. Here is
-      an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`::
-
-         # This is windows only issue.
-         CVE_CHECK_IGNORE += "CVE-2020-15523"
+      This variable is deprecated and should be replaced by :term:`CVE_STATUS`.
 
    :term:`CVE_CHECK_SHOW_WARNINGS`
       Specifies whether or not the :ref:`ref-classes-cve-check`
@@ -1698,6 +1694,34 @@ system and gives an overview of their function and contents.
 
          CVE_PRODUCT = "vendor:package"
 
+   :term:`CVE_STATUS`
+      The CVE ID which is patched or should be ignored. Here is
+      an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`::
+
+         CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows"
+
+      It has the format "reason: description" and the description is optional.
+      The Reason is mapped to the final CVE state by mapping via
+      :term:`CVE_CHECK_STATUSMAP`
+
+   :term:`CVE_STATUS_GROUPS`
+      If there are many CVEs with the same status and reason, they can by simplified by using this
+      variable instead of many similar lines with :term:`CVE_STATUS`::
+
+         CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED"
+
+         CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002"
+         CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows"
+         CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004"
+         CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally"
+
+   :term:`CVE_CHECK_STATUSMAP`
+      Mapping variable for all possible reasons of :term:`CVE_STATUS`:
+      ``Patched``, ``Unpatched`` and ``Ignored``.
+      See :ref:`ref-classes-cve-check` or ``meta/conf/cve-check-map.conf`` for more details::
+
+         CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored"
+
    :term:`CVE_VERSION`
       In a recipe, defines the version used to match the recipe version
       against the version in the `NIST CVE database <https://nvd.nist.gov/>`__