[v2] ref-manual: document CVE_STATUS and CVE_CHECK_STATUSMAP

Deprecate CVE_CHECK_IGNORE with CVE_STATUS

Signed-off-by: Andrej Valek <andrej.valek@siemens.com>
Signed-off-by: Peter Marko <peter.marko@siemens.com>
---
 documentation/dev-manual/new-recipe.rst      |  3 +-
 documentation/dev-manual/vulnerabilities.rst | 13 +++++---
 documentation/ref-manual/classes.rst         |  6 ++--
 documentation/ref-manual/variables.rst       | 33 +++++++++++++++++---
 4 files changed, 41 insertions(+), 14 deletions(-)

Hi Andrej

Many thanks for the patch and documentation update!

See my comments below.

On 20.07.23 at 09:31, Andrej Valek via lists.yoctoproject.org wrote:
> Deprecate CVE_CHECK_IGNORE with CVE_STATUS
>
> Signed-off-by: Andrej Valek <andrej.valek@siemens.com>
> Signed-off-by: Peter Marko <peter.marko@siemens.com>
> ---
>   documentation/dev-manual/new-recipe.rst      |  3 +-
>   documentation/dev-manual/vulnerabilities.rst | 13 +++++---
>   documentation/ref-manual/classes.rst         |  6 ++--
>   documentation/ref-manual/variables.rst       | 33 +++++++++++++++++---
>   4 files changed, 41 insertions(+), 14 deletions(-)
>
> diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
> index 1be04a765..af390773a 100644
> --- a/documentation/dev-manual/new-recipe.rst
> +++ b/documentation/dev-manual/new-recipe.rst
> @@ -1253,8 +1253,7 @@ In the following example, ``lz4`` is a makefile-based package::
>   
>      S = "${WORKDIR}/git"
>   
> -   # Fixed in r118, which is larger than the current version.
> -   CVE_CHECK_IGNORE += "CVE-2014-4715"
> +   CVE_STATUS[CVE-2014-4715] = "fixed-version: Fixed in r118, which is larger than the current version"
>   
>      EXTRA_OEMAKE = "PREFIX=${prefix} CC='${CC}' CFLAGS='${CFLAGS}' DESTDIR=${D} LIBDIR=${libdir} INCLUDEDIR=${includedir} BUILD_STATIC=no"
>   
> diff --git a/documentation/dev-manual/vulnerabilities.rst b/documentation/dev-manual/vulnerabilities.rst
> index 0ee3ec52c..6d87d02ec 100644
> --- a/documentation/dev-manual/vulnerabilities.rst
> +++ b/documentation/dev-manual/vulnerabilities.rst
> @@ -130,7 +130,8 @@ Fixing vulnerabilities in recipes
>   =================================
>   
>   If a CVE security issue impacts a software component, it can be fixed by updating to a newer
> -version of the software component or by applying a patch. For Poky and OE-Core master branches, updating
> +version of the software component, by applying a patch or by marking it as patched via
> +:term:`CVE_STATUS` variable flag. For Poky and OE-Core master branches, updating
>   to a newer software component release with fixes is the best option, but patches can be applied
>   if releases are not yet available.
>   
> @@ -158,7 +159,8 @@ CVE checker will then capture this information and change the CVE status to ``Pa
>   in the generated reports.
>   
>   If analysis shows that the CVE issue does not impact the recipe due to configuration, platform,
> -version or other reasons, the CVE can be marked as ``Ignored`` using the :term:`CVE_CHECK_IGNORE` variable.
> +version or other reasons, the CVE can be marked as ``Ignored`` by using
> +the :term:`CVE_STATUS` variable flag with appropriate reason which is mapped to ``Ignored``.
>   As mentioned previously, if data in the CVE database is wrong, it is recommend to fix those
>   issues in the CVE database directly.
>   
> @@ -175,6 +177,8 @@ is found in the name of the file, the corresponding CVE is considered as patched
>   Don't forget that if multiple CVE IDs are found in the filename, only the last
>   one is considered. Then, the code looks for ``CVE: CVE-ID`` lines in the patch
>   file. The found CVE IDs are also considered as patched.
> +Additionally ``CVE_STATUS`` variable flags are parsed for reasons mapped to ``Patched``
> +and these are also considered as patched.
>   
>   Then, the code looks up all the CVE IDs in the NIST database for all the
>   products defined in :term:`CVE_PRODUCT`. Then, for each found CVE:
> @@ -182,8 +186,9 @@ products defined in :term:`CVE_PRODUCT`. Then, for each found CVE:
>   -  If the package name (:term:`PN`) is part of
>      :term:`CVE_CHECK_SKIP_RECIPE`, it is considered as ``Patched``.
>   
> --  If the CVE ID is part of :term:`CVE_CHECK_IGNORE`, it is
> -   set as ``Ignored``.
> +-  If the CVE ID has status ``CVE_STATUS[<CVE ID>] = "ignored"`` or if it's set to
> +   any reason which is mapped to status ``Ignored`` via ``CVE_CHECK_STATUSMAP``,
> +   it is  set as ``Ignored``.
>   
>   -  If the CVE ID is part of the patched CVE for the recipe, it is
>      already considered as ``Patched``.
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index e555a80b5..b8d07f102 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 ac5b97a52..7e93f731a 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,33 @@ 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 format "reason: description" and description is optional.
> +      Reason is mapped to final CVE state by mapping via :term:`CVE_CHECK_STATUSMAP`

Should use "the format" and "the description".
Also "The reason" and "the final  CVE state".

I made the change by myself.

> +
> +   :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` to
> +      set of ``Patched``, ``Unpatched`` and ``Ignored``.

I modified to this too:
"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/>`__


Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
... and merged into master-next.


Many thanks again!
Cheers
Michael.