diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2022-11-24 19:04:56 +0100 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2022-11-29 10:52:16 +0000 |
commit | 22530208422d1a5d0c6790d0f02c78f6e7052ce0 (patch) | |
tree | c236a1eb8d603a00965dfe7153e33b8ff0b44f54 /documentation | |
parent | 658a991de2e9bbec711d3761706bcda88b27751c (diff) | |
download | poky-22530208422d1a5d0c6790d0f02c78f6e7052ce0.tar.gz |
backport SPDX documentation and vulnerability improvements
(From yocto-docs rev: c87d0388caba56490c32e27911b10c926ca02ea9)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/conf.py | 1 | ||||
-rw-r--r-- | documentation/dev-manual/common-tasks.rst | 289 | ||||
-rw-r--r-- | documentation/ref-manual/terms.rst | 28 | ||||
-rw-r--r-- | documentation/ref-manual/variables.rst | 94 |
4 files changed, 330 insertions, 82 deletions
diff --git a/documentation/conf.py b/documentation/conf.py index 07a15ce7de..bd45a73fa6 100644 --- a/documentation/conf.py +++ b/documentation/conf.py | |||
@@ -106,6 +106,7 @@ extlinks = { | |||
106 | 'oe_wiki': ('https://www.openembedded.org/wiki%s', None), | 106 | 'oe_wiki': ('https://www.openembedded.org/wiki%s', None), |
107 | 'oe_layerindex': ('https://layers.openembedded.org%s', None), | 107 | 'oe_layerindex': ('https://layers.openembedded.org%s', None), |
108 | 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None), | 108 | 'oe_layer': ('https://layers.openembedded.org/layerindex/branch/master/layer%s', None), |
109 | 'wikipedia': ('https://en.wikipedia.org/wiki/%s', None), | ||
109 | } | 110 | } |
110 | 111 | ||
111 | # Intersphinx config to use cross reference with BitBake user manual | 112 | # Intersphinx config to use cross reference with BitBake user manual |
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst index 53e7686633..f301ffc693 100644 --- a/documentation/dev-manual/common-tasks.rst +++ b/documentation/dev-manual/common-tasks.rst | |||
@@ -11229,8 +11229,6 @@ to be covered by assuming that there are three main areas of concern: | |||
11229 | - Compilation scripts and modifications to the source code must be | 11229 | - Compilation scripts and modifications to the source code must be |
11230 | provided. | 11230 | provided. |
11231 | 11231 | ||
11232 | - spdx files can be provided. | ||
11233 | |||
11234 | There are other requirements beyond the scope of these three and the | 11232 | There are other requirements beyond the scope of these three and the |
11235 | methods described in this section (e.g. the mechanism through which | 11233 | methods described in this section (e.g. the mechanism through which |
11236 | source code is distributed). | 11234 | source code is distributed). |
@@ -11422,39 +11420,6 @@ layers (recipes, configuration files, and so forth) enables you to meet | |||
11422 | your requirements to include the scripts to control compilation as well | 11420 | your requirements to include the scripts to control compilation as well |
11423 | as any modifications to the original source. | 11421 | as any modifications to the original source. |
11424 | 11422 | ||
11425 | Providing spdx files | ||
11426 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
11427 | |||
11428 | The spdx module has been integrated to a layer named meta-spdxscanner. | ||
11429 | meta-spdxscanner provides several kinds of scanner. If you want to enable | ||
11430 | this function, you have to follow the following steps: | ||
11431 | |||
11432 | 1. Add meta-spdxscanner layer into ``bblayers.conf``. | ||
11433 | |||
11434 | 2. Refer to the README in meta-spdxscanner to setup the environment (e.g, | ||
11435 | setup a fossology server) needed for the scanner. | ||
11436 | |||
11437 | 3. Meta-spdxscanner provides several methods within the bbclass to create spdx files. | ||
11438 | Please choose one that you want to use and enable the spdx task. You have to | ||
11439 | add some config options in ``local.conf`` file in your :term:`Build | ||
11440 | Directory`. Here is an example showing how to generate spdx files | ||
11441 | during BitBake using the fossology-python.bbclass:: | ||
11442 | |||
11443 | # Select fossology-python.bbclass. | ||
11444 | INHERIT += "fossology-python" | ||
11445 | # For fossology-python.bbclass, TOKEN is necessary, so, after setup a | ||
11446 | # Fossology server, you have to create a token. | ||
11447 | TOKEN = "eyJ0eXAiO..." | ||
11448 | # The fossology server is necessary for fossology-python.bbclass. | ||
11449 | FOSSOLOGY_SERVER = "http://xx.xx.xx.xx:8081/repo" | ||
11450 | # If you want to upload the source code to a special folder: | ||
11451 | FOLDER_NAME = "xxxx" //Optional | ||
11452 | # If you don't want to put spdx files in tmp/deploy/spdx, you can enable: | ||
11453 | SPDX_DEPLOY_DIR = "${DEPLOY_DIR}" //Optional | ||
11454 | |||
11455 | For more usage information refer to :yocto_git:`the meta-spdxscanner repository | ||
11456 | </meta-spdxscanner/>`. | ||
11457 | |||
11458 | Compliance Limitations with Executables Built from Static Libraries | 11423 | Compliance Limitations with Executables Built from Static Libraries |
11459 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | 11424 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
11460 | 11425 | ||
@@ -11495,12 +11460,12 @@ the license from the fetched source:: | |||
11495 | Checking for Vulnerabilities | 11460 | Checking for Vulnerabilities |
11496 | ============================ | 11461 | ============================ |
11497 | 11462 | ||
11498 | Vulnerabilities in images | 11463 | Vulnerabilities in Poky and OE-Core |
11499 | ------------------------- | 11464 | ----------------------------------- |
11500 | 11465 | ||
11501 | The Yocto Project has an infrastructure to track and address unfixed | 11466 | The Yocto Project has an infrastructure to track and address unfixed |
11502 | known security vulnerabilities, as tracked by the public | 11467 | known security vulnerabilities, as tracked by the public |
11503 | `Common Vulnerabilities and Exposures (CVE) <https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures>`__ | 11468 | :wikipedia:`Common Vulnerabilities and Exposures (CVE) <Common_Vulnerabilities_and_Exposures>` |
11504 | database. | 11469 | database. |
11505 | 11470 | ||
11506 | The Yocto Project maintains a `list of known vulnerabilities | 11471 | The Yocto Project maintains a `list of known vulnerabilities |
@@ -11509,14 +11474,78 @@ for packages in Poky and OE-Core, tracking the evolution of the number of | |||
11509 | unpatched CVEs and the status of patches. Such information is available for | 11474 | unpatched CVEs and the status of patches. Such information is available for |
11510 | the current development version and for each supported release. | 11475 | the current development version and for each supported release. |
11511 | 11476 | ||
11512 | To know which packages are vulnerable to known security vulnerabilities | 11477 | Security is a process, not a product, and thus at any time, a number of security |
11513 | in the specific image you are building, add the following setting to your | 11478 | issues may be impacting Poky and OE-Core. It is up to the maintainers, users, |
11514 | configuration:: | 11479 | contributors and anyone interested in the issues to investigate and possibly fix them by |
11480 | updating software components to newer versions or by applying patches to address them. | ||
11481 | It is recommended to work with Poky and OE-Core upstream maintainers and submit | ||
11482 | patches to fix them, see ":ref:`dev-manual/common-tasks:submitting a change to the yocto project`" for details. | ||
11483 | |||
11484 | Vulnerability check at build time | ||
11485 | --------------------------------- | ||
11486 | |||
11487 | To enable a check for CVE security vulnerabilities using :ref:`cve-check <ref-classes-cve-check>` in the specific image | ||
11488 | or target you are building, add the following setting to your configuration:: | ||
11515 | 11489 | ||
11516 | INHERIT += "cve-check" | 11490 | INHERIT += "cve-check" |
11517 | 11491 | ||
11518 | This way, at build time, BitBake will warn you about known CVEs | 11492 | The CVE database contains some old incomplete entries which have been |
11519 | as in the example below:: | 11493 | deemed not to impact Poky or OE-Core. These CVE entries can be excluded from the |
11494 | check using build configuration:: | ||
11495 | |||
11496 | include conf/distro/include/cve-extra-exclusions.inc | ||
11497 | |||
11498 | With this CVE check enabled, BitBake build will try to map each compiled software component | ||
11499 | recipe name and version information to the CVE database and generate recipe and | ||
11500 | image specific reports. These reports will contain: | ||
11501 | |||
11502 | - metadata about the software component like names and versions | ||
11503 | |||
11504 | - metadata about the CVE issue such as description and NVD link | ||
11505 | |||
11506 | - for each software component, a list of CVEs which are possibly impacting this version | ||
11507 | |||
11508 | - status of each CVE: ``Patched``, ``Unpatched`` or ``Ignored`` | ||
11509 | |||
11510 | The status ``Patched`` means that a patch file to address the security issue has been | ||
11511 | applied. ``Unpatched`` status means that no patches to address the issue have been | ||
11512 | applied and that the issue needs to be investigated. ``Ignored`` means that after | ||
11513 | analysis, it has been deemed to ignore the issue as it for example affects | ||
11514 | the software component on a different operating system platform. | ||
11515 | |||
11516 | After a build with CVE check enabled, reports for each compiled source recipe will be | ||
11517 | found in ``build/tmp/deploy/cve``. | ||
11518 | |||
11519 | For example the CVE check report for the ``flex-native`` recipe looks like:: | ||
11520 | |||
11521 | $ cat poky/build/tmp/deploy/cve/flex-native | ||
11522 | LAYER: meta | ||
11523 | PACKAGE NAME: flex-native | ||
11524 | PACKAGE VERSION: 2.6.4 | ||
11525 | CVE: CVE-2016-6354 | ||
11526 | CVE STATUS: Patched | ||
11527 | 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. | ||
11528 | CVSS v2 BASE SCORE: 7.5 | ||
11529 | CVSS v3 BASE SCORE: 9.8 | ||
11530 | VECTOR: NETWORK | ||
11531 | MORE INFORMATION: https://nvd.nist.gov/vuln/detail/CVE-2016-6354 | ||
11532 | |||
11533 | LAYER: meta | ||
11534 | PACKAGE NAME: flex-native | ||
11535 | PACKAGE VERSION: 2.6.4 | ||
11536 | CVE: CVE-2019-6293 | ||
11537 | CVE STATUS: Ignored | ||
11538 | 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. | ||
11539 | CVSS v2 BASE SCORE: 4.3 | ||
11540 | CVSS v3 BASE SCORE: 5.5 | ||
11541 | VECTOR: NETWORK | ||
11542 | MORE INFORMATION: https://nvd.nist.gov/vuln/detail/CVE-2019-6293 | ||
11543 | |||
11544 | For images, a summary of all recipes included in the image and their CVEs is also | ||
11545 | generated in textual and JSON formats. These ``.cve`` and ``.json`` reports can be found | ||
11546 | in the ``tmp/deploy/images`` directory for each compiled image. | ||
11547 | |||
11548 | At build time CVE check will also throw warnings about ``Unpatched`` CVEs:: | ||
11520 | 11549 | ||
11521 | 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 | 11550 | 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 |
11522 | 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 | 11551 | 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 |
@@ -11525,21 +11554,46 @@ It is also possible to check the CVE status of individual packages as follows:: | |||
11525 | 11554 | ||
11526 | bitbake -c cve_check flex libarchive | 11555 | bitbake -c cve_check flex libarchive |
11527 | 11556 | ||
11528 | Note that OpenEmbedded-Core keeps a list of known unfixed CVE issues which can | 11557 | Fixing CVE product name and version mappings |
11529 | be ignored. You can pass this list to the check as follows:: | 11558 | -------------------------------------------- |
11559 | |||
11560 | By default, :ref:`cve-check <ref-classes-cve-check>` uses the recipe name :term:`BPN` as CVE | ||
11561 | product name when querying the CVE database. If this mapping contains false positives, e.g. | ||
11562 | some reported CVEs are not for the software component in question, or false negatives like | ||
11563 | some CVEs are not found to impact the recipe when they should, then the problems can be | ||
11564 | in the recipe name to CVE product mapping. These mapping issues can be fixed by setting | ||
11565 | the :term:`CVE_PRODUCT` variable inside the recipe. This defines the name of the software component in the | ||
11566 | upstream `NIST CVE database <https://nvd.nist.gov/>`__. | ||
11530 | 11567 | ||
11531 | bitbake -c cve_check libarchive -R conf/distro/include/cve-extra-exclusions.inc | 11568 | The variable supports using vendor and product names like this:: |
11532 | 11569 | ||
11533 | Enabling vulnerabily tracking in recipes | 11570 | CVE_PRODUCT = "flex_project:flex" |
11534 | ---------------------------------------- | ||
11535 | 11571 | ||
11536 | The :term:`CVE_PRODUCT` variable defines the name used to match the recipe name | 11572 | In this example the vendor name used in the CVE database is ``flex_project`` and the |
11537 | against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__. | 11573 | product is ``flex``. With this setting the ``flex`` recipe only maps to this specific |
11574 | product and not products from other vendors with same name ``flex``. | ||
11538 | 11575 | ||
11539 | Editing recipes to fix vulnerabilities | 11576 | Similarly, when the recipe version :term:`PV` is not compatible with software versions used by |
11540 | -------------------------------------- | 11577 | the upstream software component releases and the CVE database, these can be fixed using |
11578 | the :term:`CVE_VERSION` variable. | ||
11579 | |||
11580 | Note that if the CVE entries in the NVD database contain bugs or have missing or incomplete | ||
11581 | information, it is recommended to fix the information there directly instead of working | ||
11582 | around the issues possibly for a long time in Poky and OE-Core side recipes. Feedback to | ||
11583 | NVD about CVE entries can be provided through the `NVD contact form <https://nvd.nist.gov/info/contact-form>`__. | ||
11584 | |||
11585 | Fixing vulnerabilities in recipes | ||
11586 | --------------------------------- | ||
11587 | |||
11588 | If a CVE security issue impacts a software component, it can be fixed by updating to a newer | ||
11589 | version of the software component or by applying a patch. For Poky and OE-Core master branches, updating | ||
11590 | to a newer software component release with fixes is the best option, but patches can be applied | ||
11591 | if releases are not yet available. | ||
11541 | 11592 | ||
11542 | To fix a given known vulnerability, you need to add a patch file to your recipe. Here's | 11593 | For stable branches, it is preferred to apply patches for the issues. For some software |
11594 | components minor version updates can also be applied if they are backwards compatible. | ||
11595 | |||
11596 | Here is an example of fixing CVE security issues with patch files, | ||
11543 | an example from the :oe_layerindex:`ffmpeg recipe</layerindex/recipe/47350>`:: | 11597 | an example from the :oe_layerindex:`ffmpeg recipe</layerindex/recipe/47350>`:: |
11544 | 11598 | ||
11545 | SRC_URI = "https://www.ffmpeg.org/releases/${BP}.tar.xz \ | 11599 | SRC_URI = "https://www.ffmpeg.org/releases/${BP}.tar.xz \ |
@@ -11551,31 +11605,21 @@ an example from the :oe_layerindex:`ffmpeg recipe</layerindex/recipe/47350>`:: | |||
11551 | file://fix-CVE-2020-22033-CVE-2020-22019.patch \ | 11605 | file://fix-CVE-2020-22033-CVE-2020-22019.patch \ |
11552 | file://fix-CVE-2021-33815.patch \ | 11606 | file://fix-CVE-2021-33815.patch \ |
11553 | 11607 | ||
11554 | The :ref:`cve-check <ref-classes-cve-check>` class defines two ways of | 11608 | A good practice is to include the CVE identifier in both the patch file name |
11555 | supplying a patch for a given CVE. The first | 11609 | and inside the patch file commit message using the format:: |
11556 | way is to use a patch filename that matches the below pattern:: | ||
11557 | |||
11558 | cve_file_name_match = re.compile(".*([Cc][Vv][Ee]\-\d{4}\-\d+)") | ||
11559 | |||
11560 | As shown in the example above, multiple CVE IDs can appear in a patch filename, | ||
11561 | but the :ref:`cve-check <ref-classes-cve-check>` class will only consider | ||
11562 | the last CVE ID in the filename as patched. | ||
11563 | |||
11564 | The second way to recognize a patched CVE ID is when a line matching the | ||
11565 | below pattern is found in any patch file provided by the recipe:: | ||
11566 | 11610 | ||
11567 | cve_match = re.compile("CVE:( CVE\-\d{4}\-\d+)+") | 11611 | CVE: CVE-2020-22033 |
11568 | 11612 | ||
11569 | This allows a single patch file to address multiple CVE IDs at the same time. | 11613 | CVE checker will then capture this information and change the CVE status to ``Patched`` |
11614 | in the generated reports. | ||
11570 | 11615 | ||
11571 | Of course, another way to fix vulnerabilities is to upgrade to a version | 11616 | If analysis shows that the CVE issue does not impact the recipe due to configuration, platform, |
11572 | of the package which is not impacted, typically a more recent one. | 11617 | version or other reasons, the CVE can be marked as ``Ignored`` using the :term:`CVE_CHECK_IGNORE` variable. |
11573 | The NIST database knows which versions are vulnerable and which ones | 11618 | As mentioned previously, if data in the CVE database is wrong, it is recommend to fix those |
11574 | are not. | 11619 | issues in the CVE database directly. |
11575 | 11620 | ||
11576 | Last but not least, you can choose to ignore vulnerabilities through | 11621 | Recipes can be completely skipped by CVE check by including the recipe name in |
11577 | the :term:`CVE_CHECK_SKIP_RECIPE` and :term:`CVE_CHECK_IGNORE` | 11622 | the :term:`CVE_CHECK_SKIP_RECIPE` variable. |
11578 | variables. | ||
11579 | 11623 | ||
11580 | Implementation details | 11624 | Implementation details |
11581 | ---------------------- | 11625 | ---------------------- |
@@ -11592,24 +11636,105 @@ file. The found CVE IDs are also considered as patched. | |||
11592 | Then, the code looks up all the CVE IDs in the NIST database for all the | 11636 | Then, the code looks up all the CVE IDs in the NIST database for all the |
11593 | products defined in :term:`CVE_PRODUCT`. Then, for each found CVE: | 11637 | products defined in :term:`CVE_PRODUCT`. Then, for each found CVE: |
11594 | 11638 | ||
11595 | - If the package name (:term:`PN`) is part of | 11639 | - If the package name (:term:`PN`) is part of |
11596 | :term:`CVE_CHECK_SKIP_RECIPE`, it is considered as patched. | 11640 | :term:`CVE_CHECK_SKIP_RECIPE`, it is considered as ``Patched``. |
11597 | 11641 | ||
11598 | - If the CVE ID is part of :term:`CVE_CHECK_IGNORE`, it is | 11642 | - If the CVE ID is part of :term:`CVE_CHECK_IGNORE`, it is |
11599 | considered as patched too. | 11643 | set as ``Ignored``. |
11600 | 11644 | ||
11601 | - If the CVE ID is part of the patched CVE for the recipe, it is | 11645 | - If the CVE ID is part of the patched CVE for the recipe, it is |
11602 | already considered as patched. | 11646 | already considered as ``Patched``. |
11603 | 11647 | ||
11604 | - Otherwise, the code checks whether the recipe version (:term:`PV`) | 11648 | - Otherwise, the code checks whether the recipe version (:term:`PV`) |
11605 | is within the range of versions impacted by the CVE. If so, the CVE | 11649 | is within the range of versions impacted by the CVE. If so, the CVE |
11606 | is considered as unpatched. | 11650 | is considered as ``Unpatched``. |
11607 | 11651 | ||
11608 | The CVE database is stored in :term:`DL_DIR` and can be inspected using | 11652 | The CVE database is stored in :term:`DL_DIR` and can be inspected using |
11609 | ``sqlite3`` command as follows:: | 11653 | ``sqlite3`` command as follows:: |
11610 | 11654 | ||
11611 | sqlite3 downloads/CVE_CHECK/nvdcve_1.1.db .dump | grep CVE-2021-37462 | 11655 | sqlite3 downloads/CVE_CHECK/nvdcve_1.1.db .dump | grep CVE-2021-37462 |
11612 | 11656 | ||
11657 | When analyzing CVEs, it is recommended to: | ||
11658 | |||
11659 | - study the latest information in `CVE database <https://nvd.nist.gov/vuln/search>`__. | ||
11660 | |||
11661 | - check how upstream developers of the software component addressed the issue, e.g. | ||
11662 | what patch was applied, which upstream release contains the fix. | ||
11663 | |||
11664 | - check what other Linux distributions like `Debian <https://security-tracker.debian.org/tracker/>`__ | ||
11665 | did to analyze and address the issue. | ||
11666 | |||
11667 | - follow security notices from other Linux distributions. | ||
11668 | |||
11669 | - follow public `open source security mailing lists <https://oss-security.openwall.org/wiki/mailing-lists>`__ for | ||
11670 | discussions and advance notifications of CVE bugs and software releases with fixes. | ||
11671 | |||
11672 | Creating a Software Bill of Materials | ||
11673 | ===================================== | ||
11674 | |||
11675 | Once you are able to build an image for your project, once the licenses for | ||
11676 | each software component are all identified (see | ||
11677 | ":ref:`dev-manual/common-tasks:working with licenses`") and once vulnerability | ||
11678 | fixes are applied (see ":ref:`dev-manual/common-tasks:checking | ||
11679 | for vulnerabilities`"), the OpenEmbedded build system can generate | ||
11680 | a description of all the components you used, their licenses, their dependencies, | ||
11681 | the changes that were applied and the known vulnerabilities that were fixed. | ||
11682 | |||
11683 | This description is generated in the form of a *Software Bill of Materials* | ||
11684 | (:term:`SBOM`), using the :term:`SPDX` standard. | ||
11685 | |||
11686 | When you release software, this is the most standard way to provide information | ||
11687 | about the Software Supply Chain of your software image and SDK. The | ||
11688 | :term:`SBOM` tooling is often used to ensure open source license compliance by | ||
11689 | providing the license texts used in the product which legal departments and end | ||
11690 | users can read in standardized format. | ||
11691 | |||
11692 | :term:`SBOM` information is also critical to performing vulnerability exposure | ||
11693 | assessments, as all the components used in the Software Supply Chain are listed. | ||
11694 | |||
11695 | The OpenEmbedded build system doesn't generate such information by default. | ||
11696 | To make this happen, you must inherit the | ||
11697 | :ref:`create-spdx <ref-classes-create-spdx>` class from a configuration file:: | ||
11698 | |||
11699 | INHERIT += "create-spdx" | ||
11700 | |||
11701 | You then get :term:`SPDX` output in JSON format as an | ||
11702 | ``IMAGE-MACHINE.spdx.json`` file in ``tmp/deploy/images/MACHINE/`` inside the | ||
11703 | :term:`Build Directory`. | ||
11704 | |||
11705 | This is a toplevel file accompanied by an ``IMAGE-MACHINE.spdx.index.json`` | ||
11706 | containing an index of JSON :term:`SPDX` files for individual recipes, together | ||
11707 | with an ``IMAGE-MACHINE.spdx.tar.zst`` compressed archive containing all such | ||
11708 | files. | ||
11709 | |||
11710 | The :ref:`create-spdx <ref-classes-create-spdx>` class offers options to include | ||
11711 | more information in the output :term:`SPDX` data, such as making the generated | ||
11712 | files more human readable (:term:`SPDX_PRETTY`), adding compressed archives of | ||
11713 | the files in the generated target packages (:term:`SPDX_ARCHIVE_PACKAGED`), | ||
11714 | adding a description of the source files handled by the target recipes | ||
11715 | (:term:`SPDX_INCLUDE_SOURCES`) and adding archives of these source files | ||
11716 | themselves (:term:`SPDX_ARCHIVE_SOURCES`). | ||
11717 | |||
11718 | Though the toplevel :term:`SPDX` output is available in | ||
11719 | ``tmp/deploy/images/MACHINE/`` inside the :term:`Build Directory`, ancillary | ||
11720 | generated files are available in ``tmp/deploy/spdx/MACHINE`` too, such as: | ||
11721 | |||
11722 | - The individual :term:`SPDX` JSON files in the ``IMAGE-MACHINE.spdx.tar.zst`` | ||
11723 | archive. | ||
11724 | |||
11725 | - Compressed archives of the files in the generated target packages, | ||
11726 | in ``packages/packagename.tar.zst`` (when :term:`SPDX_ARCHIVE_PACKAGED` | ||
11727 | is set). | ||
11728 | |||
11729 | - Compressed archives of the source files used to build the host tools | ||
11730 | and the target packages in ``recipes/recipe-packagename.tar.zst`` | ||
11731 | (when :term:`SPDX_ARCHIVE_SOURCES` is set). Those are needed to fulfill | ||
11732 | "source code access" license requirements. | ||
11733 | |||
11734 | See the `tools page <https://spdx.dev/resources/tools/>`__ on the :term:`SPDX` | ||
11735 | project website for a list of tools to consume and transform the :term:`SPDX` | ||
11736 | data generated by the OpenEmbedded build system. | ||
11737 | |||
11613 | Using the Error Reporting Tool | 11738 | Using the Error Reporting Tool |
11614 | ============================== | 11739 | ============================== |
11615 | 11740 | ||
diff --git a/documentation/ref-manual/terms.rst b/documentation/ref-manual/terms.rst index 1e3f718a8f..7e5295a646 100644 --- a/documentation/ref-manual/terms.rst +++ b/documentation/ref-manual/terms.rst | |||
@@ -323,6 +323,23 @@ universal, the list includes them just in case: | |||
323 | :term:`build host<Build Host>` and other components, that can | 323 | :term:`build host<Build Host>` and other components, that can |
324 | work on specific hardware. | 324 | work on specific hardware. |
325 | 325 | ||
326 | :term:`SBOM` | ||
327 | This term means *Software Bill of Materials*. When you distribute | ||
328 | software, it offers a description of all the components you used, | ||
329 | their corresponding licenses, their dependencies, the changes that were | ||
330 | applied and the known vulnerabilities that were fixed. | ||
331 | |||
332 | This can be used by the recipients of the software to assess | ||
333 | their exposure to license compliance and security vulnerability issues. | ||
334 | |||
335 | See the :wikipedia:`Software Supply Chain <Software_supply_chain>` | ||
336 | article on Wikipedia for more details. | ||
337 | |||
338 | The OpenEmbedded Build System can generate such documentation for your | ||
339 | project, in :term:`SPDX` format, based on all the metadata it used to | ||
340 | build the software images. See the ":ref:`dev-manual/common-tasks:creating | ||
341 | a software bill of materials`" section of the Development Tasks manual. | ||
342 | |||
326 | :term:`Source Directory` | 343 | :term:`Source Directory` |
327 | This term refers to the directory structure | 344 | This term refers to the directory structure |
328 | created as a result of creating a local copy of the ``poky`` Git | 345 | created as a result of creating a local copy of the ``poky`` Git |
@@ -383,6 +400,17 @@ universal, the list includes them just in case: | |||
383 | ":ref:`overview-manual/development-environment:repositories, tags, and branches`" | 400 | ":ref:`overview-manual/development-environment:repositories, tags, and branches`" |
384 | section in the Yocto Project Overview and Concepts Manual. | 401 | section in the Yocto Project Overview and Concepts Manual. |
385 | 402 | ||
403 | :term:`SPDX` | ||
404 | This term means *Software Package Data Exchange*, and is used as a open | ||
405 | standard for providing a *Software Bill of Materials* (:term:`SBOM`). | ||
406 | This standard is developed through a `Linux Foundation project | ||
407 | <https://spdx.dev/>`__ and is used by the OpenEmbedded Build System to | ||
408 | provide an :term:`SBOM` associated to each a software image. | ||
409 | |||
410 | For details, see Wikipedia's :wikipedia:`SPDX page <Software_Package_Data_Exchange>` | ||
411 | and the ":ref:`dev-manual/common-tasks:creating a software bill of materials`" | ||
412 | section of the Development Tasks manual. | ||
413 | |||
386 | :term:`Sysroot` | 414 | :term:`Sysroot` |
387 | When cross-compiling, the target file system may be differently laid | 415 | When cross-compiling, the target file system may be differently laid |
388 | out and contain different things compared to the host system. The concept | 416 | out and contain different things compared to the host system. The concept |
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 71e8c272a7..f17960e0e9 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst | |||
@@ -1508,6 +1508,18 @@ system and gives an overview of their function and contents. | |||
1508 | 1508 | ||
1509 | CVE_PRODUCT = "vendor:package" | 1509 | CVE_PRODUCT = "vendor:package" |
1510 | 1510 | ||
1511 | :term:`CVE_VERSION` | ||
1512 | In a recipe, defines the version used to match the recipe version | ||
1513 | against the version in the `NIST CVE database <https://nvd.nist.gov/>`__ | ||
1514 | when usign :ref:`cve-check <ref-classes-cve-check>`. | ||
1515 | |||
1516 | The default is ${:term:`PV`} but if recipes use custom version numbers | ||
1517 | which do not map to upstream software component release versions and the versions | ||
1518 | used in the CVE database, then this variable can be used to set the | ||
1519 | version number for :ref:`cve-check <ref-classes-cve-check>`. Example:: | ||
1520 | |||
1521 | CVE_VERSION = "2.39" | ||
1522 | |||
1511 | :term:`CVSDIR` | 1523 | :term:`CVSDIR` |
1512 | The directory in which files checked out under the CVS system are | 1524 | The directory in which files checked out under the CVS system are |
1513 | stored. | 1525 | stored. |
@@ -7278,6 +7290,88 @@ system and gives an overview of their function and contents. | |||
7278 | 7290 | ||
7279 | You can specify only a single URL in :term:`SOURCE_MIRROR_URL`. | 7291 | You can specify only a single URL in :term:`SOURCE_MIRROR_URL`. |
7280 | 7292 | ||
7293 | :term:`SPDX_ARCHIVE_PACKAGED` | ||
7294 | This option allows to add to :term:`SPDX` output compressed archives | ||
7295 | of the files in the generated target packages. | ||
7296 | |||
7297 | Such archives are available in | ||
7298 | ``tmp/deploy/spdx/MACHINE/packages/packagename.tar.zst`` | ||
7299 | under the :term:`Build Directory`. | ||
7300 | |||
7301 | Enable this option as follows:: | ||
7302 | |||
7303 | SPDX_ARCHIVE_PACKAGED = "1" | ||
7304 | |||
7305 | According to our tests on release 4.1 "langdale", building | ||
7306 | ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this | ||
7307 | option multiplied the size of the ``tmp/deploy/spdx`` directory by a | ||
7308 | factor of 13 (+1.6 GiB for this image), compared to just using the | ||
7309 | :ref:`create-spdx <ref-classes-create-spdx>` class with no option. | ||
7310 | |||
7311 | Note that this option doesn't increase the size of :term:`SPDX` | ||
7312 | files in ``tmp/deploy/images/MACHINE``. | ||
7313 | |||
7314 | :term:`SPDX_ARCHIVE_SOURCES` | ||
7315 | This option allows to add to :term:`SPDX` output compressed archives | ||
7316 | of the sources for packages installed on the target. It currently | ||
7317 | only works when :term:`SPDX_INCLUDE_SOURCES` is set. | ||
7318 | |||
7319 | This is one way of fulfilling "source code access" license | ||
7320 | requirements. | ||
7321 | |||
7322 | Such source archives are available in | ||
7323 | ``tmp/deploy/spdx/MACHINE/recipes/recipe-packagename.tar.zst`` | ||
7324 | under the :term:`Build Directory`. | ||
7325 | |||
7326 | Enable this option as follows:: | ||
7327 | |||
7328 | SPDX_INCLUDE_SOURCES = "1" | ||
7329 | SPDX_ARCHIVE_SOURCES = "1" | ||
7330 | |||
7331 | According to our tests on release 4.1 "langdale", building | ||
7332 | ``core-image-minimal`` for the ``qemux86-64`` machine, enabling | ||
7333 | these options multiplied the size of the ``tmp/deploy/spdx`` | ||
7334 | directory by a factor of 11 (+1.4 GiB for this image), | ||
7335 | compared to just using the :ref:`create-spdx <ref-classes-create-spdx>` | ||
7336 | class with no option. | ||
7337 | |||
7338 | Note that using this option only marginally increases the size | ||
7339 | of the :term:`SPDX` output in ``tmp/deploy/images/MACHINE/`` | ||
7340 | (+ 0.07\% with the tested image), compared to just enabling | ||
7341 | :term:`SPDX_INCLUDE_SOURCES`. | ||
7342 | |||
7343 | :term:`SPDX_INCLUDE_SOURCES` | ||
7344 | This option allows to add a description of the source files used to build | ||
7345 | the host tools and the target packages, to the ``spdx.json`` files in | ||
7346 | ``tmp/deploy/spdx/MACHINE/recipes/`` under the :term:`Build Directory`. | ||
7347 | As a consequence, the ``spdx.json`` files under the ``by-namespace`` and | ||
7348 | ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also | ||
7349 | modified to include references to such source file descriptions. | ||
7350 | |||
7351 | Enable this option as follows:: | ||
7352 | |||
7353 | SPDX_INCLUDE_SOURCES = "1" | ||
7354 | |||
7355 | According to our tests on release 4.1 "langdale", building | ||
7356 | ``core-image-minimal`` for the ``qemux86-64`` machine, enabling | ||
7357 | this option multiplied the total size of the ``tmp/deploy/spdx`` | ||
7358 | directory by a factor of 3 (+291 MiB for this image), | ||
7359 | and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in | ||
7360 | ``tmp/deploy/images/MACHINE`` by a factor of 130 (+15 MiB for this | ||
7361 | image), compared to just using the | ||
7362 | :ref:`create-spdx <ref-classes-create-spdx>` class with no option. | ||
7363 | |||
7364 | :term:`SPDX_PRETTY` | ||
7365 | This option makes the SPDX output more human-readable, using | ||
7366 | identation and newlines, instead of the default output in a | ||
7367 | single line:: | ||
7368 | |||
7369 | SPDX_PRETTY = "1" | ||
7370 | |||
7371 | The generated SPDX files are approximately 20% bigger, but | ||
7372 | this option is recommended if you want to inspect the SPDX | ||
7373 | output files with a text editor. | ||
7374 | |||
7281 | :term:`SPDXLICENSEMAP` | 7375 | :term:`SPDXLICENSEMAP` |
7282 | Maps commonly used license names to their SPDX counterparts found in | 7376 | Maps commonly used license names to their SPDX counterparts found in |
7283 | ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP` | 7377 | ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP` |