From 89e2fe207915b820232c2bb20b855135794fc40b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ant=C3=B3n=20Molleda?= Date: Tue, 30 Mar 2021 11:53:10 -0700 Subject: [PATCH] docs: backport current tutorials to 13-x-y (#28397) --- docs/README.md | 1 - docs/breaking-changes.md | 3 + docs/development/issues.md | 3 +- docs/tutorial/quick-start.md | 3 +- docs/tutorial/security.md | 135 +----------------- docs/tutorial/using-selenium-and-webdriver.md | 4 +- 6 files changed, 11 insertions(+), 138 deletions(-) diff --git a/docs/README.md b/docs/README.md index e4d83c83f8..9db83ed151 100644 --- a/docs/README.md +++ b/docs/README.md @@ -145,7 +145,6 @@ These individual tutorials expand on topics discussed in the guide above. * [contextBridge](api/context-bridge.md) * [ipcRenderer](api/ipc-renderer.md) -* [remote](api/remote.md) * [webFrame](api/web-frame.md) ### Modules for Both Processes: diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index f3128cf335..23c0c9cf09 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -160,6 +160,9 @@ the previous behavior, `contextIsolation: false` must be specified in WebPrefere We [recommend having contextIsolation enabled](https://github.com/electron/electron/blob/master/docs/tutorial/security.md#3-enable-context-isolation-for-remote-content) for the security of your application. +Another implication is that `require()` cannot be used in the renderer process unless +`nodeIntegration` is `true` and `contextIsolation` is `false`. + For more details see: https://github.com/electron/electron/issues/23506 ### Removed: `crashReporter.getCrashesDirectory()` diff --git a/docs/development/issues.md b/docs/development/issues.md index 7478433cdd..ec0ad5dc04 100644 --- a/docs/development/issues.md +++ b/docs/development/issues.md @@ -33,8 +33,7 @@ contributing, and more. Please use the issue tracker for bugs only! To submit a bug report: When opening a new issue in the [`electron/electron` issue tracker](https://github.com/electron/electron/issues/new/choose), users -will be presented with [a template](https://github.com/electron/electron/blob/master/.github/ISSUE_TEMPLATE/Bug_report.md) -that should be filled in. +will be presented with a template that should be filled in. If you believe that you have found a bug in Electron, please fill out the template to the best of your ability. diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index e564d9e2ac..4c7c078806 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -196,7 +196,8 @@ The simplest and the fastest way to distribute your newly created app is using 1. Import Electron Forge to your app folder: ```sh - npx @electron-forge/cli import + npm install --save-dev @electron-forge/cli + npx electron-forge import ✔ Checking your system ✔ Initializing Git Repository diff --git a/docs/tutorial/security.md b/docs/tutorial/security.md index 4667b26e64..f22de2a6be 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](#17-use-a-current-version-of-electron)". +see "[Use a current version of Electron](#15-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 @@ -99,9 +99,7 @@ You should at least follow these steps to improve the security of your applicati 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. [Disable the `remote` module](#15-disable-the-remote-module) -16. [Filter the `remote` module](#16-filter-the-remote-module) -17. [Use a current version of Electron](#17-use-a-current-version-of-electron) +15. [Use a current version of Electron](#15-use-a-current-version-of-electron) To automate the detection of misconfigurations and insecure patterns, it is possible to use @@ -665,134 +663,7 @@ const { shell } = require('electron') shell.openExternal('https://example.com/index.html') ``` -## 15) Disable the `remote` module - -The `remote` module provides a way for the renderer processes to -access APIs normally only available in the main process. Using it, a -renderer can invoke methods of a main process object without explicitly sending -inter-process messages. If your desktop application does not run untrusted -content, this can be a useful way to have your renderer processes access and -work with modules that are only available to the main process, such as -GUI-related modules (dialogs, menus, etc.). - -However, if your app can run untrusted content and even if you -[sandbox][sandbox] your renderer processes accordingly, the `remote` module -makes it easy for malicious code to escape the sandbox and have access to -system resources via the higher privileges of the main process. Therefore, -it should be disabled in such circumstances. - -### Why? - -`remote` uses an internal IPC channel to communicate with the main process. -"Prototype pollution" attacks can grant malicious code access to the internal -IPC channel, which can then be used to escape the sandbox by mimicking `remote` -IPC messages and getting access to main process modules running with higher -privileges. - -Additionally, it's possible for preload scripts to accidentally leak modules to a -sandboxed renderer. Leaking `remote` arms malicious code with a multitude -of main process modules with which to perform an attack. - -Disabling the `remote` module eliminates these attack vectors. Enabling -context isolation also prevents the "prototype pollution" attacks from -succeeding. - -### How? - -```js -// Bad if the renderer can run untrusted content -const mainWindow = new BrowserWindow({ - webPreferences: { - enableRemoteModule: true - } -}) -``` - -```js -// Good -const mainWindow = new BrowserWindow({ - webPreferences: { - enableRemoteModule: false - } -}) -``` - -```html - - - - - -``` - -> **Note:** The default value of `enableRemoteModule` is `false` starting -> from Electron 10. For prior versions, you need to explicitly disable -> the `remote` module by the means above. - -## 16) Filter the `remote` module - -If you cannot disable the `remote` module, you should filter the globals, -Node, and Electron modules (so-called built-ins) accessible via `remote` -that your application does not require. This can be done by blocking -certain modules entirely and by replacing others with proxies that -expose only the functionality that your app needs. - -### Why? - -Due to the system access privileges of the main process, functionality -provided by the main process modules may be dangerous in the hands of -malicious code running in a compromised renderer process. By limiting -the set of accessible modules to the minimum that your app needs and -filtering out the others, you reduce the toolset that malicious code -can use to attack the system. - -Note that the safest option is to -[fully disable the remote module](#15-disable-the-remote-module). If -you choose to filter access rather than completely disable the module, -you must be very careful to ensure that no escalation of privilege is -possible through the modules you allow past the filter. - -### How? - -```js -const readOnlyFsProxy = require(/* ... */) // exposes only file read functionality - -const allowedModules = new Set(['crypto']) -const proxiedModules = new Map([['fs', readOnlyFsProxy]]) -const allowedElectronModules = new Set(['shell']) -const allowedGlobals = new Set() - -app.on('remote-require', (event, webContents, moduleName) => { - if (proxiedModules.has(moduleName)) { - event.returnValue = proxiedModules.get(moduleName) - } - if (!allowedModules.has(moduleName)) { - event.preventDefault() - } -}) - -app.on('remote-get-builtin', (event, webContents, moduleName) => { - if (!allowedElectronModules.has(moduleName)) { - event.preventDefault() - } -}) - -app.on('remote-get-global', (event, webContents, globalName) => { - if (!allowedGlobals.has(globalName)) { - event.preventDefault() - } -}) - -app.on('remote-get-current-window', (event, webContents) => { - event.preventDefault() -}) - -app.on('remote-get-current-web-contents', (event, webContents) => { - event.preventDefault() -}) -``` - -## 17) Use a current version of Electron +## 15) 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 diff --git a/docs/tutorial/using-selenium-and-webdriver.md b/docs/tutorial/using-selenium-and-webdriver.md index 61ff0e1cb4..197c29a5ff 100644 --- a/docs/tutorial/using-selenium-and-webdriver.md +++ b/docs/tutorial/using-selenium-and-webdriver.md @@ -86,12 +86,12 @@ const driver = new webdriver.Builder() // The "9515" is the port opened by chrome driver. .usingServer('http://localhost:9515') .withCapabilities({ - chromeOptions: { + 'goog:chromeOptions': { // Here is the path to your Electron binary. binary: '/Path-to-Your-App.app/Contents/MacOS/Electron' } }) - .forBrowser('electron') + .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0 .build() driver.get('http://www.google.com')