Skip to contentSkip to conversation

manuals: further documentation for cve-check

PATCH Superseded Michael Opdenacker 3 participants 6 messages Aug 6, 2021 – Aug 9, 2021 1 message not in the archive

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 manuals: further documentation for cve-check

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.

---
 documentation/dev-manual/common-tasks.rst | 67 +++++++++++++++++++++++
 documentation/ref-manual/variables.rst    | 13 ++++-
 2 files changed, 79 insertions(+), 1 deletion(-)
documentation/dev-manual/common-tasks.rst +67 -0
index 7fa0df4d39..a7eb4642de 100644
@@ -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://nvd.nist.gov/>`__.
 
+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://www.ffmpeg.org/releases/${BP}.tar.xz \
+              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
+way is to use a patch file name that matches the below pattern::
+
+   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.
+
+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
+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::
 
documentation/ref-manual/variables.rst +12 -1
index 1150940133..cc7be01fc5 100644
@@ -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.
+
+   :term:`CVE_CHECK_WHITELIST`
+      The list of vulnerability 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_WHITELIST += "CVE-2020-15523"
+
    :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/>`__.
 
-      The default is ${:term:`BPN`}. If it does not match the name in NIST CVE
+      The default is ${:term:`BPN`}. If it does not match the name in the NIST CVE
       database or matches with multiple entries in the database, the default
       value needs to be changed.
 
Signature · 1 line
2.25.1
#1 lore raw

Hi Michael,

Quoted 25 lines · Michael Opdenacker

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.

---
 documentation/dev-manual/common-tasks.rst | 67 +++++++++++++++++++++++
 documentation/ref-manual/variables.rst    | 13 ++++-
 2 files changed, 79 insertions(+), 1 deletion(-)
documentation/dev-manual/common-tasks.rst +6 -0
index 7fa0df4d39..a7eb4642de 100644
@@ -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>`::
+

documentation/dev-manual/common-tasks.rst Enabling vulnerabily tracking in recipes · line 11149

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

documentation/dev-manual/common-tasks.rst Enabling vulnerabily tracking in recipes · line 11151

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

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

documentation/dev-manual/common-tasks.rst Enabling vulnerabily tracking in recipes · line 11178

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

documentation/dev-manual/common-tasks.rst Enabling vulnerabily tracking in recipes · line 11185

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

Quoted 23 lines
documentation/dev-manual/common-tasks.rst +15 -0
+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::
 
documentation/ref-manual/variables.rst +0 -0
index 1150940133..cc7be01fc5 100644

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

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

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

Quoted 2 lines
documentation/ref-manual/variables.rst +2 -0
+   :term:`CVE_CHECK_WHITELIST`
+      The list of vulnerability CVE IDs which are ignored. Here is

Ditto.

Thanks for the patch :)
Quentin

#2 lore raw

Hi Quentin

Thank you once again for the quick (and thorough!) review!

Quoted 4 lines · Quentin Schulz

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>/ ?

Very good idea, and it wouldn't cost too much. I'll do it (good catch by the way).

Quoted 5 lines

Review

Quoted 3 lines
(quoted diff) +2 -0
+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 :)

Good idea!

$ git grep "filename" |wc -l
56
git grep "file name" |wc -l
22

So "filename" wins. That's an even stronger win for the plural variant. I'll update.

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

documentation/dev-manual/common-tasks.rst Enabling vulnerabily tracking in recipes · line 11178

Quoted 7 lines
documentation/dev-manual/common-tasks.rst +7 -0
+variables.
+
+Implementation details
+----------------------
+
+Here's what ``cve-check.bbclass`` does to find unpatched CVE IDs.
+

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

Sure.

Quoted 9 lines

documentation/dev-manual/common-tasks.rst Enabling vulnerabily tracking in recipes · line 11185

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

Pfooh, it seems that both are valid buth "all the CVE IDs" is perhaps a bit too long for "shifting" to be the preferred solution. See
https://en.wikipedia.org/wiki/English_phrasal_verbs#Shifting (nice reading by the way, at least the first sections that I read).

Actually, the hyphen is bad, so I'll write:

"looks up all the CVE IDs"

Quoted 6 lines

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

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

Oh yes, agreed!

Quoted 6 lines

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

Quoted 3 lines
documentation/ref-manual/variables.rst +2 -0
+   :term:`CVE_CHECK_WHITELIST`
+      The list of vulnerability CVE IDs which are ignored. Here is

Ditto.

Thanks for the patch :)

Thanks again for the review.
Cheers,
Michael

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

A message that is not in the archive (sent off-list or not yet received): [email protected]

#4 lore raw

Hello Quentin,

Preemptive nitpicking ;-)

Quoted 5 lines · Michael Opdenacker
Quoted 3 lines

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

Oh yes, agreed!

Worse, CVE is already a plural acronym. So, we should use "CVE" instead of "CVEs", otherwise we're making a multi-plural! I'm sure you would have ended up noticing this.

Fortunately, not all readers are like you, but those are the best ones :-P Cheers,
Michael.

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

-----Original Message-----
From: [email protected] <[email protected]> On Behalf Of Michael Opdenacker
Sent: den 6 augusti 2021 16:59
To: Quentin Schulz <[email protected]>
Cc: [email protected]
Subject: Re: [docs] [PATCH] manuals: further documentation for cve-check

Quoted 8 lines

Hello Quentin,

Preemptive nitpicking ;-)

Quoted 3 lines · Michael Opdenacker
Quoted 3 lines

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

Not much different from using, e.g., "a CD disc". ;)

Quoted 5 lines
Quoted 1 line

Oh yes, agreed!

Worse, CVE is already a plural acronym. So, we should use "CVE" instead of "CVEs", otherwise we're making a multi-plural! I'm sure you would have ended up noticing this.

That doesn't make sense. I would argue that "a CVE" is singular and refers to one entry in the CVE database, regardless of what the acronym actually stands for. Thus "bugs and CVEs" make sense, while "bugs and CVE" does not.

Quoted 3 lines

Fortunately, not all readers are like you, but those are the best ones :-P Cheers,
Michael.

//Peter

#6 lore raw

Hi Peter,

Thank you for your review and feedback.

Quoted 7 lines · Peter Kjellerstedt
Quoted 4 lines

Worse, CVE is already a plural acronym. So, we should use "CVE" instead of "CVEs", otherwise we're making a multi-plural! I'm sure you would have ended up noticing this.

That doesn't make sense. I would argue that "a CVE" is singular and refers to one entry in the CVE database, regardless of what the acronym actually stands for. Thus "bugs and CVEs" make sense, while "bugs and CVE" does not.

You have a point, and this is consistent with the CVE warning messages issued by the cve-check class.
I fixed this in "master-next", actually before Richard merged it into master.

Thanks again,
Cheers,
Michael.

Signature · 3 lines
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com