From 7319e5c18be54fdbb9bed61df68475c2f1ce9cc7 Mon Sep 17 00:00:00 2001 From: "trop[bot]" <37223003+trop[bot]@users.noreply.github.com> Date: Fri, 24 Oct 2025 11:16:15 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20security.md=20mark=20'Enable=20process?= =?UTF-8?q?=20sandboxing'=20as=20active=20by=20defau=E2=80=A6=20(#48647)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: security.md mark 'Enable process sandboxing' as active by default since electron 20 Co-authored-by: LeUser111 * Adjusted according to feedback Co-authored-by: LeUser111 * Updated according to feedback - adjusted sandbox.md Co-authored-by: LeUser111 * formatting Co-authored-by: LeUser111 * Fixed broken markup Co-authored-by: LeUser111 * Implemented docs linting suggestions Co-authored-by: LeUser111 * docs: docs/tutorial/sandbox.md - fixed typo Co-authored-by: Erick Zhao Co-authored-by: Teaveloper <49181620+LeUser111@users.noreply.github.com> * docs: web-preferences.md - sandbox: mention default value and relation to nodeIntegration Co-authored-by: LeUser111 --------- Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com> Co-authored-by: LeUser111 Co-authored-by: Teaveloper <49181620+LeUser111@users.noreply.github.com> --- docs/api/structures/web-preferences.md | 4 +++- docs/tutorial/sandbox.md | 15 +++++++++++++-- docs/tutorial/security.md | 14 ++++++++++++++ 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/api/structures/web-preferences.md b/docs/api/structures/web-preferences.md index b0ca4cc1090c..ceb55730148e 100644 --- a/docs/api/structures/web-preferences.md +++ b/docs/api/structures/web-preferences.md @@ -21,7 +21,9 @@ associated with the window, making it compatible with the Chromium OS-level sandbox and disabling the Node.js engine. This is not the same as the `nodeIntegration` option and the APIs available to the preload script - are more limited. Read more about the option [here](../../tutorial/sandbox.md). + are more limited. Default is `true` since Electron 20. The sandbox will + automatically be disabled when `nodeIntegration` is set to `true`. + Read more about the option [here](../../tutorial/sandbox.md). * `session` [Session](../session.md#class-session) (optional) - Sets the session used by the page. Instead of passing the Session object directly, you can also choose to use the `partition` option instead, which accepts a partition string. When diff --git a/docs/tutorial/sandbox.md b/docs/tutorial/sandbox.md index 2580f1d92bc5..cbc0d13ae3ed 100644 --- a/docs/tutorial/sandbox.md +++ b/docs/tutorial/sandbox.md @@ -13,7 +13,13 @@ the GPU service and the network service. See Chromium's [Sandbox design document][sandbox] for more information. Starting from Electron 20, the sandbox is enabled for renderer processes without any -further configuration. If you want to disable the sandbox for a process, see the +further configuration. + +Sandboxing is tied to Node.js integration. _Enabling Node.js integration_ for a +renderer process by setting `nodeIntegration: true` _disables the sandbox_ for the +process. + +If you want to disable the sandbox for a process, see the [Disabling the sandbox for a single process](#disabling-the-sandbox-for-a-single-process) section. @@ -98,7 +104,8 @@ app.whenReady().then(() => { ``` Sandboxing is also disabled whenever Node.js integration is enabled in the renderer. -This can be done through the BrowserWindow constructor with the `nodeIntegration: true` flag. +This can be done through the BrowserWindow constructor with the `nodeIntegration: true` flag +or by providing the respective HTML boolean attribute for a `webview`. ```js title='main.js' app.whenReady().then(() => { @@ -111,6 +118,10 @@ app.whenReady().then(() => { }) ``` +```html title='index.html (Renderer Process)' + +``` + ### Enabling the sandbox globally If you want to force sandboxing for all renderers, you can also use the diff --git a/docs/tutorial/security.md b/docs/tutorial/security.md index f7dcd3ebe5b8..3bbbd139dae7 100644 --- a/docs/tutorial/security.md +++ b/docs/tutorial/security.md @@ -244,6 +244,10 @@ to enable this behavior. Even when `nodeIntegration: false` is used, to truly enforce strong isolation and prevent the use of Node primitives `contextIsolation` **must** also be used. +Beware that _disabling context isolation_ for a renderer process by setting +`nodeIntegration: true` _also disables process sandboxing_ for that process. +See section below. + :::info For more information on what `contextIsolation` is and how to enable it please see our dedicated [Context Isolation](context-isolation.md) document. @@ -251,6 +255,16 @@ see our dedicated [Context Isolation](context-isolation.md) document. ### 4. Enable process sandboxing +:::info +This recommendation is the default behavior in Electron since 20.0.0. + +Additionally, process sandboxing can be enforced for all renderer processes +application wide: [Enabling the sandbox globally](sandbox.md#enabling-the-sandbox-globally) + +_Disabling context isolation_ (see above) _also disables process sandboxing_, +regardless of the default, `sandbox: false` or globally enabled sandboxing! +::: + [Sandboxing](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/design/sandbox.md) is a Chromium feature that uses the operating system to significantly limit what renderer processes have access to. You should enable