[PATCH] manuals: initial documentation for CVE management

[PATCH] manuals: initial documentation for CVE management

[Michael Opdenacker]

This starts to document vulnerability management
and the use of the CVE_PRODUCT variable

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/dev-manual/common-tasks.rst | 46 +++++++++++++++++++++++
 documentation/ref-manual/variables.rst    | 11 ++++++
 2 files changed, 57 insertions(+)

diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index 9a6f4e1a8e..aa296850f8 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -10528,6 +10528,9 @@ follows:
 1. *Identify the bug or CVE to be fixed:* This information should be
    collected so that it can be included in your submission.
 
+   See :ref:`dev-manual/common-tasks:checking for vulnerabilities`
+   for details about CVE tracking.
+
 2. *Check if the fix is already present in the master branch:* This will
    result in the most straightforward path into the stable branch for the
    fix.
@@ -11090,6 +11093,49 @@ the license from the fetched source::
 
    NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
 
+Checking for Vulnerabilities
+============================
+
+Vulnerabilities in images
+-------------------------
+
+The Yocto Project has an infrastructure to track and address unfixed
+known security vulnerabilities, as tracked by the public
+`Common Vulnerabilities and Exposures (CVE) <https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures>`__
+database.
+
+To know which packages are vulnerable to known security vulnerabilities,
+add the following setting to your configuration::
+
+   INHERIT += "cve-check"
+
+This way, at build time, BitBake will warn you about known CVEs
+as in the example below::
+
+   WARNING: flex-2.6.4-r0 do_cve_check: Found unpatched CVE (CVE-2019-6293), for more information check /poky/build/tmp/work/core2-64-poky-linux/flex/2.6.4-r0/temp/cve.log
+   WARNING: libarchive-3.5.1-r0 do_cve_check: Found unpatched CVE (CVE-2021-36976), for more information check /poky/build/tmp/work/core2-64-poky-linux/libarchive/3.5.1-r0/temp/cve.log
+
+It is also possible to check the CVE status of individual packages as follows::
+
+   bitbake -c cve_check flex libarchive
+
+Note that OpenEmbedded-Core keeps a list of known unfixed CVE issues which can
+be ignore. You can pass this list to the check as follows::
+
+   bitbake -c cve_check libarchive -R conf/distro/include/cve-extra-exclusions.inc
+
+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://nvd.nist.gov/>`__.
+
+The CVE database is created by a recipe and stored in :term:`DL_DIR`.
+For example, you can look inside the database using the ``sqlite3`` command
+as follows::
+
+   sqlite3 downloads/CVE_CHECK/nvdcve_1.1.db .dump | grep CVE-2021-37462
+
 Using the Error Reporting Tool
 ==============================
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index b61de1993d..72e1c832c6 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -1471,6 +1471,17 @@ 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_PRODUCT`
+      In a recipe, defines the name used to match the recipe name
+      against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__.
+
+      This is only needed in case of a mitmatch, or if the
+      recipes matches with multiples entries in the database.
+
+      Here is an example from the Berkeley DB recipe (``db_${PV}.bb``)::
+
+         CVE_PRODUCT = "oracle_berkeley_db berkeley_db"
+
    :term:`CVSDIR`
       The directory in which files checked out under the CVS system are
       stored.
-- 
2.25.1

Re: [docs] [PATCH] manuals: initial documentation for CVE management

[Quentin Schulz]

Hi Michael,

On Fri, Jul 30, 2021 at 08:54:33PM +0200, Michael Opdenacker wrote:
> This starts to document vulnerability management
> and the use of the CVE_PRODUCT variable
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>  documentation/dev-manual/common-tasks.rst | 46 +++++++++++++++++++++++
>  documentation/ref-manual/variables.rst    | 11 ++++++
>  2 files changed, 57 insertions(+)
> 
> diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
> index 9a6f4e1a8e..aa296850f8 100644
> --- a/documentation/dev-manual/common-tasks.rst
> +++ b/documentation/dev-manual/common-tasks.rst
> @@ -10528,6 +10528,9 @@ follows:
>  1. *Identify the bug or CVE to be fixed:* This information should be
>     collected so that it can be included in your submission.
>  
> +   See :ref:`dev-manual/common-tasks:checking for vulnerabilities`
> +   for details about CVE tracking.
> +
>  2. *Check if the fix is already present in the master branch:* This will
>     result in the most straightforward path into the stable branch for the
>     fix.
> @@ -11090,6 +11093,49 @@ the license from the fetched source::
>  
>     NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
>  
> +Checking for Vulnerabilities
> +============================
> +
> +Vulnerabilities in images
> +-------------------------
> +
> +The Yocto Project has an infrastructure to track and address unfixed
> +known security vulnerabilities, as tracked by the public
> +`Common Vulnerabilities and Exposures (CVE) <https://urldefense.proofpoint.com/v2/url?u=https-3A__en.wikipedia.org_wiki_Common-5FVulnerabilities-5Fand-5FExposures&d=DwIDAg&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=hekyLAdEcYu52ifxV5ERIziCTL0mv8hKI_2zFGHfCiY&s=6SHbCNpyGeEIS-wx0ocS3IvlInldBWzG0CPei2x4xWI&e= >`__
> +database.
> +
> +To know which packages are vulnerable to known security vulnerabilities,
> +add the following setting to your configuration::
> +
> +   INHERIT += "cve-check"
> +
> +This way, at build time, BitBake will warn you about known CVEs
> +as in the example below::
> +
> +   WARNING: flex-2.6.4-r0 do_cve_check: Found unpatched CVE (CVE-2019-6293), for more information check /poky/build/tmp/work/core2-64-poky-linux/flex/2.6.4-r0/temp/cve.log
> +   WARNING: libarchive-3.5.1-r0 do_cve_check: Found unpatched CVE (CVE-2021-36976), for more information check /poky/build/tmp/work/core2-64-poky-linux/libarchive/3.5.1-r0/temp/cve.log
> +
> +It is also possible to check the CVE status of individual packages as follows::
> +
> +   bitbake -c cve_check flex libarchive
> +
> +Note that OpenEmbedded-Core keeps a list of known unfixed CVE issues which can
> +be ignore. You can pass this list to the check as follows::
> +

