Skip to contentSkip to conversation

manuals: initial documentation for CVE management

PATCH Superseded Michael Opdenacker 3 participants 4 messages Jul 30, 2021 – Aug 2, 2021

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 manuals: initial documentation for CVE management

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

---
 documentation/dev-manual/common-tasks.rst | 46 +++++++++++++++++++++++
 documentation/ref-manual/variables.rst    | 11 ++++++
 2 files changed, 57 insertions(+)
documentation/dev-manual/common-tasks.rst +46 -0
index 9a6f4e1a8e..aa296850f8 100644
@@ -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
 ==============================
 
documentation/ref-manual/variables.rst +11 -0
index b61de1993d..72e1c832c6 100644
@@ -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.
Signature · 1 line
2.25.1
#1 lore raw

Hi Michael,

Quoted 46 lines · Michael Opdenacker

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

---
 documentation/dev-manual/common-tasks.rst | 46 +++++++++++++++++++++++
 documentation/ref-manual/variables.rst    | 11 ++++++
 2 files changed, 57 insertions(+)
documentation/dev-manual/common-tasks.rst +22 -0
index 9a6f4e1a8e..aa296850f8 100644
@@ -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::
+

documentation/dev-manual/common-tasks.rst the license from the fetched source:: · line 11124

Quoted 10 lines
documentation/dev-manual/common-tasks.rst +10 -0
+   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/

documentation/dev-manual/common-tasks.rst the license from the fetched source:: · line 11133

Quoted 9 lines
documentation/dev-manual/common-tasks.rst +9 -0
+   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?

documentation/dev-manual/common-tasks.rst the license from the fetched source:: · line 11138

Quoted 5 lines
documentation/dev-manual/common-tasks.rst +5 -0
+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?

Quoted 8 lines
documentation/dev-manual/common-tasks.rst +0 -0
 Using the Error Reporting Tool
 ==============================
 
documentation/ref-manual/variables.rst +0 -0
index b61de1993d..72e1c832c6 100644

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 1478

Quoted 8 lines
documentation/ref-manual/variables.rst +5 -0
@@ -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?

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 1480

Quoted 2 lines
documentation/ref-manual/variables.rst +2 -0
+      recipes matches with multiples entries in the database.
+

s/recipes/recipe name/

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 1482

Quoted 2 lines
documentation/ref-manual/variables.rst +2 -0
+      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

#2 lore raw

Hi Quentin,

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

Quoted 1 line · Quentin Schulz

s/ignore/ignored/

Oops, fixed, thanks.

Quoted 20 lines

documentation/dev-manual/common-tasks.rst the license from the fetched source:: · line 11133

Quoted 10 lines
documentation/dev-manual/common-tasks.rst +9 -0
+   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?

documentation/dev-manual/common-tasks.rst the license from the fetched source:: · line 11138

Quoted 5 lines
documentation/dev-manual/common-tasks.rst +5 -0
+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:

Quoted 6 lines

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?

Quoted 3 lines

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.

Quoted 22 lines
Quoted 9 lines

Using the Error Reporting Tool
==============================

documentation/ref-manual/variables.rst +0 -0
index b61de1993d..72e1c832c6 100644

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 1478

Quoted 8 lines
documentation/ref-manual/variables.rst +5 -0
@@ -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}.

Quoted 7 lines

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!

Quoted 8 lines

documentation/ref-manual/variables.rst system and gives an overview of their function and contents. · line 1480

Quoted 2 lines
documentation/ref-manual/variables.rst +2 -0
+      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.

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
#3 lore raw
Quoted 5 lines · Michael Opdenacker
Quoted 5 lines

What about:

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

Quoted 8 lines
Quoted 3 lines

[...]

?

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?

Quoted 1 line

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

Cheers,

Richard