add full docs for new security flag
MODIFY
commands-yml/commands/mobile-command.yml
commands-yml/commands/mobile-command.yml
### Android
| Command | Description | Argument | Argument Example |
| ------- | ----------- | -------- | ---------------- |
- | mobile:shell | Execute [ADB shell](https://developer.android.com/studio/command-line/adb#shellcommands) commands (requires [server flag](/docs/en/writing-running-appium/server-args.md#server-flags) `--relaxed-security` to be set) | ADB shell string | `am start -n com.example.demo/com.example.test.MainActivity` |
+ | mobile:shell | Execute [ADB shell](https://developer.android.com/studio/command-line/adb#shellcommands) commands (requires [insecure feature](/docs/en/writing-running-appium/security.md) `adb_shell` to be enabled) | ADB shell string | `am start -n com.example.demo/com.example.test.MainActivity` |
| mobile:startLogsBroadcast | Starts Android logcat broadcast websocket on the same host and port where Appium is running at `/ws/session/:sessionId:/appium/device/logcat` endpoint | <none> | <none> |
| mobile:stopLogsBroadcast | Stops the logcat broadcasting websocket server started by `mobile:startLogsBroadcast` | <none> | <none> |
| mobile:performEditorAction | Performs the given editor action on the focused input field. The following action names are supported: `normal, unspecified, none, go, search, send, next, done, previous`. | `{action}` | `{action: "previous"}`|

MODIFY
docs/en/writing-running-appium/ios/ios-xctest-performance.md
docs/en/writing-running-appium/ios/ios-xctest-performance.md
@@ -7,7 +7,7 @@ Apple provides the `instruments` tool with quite a rich set of features for desk
This command starts the performance recorder for the given profile name (template) on the device under test. In case this command is called two or more times in a row then the previous recorder will be forcefully stopped and the new one will start. All the previous data will be lost.
-Important: It is expected, that `--relaxed-security` command line parameter is set for the Appium server command line in order to measure Simulator performance, since the `instruments` tool records the data from all running processes on the host machine.
+Important: It is expected that the appropriate [security flag](/docs/en/writing-running-appium/security.md) is set from the Appium server command line in order to measure Simulator performance, since the `instruments` tool records the data from all running processes on the host machine.
#### Supported arguments
@@ -30,7 +30,7 @@ driver.executeScript("mobile: startPerfRecord", args);
This command stops performance recorder for the given profile name (template) on the device under test and returns the collected data in zipped format or uploads it to a remote server. An exception will be thrown if `startPerfRecord` command has not been invoked before.
-Important: It is expected, that `--relaxed-security` command line parameter is set for the Appium server command line in order to meassure Simulator performance, since the `instruments` tool records the data from all running processes on the host machine.
+Important: It is expected that the appropriate [security flag](/docs/en/writing-running-appium/security.md) is set from the Appium server command line in order to measure Simulator performance, since the `instruments` tool records the data from all running processes on the host machine.
#### Supported arguments

ADD
docs/en/writing-running-appium/security.md
+# Security
+
+The Appium team makes every effort to ensure the security of the Appium server. This is especially important when Appium is run in a multitenant environment, or when multiple users are running sessions on the same Appium server. In general, if you're running your own Appium server locally, and not sharing it with anyone else, and don't expose Appium's port to the wider internet, you should have nothing to worry about, and can safely enable all Appium's features.
+
+But because many Appium users might not be able to guarantee such a safe environment, the Appium team puts many features behind a security protection mechanism which forces system admins (the people that are in charge of starting the Appium server) to opt-in to these features explicitly.
+
+For security reasons, Appium client sessions can _not_ request feature enablement via capabilities. This is the responsibility of the one who launches the Appium server.
+
+## Security Server Args
+
+The [server args](/docs/en/writing-running-appium/server-args.md) doc outlines three relevant arguments which may be passed to Appium when starting it from the command line:
+
+* `--relaxed-security`: Setting this flag turns on _all_ insecure features (unless blocked by `--deny-insecure`; see below)
+* `--allow-insecure`: Setting this flag to a comma-separated list of feature names or a path to a file containing a feature list (each name on a separate line) will allow _only_ the features listed. For example, `--allow-insecure=adb_shell` will cause _only_ the ADB shell execution feature to be enabled. This is true _unless_ `--relaxed-security` is also used, in which case all features will still be enabled. It makes no sense to combine this flag with `--relaxed-security`.
+* `--deny-insecure`: This flag can likewise be set to a comma-separated list of feature names, or a path to a feature file. Any features listed here will be _disabled_, regardless of whether `--relaxed-security` is set and regardless of whether the names are also listed with `--allow-insecure`.
+
+## Insecure Features
+
+Each Appium driver is responsible for its own security, and can create its own feature names. These are the features and names we know about for the officially-supported Appium drivers.
+
+|Feature Name|Description|Support|
+|------------|-----------|-------|
+|`get_server_logs`|Allows retrieving of Appium server logs via the Webdriver log interface|IOSDriver, XCUITestDriver, AndroidDriver, UiAutomator2Driver, EspressoDriver|
+|`adb_shell`|Allows execution of arbitrary shell commands via ADB, using the `mobile: shell` command|AndroidDriver, UiAutomator2Driver, EspressoDriver|
+|`shutdown_other_sims`|Allow any session to use a capability to shutdown any running simulators on the host|XCUITestDriver|
+|`perf_record`|Allow recording the system performance and other metrics of the simulator|XCUITestDriver|

MODIFY
docs/en/writing-running-appium/server-args.md
docs/en/writing-running-appium/server-args.md
# Appium server arguments
-Many Appium 1.5 server arguments have been deprecated in favor of the [--default-capabilities flag](/docs/en/writing-running-appium/default-capabilities-arg.md).
+Since Appium 1.5, many server arguments have been deprecated in favor of the [--default-capabilities flag](/docs/en/writing-running-appium/default-capabilities-arg.md).
Usage: `node . [flags]`
@@ -92,6 +92,6 @@ All flags are optional, but some are required in conjunction with certain others
|`--keep-keychains`|false|[DEPRECATED] - (iOS-only) Whether to keep keychains (Library/Keychains) when reset app between sessions||
|`--localizable-strings-dir`|en.lproj|[DEPRECATED] - (IOS-only) the relative path of the dir where Localizable.strings file resides |`--localizable-strings-dir en.lproj`|
|`--show-ios-log`|false|[DEPRECATED] - (IOS-only) if set, the iOS system log will be written to the console||
-|`--relaxed-security`|false|Disable additional security checks, so it is possible to use some advanced features, provided by drivers supporting this option. Only enable it if all the clients are in the trusted network and it is not the case if a client could potentially break out of the session sandbox.||
-|`--allow-insecure`|[]|Allow a list of features which are considered insecure and must be turned on explicitly by system administrators. Feature names are documented by the relevant server/driver. Should be a comma-separated list, or a path to a filename containing one feature name per line. Features listed in --deny-insecure will override anything listed here.|`--allow-insecure=foo,bar`|
-|`--deny-insecure`|[]|Specify a list of features which will never be allowed to run, even if --relaxed-security is turned on, and even if feature names are listed with --allow-insecure. Should be a comma-separated list, or a path to a filename containing one feature name per line.|`--deny-insecure=foo,bar`|
+|`--relaxed-security`|false|Disable additional security checks, so it is possible to use some advanced features, provided by drivers supporting this option. Only enable it if all the clients are in the trusted network and it is not the case if a client could potentially break out of the session sandbox. Can override enabling of specific features with --deny-insecure. See also the [security doc](/docs/en/writing-running-appium/security.md)||
+|`--allow-insecure`|[]|Allow a list of features which are considered insecure and must be turned on explicitly by system administrators. Feature names are documented by the relevant server/driver. Should be a comma-separated list, or a path to a filename containing one feature name per line. Features listed in --deny-insecure will override anything listed here. Does not make sense to use in conjunction with --relaxed-security. See also the [security doc](/docs/en/writing-running-appium/security.md)|`--allow-insecure=foo,bar`|
+|`--deny-insecure`|[]|Specify a list of features which will never be allowed to run, even if --relaxed-security is turned on, and even if feature names are listed with --allow-insecure. Should be a comma-separated list, or a path to a filename containing one feature name per line. See also the [security doc](/docs/en/writing-running-appium/security.md)|`--deny-insecure=foo,bar`|

MODIFY
docs/toc.js
docs/toc.js
@@ -226,6 +226,7 @@ module.exports = {
['Finding Elements', 'finding-elements.md'],
['Touch Actions', 'touch-actions.md'],
['CLI Arguments', 'server-args.md'],
+ ['Server Security', 'security.md'],
['Web/Web Views', ['web',
['Mobile Web Testing', 'mobile-web.md'],
['Automating Hybrid Apps', 'hybrid.md'],

MODIFY
lib/appium.js
lib/appium.js
@@ -177,11 +177,6 @@ class AppiumDriver extends BaseDriver {
// It is not recommended to access this property directly from the outside
this.pendingDrivers = {};
- // initialize security modes
- this.relaxedSecurityEnabled = false;
- this.allowInsecure = [];
- this.denyInsecure = [];
-
// allow this to happen in the background, so no `await`
updateBuildInfo();
}

MODIFY
lib/parser.js
lib/parser.js
import fs from 'fs';
-import os from 'os';
import path from 'path';
import _ from 'lodash';
import { ArgumentParser } from 'argparse';
@@ -400,7 +399,7 @@ const args = [
defaultValue: [],
type: parseSecurityFeatures,
required: false,
- example: 'execute-webdriver,adb-shell',
+ example: 'execute_driver_script,adb_shell',
help: 'Set which insecure features are allowed to run in this server\'s sessions. ' +
'Features are defined on a driver level; see documentation for more details. ' +
'This should be either a comma-separated list of feature names, or a path to ' +
@@ -413,7 +412,7 @@ const args = [
defaultValue: [],
type: parseSecurityFeatures,
required: false,
- example: 'execute-webdriver,adb-shell',
+ example: 'execute_driver_script,adb_shell',
help: 'Set which insecure features are not allowed to run in this server\'s sessions. ' +
'Features are defined on a driver level; see documentation for more details. ' +
'This should be either a comma-separated list of feature names, or a path to ' +
@@ -819,24 +818,25 @@ function updateParseArgsForDefaultCapabilities (parser) {
}
function parseSecurityFeatures (features) {
- const splitter = (splitOn) => {
- return (str) => {
- return str.toString().split(splitOn).map(s => s.trim()).filter(Boolean);
- };
- };
+ const splitter = (splitOn, str) => `${str}`.split(splitOn).map(s => s.trim()).filter(Boolean);
let parsedFeatures;
try {
- parsedFeatures = splitter(',')(features);
+ parsedFeatures = splitter(',', features);
} catch (err) {
- throw new Error('Could not parse value of --allow-insecure. Should be a list of strings separated by commas');
+ throw new Error('Could not parse value of --allow/deny-insecure. Should be ' +
+ 'a list of strings separated by commas, or a path to a file ' +
+ 'listing one feature name per line.');
}
- if (parsedFeatures.length === 1) {
+ if (parsedFeatures.length === 1 && fs.existsSync(parsedFeatures[0])) {
// we might have a file which is a list of features
try {
const fileFeatures = fs.readFileSync(parsedFeatures[0], 'utf8');
- parsedFeatures = splitter(os.EOL)(fileFeatures);
- } catch (ign) {}
+ parsedFeatures = splitter('\n', fileFeatures);
+ } catch (err) {
+ throw new Error(`Attempted to read --allow/deny-insecure feature names ` +
+ `from file ${parsedFeatures[0]} but got error: ${err.message}`);
+ }
}
return parsedFeatures;

add full docs for new security flag