electron/docs/tutorial/security.md

139 lines
6.5 KiB
Markdown
Raw Normal View History

# Security, Native Capabilities, and Your Responsibility
As web developers, we usually enjoy the strong security net of the browser - the
risks associated with the code we write are relatively small. Our websites are
2016-05-08 18:21:11 +00:00
granted limited powers in a sandbox, and we trust that our users enjoy a browser
built by a large team of engineers that is able to quickly respond to newly
discovered security threats.
2016-05-08 18:21:11 +00:00
When working with Electron, it is important to understand that Electron is not
a web browser. It allows you to build feature-rich desktop applications with
familiar web technologies, but your code wields much greater power. JavaScript
2016-06-01 05:36:45 +00:00
can access the filesystem, user shell, and more. This allows you to build
2016-05-08 18:21:11 +00:00
high quality native applications, but the inherent security risks scale with the
additional powers granted to your code.
With that in mind, be aware that displaying arbitrary content from untrusted
2016-05-08 18:21:11 +00:00
sources poses a severe security risk that Electron is not intended to handle.
In fact, the most popular Electron apps (Atom, Slack, Visual Studio Code, etc)
display primarily local content (or trusted, secure remote content without Node
integration) if your application executes code from an online source, it is
your responsibility to ensure that the code is not malicious.
2017-01-30 18:57:53 +00:00
## Reporting Security Issues
2017-01-30 18:49:17 +00:00
For information on how to properly disclose an Electron vulnerability,
see [SECURITY.md](https://github.com/electron/electron/tree/master/SECURITY.md)
## Chromium Security Issues and Upgrades
While Electron strives to support new versions of Chromium as soon as possible,
developers should be aware that upgrading is a serious undertaking - involving
hand-editing dozens or even hundreds of files. Given the resources and
contributions available today, Electron will often not be on the very latest
version of Chromium, lagging behind by either days or weeks.
We feel that our current system of updating the Chromium component strikes an
appropriate balance between the resources we have available and the needs of the
majority of applications built on top of the framework. We definitely are
interested in hearing more about specific use cases from the people that build
things on top of Electron. Pull requests and contributions supporting this
effort are always very welcome.
## Ignoring Above Advice
2016-09-08 17:39:29 +00:00
A security issue exists whenever you receive code from a remote destination and
execute it locally. As an example, consider a remote website being displayed
inside a browser window. If an attacker somehow manages to change said content
(either by attacking the source directly, or by sitting between your app and
the actual destination), they will be able to execute native code on the user's
machine.
> :warning: Under no circumstances should you load and execute remote code with
2016-05-08 18:21:11 +00:00
Node integration enabled. Instead, use only local files (packaged together with
your application) to execute Node code. To display remote content, use the
`webview` tag and make sure to disable the `nodeIntegration`.
2018-01-29 00:55:11 +00:00
#### Checklist: Security Recommendations
2016-09-08 17:39:29 +00:00
This is not bulletproof, but at the least, you should attempt the following:
2018-01-29 00:55:11 +00:00
* [Only display secure (https) content](#only-display-secure-content)
* Disable the Node integration in all renderers that display remote content
2017-01-09 17:25:34 +00:00
(setting `nodeIntegration` to `false` in `webPreferences`)
2017-01-20 14:45:39 +00:00
* Enable context isolation in all renderers that display remote content
2017-01-09 17:25:34 +00:00
(setting `contextIsolation` to `true` in `webPreferences`)
* Use `ses.setPermissionRequestHandler()` in all sessions that load remote content
* Do not disable `webSecurity`. Disabling it will disable the same-origin policy.
2016-05-08 18:21:11 +00:00
* Define a [`Content-Security-Policy`](http://www.html5rocks.com/en/tutorials/security/content-security-policy/)
2016-06-16 22:19:38 +00:00
, and use restrictive rules (i.e. `script-src 'self'`)
* [Override and disable `eval`](https://github.com/nylas/N1/blob/0abc5d5defcdb057120d726b271933425b75b415/static/index.js#L6-L8)
2016-05-08 18:21:11 +00:00
, which allows strings to be executed as code.
* Do not set `allowRunningInsecureContent` to true.
* Do not enable `experimentalFeatures` or `experimentalCanvasFeatures` unless
you know what you're doing.
* Do not use `blinkFeatures` unless you know what you're doing.
* WebViews: Do not add the `nodeintegration` attribute.
* WebViews: Do not use `disablewebsecurity`
* WebViews: Do not use `allowpopups`
* WebViews: Do not use `insertCSS` or `executeJavaScript` with remote CSS/JS.
* WebViews: Verify the options and params of all `<webview>` tags before they
get attached using the `will-attach-webview` event:
```js
app.on('web-contents-created', (event, contents) => {
contents.on('will-attach-webview', (event, webPreferences, params) => {
// Strip away preload scripts if unused or verify their location is legitimate
delete webPreferences.preload
delete webPreferences.preloadURL
// Disable node integration
webPreferences.nodeIntegration = false
// Verify URL being loaded
if (!params.src.startsWith('https://yourapp.com/')) {
event.preventDefault()
}
})
})
```
2018-01-29 00:55:11 +00:00
## Only Display Secure Content
Any resources not included with your application should be loaded using a secure protocol
like `HTTPS`. Furthermore, avoid "mixed content", which occurs when the initial HTML is
loaded over an `HTTPS` connection, but additional resources (scripts, stylesheets, etc)
are loaded over an insecure connection.
#### Why?
`HTTPS` has three main benefits:
1) It authenticates the remote server, ensuring that the host is actually who it claims
to be. When loading a resource from an `HTTPS` host, it prevents an attacker from
impersonating that host, thus ensuring that the computer your app's users are
connecting to is actually the host you wanted them to connect to.
2) It ensures data integrity, asserting that the data was not modified while in transit
between your application and the host.
3) It encryps the traffic between your user and the destination host, making it more
difficult to eavesdropping on the information sent between your app and the host.
```js
// Bad
browserWindow.loadURL('http://my-website.com')
// Good
browserWindow.loadURL('https://my-website.com')
```
```html
<!-- Bad -->
<script crossorigin src="http://cdn.com/react.js"></script>
<link rel="stylesheet" href="http://cdn.com/style.css">
<!-- Good -->
<script crossorigin src="https://cdn.com/react.js"></script>
<link rel="stylesheet" href="https://cdn.com/style.css">
```
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.