summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorMikko Rapeli <mikko.rapeli@linaro.org>2022-10-26 16:12:07 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2022-10-28 15:48:03 +0100
commite12050dcadde33073dc0af4f0d8432cc80f36e38 (patch)
tree3ac77cf548466e7cab526d78e060fb2b9c0701bd /documentation
parentaa5fd56b9abf9b5ab8deaf65be6e5127fb0368da (diff)
downloadpoky-e12050dcadde33073dc0af4f0d8432cc80f36e38.tar.gz
dev-manual: common-tasks.rst: refactor and improve "Checking for Vulnerabilities" section
Add sub section to how Poky and OE-Core handle CVE security issues. This is a generic intro chapter. Also add note that this is a process which needs quite a bit of review and iteration to keep products and SW stack secure, a process not a product. Then change "Vulnerabilites in images" chapter to "Vulnerability check at build time" since the process applies to anything compiled with bitbake, not just images. Explain details of how to work with cve-check.bbclass, especially the states Patched, Unpatched and Ignored in the generated reports. Rename recipe chapter to "Fixing CVE product name and version mappings" since CVE check has some default which works for all recipes but generated reports may be completely broken. Fixes are then done with CVE_PRODUCT and CVE_VERSION. Give some hints how to analyze "Unpatched" CVEs by checking what happens in other Linux distros etc. (From yocto-docs rev: 77a9c1a9fe651bf11f1d5a723b0741dd1764b2c8) Signed-off-by: Mikko Rapeli <mikko.rapeli@linaro.org> Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/dev-manual/common-tasks.rst186
1 files changed, 140 insertions, 46 deletions
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst
index d435bc8a4c..25d7edbc29 100644
--- a/documentation/dev-manual/common-tasks.rst
+++ b/documentation/dev-manual/common-tasks.rst
@@ -11502,8 +11502,8 @@ the license from the fetched source::
11502Checking for Vulnerabilities 11502Checking for Vulnerabilities
11503============================ 11503============================
11504 11504
11505Vulnerabilities in images 11505Vulnerabilities in Poky and OE-Core
11506------------------------- 11506-----------------------------------
11507 11507
11508The Yocto Project has an infrastructure to track and address unfixed 11508The Yocto Project has an infrastructure to track and address unfixed
11509known security vulnerabilities, as tracked by the public 11509known security vulnerabilities, as tracked by the public
@@ -11516,14 +11516,78 @@ for packages in Poky and OE-Core, tracking the evolution of the number of
11516unpatched CVEs and the status of patches. Such information is available for 11516unpatched CVEs and the status of patches. Such information is available for
11517the current development version and for each supported release. 11517the current development version and for each supported release.
11518 11518
11519To know which packages are vulnerable to known security vulnerabilities 11519Security is a process, not a product, and thus at any time, a number of security
11520in the specific image you are building, add the following setting to your 11520issues may be impacting Poky and OE-Core. It is up to the maintainers, users,
11521configuration:: 11521contributors and anyone interested in the issues to investigate and possibly fix them by
11522updating software components to newer versions or by applying patches to address them.
11523It is recommended to work with Poky and OE-Core upstream maintainers and submit
11524patches to fix them, see ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" for details.
11525
11526Vulnerability check at build time
11527---------------------------------
11528
11529To enable a check for CVE security vulnerabilities using :ref:`cve-check <ref-classes-cve-check>` in the specific image
11530or target you are building, add the following setting to your configuration::
11522 11531
11523 INHERIT += "cve-check" 11532 INHERIT += "cve-check"
11524 11533
11525This way, at build time, BitBake will warn you about known CVEs 11534The CVE database contains some old incomplete entries which have been
11526as in the example below:: 11535deemed not to impact Poky or OE-Core. These CVE entries can be excluded from the
11536check using build configuration::
11537
11538 include conf/distro/include/cve-extra-exclusions.inc
11539
11540With this CVE check enabled, BitBake build will try to map each compiled software component
11541recipe name and version information to the CVE database and generate recipe and
11542image specific reports. These reports will contain:
11543
11544- metadata about the software component like names and versions
11545
11546- metadata about the CVE issue such as description and NVD link
11547
11548- for each software component, a list of CVEs which are possibly impacting this version
11549
11550- status of each CVE: ``Patched``, ``Unpatched`` or ``Ignored``
11551
11552The status ``Patched`` means that a patch file to address the security issue has been
11553applied. ``Unpatched`` status means that no patches to address the issue have been
11554applied and that the issue needs to be investigated. ``Ignored`` means that after
11555analysis, it has been deemed to ignore the issue as it for example affects
11556the software component on a different operating system platform.
11557
11558After build with CVE check enabled, reports for each compiled source recipe will be
11559found in ``build/tmp/deploy/cve``.
11560
11561For example the CVE check report for the ``flex-native`` recipe looks like::
11562
11563 $ cat poky/build/tmp/deploy/cve/flex-native
11564 LAYER: meta
11565 PACKAGE NAME: flex-native
11566 PACKAGE VERSION: 2.6.4
11567 CVE: CVE-2016-6354
11568 CVE STATUS: Patched
11569 CVE SUMMARY: Heap-based buffer overflow in the yy_get_next_buffer function in Flex before 2.6.1 might allow context-dependent attackers to cause a denial of service or possibly execute arbitrary code via vectors involving num_to_read.
11570 CVSS v2 BASE SCORE: 7.5
11571 CVSS v3 BASE SCORE: 9.8
11572 VECTOR: NETWORK
11573 MORE INFORMATION: https://nvd.nist.gov/vuln/detail/CVE-2016-6354
11574
11575 LAYER: meta
11576 PACKAGE NAME: flex-native
11577 PACKAGE VERSION: 2.6.4
11578 CVE: CVE-2019-6293
11579 CVE STATUS: Ignored
11580 CVE SUMMARY: An issue was discovered in the function mark_beginning_as_normal in nfa.c in flex 2.6.4. There is a stack exhaustion problem caused by the mark_beginning_as_normal function making recursive calls to itself in certain scenarios involving lots of '*' characters. Remote attackers could leverage this vulnerability to cause a denial-of-service.
11581 CVSS v2 BASE SCORE: 4.3
11582 CVSS v3 BASE SCORE: 5.5
11583 VECTOR: NETWORK
11584 MORE INFORMATION: https://nvd.nist.gov/vuln/detail/CVE-2019-6293
11585
11586For images, a summary of all recipes included in the image and their CVEs is also
11587generated in textual and JSON formats. These ``.cve`` and ``.json`` reports can be found
11588in the ``tmp/deploy/images`` directory for each compiled image.
11589
11590At build time CVE check will also throw warnings about ``Unpatched`` CVEs::
11527 11591
11528 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 11592 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
11529 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 11593 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
@@ -11532,21 +11596,46 @@ It is also possible to check the CVE status of individual packages as follows::
11532 11596
11533 bitbake -c cve_check flex libarchive 11597 bitbake -c cve_check flex libarchive
11534 11598
11535Note that OpenEmbedded-Core keeps a list of known unfixed CVE issues which can 11599Fixing CVE product name and version mappings
11536be ignored. You can pass this list to the check as follows:: 11600--------------------------------------------
11537 11601
11538 bitbake -c cve_check libarchive -R conf/distro/include/cve-extra-exclusions.inc 11602By default, :ref:`cve-check <ref-classes-cve-check>` uses the recipe name :term:`BPN` as CVE
11603product name when querying the CVE database. If this mapping contains false positives, e.g.
11604some reported CVEs are not for the software component in question, or false negatives like
11605some CVEs are not found to impact the recipe when they should, then the problems can be
11606in the recipe name to CVE product mapping. These mapping issues can be fixed by setting
11607the :term:`CVE_PRODUCT` variable inside the recipe. This defines the name of software component in the
11608upstream `NIST CVE database <https://nvd.nist.gov/>`__.
11539 11609
11540Enabling vulnerabily tracking in recipes 11610The variable supports using vendor and product names like this::
11541----------------------------------------
11542 11611
11543The :term:`CVE_PRODUCT` variable defines the name used to match the recipe name 11612 CVE_PRODUCT = "flex_project:flex"
11544against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__.
11545 11613
11546Editing recipes to fix vulnerabilities 11614In this example from the vendor name used in CVE database is ``flex_project`` and
11547-------------------------------------- 11615product is ``flex``. With this setting the ``flex`` recipe only maps to this specific
11616product and not products from other vendors with same name ``flex``.
11617
11618Similary, when the recipe version :term:`PV` is not compatible with software versions used by
11619the upstream software component releases and the CVE database, these can be fixed using
11620:term:`CVE_VERSION` variable.
11621
11622Note that if the CVE entries in NVD databse contain bugs or have missing or incomplete
11623information, it is recommended to fix the information there directly instead of working
11624around the issues for a possibly long time in Poky and OE-Core side recipes. Feedback to
11625NVD about CVEs entries can be provided through the `NVD contact form <https://nvd.nist.gov/info/contact-form>`__.
11626
11627Fixing vulnerabilities in recipes
11628---------------------------------
11629
11630If a CVE security issue impacts a software component, it can be fixed by updating to a newer
11631version of the software component or by applying a patch. For Poky and OE-Core master branches, updating
11632to newer software component release with fixes is the best option, but patches can be applied
11633if releases are not yet available.
11634
11635For stable branches, it is preferred to apply patches for the issues. For some software
11636components minor version updates can also applied if they are backwards compatible.
11548 11637
11549To fix a given known vulnerability, you need to add a patch file to your recipe. Here's 11638Here is an example of fixing CVE security issues with patch files,
11550an example from the :oe_layerindex:`ffmpeg recipe</layerindex/recipe/47350>`:: 11639an example from the :oe_layerindex:`ffmpeg recipe</layerindex/recipe/47350>`::
11551 11640
11552 SRC_URI = "https://www.ffmpeg.org/releases/${BP}.tar.xz \ 11641 SRC_URI = "https://www.ffmpeg.org/releases/${BP}.tar.xz \
@@ -11558,31 +11647,21 @@ an example from the :oe_layerindex:`ffmpeg recipe</layerindex/recipe/47350>`::
11558 file://fix-CVE-2020-22033-CVE-2020-22019.patch \ 11647 file://fix-CVE-2020-22033-CVE-2020-22019.patch \
11559 file://fix-CVE-2021-33815.patch \ 11648 file://fix-CVE-2021-33815.patch \
11560 11649
11561The :ref:`cve-check <ref-classes-cve-check>` class defines two ways of 11650A good practice is to include the CVE identifier in both patch file name
11562supplying a patch for a given CVE. The first 11651and inside the patch file commit message use the format::
11563way is to use a patch filename that matches the below pattern::
11564 11652
11565 cve_file_name_match = re.compile(".*([Cc][Vv][Ee]\-\d{4}\-\d+)") 11653 CVE: CVE-2020-22033
11566 11654
11567As shown in the example above, multiple CVE IDs can appear in a patch filename, 11655CVE checker will then capture this information and change the CVE status to ``Patched``
11568but the :ref:`cve-check <ref-classes-cve-check>` class will only consider 11656in the generated reports.
11569the last CVE ID in the filename as patched.
11570 11657
11571The second way to recognize a patched CVE ID is when a line matching the 11658If analysis shows that the CVE issue does not impact the recipe due to configuration, platform,
11572below pattern is found in any patch file provided by the recipe:: 11659version or other reasons, the CVE can be marked as ``Ignored`` using :term:`CVE_CHECK_IGNORE` variable.
11660As mentioned previously, if data in the CVE database is wrong, it is recommend to fix those
11661issues in the CVE database directly.
11573 11662
11574 cve_match = re.compile("CVE:( CVE\-\d{4}\-\d+)+") 11663Recipes can be completely skipped by CVE check by including the recipe name in
11575 11664the :term:`CVE_CHECK_SKIP_RECIPE` variable.
11576This allows a single patch file to address multiple CVE IDs at the same time.
11577
11578Of course, another way to fix vulnerabilities is to upgrade to a version
11579of the package which is not impacted, typically a more recent one.
11580The NIST database knows which versions are vulnerable and which ones
11581are not.
11582
11583Last but not least, you can choose to ignore vulnerabilities through
11584the :term:`CVE_CHECK_SKIP_RECIPE` and :term:`CVE_CHECK_IGNORE`
11585variables.
11586 11665
11587Implementation details 11666Implementation details
11588---------------------- 11667----------------------
@@ -11599,24 +11678,39 @@ file. The found CVE IDs are also considered as patched.
11599Then, the code looks up all the CVE IDs in the NIST database for all the 11678Then, the code looks up all the CVE IDs in the NIST database for all the
11600products defined in :term:`CVE_PRODUCT`. Then, for each found CVE: 11679products defined in :term:`CVE_PRODUCT`. Then, for each found CVE:
11601 11680
11602 - If the package name (:term:`PN`) is part of 11681- If the package name (:term:`PN`) is part of
11603 :term:`CVE_CHECK_SKIP_RECIPE`, it is considered as patched. 11682 :term:`CVE_CHECK_SKIP_RECIPE`, it is considered as ``Patched``.
11604 11683
11605 - If the CVE ID is part of :term:`CVE_CHECK_IGNORE`, it is 11684- If the CVE ID is part of :term:`CVE_CHECK_IGNORE`, it is
11606 considered as patched too. 11685 set as ``Ignored``.
11607 11686
11608 - If the CVE ID is part of the patched CVE for the recipe, it is 11687- If the CVE ID is part of the patched CVE for the recipe, it is
11609 already considered as patched. 11688 already considered as ``Patched``.
11610 11689
11611 - Otherwise, the code checks whether the recipe version (:term:`PV`) 11690- Otherwise, the code checks whether the recipe version (:term:`PV`)
11612 is within the range of versions impacted by the CVE. If so, the CVE 11691 is within the range of versions impacted by the CVE. If so, the CVE
11613 is considered as unpatched. 11692 is considered as ``Unpatched``.
11614 11693
11615The CVE database is stored in :term:`DL_DIR` and can be inspected using 11694The CVE database is stored in :term:`DL_DIR` and can be inspected using
11616``sqlite3`` command as follows:: 11695``sqlite3`` command as follows::
11617 11696
11618 sqlite3 downloads/CVE_CHECK/nvdcve_1.1.db .dump | grep CVE-2021-37462 11697 sqlite3 downloads/CVE_CHECK/nvdcve_1.1.db .dump | grep CVE-2021-37462
11619 11698
11699When analyzing CVEs, it is recommended to:
11700
11701- study the latest information in `CVE database <https://nvd.nist.gov/vuln/search>`__.
11702
11703- check how upstream developers of the software component addressed the issue, e.g.
11704 what patch was applied, which upstream release contains the fix.
11705
11706- check what other Linux distributions like `Debian <https://security-tracker.debian.org/tracker/>`__
11707 did to analyze and address the issue.
11708
11709- follow security notices from other Linux distributions.
11710
11711- follow public `open source security mailing lists <https://oss-security.openwall.org/wiki/mailing-lists>`__ for
11712 discussions and advance notifications of CVE bugs and software releases with fixes.
11713
11620Using the Error Reporting Tool 11714Using the Error Reporting Tool
11621============================== 11715==============================
11622 11716