s/ignore/ignored/

> +   bitbake -c cve_check libarchive -R conf/distro/include/cve-extra-exclusions.inc
> +
> +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=hekyLAdEcYu52ifxV5ERIziCTL0mv8hKI_2zFGHfCiY&s=2VyieDwk2kXSn66jsySlUL_eB6CvuUWR-yRh-DMaIv0&e= >`__.
> +
> +The CVE database is created by a recipe and stored in :term:`DL_DIR`.

A bit unclear to me the "created by a recipe" part. I'm not sure it is
important information?

> +For example, you can look inside the database using the ``sqlite3`` command
> +as follows::
> +
> +   sqlite3 downloads/CVE_CHECK/nvdcve_1.1.db .dump | grep CVE-2021-37462
> +

What about:

The CVE database is stored in :term:`DL_DIR` and can be inspected using
``sqlite3`` command as follows:

[...]

?

If the "created by a recipe" part is important maybe it needs to be a
bit more explicit what it means?

>  Using the Error Reporting Tool
>  ==============================
>  
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index b61de1993d..72e1c832c6 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -1471,6 +1471,17 @@ 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_PRODUCT`
> +      In a recipe, 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=hekyLAdEcYu52ifxV5ERIziCTL0mv8hKI_2zFGHfCiY&s=2VyieDwk2kXSn66jsySlUL_eB6CvuUWR-yRh-DMaIv0&e= >`__.
> +
> +      This is only needed in case of a mitmatch, or if the

s/mitmatch/mismatch/

Technically, it is needed by all recipes, it's just that the default is
${BPN}.

I'd rather say that "
The default is ${:term:`BPN`}. If it does not match the name in NIST CVE
database or matches with multiple entries in the database, the default
value needs to be changed.
"

What do you think?

> +      recipes matches with multiples entries in the database.
> +

s/recipes/recipe name/

> +      Here is an example from the Berkeley DB recipe (``db_${PV}.bb``)::
> +

``db_${PV}.bb`` is an invalid name for a recipe name I think, can we
just give it the current version (and eventually says from which release
it is?). Or maybe we can just not give the full recipe name but just
that it's named db and link to its page on the layer index:
https://layers.openembedded.org/layerindex/recipe/544/ so that it's
always up-to-date?

Thanks,
Quentin

Re: [docs] [PATCH] manuals: initial documentation for CVE management

[Michael Opdenacker]

Hi Quentin,

Many thanks for reviewing my patch and for all your contributions to
YP's documentation!

On 8/2/21 11:36 AM, Quentin Schulz wrote:
> s/ignore/ignored/


Oops, fixed, thanks.

>
>> +   bitbake -c cve_check libarchive -R conf/distro/include/cve-extra-exclusions.inc
>> +
>> +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=hekyLAdEcYu52ifxV5ERIziCTL0mv8hKI_2zFGHfCiY&s=2VyieDwk2kXSn66jsySlUL_eB6CvuUWR-yRh-DMaIv0&e= >`__.
>> +
>> +The CVE database is created by a recipe and stored in :term:`DL_DIR`.
> A bit unclear to me the "created by a recipe" part. I'm not sure it is
> important information?
>
>> +For example, you can look inside the database using the ``sqlite3`` command
>> +as follows::
>> +
>> +   sqlite3 downloads/CVE_CHECK/nvdcve_1.1.db .dump | grep CVE-2021-37462
>> +
> What about:
>
> The CVE database is stored in :term:`DL_DIR` and can be inspected using
> ``sqlite3`` command as follows:
>
> [...]
>
> ?

