Re: [docs] [PATCH] manuals: further documentation for cve-check

["Quentin Schulz" <quentin.schulz@theobroma-systems.com>]

Hi Michael,

On Fri, Aug 06, 2021 at 12:37:20PM +0200, Michael Opdenacker wrote:
> This adds details about the actual implementation
> of vulnerability checks, about how to fix or ignore
> vulnerabilities in recipes, and documents the
> CVE_CHECK_PN_WHITELIST and CVE_CHECK_WHITELIST variables.
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>  documentation/dev-manual/common-tasks.rst | 67 +++++++++++++++++++++++
>  documentation/ref-manual/variables.rst    | 13 ++++-
>  2 files changed, 79 insertions(+), 1 deletion(-)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 7fa0df4d39..a7eb4642de 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -11131,6 +11131,73 @@ Enabling vulnerabily tracking in recipes
>  The :term:`CVE_PRODUCT` variable defines the name used to match the recipe name
>  against the name in the upstream `NIST CVE database <https://urldefense.proofpoint.com/v2/url?u=https-3A__nvd.nist.gov_&d=DwIDAg&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=9ML--ZrDALJnWP-cdKUdSr7aZojrZSP_ZftKiDw8b90&s=X75uMn2Jgp5D1ZeIRtUVm_E0hUPd6JAN5YALxFwNawI&e= >`__.
>  
> +Editing recipes to fix vulnerabilities
> +--------------------------------------
> +
> +To fix a given known vulnerability, you need to add a patch file to your recipe. Here's
> +an example from the :oe_layerindex:`ffmpeg recipe</layerindex/recipe/47350>`::
> +
> +   SRC_URI = "https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ffmpeg.org_releases_-24-257BBP-257D.tar.xz&d=DwIDAg&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=9ML--ZrDALJnWP-cdKUdSr7aZojrZSP_ZftKiDw8b90&s=jlaowuJQXhq1Lp2jXZTs3bYLiFspslcuyaTiPLrhe-o&e=  \
> +              file://0001-libavutil-include-assembly-with-full-path-from-sourc.patch \
> +              file://fix-CVE-2020-20446.patch \
> +              file://fix-CVE-2020-20453.patch \
> +              file://fix-CVE-2020-22015.patch \
> +              file://fix-CVE-2020-22021.patch \
> +              file://fix-CVE-2020-22033-CVE-2020-22019.patch \
> +              file://fix-CVE-2021-33815.patch \
> +
> +``cve-check.bbclass`` defines two ways of supplying a patch for a given CVE. The first

I think we could afford saying a few words about this class in the
Reference Manual? In which case:
s/``cve-check.bbclass``/:ref:`cve-check.bbclass <ref-classes-cve-check>`/ ?

> +way is to use a patch file name that matches the below pattern::
> +

Not sure about that one but s/file name/filename/ ? If chosen, fix the
other occurences at the same time :)

> +   cve_file_name_match = re.compile(".*([Cc][Vv][Ee]\-\d{4}\-\d+)")
> +
> +As shown in the example above, multiple CVE IDs can appear in a patch file name,
> +but the ``cve-check.bbclass`` code will only consider the last CVE ID in the
> +file name as patched.
> +
> +The second way to recognize a patched CVE ID is when a line matching the
> +below pattern is found in any patch file provided by the recipe::
> +
> +  cve_match = re.compile("CVE:( CVE\-\d{4}\-\d+)+")
> +
> +This allows a single patch file to address multiple CVE IDs at the same time.
> +
> +Of course, another way to fix vulnerabilities is to upgrade to a version
> +of the package which is not impacted, typically a more recent one.
> +The NIST database knows which versions are vulnerable and which ones
> +are not.
> +
> +Last but not least, you can choose to ignore vulnerabilities through
> +the :term:`CVE_CHECK_PN_WHITELIST` and :term:`CVE_CHECK_WHITELIST`
> +variables.
> +
> +Implementation details
> +----------------------
> +
> +Here's what ``cve-check.bbclass`` does to find unpatched CVE IDs.
> +

Would need the :ref: link here too if chosen.

> +First the code goes through each patch file provided by a recipe. If a valid CVE ID
> +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 file name, 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.
> +
> +Then, the code looks-up all the CVE IDs in the NIST database for all the

s/looks-up all the CVE IDs/looks all the CVE IDs up/ ?

> +products defined in :term:`CVE_PRODUCT`. Then, for each found CVE:
> +
> + - If the package name (:term:`PN`) is part of
> +   :term:`CVE_CHECK_PN_WHITELIST`, it is considered as patched.
> +
> + - If the CVE ID is part of :term:`CVE_CHECK_WHITELIST`, it is
> +   considered as patched too.
> +
> + - If the CVE ID is part of the patched CVEs for the recipe, it is
> +   already considered as patched.
> +
> + - Otherwise, the code checks whether the recipe version (:term:`PV`)
> +   is within the range of versions impacted by the CVE. If so, the CVE
> +   is considered as unpatched.
> +
>  The CVE database is stored in :term:`DL_DIR` and can be inspected using
>  ``sqlite3`` command as follows::
>  
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 1150940133..cc7be01fc5 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -1471,11 +1471,22 @@ system and gives an overview of their function and contents.
>           variable only in certain contexts (e.g. when building for kernel
>           and kernel module recipes).
>  
> +   :term:`CVE_CHECK_PN_WHITELIST`
> +      The list of package names (:term:`PN`) for which
> +      CVE vulnerabilities are ignored.
> +

Since CVE stands for "Common Vulnerabilities and Exposures", isn't
adding vulnerabilities redundant?

> +   :term:`CVE_CHECK_WHITELIST`
> +      The list of vulnerability CVE IDs which are ignored. Here is

Ditto.

Thanks for the patch :)
Quentin