Merge tag 'docs-7.1-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux

Pull documentation fixes from Jonathan Corbet: "This is Willy Tarreau's new document clarifying the definition and handling of security-related bugs, which we're trying to get out there quickly on the theory that some of the bug reporters might actually read and pay attention to it" * tag 'docs-7.1-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: docs: threat-model: don't limit root capabilities to CAP_SYS_ADMIN docs: security-bugs: add a link to the threat-model documentation Documentation: security-bugs: clarify requirements for AI-assisted reports Documentation: security-bugs: explain what is and is not a security bug Documentation: security-bugs: do not systematically Cc the security team

Linus Torvalds committed 6 months ago

Commit 36d49bb2 parents 4844e7c f2e65e43 files · +340 −2Browse files

Unified · Split

3 files

Documentation/process/index.rst +1 −0
Documentation/process/security-bugs.rst +104 −2
Documentation/process/threat-model.rst +235 −0

Documentation/process/index.rst+1−0

@@ -86,6 +86,7 @@ regressions and security problems. · 85 unmodified lines
86	debugging/index	86	debugging/index
87	handling-regressions	87	handling-regressions
88	security-bugs	88	security-bugs
		89	threat-model
89	cve	90	cve
90	embargoed-hardware-issues	91	embargoed-hardware-issues
91		92

Documentation/process/security-bugs.rst+104−2

@@ -66,6 +66,42 @@ In addition, the following information are highly desirable: · 65 unmodified lines
66	the issue appear. It is useful to share them, as they can be helpful to	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.	67	keep end users protected during the time it takes them to apply the fix.
68		68
		69	What qualifies as a security bug
		70	--------------------------------
		71
		72	It is important that most bugs are handled publicly so as to involve the widest
		73	possible audience and find the best solution. By nature, bugs that are handled
		74	in closed discussions between a small set of participants are less likely to
		75	produce the best possible fix (e.g., risk of missing valid use cases, limited
		76	testing abilities).
		77
		78	It turns out that the majority of the bugs reported via the security team are
		79	just regular bugs that have been improperly qualified as security bugs due to
		80	a lack of awareness of the Linux kernel's threat model, as described in
		81	Documentation/process/threat-model.rst, and ought to have been sent through
		82	the normal channels described in Documentation/admin-guide/reporting-issues.rst
		83	instead.
		84
		85	The security list exists for urgent bugs that grant an attacker a capability
		86	they are not supposed to have on a correctly configured production system, and
		87	can be easily exploited, representing an imminent threat to many users. Before
		88	reporting, consider whether the issue actually crosses a trust boundary on such
		89	a system.
		90
		91	**If you resorted to AI assistance to identify a bug, you must treat it as
		92	public**. While you may have valid reasons to believe it is not, the security
		93	team's experience shows that bugs discovered this way systematically surface
		94	simultaneously across multiple researchers, often on the same day. In this
		95	case, do not publicly share a reproducer, as this could cause unintended harm;
		96	just mention that one is available and maintainers might ask for it privately
		97	if they need it.
		98
		99	If you are unsure whether an issue qualifies, err on the side of reporting
		100	privately: the security team would rather triage a borderline report than miss
		101	a real vulnerability. Reporting ordinary bugs to the security list, however,
		102	does not make them move faster and consumes triage capacity that other reports
		103	need.
		104
