diff options
Diffstat (limited to 'documentation/dev-manual/vulnerabilities.rst')
-rw-r--r-- | documentation/dev-manual/vulnerabilities.rst | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/documentation/dev-manual/vulnerabilities.rst b/documentation/dev-manual/vulnerabilities.rst new file mode 100644 index 0000000000..f8dac5edc6 --- /dev/null +++ b/documentation/dev-manual/vulnerabilities.rst | |||
@@ -0,0 +1,214 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Checking for Vulnerabilities | ||
4 | **************************** | ||
5 | |||
6 | Vulnerabilities in Poky and OE-Core | ||
7 | =================================== | ||
8 | |||
9 | The Yocto Project has an infrastructure to track and address unfixed | ||
10 | known security vulnerabilities, as tracked by the public | ||
11 | :wikipedia:`Common Vulnerabilities and Exposures (CVE) <Common_Vulnerabilities_and_Exposures>` | ||
12 | database. | ||
13 | |||
14 | The Yocto Project maintains a `list of known vulnerabilities | ||
15 | <https://autobuilder.yocto.io/pub/non-release/patchmetrics/>`__ | ||
16 | for packages in Poky and OE-Core, tracking the evolution of the number of | ||
17 | unpatched CVEs and the status of patches. Such information is available for | ||
18 | the current development version and for each supported release. | ||
19 | |||
20 | Security is a process, not a product, and thus at any time, a number of security | ||
21 | issues may be impacting Poky and OE-Core. It is up to the maintainers, users, | ||
22 | contributors and anyone interested in the issues to investigate and possibly fix them by | ||
23 | updating software components to newer versions or by applying patches to address them. | ||
24 | It is recommended to work with Poky and OE-Core upstream maintainers and submit | ||
25 | patches to fix them, see ":ref:`dev-manual/changes:submitting a change to the yocto project`" for details. | ||
26 | |||
27 | Vulnerability check at build time | ||
28 | ================================= | ||
29 | |||
30 | To enable a check for CVE security vulnerabilities using :ref:`cve-check <ref-classes-cve-check>` in the specific image | ||
31 | or target you are building, add the following setting to your configuration:: | ||
32 | |||
33 | INHERIT += "cve-check" | ||
34 | |||
35 | The CVE database contains some old incomplete entries which have been | ||
36 | deemed not to impact Poky or OE-Core. These CVE entries can be excluded from the | ||
37 | check using build configuration:: | ||
38 | |||
39 | include conf/distro/include/cve-extra-exclusions.inc | ||
40 | |||
41 | With this CVE check enabled, BitBake build will try to map each compiled software component | ||
42 | recipe name and version information to the CVE database and generate recipe and | ||
43 | image specific reports. These reports will contain: | ||
44 | |||
45 | - metadata about the software component like names and versions | ||
46 | |||
47 | - metadata about the CVE issue such as description and NVD link | ||
48 | |||
49 | - for each software component, a list of CVEs which are possibly impacting this version | ||
50 | |||
51 | - status of each CVE: ``Patched``, ``Unpatched`` or ``Ignored`` | ||
52 | |||
53 | The status ``Patched`` means that a patch file to address the security issue has been | ||
54 | applied. ``Unpatched`` status means that no patches to address the issue have been | ||
55 | applied and that the issue needs to be investigated. ``Ignored`` means that after | ||
56 | analysis, it has been deemed to ignore the issue as it for example affects | ||
57 | the software component on a different operating system platform. | ||
58 | |||
59 | After a build with CVE check enabled, reports for each compiled source recipe will be | ||
60 | found in ``build/tmp/deploy/cve``. | ||
61 | |||
62 | For example the CVE check report for the ``flex-native`` recipe looks like:: | ||
63 | |||
64 | $ cat poky/build/tmp/deploy/cve/flex-native | ||
65 | LAYER: meta | ||
66 | PACKAGE NAME: flex-native | ||
67 | PACKAGE VERSION: 2.6.4 | ||
68 | CVE: CVE-2016-6354 | ||
69 | CVE STATUS: Patched | ||
70 | 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. | ||
71 | CVSS v2 BASE SCORE: 7.5 | ||
72 | CVSS v3 BASE SCORE: 9.8 | ||
73 | VECTOR: NETWORK | ||
74 | MORE INFORMATION: https://nvd.nist.gov/vuln/detail/CVE-2016-6354 | ||
75 | |||
76 | LAYER: meta | ||
77 | PACKAGE NAME: flex-native | ||
78 | PACKAGE VERSION: 2.6.4 | ||
79 | CVE: CVE-2019-6293 | ||
80 | CVE STATUS: Ignored | ||
81 | 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. | ||
82 | CVSS v2 BASE SCORE: 4.3 | ||
83 | CVSS v3 BASE SCORE: 5.5 | ||
84 | VECTOR: NETWORK | ||
85 | MORE INFORMATION: https://nvd.nist.gov/vuln/detail/CVE-2019-6293 | ||
86 | |||
87 | For images, a summary of all recipes included in the image and their CVEs is also | ||
88 | generated in textual and JSON formats. These ``.cve`` and ``.json`` reports can be found | ||
89 | in the ``tmp/deploy/images`` directory for each compiled image. | ||
90 | |||
91 | At build time CVE check will also throw warnings about ``Unpatched`` CVEs:: | ||
92 | |||
93 | 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 | ||
94 | 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 | ||
95 | |||
96 | It is also possible to check the CVE status of individual packages as follows:: | ||
97 | |||
98 | bitbake -c cve_check flex libarchive | ||
99 | |||
100 | Fixing CVE product name and version mappings | ||
101 | ============================================ | ||
102 | |||
103 | By default, :ref:`cve-check <ref-classes-cve-check>` uses the recipe name :term:`BPN` as CVE | ||
104 | product name when querying the CVE database. If this mapping contains false positives, e.g. | ||
105 | some reported CVEs are not for the software component in question, or false negatives like | ||
106 | some CVEs are not found to impact the recipe when they should, then the problems can be | ||
107 | in the recipe name to CVE product mapping. These mapping issues can be fixed by setting | ||
108 | the :term:`CVE_PRODUCT` variable inside the recipe. This defines the name of the software component in the | ||
109 | upstream `NIST CVE database <https://nvd.nist.gov/>`__. | ||
110 | |||
111 | The variable supports using vendor and product names like this:: | ||
112 | |||
113 | CVE_PRODUCT = "flex_project:flex" | ||
114 | |||
115 | In this example the vendor name used in the CVE database is ``flex_project`` and the | ||
116 | product is ``flex``. With this setting the ``flex`` recipe only maps to this specific | ||
117 | product and not products from other vendors with same name ``flex``. | ||
118 | |||
119 | Similarly, when the recipe version :term:`PV` is not compatible with software versions used by | ||
120 | the upstream software component releases and the CVE database, these can be fixed using | ||
121 | the :term:`CVE_VERSION` variable. | ||
122 | |||
123 | Note that if the CVE entries in the NVD database contain bugs or have missing or incomplete | ||
124 | information, it is recommended to fix the information there directly instead of working | ||
125 | around the issues possibly for a long time in Poky and OE-Core side recipes. Feedback to | ||
126 | NVD about CVE entries can be provided through the `NVD contact form <https://nvd.nist.gov/info/contact-form>`__. | ||
127 | |||
128 | Fixing vulnerabilities in recipes | ||
129 | ================================= | ||
130 | |||
131 | If a CVE security issue impacts a software component, it can be fixed by updating to a newer | ||
132 | version of the software component or by applying a patch. For Poky and OE-Core master branches, updating | ||
133 | to a newer software component release with fixes is the best option, but patches can be applied | ||
134 | if releases are not yet available. | ||
135 | |||
136 | For stable branches, it is preferred to apply patches for the issues. For some software | ||
137 | components minor version updates can also be applied if they are backwards compatible. | ||
138 | |||
139 | Here is an example of fixing CVE security issues with patch files, | ||
140 | an example from the :oe_layerindex:`ffmpeg recipe</layerindex/recipe/47350>`:: | ||
141 | |||
142 | SRC_URI = "https://www.ffmpeg.org/releases/${BP}.tar.xz \ | ||
143 | file://0001-libavutil-include-assembly-with-full-path-from-sourc.patch \ | ||
144 | file://fix-CVE-2020-20446.patch \ | ||
145 | file://fix-CVE-2020-20453.patch \ | ||
146 | file://fix-CVE-2020-22015.patch \ | ||
147 | file://fix-CVE-2020-22021.patch \ | ||
148 | file://fix-CVE-2020-22033-CVE-2020-22019.patch \ | ||
149 | file://fix-CVE-2021-33815.patch \ | ||
150 | |||
151 | A good practice is to include the CVE identifier in both the patch file name | ||
152 | and inside the patch file commit message using the format:: | ||
153 | |||
154 | CVE: CVE-2020-22033 | ||
155 | |||
156 | CVE checker will then capture this information and change the CVE status to ``Patched`` | ||
157 | in the generated reports. | ||
158 | |||
159 | If analysis shows that the CVE issue does not impact the recipe due to configuration, platform, | ||
160 | version or other reasons, the CVE can be marked as ``Ignored`` using the :term:`CVE_CHECK_IGNORE` variable. | ||
161 | As mentioned previously, if data in the CVE database is wrong, it is recommend to fix those | ||
162 | issues in the CVE database directly. | ||
163 | |||
164 | Recipes can be completely skipped by CVE check by including the recipe name in | ||
165 | the :term:`CVE_CHECK_SKIP_RECIPE` variable. | ||
166 | |||
167 | Implementation details | ||
168 | ====================== | ||
169 | |||
170 | Here's what the :ref:`cve-check <ref-classes-cve-check>` class does to | ||
171 | find unpatched CVE IDs. | ||
172 | |||
173 | First the code goes through each patch file provided by a recipe. If a valid CVE ID | ||
174 | is found in the name of the file, the corresponding CVE is considered as patched. | ||
175 | Don't forget that if multiple CVE IDs are found in the filename, only the last | ||
176 | one is considered. Then, the code looks for ``CVE: CVE-ID`` lines in the patch | ||
177 | file. The found CVE IDs are also considered as patched. | ||
178 | |||
179 | Then, the code looks up all the CVE IDs in the NIST database for all the | ||
180 | products defined in :term:`CVE_PRODUCT`. Then, for each found CVE: | ||
181 | |||
182 | - If the package name (:term:`PN`) is part of | ||
183 | :term:`CVE_CHECK_SKIP_RECIPE`, it is considered as ``Patched``. | ||
184 | |||
185 | - If the CVE ID is part of :term:`CVE_CHECK_IGNORE`, it is | ||
186 | set as ``Ignored``. | ||
187 | |||
188 | - If the CVE ID is part of the patched CVE for the recipe, it is | ||
189 | already considered as ``Patched``. | ||
190 | |||
191 | - Otherwise, the code checks whether the recipe version (:term:`PV`) | ||
192 | is within the range of versions impacted by the CVE. If so, the CVE | ||
193 | is considered as ``Unpatched``. | ||
194 | |||
195 | The CVE database is stored in :term:`DL_DIR` and can be inspected using | ||
196 | ``sqlite3`` command as follows:: | ||
197 | |||
198 | sqlite3 downloads/CVE_CHECK/nvdcve_1.1.db .dump | grep CVE-2021-37462 | ||
199 | |||
200 | When analyzing CVEs, it is recommended to: | ||
201 | |||
202 | - study the latest information in `CVE database <https://nvd.nist.gov/vuln/search>`__. | ||
203 | |||
204 | - check how upstream developers of the software component addressed the issue, e.g. | ||
205 | what patch was applied, which upstream release contains the fix. | ||
206 | |||
207 | - check what other Linux distributions like `Debian <https://security-tracker.debian.org/tracker/>`__ | ||
208 | did to analyze and address the issue. | ||
209 | |||
210 | - follow security notices from other Linux distributions. | ||
211 | |||
212 | - follow public `open source security mailing lists <https://oss-security.openwall.org/wiki/mailing-lists>`__ for | ||
213 | discussions and advance notifications of CVE bugs and software releases with fixes. | ||
214 | |||