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