Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: mention sandboxing in security docs #30191

Merged
merged 3 commits into from Aug 2, 2021
Merged

docs: mention sandboxing in security docs #30191

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a149859
docs: mention sandboxing in security docs
nornagon Jul 14, 2021
99226de
link to sandboxing tutorial
nornagon Jul 19, 2021
265f7a3
Update security.md
nornagon Jul 19, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
70 changes: 45 additions & 25 deletions docs/tutorial/security.md
View file
Open in desktop
Expand Up @@ -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
Expand Down Expand Up @@ -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. [`<webview>`: Do not use `allowpopups`](#10-do-not-use-allowpopups)
11. [`<webview>`: 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. [`<webview>`: Do not use `allowpopups`](#11-do-not-use-allowpopups)
12. [`<webview>`: 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
Expand Down Expand Up @@ -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 (
Expand Down Expand Up @@ -277,7 +297,7 @@ session
})
```

## 5) Do Not Disable WebSecurity
## 6) Do Not Disable WebSecurity

_Recommendation is Electron's default_

Expand Down Expand Up @@ -318,7 +338,7 @@ const mainWindow = new BrowserWindow()
<webview src="page.html"></webview>
```

## 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
Expand Down Expand Up @@ -374,7 +394,7 @@ on a page directly in the markup using a `<meta>` tag:
<meta http-equiv="Content-Security-Policy" content="default-src 'none'">
```

## 7) Do Not Set `allowRunningInsecureContent` to `true`
## 8) Do Not Set `allowRunningInsecureContent` to `true`

_Recommendation is Electron's default_

Expand Down Expand Up @@ -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_

Expand Down Expand Up @@ -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_

Expand Down Expand Up @@ -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_

Expand All @@ -498,7 +518,7 @@ you know it needs that feature.
<webview src="page.html"></webview>
```

## 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down