This sounds good to me. The initial text was written by Richard and I
admit I didn't pay enough attention to this detail. Richard, would this
be OK?
>
> If the "created by a recipe" part is important maybe it needs to be a
> bit more explicit what it means?

Yes, in this case, it would be good to know which recipe we are
referring to.
>
>>  Using the Error Reporting Tool
>>  ==============================
>>  
>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>> index b61de1993d..72e1c832c6 100644
>> --- a/documentation/ref-manual/variables.rst
>> +++ b/documentation/ref-manual/variables.rst
>> @@ -1471,6 +1471,17 @@ 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_PRODUCT`
>> +      In a recipe, 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=hekyLAdEcYu52ifxV5ERIziCTL0mv8hKI_2zFGHfCiY&s=2VyieDwk2kXSn66jsySlUL_eB6CvuUWR-yRh-DMaIv0&e= >`__.
>> +
>> +      This is only needed in case of a mitmatch, or if the
> s/mitmatch/mismatch/
>
> Technically, it is needed by all recipes, it's just that the default is
> ${BPN}.
>
> I'd rather say that "
> The default is ${:term:`BPN`}. If it does not match the name in NIST CVE
> database or matches with multiple entries in the database, the default
> value needs to be changed.
> "
>
> What do you think?

It sounds better than my original text. Adopted, thanks!

>> +      Here is an example from the Berkeley DB recipe (``db_${PV}.bb``)::
>> +
> ``db_${PV}.bb`` is an invalid name for a recipe name I think, can we
> just give it the current version (and eventually says from which release
> it is?). Or maybe we can just not give the full recipe name but just
> that it's named db and link to its page on the layer index:
> https://layers.openembedded.org/layerindex/recipe/544/ so that it's
> always up-to-date?


I like this idea, and I'll remember this way of referring to recipes.
Adopted too. I'll send a V2 very soon.

Many thanks,
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] manuals: initial documentation for CVE management

[Richard Purdie]

On Mon, 2021-08-02 at 16:49 +0200, Michael Opdenacker wrote:
> > What about:
> > 
> > The CVE database is stored in :term:`DL_DIR` and can be inspected using
> > ``sqlite3`` command as follows:
> > 
> > [...]
> > 
> > ?
> 
> This sounds good to me. The initial text was written by Richard and I
> admit I didn't pay enough attention to this detail. Richard, would this
> be OK?
> > 

Yes, I was just dumping data into the bug whilst I had the context in my
mind/terminal :)

Cheers,

Richard

Re: [docs] [PATCH] manuals: initial documentation for CVE management

[Michael Opdenacker]

Greetings,

On 7/30/21 8:54 PM, Michael Opdenacker wrote:
> This starts to document vulnerability management
> and the use of the CVE_PRODUCT variable
>
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>  documentation/dev-manual/common-tasks.rst | 46 +++++++++++++++++++++++
>  documentation/ref-manual/variables.rst    | 11 ++++++
>  2 files changed, 57 insertions(+)

In addition to your reviews of this particular text, I'm also interested
in further guidelines for managing CVEs in production projects.

I already asked such questions in
https://bugzilla.yoctoproject.org/show_bug.cgi?id=14419:

  * How to check for vulnerabilities in my image without regenerating
    it, and without runing "bitbake -c cve_check" on individual package
    names?
  * How to check production images for vulnerability checks? Anything
    better than manual or cronjob checks?

Thank you in advance for your advise for our readers!
Cheers,
Michael

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com