diff --git a/docs/tutorial/security.md b/docs/tutorial/security.md index 598e0242aa8fe..55129495ca9d2 100644 --- a/docs/tutorial/security.md +++ b/docs/tutorial/security.md @@ -44,7 +44,7 @@ Chromium shared library and Node.js. Vulnerabilities affecting these components may impact the security of your application. By updating Electron to the latest version, you ensure that critical vulnerabilities (such as *nodeIntegration bypasses*) are already patched and cannot be exploited in your application. For more information, -see "[Use a current version of Electron](#15-use-a-current-version-of-electron)". +see "[Use a current version of Electron](#16-use-a-current-version-of-electron)". * **Evaluate your dependencies.** While NPM provides half a million reusable packages, it is your responsibility to choose trusted 3rd-party libraries. If you use outdated @@ -88,18 +88,19 @@ You should at least follow these steps to improve the security of your applicati 1. [Only load secure content](#1-only-load-secure-content) 2. [Disable the Node.js integration in all renderers that display remote content](#2-do-not-enable-nodejs-integration-for-remote-content) 3. [Enable context isolation in all renderers that display remote content](#3-enable-context-isolation-for-remote-content) -4. [Use `ses.setPermissionRequestHandler()` in all sessions that load remote content](#4-handle-session-permission-requests-from-remote-content) -5. [Do not disable `webSecurity`](#5-do-not-disable-websecurity) -6. [Define a `Content-Security-Policy`](#6-define-a-content-security-policy) and use restrictive rules (i.e. `script-src 'self'`) -7. [Do not set `allowRunningInsecureContent` to `true`](#7-do-not-set-allowrunninginsecurecontent-to-true) -8. [Do not enable experimental features](#8-do-not-enable-experimental-features) -9. [Do not use `enableBlinkFeatures`](#9-do-not-use-enableblinkfeatures) -10. [``: Do not use `allowpopups`](#10-do-not-use-allowpopups) -11. [``: Verify options and params](#11-verify-webview-options-before-creation) -12. [Disable or limit navigation](#12-disable-or-limit-navigation) -13. [Disable or limit creation of new windows](#13-disable-or-limit-creation-of-new-windows) -14. [Do not use `openExternal` with untrusted content](#14-do-not-use-openexternal-with-untrusted-content) -15. [Use a current version of Electron](#15-use-a-current-version-of-electron) +4. [Enable sandboxing](#4-enable-sandboxing) +5. [Use `ses.setPermissionRequestHandler()` in all sessions that load remote content](#5-handle-session-permission-requests-from-remote-content) +6. [Do not disable `webSecurity`](#6-do-not-disable-websecurity) +7. [Define a `Content-Security-Policy`](#7-define-a-content-security-policy) and use restrictive rules (i.e. `script-src 'self'`) +8. [Do not set `allowRunningInsecureContent` to `true`](#8-do-not-set-allowrunninginsecurecontent-to-true) +9. [Do not enable experimental features](#9-do-not-enable-experimental-features) +10. [Do not use `enableBlinkFeatures`](#10-do-not-use-enableblinkfeatures) +11. [``: Do not use `allowpopups`](#11-do-not-use-allowpopups) +12. [``: Verify options and params](#12-verify-webview-options-before-creation) +13. [Disable or limit navigation](#13-disable-or-limit-navigation) +14. [Disable or limit creation of new windows](#14-disable-or-limit-creation-of-new-windows) +15. [Do not use `openExternal` with untrusted content](#15-do-not-use-openexternal-with-untrusted-content) +16. [Use a current version of Electron](#16-use-a-current-version-of-electron) To automate the detection of misconfigurations and insecure patterns, it is possible to use @@ -239,7 +240,26 @@ and prevent the use of Node primitives `contextIsolation` **must** also be used. For more information on what `contextIsolation` is and how to enable it please see our dedicated [Context Isolation](context-isolation.md) document. -## 4) Handle Session Permission Requests From Remote Content +## 4) Enable Sandboxing + +[Sandboxing](sandbox.md) is a Chromium feature that uses the operating system to +significantly limit what renderer processes have access to. You should enable +the sandbox in all renderers. Loading, reading or processing any untrusted +content in an unsandboxed process, including the main process, is not advised. + +### How? + +When creating a window, pass the `sandbox: true` option in `webPreferences`: + +```js +const win = new BrowserWindow({ + webPreferences: { + sandbox: true + } +}) +``` + +## 5) Handle Session Permission Requests From Remote Content You may have seen permission requests while using Chrome: They pop up whenever the website attempts to use a feature that the user has to manually approve ( @@ -277,7 +297,7 @@ session }) ``` -## 5) Do Not Disable WebSecurity +## 6) Do Not Disable WebSecurity _Recommendation is Electron's default_ @@ -318,7 +338,7 @@ const mainWindow = new BrowserWindow() ``` -## 6) Define a Content Security Policy +## 7) Define a Content Security Policy A Content Security Policy (CSP) is an additional layer of protection against cross-site-scripting attacks and data injection attacks. We recommend that they @@ -374,7 +394,7 @@ on a page directly in the markup using a `` tag: ``` -## 7) Do Not Set `allowRunningInsecureContent` to `true` +## 8) Do Not Set `allowRunningInsecureContent` to `true` _Recommendation is Electron's default_ @@ -407,7 +427,7 @@ const mainWindow = new BrowserWindow({ const mainWindow = new BrowserWindow({}) ``` -## 8) Do Not Enable Experimental Features +## 9) Do Not Enable Experimental Features _Recommendation is Electron's default_ @@ -439,7 +459,7 @@ const mainWindow = new BrowserWindow({ const mainWindow = new BrowserWindow({}) ``` -## 9) Do Not Use `enableBlinkFeatures` +## 10) Do Not Use `enableBlinkFeatures` _Recommendation is Electron's default_ @@ -471,7 +491,7 @@ const mainWindow = new BrowserWindow({ const mainWindow = new BrowserWindow() ``` -## 10) Do Not Use `allowpopups` +## 11) Do Not Use `allowpopups` _Recommendation is Electron's default_ @@ -498,7 +518,7 @@ you know it needs that feature. ``` -## 11) Verify WebView Options Before Creation +## 12) Verify WebView Options Before Creation A WebView created in a renderer process that does not have Node.js integration enabled will not be able to enable integration itself. However, a WebView will @@ -545,7 +565,7 @@ app.on('web-contents-created', (event, contents) => { Again, this list merely minimizes the risk, it does not remove it. If your goal is to display a website, a browser will be a more secure option. -## 12) Disable or limit navigation +## 13) Disable or limit navigation If your app has no need to navigate or only needs to navigate to known pages, it is a good idea to limit navigation outright to that known scope, disallowing @@ -589,7 +609,7 @@ app.on('web-contents-created', (event, contents) => { }) ``` -## 13) Disable or limit creation of new windows +## 14) Disable or limit creation of new windows If you have a known set of windows, it's a good idea to limit the creation of additional windows in your app. @@ -636,7 +656,7 @@ app.on('web-contents-created', (event, contents) => { }) ``` -## 14) Do not use `openExternal` with untrusted content +## 15) Do not use `openExternal` with untrusted content Shell's [`openExternal`][open-external] allows opening a given protocol URI with the desktop's native utilities. On macOS, for instance, this function is similar @@ -663,7 +683,7 @@ const { shell } = require('electron') shell.openExternal('https://example.com/index.html') ``` -## 15) Use a current version of Electron +## 16) Use a current version of Electron You should strive for always using the latest available version of Electron. Whenever a new major version is released, you should attempt to update your