| 1 | .. _securitybugs:
|
| 2 |
|
| 3 | Security bugs
|
| 4 | =============
|
| 5 |
|
| 6 | Linux kernel developers take security very seriously. As such, we'd
|
| 7 | like to know when a security bug is found so that it can be fixed and
|
| 8 | disclosed as quickly as possible.
|
| 9 |
|
| 10 | Preparing your report
|
| 11 | ---------------------
|
| 12 |
|
| 13 | Like with any bug report, a security bug report requires a lot of analysis work
|
| 14 | from the developers, so the more information you can share about the issue, the
|
| 15 | better. Please review the procedure outlined in
|
| 16 | Documentation/admin-guide/reporting-issues.rst if you are unclear about what
|
| 17 | information 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 |
|
| 49 | In 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 |
|
| 73 | What qualifies as a security bug
|
| 74 | --------------------------------
|
| 75 |
|
| 76 | It is important that most bugs are handled publicly so as to involve the widest
|
| 77 | possible audience and find the best solution. By nature, bugs that are handled
|
| 78 | in closed discussions between a small set of participants are less likely to
|
| 79 | produce the best possible fix (e.g., risk of missing valid use cases, limited
|
| 80 | testing abilities).
|
| 81 |
|
| 82 | It turns out that the majority of the bugs reported via the security team are
|
| 83 | just regular bugs that have been improperly qualified as security bugs due to
|
| 84 | a lack of awareness of the Linux kernel's threat model, as described in
|
| 85 | Documentation/process/threat-model.rst, and ought to have been sent through
|
| 86 | the normal channels described in Documentation/admin-guide/reporting-issues.rst
|
| 87 | instead.
|
| 88 |
|
| 89 | The security list exists for urgent bugs that grant an attacker a capability
|
| 90 | they are not supposed to have on a correctly configured production system, and
|
| 91 | can be easily exploited, representing an imminent threat to many users. Before
|
| 92 | reporting, consider whether the issue actually crosses a trust boundary on such
|
| 93 | a system.
|
| 94 |
|
| 95 | **If you resorted to AI assistance to identify a bug, you must treat it as
|
| 96 | public**. While you may have valid reasons to believe it is not, the security
|
| 97 | team's experience shows that bugs discovered this way systematically surface
|
| 98 | simultaneously across multiple researchers, often on the same day. In this
|
| 99 | case, do not publicly share a reproducer, as this could cause unintended harm;
|
| 100 | just mention that one is available and maintainers might ask for it privately
|
| 101 | if they need it.
|
| 102 |
|
| 103 | If you are unsure whether an issue qualifies, err on the side of reporting
|
| 104 | privately: the security team would rather triage a borderline report than miss
|
| 105 | a real vulnerability. Reporting ordinary bugs to the security list, however,
|
| 106 | does not make them move faster and consumes triage capacity that other reports
|
| 107 | need.
|
| 108 |
|
| 109 | Identifying contacts
|
| 110 | --------------------
|
| 111 |
|
| 112 | The most effective way to report a security bug is to send it directly to the
|
| 113 | affected subsystem's maintainers and Cc: the Linux kernel security team. Do
|
| 114 | not send it to a public list at this stage, unless you have good reasons to
|
| 115 | consider the issue as being public or trivial to discover (e.g. result of a
|
| 116 | widely available automated vulnerability scanning tool that can be repeated by
|
| 117 | anyone, or use of AI-based tools).
|
| 118 |
|
| 119 | If you're sending a report for issues affecting multiple parts in the kernel,
|
| 120 | even if they're fairly similar issues, please send individual messages (think
|
| 121 | that maintainers will not all work on the issues at the same time). The only
|
| 122 | exception is when an issue concerns closely related parts maintained by the
|
| 123 | exact same subset of maintainers, and these parts are expected to be fixed all
|
| 124 | at once by the same commit, then it may be acceptable to report them at once.
|
| 125 |
|
| 126 | One difficulty for most first-time reporters is to figure the right list of
|
| 127 | recipients to send a report to. In the Linux kernel, all official maintainers
|
| 128 | are trusted, so the consequences of accidentally including the wrong maintainer
|
| 129 | are essentially a bit more noise for that person, i.e. nothing dramatic. As
|
| 130 | such, a suitable method to figure the list of maintainers (which kernel
|
| 131 | security officers use) is to rely on the get_maintainer.pl script, tuned to
|
| 132 | only report maintainers. This script, when passed a file name, will look for
|
| 133 | its path in the MAINTAINERS file to figure a hierarchical list of relevant
|
| 134 | maintainers. Calling it a first time with the finest level of filtering will
|
| 135 | most 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 <[email protected]> (maintainer:example driver)
|
| 140 | Developer Two <[email protected]> (maintainer:example driver)
|
| 141 |
|
| 142 | These two maintainers should then receive the message. If the command does not
|
| 143 | return anything, it means the affected file is part of a wider subsystem, so we
|
| 144 | should be less specific::
|
| 145 |
|
| 146 | $ ./scripts/get_maintainer.pl --no-l --no-r drivers/example.c
|
| 147 | Developer One <[email protected]> (maintainer:example subsystem)
|
| 148 | Developer Two <[email protected]> (maintainer:example subsystem)
|
| 149 | Developer Three <[email protected]> (maintainer:example subsystem [GENERAL])
|
| 150 | Developer Four <[email protected]> (maintainer:example subsystem [GENERAL])
|
| 151 |
|
| 152 | Here, picking the first, most specific ones, is sufficient. When the list is
|
| 153 | long, it is possible to produce a comma-delimited e-mail address list on a
|
| 154 | single 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 | [email protected], [email protected]
|
| 160 |
|
| 161 | or 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 | [email protected], [email protected], [email protected], [email protected]
|
| 167 |
|
| 168 | If at this point you're still facing difficulties spotting the right
|
| 169 | maintainers, **and only in this case**, it's possible to send your report to
|
| 170 | the Linux kernel security team only. Your message will be triaged, and you
|
| 171 | will receive instructions about whom to contact, if needed. Your message may
|
| 172 | equally be forwarded as-is to the relevant maintainers.
|
| 173 |
|
| 174 | Responsible use of AI to find bugs
|
| 175 | ----------------------------------
|
| 176 |
|
| 177 | A significant fraction of bug reports submitted to the security team are
|
| 178 | actually the result of code reviews assisted by AI tools. While this can be an
|
| 179 | efficient means to find bugs in rarely explored areas, it causes an overload on
|
| 180 | maintainers, who are sometimes forced to ignore such reports due to their poor
|
| 181 | quality or accuracy. As such, reporters must be particularly cautious about a
|
| 182 | number of points which tend to make these reports needlessly difficult to
|
| 183 | handle:
|
| 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 |
|
| 221 | Failure to consider these points exposes your report to the risk of being
|
| 222 | ignored.
|
| 223 |
|
| 224 | Use common sense when evaluating the report. If the affected file has not been
|
| 225 | touched for more than one year and is maintained by a single individual, it is
|
| 226 | likely that usage has declined and exposed users are virtually non-existent
|
| 227 | (e.g., drivers for very old hardware, obsolete filesystems). In such cases,
|
| 228 | there is no need to consume a maintainer's time with an unimportant report. If
|
| 229 | the issue is clearly trivial and publicly discoverable, you should report it
|
| 230 | directly to the public mailing lists.
|
| 231 |
|
| 232 | At the very least, when using an AI assistant to find and report bugs, make the
|
| 233 | assistant read this file and threat-model.rst before proceeding, and have it
|
| 234 | follow the procedure described in coding-assistants.rst: work on an up-to-date
|
| 235 | mainline tree and note the commit ID, verify the bug is real, write a fix,
|
| 236 | build it warning-free and checkpatch-clean, commit it with a Fixes tag, and
|
| 237 | identify the maintainers with get_maintainer.pl.
|
| 238 |
|
| 239 | On top of that procedure, the AI assistant **MUST**:
|
| 240 |
|
| 241 | 1. 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.
|
| 246 | 2. 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 |
|
| 252 | A more detailed process is covered at https://github.com/masoncl/kres.git.
|
| 253 |
|
| 254 | Sending the report
|
| 255 | ------------------
|
| 256 |
|
| 257 | Reports are to be sent over e-mail exclusively. Please use a working e-mail
|
| 258 | address, preferably the same that you want to appear in ``Reported-by`` tags
|
| 259 | if any. If unsure, send your report to yourself first.
|
| 260 |
|
| 261 | The security team and maintainers almost always require additional
|
| 262 | information beyond what was initially provided in a report and rely on
|
| 263 | active and efficient collaboration with the reporter to perform further
|
| 264 | testing (e.g., verifying versions, configuration options, mitigations, or
|
| 265 | patches). Before contacting the security team, the reporter must ensure
|
| 266 | they are available to explain their findings, engage in discussions, and
|
| 267 | run additional tests. Reports where the reporter does not respond promptly
|
| 268 | or cannot effectively discuss their findings may be abandoned if the
|
| 269 | communication does not quickly improve.
|
| 270 |
|
| 271 | The report must be sent to maintainers. If there are two or fewer
|
| 272 | recipients in your message, you must also always Cc: the Linux kernel
|
| 273 | security team who will ensure the message is delivered to the proper
|
| 274 | people, and will be able to assist small maintainer teams with processes
|
| 275 | they may not be familiar with. For larger teams, Cc: the Linux kernel
|
| 276 | security team for your first few reports or when seeking specific help,
|
| 277 | such as when resending a message which got no response within a week.
|
| 278 | Once you have become comfortable with the process for a few reports, it is
|
| 279 | no longer necessary to Cc: the security list when sending to large teams.
|
| 280 | The Linux kernel security team can be contacted by email at
|
| 281 | <[email protected]>. This is a private list of security officers
|
| 282 | who will help verify the bug report and assist developers working on a fix.
|
| 283 | It is possible that the security team will bring in extra help from area
|
| 284 | maintainers to understand and fix the security vulnerability.
|
| 285 |
|
| 286 | Please send **plain text** emails without attachments where possible.
|
| 287 | It is much harder to have a context-quoted discussion about a complex
|
| 288 | issue 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
|
| 291 | reproduction steps, and follow it with a proposed fix, all in plain text.
|
| 292 | Markdown, HTML and RST formatted reports are particularly frowned upon since
|
| 293 | they're quite hard to read for humans and encourage to use dedicated viewers,
|
| 294 | sometimes online, which by definition is not acceptable for a confidential
|
| 295 | security report. Note that some mailers tend to mangle formatting of plain
|
| 296 | text by default, please consult Documentation/process/email-clients.rst for
|
| 297 | more info.
|
| 298 |
|
| 299 | Disclosure and embargoed information
|
| 300 | ------------------------------------
|
| 301 |
|
| 302 | The security list is not a disclosure channel. For that, see Coordination
|
| 303 | below.
|
| 304 |
|
| 305 | Once a robust fix has been developed, the release process starts. Fixes
|
| 306 | for publicly known bugs are released immediately.
|
| 307 |
|
| 308 | Although our preference is to release fixes for publicly undisclosed bugs
|
| 309 | as soon as they become available, this may be postponed at the request of
|
| 310 | the reporter or an affected party for up to 7 calendar days from the start
|
| 311 | of the release process, with an exceptional extension to 14 calendar days
|
| 312 | if it is agreed that the criticality of the bug requires more time. The
|
| 313 | only valid reason for deferring the publication of a fix is to accommodate
|
| 314 | the logistics of QA and large scale rollouts which require release
|
| 315 | coordination.
|
| 316 |
|
| 317 | While embargoed information may be shared with trusted individuals in
|
| 318 | order to develop a fix, such information will not be published alongside
|
| 319 | the fix or on any other disclosure channel without the permission of the
|
| 320 | reporter. This includes but is not limited to the original bug report
|
| 321 | and followup discussions (if any), exploits, CVE information or the
|
| 322 | identity of the reporter.
|
| 323 |
|
| 324 | In other words our only interest is in getting bugs fixed. All other
|
| 325 | information submitted to the security list and any followup discussions
|
| 326 | of the report are treated confidentially even after the embargo has been
|
| 327 | lifted, in perpetuity.
|
| 328 |
|
| 329 | Coordination with other groups
|
| 330 | ------------------------------
|
| 331 |
|
| 332 | While the kernel security team solely focuses on getting bugs fixed,
|
| 333 | other groups focus on fixing issues in distros and coordinating
|
| 334 | disclosure between operating system vendors. Coordination is usually
|
| 335 | handled by the "linux-distros" mailing list and disclosure by the
|
| 336 | public "oss-security" mailing list, both of which are closely related
|
| 337 | and presented in the linux-distros wiki:
|
| 338 | <https://oss-security.openwall.org/wiki/mailing-lists/distros>
|
| 339 |
|
| 340 | Please note that the respective policies and rules are different since
|
| 341 | the 3 lists pursue different goals. Coordinating between the kernel
|
| 342 | security team and other teams is difficult since for the kernel security
|
| 343 | team occasional embargoes (as subject to a maximum allowed number of
|
| 344 | days) start from the availability of a fix, while for "linux-distros"
|
| 345 | they start from the initial post to the list regardless of the
|
| 346 | availability of a fix.
|
| 347 |
|
| 348 | As such, the kernel security team strongly recommends that as a reporter
|
| 349 | of a potential security issue you DO NOT contact the "linux-distros"
|
| 350 | mailing list UNTIL a fix is accepted by the affected code's maintainers
|
| 351 | and you have read the distros wiki page above and you fully understand
|
| 352 | the requirements that contacting "linux-distros" will impose on you and
|
| 353 | the kernel community. This also means that in general it doesn't make
|
| 354 | sense to Cc: both lists at once, except maybe for coordination if and
|
| 355 | while an accepted fix has not yet been merged. In other words, until a
|
| 356 | fix is accepted do not Cc: "linux-distros", and after it's merged do not
|
| 357 | Cc: the kernel security team.
|
| 358 |
|
| 359 | CVE assignment
|
| 360 | --------------
|
| 361 |
|
| 362 | The security team does not assign CVEs, nor do we require them for
|
| 363 | reports or fixes, as this can needlessly complicate the process and may
|
| 364 | delay the bug handling. If a reporter wishes to have a CVE identifier
|
| 365 | assigned for a confirmed issue, they can contact the :doc:`kernel CVE
|
| 366 | assignment team<../process/cve>` to obtain one.
|
| 367 |
|
| 368 | Non-disclosure agreements
|
| 369 | -------------------------
|
| 370 |
|
| 371 | The Linux kernel security team is not a formal body and therefore unable
|
| 372 | to enter any non-disclosure agreements.
|