diff --git a/docs/latest/.sha b/docs/latest/.sha index 35f47bbc4..0ad5151fa 100644 --- a/docs/latest/.sha +++ b/docs/latest/.sha @@ -1 +1 @@ -5e29e21a6019d5e222f8e67c7b5f7b51538b0125 \ No newline at end of file +d14320748df1c868437b413083846302660c5804 \ No newline at end of file diff --git a/docs/latest/api/structures/web-preferences.md b/docs/latest/api/structures/web-preferences.md index 4b9f8a328..d3a3d5009 100644 --- a/docs/latest/api/structures/web-preferences.md +++ b/docs/latest/api/structures/web-preferences.md @@ -28,7 +28,9 @@ hide_title: false 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/latest/tutorial/sandbox.md b/docs/latest/tutorial/sandbox.md index b5e8f36c9..a590d3d94 100644 --- a/docs/latest/tutorial/sandbox.md +++ b/docs/latest/tutorial/sandbox.md @@ -20,7 +20,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. @@ -105,7 +111,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(() => { @@ -118,6 +125,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/latest/tutorial/security.md b/docs/latest/tutorial/security.md index d599ca8fa..ef1353d73 100644 --- a/docs/latest/tutorial/security.md +++ b/docs/latest/tutorial/security.md @@ -254,6 +254,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 @@ -263,6 +267,18 @@ 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