69	Identifying contacts	105	Identifying contacts
70	--------------------	106	--------------------
71		107
@@ -74,7 +110,7 @@ affected subsystem's maintainers and Cc: the Linux kernel security team. Do · 2 unmodified lines
74	not send it to a public list at this stage, unless you have good reasons to	110	not send it to a public list at this stage, unless you have good reasons to
75	consider the issue as being public or trivial to discover (e.g. result of a	111	consider the issue as being public or trivial to discover (e.g. result of a
76	widely available automated vulnerability scanning tool that can be repeated by	112	widely available automated vulnerability scanning tool that can be repeated by
77	anyone).	113	anyone, or use of AI-based tools).
78		114
79	If you're sending a report for issues affecting multiple parts in the kernel,	115	If you're sending a report for issues affecting multiple parts in the kernel,
80	even if they're fairly similar issues, please send individual messages (think	116	even if they're fairly similar issues, please send individual messages (think
@@ -131,6 +167,64 @@ the Linux kernel security team only. Your message will be triaged, and you · 50 unmodified lines
131	will receive instructions about whom to contact, if needed. Your message may	167	will receive instructions about whom to contact, if needed. Your message may
132	equally be forwarded as-is to the relevant maintainers.	168	equally be forwarded as-is to the relevant maintainers.
133		169
		170	Responsible use of AI to find bugs
		171	----------------------------------
		172
		173	A significant fraction of bug reports submitted to the security team are
		174	actually the result of code reviews assisted by AI tools. While this can be an
		175	efficient means to find bugs in rarely explored areas, it causes an overload on
		176	maintainers, who are sometimes forced to ignore such reports due to their poor
		177	quality or accuracy. As such, reporters must be particularly cautious about a
		178	number of points which tend to make these reports needlessly difficult to
		179	handle:
		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
		217	Failure to consider these points exposes your report to the risk of being
		218	ignored.
		219
		220	Use common sense when evaluating the report. If the affected file has not been
		221	touched for more than one year and is maintained by a single individual, it is
		222	likely that usage has declined and exposed users are virtually non-existent
		223	(e.g., drivers for very old hardware, obsolete filesystems). In such cases,
		224	there is no need to consume a maintainer's time with an unimportant report. If
		225	the issue is clearly trivial and publicly discoverable, you should report it
		226	directly to the public mailing lists.
		227
134	Sending the report	228	Sending the report
135	------------------	229	------------------
136		230
@@ -148,7 +242,15 @@ run additional tests. Reports where the reporter does not respond promptly · 11 unmodified lines
148	or cannot effectively discuss their findings may be abandoned if the	242	or cannot effectively discuss their findings may be abandoned if the
149	communication does not quickly improve.	243	communication does not quickly improve.
150		244
151	The report must be sent to maintainers, with the security team in ``Cc:``.	245	The report must be sent to maintainers. If there are two or fewer
		246	recipients in your message, you must also always Cc: the Linux kernel
		247	security team who will ensure the message is delivered to the proper
		248	people, and will be able to assist small maintainer teams with processes
		249	they may not be familiar with. For larger teams, Cc: the Linux kernel
		250	security team for your first few reports or when seeking specific help,
		251	such as when resending a message which got no response within a week.
		252	Once you have become comfortable with the process for a few reports, it is
		253	no longer necessary to Cc: the security list when sending to large teams.
152	The Linux kernel security team can be contacted by email at	254	The Linux kernel security team can be contacted by email at
153	<security@kernel.org>. This is a private list of security officers	255	<security@kernel.org>. This is a private list of security officers
154	who will help verify the bug report and assist developers working on a fix.	256	who will help verify the bug report and assist developers working on a fix.

Documentation/process/threat-model.rst+235−0

@@ -0,0 +1,235 @@
	1	The Linux Kernel threat model
	2	=============================
	3
	4	There are a lot of assumptions regarding what the kernel does and does not
	5	protect against. These assumptions tend to cause confusion for bug reports
	6	(:doc:`security-related ones <security-bugs>` vs :doc:`non-security ones
	7	<../admin-guide/reporting-issues>`), and can complicate security enforcement
	8	when the responsibilities for some boundaries is not clear between the kernel,
	9	distros, administrators and users.
	10
	11	This document tries to clarify the responsibilities of the kernel in this
	12	domain.
	13
	14	The kernel's responsibilities
	15	-----------------------------
	16
	17	The kernel abstracts access to local hardware resources and to remote systems
	18	in a way that allows multiple local users to get a fair share of the available
	19	resources granted to them, and, when the underlying hardware permits, to assign
	20	a level of confidentiality to their communications and to the data they are
	21	processing or storing.
	22
	23	The kernel assumes that the underlying hardware behaves according to its
	24	specifications. This includes the integrity of the CPU's instruction set, the
	25	transparency of the branch prediction unit and the cache units, the consistency
	26	of the Memory Management Unit (MMU), the isolation of DMA-capable peripherals
	27	(e.g., via IOMMU), state transitions in controllers, ranges of values read from
	28	registers, the respect of documented hardware limitations, etc.
	29
	30	When hardware fails to maintain its specified isolation (e.g., CPU bugs,
	31	side-channels, hardware response to unexpected inputs), the kernel will usually
	32	attempt to implement reasonable mitigations. These are best-effort measures
	33	intended to reduce the attack surface or elevate the cost of an attack within
	34	the limits of the hardware's facilities; they do not constitute a
	35	kernel-provided safety guarantee.
	36
	37	Users always perform their activities under the authority of an administrator
	38	who is able to grant or deny various types of permissions that may affect how
	39	users benefit from available resources, or the level of confidentiality of
	40	their activities. Administrators may also delegate all or part of their own
	41	permissions to some users, particularly via capabilities but not only. All this
	42	is performed via configuration (sysctl, file-system permissions etc).
	43
	44	The Linux Kernel applies a certain collection of default settings that match
	45	its threat model. Distros have their own threat model and will come with their
	46	own configuration presets, that the administrator may have to adjust to better
	47	suit their expectations (relax or restrict).
	48
	49	By default, the Linux Kernel guarantees the following protections when running
	50	on common processors featuring privilege levels and memory management units:
	51
	52	* User-based isolation: an unprivileged user may restrict access to their
	53	own data from other unprivileged users running on the same system. This
	54	includes:
	55
	56	* stored data, via file system permissions
	57	* in-memory data (pages are not accessible by default to other users)
	58	* process activity (ptrace is not permitted to other users)
	59	* inter-process communication (other users may not observe data exchanged via
	60	UNIX domain sockets or other IPC mechanisms).
	61	* network communications within the same or with other systems
	62
	63	* Capability-based protection:
	64
	65	* users not having elevated capabilities (including but not limited to
	66	CAP_SYS_ADMIN) may not alter the
	67	kernel's configuration, memory nor state, change other users' view of the
	68	file system layout, grant any user capabilities they do not have, nor
	69	affect the system's availability (shutdown, reboot, panic, hang, or making
	70	the system unresponsive via unbounded resource exhaustion).
	71	* users not having the ``CAP_NET_ADMIN`` capability may not alter the network
	72	configuration, intercept nor spoof network communications from other users
	73	nor systems.
	74	* users not having ``CAP_SYS_PTRACE`` may not observe other users' processes
	75	activities.
	76
	77	When ``CONFIG_USER_NS`` is set, the kernel also permits unprivileged users to
	78	create their own user namespace in which they have all capabilities, but with a
	79	number of restrictions (they may not perform actions that have impacts on the
	80	initial user namespace, such as changing time, loading modules or mounting
	81	block devices). Please refer to ``user_namespaces(7)`` for more details, the
	82	possibilities of user namespaces are not covered in this document.
	83
	84	The kernel also offers a lot of troubleshooting and debugging facilities, which
	85	can constitute attack vectors when placed in wrong hands. While some of them
	86	are designed to be accessible to regular local users with a low risk (e.g.
	87	kernel logs via ``/proc/kmsg``), some would expose enough information to
	88	represent a risk in most places and the decision to expose them is under the
	89	administrator's responsibility (perf events, traces), and others are not
	90	designed to be accessed by non-privileged users (e.g. debugfs). Access to these
	91	facilities by a user who has been explicitly granted permission by an
	92	administrator does not constitute a security breach.
	93
	94	Bugs that permit to violate the principles above constitute security breaches.
	95	However, bugs that permit one violation only once another one was already
	96	achieved are only weaknesses. The kernel applies a number of self-protection
	97	measures whose purpose is to avoid crossing a security boundary when certain
	98	classes of bugs are found, but a failure of these extra protections do not
	99	constitute a vulnerability alone.
	100
	101	What does not constitute a security bug
	102	---------------------------------------
	103
	104	In the Linux kernel's threat model, the following classes of problems are
	105	NOT considered as Linux Kernel security bugs. However, when it is believed
	106	that the kernel could do better, they should be reported, so that they can be
	107	reviewed and fixed where reasonably possible, but they will be handled as any
	108	regular bug:
	109
	110	* Configuration:
	111
	112	* outdated kernels and particularly end-of-life branches are out of the scope
	113	of the kernel's threat model: administrators are responsible for keeping
	114	their system up to date. For a bug to qualify as a security bug, it must be
	115	demonstrated that it affects actively maintained versions.
	116
	117	* build-level: changes to the kernel configuration that are explicitly
	118	documented as lowering the security level (e.g. ``CONFIG_NOMMU``), or
	119	targeted at developers only.
	120
	121	* OS-level: changes to command line parameters, sysctls, filesystem
	122	permissions, user capabilities, exposure of privileged interfaces, that
	123	explicitly increase exposure by either offering non-default access to
	124	unprivileged users, or reduce the kernel's ability to enforce some
	125	protections or mitigations. Example: write access to procfs or debugfs.
	126
	127	* issues triggered only when using features intended for development or
	128	debugging (e.g., LOCKDEP, KASAN, FAULT_INJECTION): these features are known
	129	to introduce overhead and potential instability and are not intended for
	130	production use.
	131
	132	* issues affecting drivers exposed under CONFIG_STAGING, as well as features
	133	marked EXPERIMENTAL in the configuration.
	134
	135	* loading of explicitly insecure/broken/staging modules, and generally any
	136	using any subsystem marked as experimental or not intended for production
	137	use.
	138
	139	* running out-of-tree modules or unofficial kernel forks; these should be
	140	reported to the relevant vendor.
	141
	142	* Excess of initial privileges:
	143
	144	* actions performed by a user already possessing the privileges required to
	145	perform that action or modify that state (e.g. ``CAP_SYS_ADMIN``,
	146	``CAP_NET_ADMIN``, ``CAP_SYS_RAWIO``, ``CAP_SYS_MODULE`` with no further
	147	boundary being crossed).
	148
	149	* actions performed in user namespace that do not bypass the restrictions
	150	imposed to the initial user (e.g. ptrace usage, signal delivery, resource
	151	usage, access to FS/device/sysctl/memory, network binding, system/network
	152	configuration etc).
	153
	154	* anything performed by the root user in the initial namespace (e.g. kernel
	155	oops when writing to a privileged device).
	156
	157	* Out of production use:
	158
	159	This covers theoretical/probabilistic attacks that rely on laboratory
	160	conditions with zero system noise, or those requiring an unrealistic number
	161	of attempts (e.g., billions of trials) that would be detected by standard
	162	system monitoring long before success, such as:
	163
	164	* prediction of random numbers that only works in a totally silent
	165	environment (such as IP ID, TCP ports or sequence numbers that can only be
	166	guessed in a lab).
	167
	168	* activity observation and information leaks based on probabilistic
	169	approaches that are prone to measurement noise and not realistically
	170	reproducible on a production system.
	171
	172	* issues that can only be triggered by heavy attacks (e.g. brute force) whose
	173	impact on the system makes it unlikely or impossible to remain undetected
	174	before they succeed (e.g. consuming all memory before succeeding).
	175
	176	* problems seen only under development simulators, emulators, or combinations
	177	that do not exist on real systems at the time of reporting (issues
	178	involving tens of millions of threads, tens of thousands of CPUs,
	179	unrealistic CPU frequencies, RAM sizes or disk capacities, network speeds.
	180
	181	* issues whose reproduction requires hardware modification or emulation,
	182	including fake USB devices that pretend to be another one.
	183
	184	* as well as issues that can be triggered at a cost that is orders of
	185	magnitude higher than the expected benefits (e.g. fully functional keyboard
	186	emulator only to retrieve 7 uninitialized bytes in a structure, or
	187	brute-force method involving millions of connection attempts to guess a
	188	port number).
	189
	190	* Hardening failures:
	191
	192	* ability to bypass some of the kernel's hardening measures with no
	193	demonstrable exploit path (e.g. ASLR bypass, events timing or probing with
	194	no demonstrable consequence). These are just weaknesses, not
	195	vulnerabilities.
	196
	197	* missing argument checks and failure to report certain errors with no
	198	immediate consequence.
	199
	200	* Random information leaks:
	201
	202	This concerns information leaks of small data parts that happen to be there
	203	and that cannot be chosen by the attacker, or face access restrictions:
	204
	205	* structure padding reported by syscalls or other interfaces.
	206
	207	* identifiers, partial data, non-terminated strings reported in error
	208	messages.
	209
	210	* Leaks of kernel memory addresses/pointers do not constitute an immediately
	211	exploitable vector and are not security bugs, though they must be reported
	212	and fixed.
	213
	214	* Crafted file system images:
	215
	216	* bugs triggered by mounting a corrupted or maliciously crafted file system
	217	image are generally not security bugs, as the kernel assumes the underlying
	218	storage media is under the administrator's control, unless the filesystem
	219	driver is specifically documented as being hardened against untrusted media.
	220
	221	* issues that are resolved, mitigated, or detected by running a filesystem
	222	consistency check (fsck) on the image prior to mounting.
	223
	224	* Physical access:
	225
	226	Issues that require physical access to the machine, hardware modification, or
	227	the use of specialized hardware (e.g., logic analyzers, DMA-attack tools over
	228	PCI-E/Thunderbolt) are out of scope unless the system is explicitly
	229	configured with technologies meant to defend against such attacks
	230	(e.g. IOMMU).
	231
	232	* Functional and performance regressions:
	233
	234	Any issue that can be mitigated by setting proper permissions and limits
	235	doesn't qualify as a security bug.