docs: update sandbox-option.md (#17468)
* docs: update sandbox-option.md * Update docs/api/sandbox-option.md Co-Authored-By: miniak <milan.burda@gmail.com>
This commit is contained in:
Milan Burda
Alexey Kuzmin
parent
b25279df89
commit
07b02653ba
2 changed files with 12 additions and 35 deletions
|
|
@ -1240,7 +1240,7 @@ Returns `String` - The command-line switch value.
|
|||
|
||||
**Note:** When the switch is not present or has no value, it returns empty string.
|
||||
|
||||
### `app.enableSandbox()` _Experimental_ _macOS_ _Windows_
|
||||
### `app.enableSandbox()` _Experimental_
|
||||
|
||||
Enables full sandbox mode on the app.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,7 @@
|
|||
# `sandbox` Option
|
||||
|
||||
> Create a browser window with a renderer that can run inside Chromium OS sandbox. With this
|
||||
> Create a browser window with a sandboxed renderer. With this
|
||||
option enabled, the renderer must communicate via IPC to the main process in order to access node APIs.
|
||||
However, in order to enable the Chromium OS sandbox, Electron must be run with the `--enable-sandbox`
|
||||
command line argument.
|
||||
|
||||
One of the key security features of Chromium is that all blink rendering/JavaScript
|
||||
code is executed within a sandbox. This sandbox uses OS-specific features to ensure
|
||||
|
|
@ -56,36 +54,18 @@ only via IPC. The use of this option stops Electron from creating a Node.js runt
|
|||
within this new window `window.open` follows the native behaviour (by default Electron creates a [`BrowserWindow`](browser-window.md)
|
||||
and returns a proxy to this via `window.open`).
|
||||
|
||||
It is important to note that this option alone won't enable the OS-enforced sandbox. To enable this feature, the
|
||||
`--enable-sandbox` command-line argument must be passed to electron, which will
|
||||
force `sandbox: true` for all `BrowserWindow` instances.
|
||||
[`app.enableSandbox`](app.md#appenablesandbox-experimental) can be used to force `sandbox: true` for all `BrowserWindow` instances.
|
||||
|
||||
```js
|
||||
let win
|
||||
app.enableSandbox()
|
||||
app.on('ready', () => {
|
||||
// no need to pass `sandbox: true` since `--enable-sandbox` was enabled.
|
||||
// no need to pass `sandbox: true` since `app.enableSandbox()` was called.
|
||||
win = new BrowserWindow()
|
||||
win.loadURL('http://google.com')
|
||||
})
|
||||
```
|
||||
|
||||
Note that it is not enough to call
|
||||
`app.commandLine.appendSwitch('--enable-sandbox')`, as electron/node startup
|
||||
code runs after it is possible to make changes to Chromium sandbox settings. The
|
||||
switch must be passed to Electron on the command-line:
|
||||
|
||||
```sh
|
||||
electron --enable-sandbox app.js
|
||||
```
|
||||
|
||||
It is not possible to have the OS sandbox active only for some renderers, if
|
||||
`--enable-sandbox` is enabled, normal Electron windows cannot be created.
|
||||
|
||||
If you need to mix sandboxed and non-sandboxed renderers in one application,
|
||||
omit the `--enable-sandbox` argument. Without this argument, windows
|
||||
created with `sandbox: true` will still have Node.js disabled and communicate
|
||||
only via IPC, which by itself is already a gain from security POV.
|
||||
|
||||
## Preload
|
||||
|
||||
An app can make customizations to sandboxed renderers using a preload script.
|
||||
|
|
@ -110,8 +90,8 @@ and preload.js:
|
|||
// This file is loaded whenever a javascript context is created. It runs in a
|
||||
// private scope that can access a subset of Electron renderer APIs. We must be
|
||||
// careful to not leak any objects into the global scope!
|
||||
const fs = require('fs')
|
||||
const { ipcRenderer } = require('electron')
|
||||
const { ipcRenderer, remote } = require('electron')
|
||||
const fs = remote.require('fs')
|
||||
|
||||
// read a configuration file using the `fs` module
|
||||
const buf = fs.readFileSync('allowed-popup-urls.json')
|
||||
|
|
@ -136,9 +116,7 @@ Important things to notice in the preload script:
|
|||
access to a limited node-like environment: `Buffer`, `process`, `setImmediate`
|
||||
and `require` are available.
|
||||
- The preload script can indirectly access all APIs from the main process through the
|
||||
`remote` and `ipcRenderer` modules. This is how `fs` (used above) and other
|
||||
modules are implemented: They are proxies to remote counterparts in the main
|
||||
process.
|
||||
`remote` and `ipcRenderer` modules.
|
||||
- The preload script must be contained in a single script, but it is possible to have
|
||||
complex preload code composed with multiple modules by using a tool like
|
||||
browserify, as explained below. In fact, browserify is already used by
|
||||
|
|
@ -150,7 +128,6 @@ the following should be used:
|
|||
```sh
|
||||
browserify preload/index.js \
|
||||
-x electron \
|
||||
-x fs \
|
||||
--insert-global-vars=__filename,__dirname -o preload.js
|
||||
```
|
||||
|
||||
|
|
@ -163,14 +140,14 @@ injects code for those).
|
|||
Currently the `require` function provided in the preload scope exposes the
|
||||
following modules:
|
||||
|
||||
- `child_process`
|
||||
- `electron`
|
||||
- `crashReporter`
|
||||
- `remote`
|
||||
- `desktopCapturer`
|
||||
- `ipcRenderer`
|
||||
- `nativeImage`
|
||||
- `remote`
|
||||
- `webFrame`
|
||||
- `fs`
|
||||
- `os`
|
||||
- `events`
|
||||
- `timers`
|
||||
- `url`
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue