diff --git a/docs/api/structures/web-preferences.md b/docs/api/structures/web-preferences.md index 26ead57c2329..a576a4b56802 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 7923077c69bd..6500aea6d537 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