1.. _securitybugs: 2 3Security bugs 4============= 5 6Linux kernel developers take security very seriously. As such, we'd 7like to know when a security bug is found so that it can be fixed and 8disclosed as quickly as possible. 9 10Preparing your report 11--------------------- 12 13Like with any bug report, a security bug report requires a lot of analysis work 14from the developers, so the more information you can share about the issue, the 15better. Please review the procedure outlined in 16Documentation/admin-guide/reporting-issues.rst if you are unclear about what 17information is helpful. The following information are absolutely necessary in 18**any** security bug report: 19 20 * **affected kernel version range**: with no version indication, your report 21 will not be processed. A significant part of reports are for bugs that 22 have already been fixed, so it is extremely important that vulnerabilities 23 are verified on recent versions (development tree or latest stable 24 version), at least by verifying that the code has not changed since the 25 version where it was detected. 26 27 * **description of the problem**: a detailed description of the problem, with 28 traces showing its manifestation, and why you consider that the observed 29 behavior as a problem in the kernel, is necessary. 30 31 * **reproducer**: developers will need to be able to reproduce the problem to 32 consider a fix as effective. This includes both a way to trigger the issue 33 and a way to confirm it happens. A reproducer with low complexity 34 dependencies will be needed (source code, shell script, sequence of 35 instructions, file-system image etc). Binary-only executables are not 36 accepted. Working exploits are extremely helpful and will not be released 37 without consent from the reporter, unless they are already public. By 38 definition if an issue cannot be reproduced, it is not exploitable, thus it 39 is not a security bug. 40 41 * **conditions**: if the bug depends on certain configuration options, 42 sysctls, permissions, timing, code modifications etc, these should be 43 indicated. 44 45In addition, the following information are highly desirable: 46 47 * **suspected location of the bug**: the file names and functions where the 48 bug is suspected to be present are very important, at least to help forward 49 the report to the appropriate maintainers. When not possible (for example, 50 "system freezes each time I run this command"), the security team will help 51 identify the source of the bug. 52 53 * **a proposed fix**: bug reporters who have analyzed the cause of a bug in 54 the source code almost always have an accurate idea on how to fix it, 55 because they spent a long time studying it and its implications. Proposing 56 a tested fix will save maintainers a lot of time, even if the fix ends up 57 not being the right one, because it helps understand the bug. When 58 proposing a tested fix, please always format it in a way that can be 59 immediately merged (see Documentation/process/submitting-patches.rst). 60 This will save some back-and-forth exchanges if it is accepted, and you 61 will be credited for finding and fixing this issue. Note that in this case 62 only a ``Signed-off-by:`` tag is needed, without ``Reported-by:`` when the 63 reporter and author are the same. 64 65 * **mitigations**: very often during a bug analysis, some ways of mitigating 66 the issue appear. It is useful to share them, as they can be helpful to 67 keep end users protected during the time it takes them to apply the fix. 68 69What qualifies as a security bug 70-------------------------------- 71 72It is important that most bugs are handled publicly so as to involve the widest 73possible audience and find the best solution. By nature, bugs that are handled 74in closed discussions between a small set of participants are less likely to 75produce the best possible fix (e.g., risk of missing valid use cases, limited 76testing abilities). 77 78It turns out that the majority of the bugs reported via the security team are 79just regular bugs that have been improperly qualified as security bugs due to 80a lack of awareness of the Linux kernel's threat model, as described in 81Documentation/process/threat-model.rst, and ought to have been sent through 82the normal channels described in Documentation/admin-guide/reporting-issues.rst 83instead. 84 85The security list exists for urgent bugs that grant an attacker a capability 86they are not supposed to have on a correctly configured production system, and 87can be easily exploited, representing an imminent threat to many users. Before 88reporting, consider whether the issue actually crosses a trust boundary on such 89a system. 90 91**If you resorted to AI assistance to identify a bug, you must treat it as 92public**. While you may have valid reasons to believe it is not, the security 93team's experience shows that bugs discovered this way systematically surface 94simultaneously across multiple researchers, often on the same day. In this 95case, do not publicly share a reproducer, as this could cause unintended harm; 96just mention that one is available and maintainers might ask for it privately 97if they need it. 98 99If you are unsure whether an issue qualifies, err on the side of reporting 100privately: the security team would rather triage a borderline report than miss 101a real vulnerability. Reporting ordinary bugs to the security list, however, 102does not make them move faster and consumes triage capacity that other reports 103need. 104 105Identifying contacts 106-------------------- 107 108The most effective way to report a security bug is to send it directly to the 109affected subsystem's maintainers and Cc: the Linux kernel security team. Do 110not send it to a public list at this stage, unless you have good reasons to 111consider the issue as being public or trivial to discover (e.g. result of a 112widely available automated vulnerability scanning tool that can be repeated by 113anyone, or use of AI-based tools). 114 115If you're sending a report for issues affecting multiple parts in the kernel, 116even if they're fairly similar issues, please send individual messages (think 117that maintainers will not all work on the issues at the same time). The only 118exception is when an issue concerns closely related parts maintained by the 119exact same subset of maintainers, and these parts are expected to be fixed all 120at once by the same commit, then it may be acceptable to report them at once. 121 122One difficulty for most first-time reporters is to figure the right list of 123recipients to send a report to. In the Linux kernel, all official maintainers 124are trusted, so the consequences of accidentally including the wrong maintainer 125are essentially a bit more noise for that person, i.e. nothing dramatic. As 126such, a suitable method to figure the list of maintainers (which kernel 127security officers use) is to rely on the get_maintainer.pl script, tuned to 128only report maintainers. This script, when passed a file name, will look for 129its path in the MAINTAINERS file to figure a hierarchical list of relevant 130maintainers. Calling it a first time with the finest level of filtering will 131most of the time return a short list of this specific file's maintainers:: 132 133 $ ./scripts/get_maintainer.pl --no-l --no-r --pattern-depth 1 \ 134 drivers/example.c 135 Developer One <dev1@example.com> (maintainer:example driver) 136 Developer Two <dev2@example.org> (maintainer:example driver) 137 138These two maintainers should then receive the message. If the command does not 139return anything, it means the affected file is part of a wider subsystem, so we 140should be less specific:: 141 142 $ ./scripts/get_maintainer.pl --no-l --no-r drivers/example.c 143 Developer One <dev1@example.com> (maintainer:example subsystem) 144 Developer Two <dev2@example.org> (maintainer:example subsystem) 145 Developer Three <dev3@example.com> (maintainer:example subsystem [GENERAL]) 146 Developer Four <dev4@example.org> (maintainer:example subsystem [GENERAL]) 147 148Here, picking the first, most specific ones, is sufficient. When the list is 149long, it is possible to produce a comma-delimited e-mail address list on a 150single line suitable for use in the To: field of a mailer like this:: 151 152 $ ./scripts/get_maintainer.pl --no-tree --no-l --no-r --no-n --m \ 153 --no-git-fallback --no-substatus --no-rolestats --no-multiline \ 154 --pattern-depth 1 drivers/example.c 155 dev1@example.com, dev2@example.org 156 157or this for the wider list:: 158 159 $ ./scripts/get_maintainer.pl --no-tree --no-l --no-r --no-n --m \ 160 --no-git-fallback --no-substatus --no-rolestats --no-multiline \ 161 drivers/example.c 162 dev1@example.com, dev2@example.org, dev3@example.com, dev4@example.org 163 164If at this point you're still facing difficulties spotting the right 165maintainers, **and only in this case**, it's possible to send your report to 166the Linux kernel security team only. Your message will be triaged, and you 167will receive instructions about whom to contact, if needed. Your message may 168equally be forwarded as-is to the relevant maintainers. 169 170Responsible use of AI to find bugs 171---------------------------------- 172 173A significant fraction of bug reports submitted to the security team are 174actually the result of code reviews assisted by AI tools. While this can be an 175efficient means to find bugs in rarely explored areas, it causes an overload on 176maintainers, who are sometimes forced to ignore such reports due to their poor 177quality or accuracy. As such, reporters must be particularly cautious about a 178number of points which tend to make these reports needlessly difficult to 179handle: 180 181 * **Length**: AI-generated reports tend to be excessively long, containing 182 multiple sections and excessive detail. This makes it difficult to spot 183 important information such as affected files, versions, and impact. Please 184 ensure that a clear summary of the problem and all critical details are 185 presented first. Do not require triage engineers to scan multiple pages of 186 text. Configure your tools to produce concise, human-style reports. 187 188 * **Formatting**: Most AI-generated reports are littered with Markdown tags. 189 These decorations complicate the search for important information and do 190 not survive the quoting processes involved in forwarding or replying. 191 Please **always convert your report to plain text** without any formatting 192 decorations before sending it. 193 194 * **Impact Evaluation**: Many AI-generated reports lack an understanding 195 of the kernel's threat model (see Documentation/process/threat-model.rst) 196 and go to great lengths inventing theoretical consequences. This adds 197 noise and complicates triage. Please stick to verifiable facts (e.g., 198 "this bug permits any user to gain CAP_NET_ADMIN") without enumerating 199 speculative implications. Have your tool read this documentation as 200 part of the evaluation process. 201 202 * **Reproducer**: AI-based tools are often capable of generating reproducers. 203 Please always ensure your tool provides one and **test it thoroughly**. If 204 the reproducer does not work, or if the tool cannot produce one, the 205 validity of the report should be seriously questioned. Note that since the 206 report will be posted to a public list, the reproducer should only be 207 shared upon maintainers' request. 208 209 * **Propose a Fix**: Many AI tools are actually better at writing code than 210 evaluating it. Please ask your tool to propose a fix and **test it** before 211 reporting the problem. If the fix cannot be tested because it relies on 212 rare hardware or almost extinct network protocols, the issue is likely not 213 a security bug. In any case, if a fix is proposed, it must adhere to 214 Documentation/process/submitting-patches.rst and include a 'Fixes:' tag 215 designating the commit that introduced the bug. 216 217Failure to consider these points exposes your report to the risk of being 218ignored. 219 220Use common sense when evaluating the report. If the affected file has not been 221touched for more than one year and is maintained by a single individual, it is 222likely that usage has declined and exposed users are virtually non-existent 223(e.g., drivers for very old hardware, obsolete filesystems). In such cases, 224there is no need to consume a maintainer's time with an unimportant report. If 225the issue is clearly trivial and publicly discoverable, you should report it 226directly to the public mailing lists. 227 228Sending the report 229------------------ 230 231Reports are to be sent over e-mail exclusively. Please use a working e-mail 232address, preferably the same that you want to appear in ``Reported-by`` tags 233if any. If unsure, send your report to yourself first. 234 235The security team and maintainers almost always require additional 236information beyond what was initially provided in a report and rely on 237active and efficient collaboration with the reporter to perform further 238testing (e.g., verifying versions, configuration options, mitigations, or 239patches). Before contacting the security team, the reporter must ensure 240they are available to explain their findings, engage in discussions, and 241run additional tests. Reports where the reporter does not respond promptly 242or cannot effectively discuss their findings may be abandoned if the 243communication does not quickly improve. 244 245The report must be sent to maintainers. If there are two or fewer 246recipients in your message, you must also always Cc: the Linux kernel 247security team who will ensure the message is delivered to the proper 248people, and will be able to assist small maintainer teams with processes 249they may not be familiar with. For larger teams, Cc: the Linux kernel 250security team for your first few reports or when seeking specific help, 251such as when resending a message which got no response within a week. 252Once you have become comfortable with the process for a few reports, it is 253no longer necessary to Cc: the security list when sending to large teams. 254The Linux kernel security team can be contacted by email at 255<security@kernel.org>. This is a private list of security officers 256who will help verify the bug report and assist developers working on a fix. 257It is possible that the security team will bring in extra help from area 258maintainers to understand and fix the security vulnerability. 259 260Please send **plain text** emails without attachments where possible. 261It is much harder to have a context-quoted discussion about a complex 262issue if all the details are hidden away in attachments. Think of it like a 263:doc:`regular patch submission <../process/submitting-patches>` 264(even if you don't have a patch yet): describe the problem and impact, list 265reproduction steps, and follow it with a proposed fix, all in plain text. 266Markdown, HTML and RST formatted reports are particularly frowned upon since 267they're quite hard to read for humans and encourage to use dedicated viewers, 268sometimes online, which by definition is not acceptable for a confidential 269security report. Note that some mailers tend to mangle formatting of plain 270text by default, please consult Documentation/process/email-clients.rst for 271more info. 272 273Disclosure and embargoed information 274------------------------------------ 275 276The security list is not a disclosure channel. For that, see Coordination 277below. 278 279Once a robust fix has been developed, the release process starts. Fixes 280for publicly known bugs are released immediately. 281 282Although our preference is to release fixes for publicly undisclosed bugs 283as soon as they become available, this may be postponed at the request of 284the reporter or an affected party for up to 7 calendar days from the start 285of the release process, with an exceptional extension to 14 calendar days 286if it is agreed that the criticality of the bug requires more time. The 287only valid reason for deferring the publication of a fix is to accommodate 288the logistics of QA and large scale rollouts which require release 289coordination. 290 291While embargoed information may be shared with trusted individuals in 292order to develop a fix, such information will not be published alongside 293the fix or on any other disclosure channel without the permission of the 294reporter. This includes but is not limited to the original bug report 295and followup discussions (if any), exploits, CVE information or the 296identity of the reporter. 297 298In other words our only interest is in getting bugs fixed. All other 299information submitted to the security list and any followup discussions 300of the report are treated confidentially even after the embargo has been 301lifted, in perpetuity. 302 303Coordination with other groups 304------------------------------ 305 306While the kernel security team solely focuses on getting bugs fixed, 307other groups focus on fixing issues in distros and coordinating 308disclosure between operating system vendors. Coordination is usually 309handled by the "linux-distros" mailing list and disclosure by the 310public "oss-security" mailing list, both of which are closely related 311and presented in the linux-distros wiki: 312<https://oss-security.openwall.org/wiki/mailing-lists/distros> 313 314Please note that the respective policies and rules are different since 315the 3 lists pursue different goals. Coordinating between the kernel 316security team and other teams is difficult since for the kernel security 317team occasional embargoes (as subject to a maximum allowed number of 318days) start from the availability of a fix, while for "linux-distros" 319they start from the initial post to the list regardless of the 320availability of a fix. 321 322As such, the kernel security team strongly recommends that as a reporter 323of a potential security issue you DO NOT contact the "linux-distros" 324mailing list UNTIL a fix is accepted by the affected code's maintainers 325and you have read the distros wiki page above and you fully understand 326the requirements that contacting "linux-distros" will impose on you and 327the kernel community. This also means that in general it doesn't make 328sense to Cc: both lists at once, except maybe for coordination if and 329while an accepted fix has not yet been merged. In other words, until a 330fix is accepted do not Cc: "linux-distros", and after it's merged do not 331Cc: the kernel security team. 332 333CVE assignment 334-------------- 335 336The security team does not assign CVEs, nor do we require them for 337reports or fixes, as this can needlessly complicate the process and may 338delay the bug handling. If a reporter wishes to have a CVE identifier 339assigned for a confirmed issue, they can contact the :doc:`kernel CVE 340assignment team<../process/cve>` to obtain one. 341 342Non-disclosure agreements 343------------------------- 344 345The Linux kernel security team is not a formal body and therefore unable 346to enter any non-disclosure agreements. 347