docs(appium): add server security doc
MODIFY
packages/appium/docs/en/cli/index.md
packages/appium/docs/en/cli/index.md
title: CLI Intro
---
-When you install Appium globally from NPM, an `appium` "binary" is placed in your global
-`node_modules` folder. If your `PATH` is set up to look for programs in that folder, then you will
-be able to run `appium` from the command line of your terminal. The `appium` program has two main
+When you install Appium globally via `npm`, an executable shell script named `appium` is placed in
+your global Node `bin` folder, often also symlinked to places like `/usr/local/bin`. If your `PATH`
+is set up to look for programs in appropriate directory, then you will be able to run `appium` from
+the command line of your terminal, like any other executable. The `appium` program has three main
subcommands, each of which has its own set of documentation:
-1. The [Server](./args.md) subcommand starts an Appium server listening for new session requests,
+1. The [`server`](./args.md) subcommand starts an Appium server listening for new session requests,
and takes a variety of parameters related to the operation of the server and also those consumed
by active drivers or plugins.
-2. The [Extension](./extensions) subcommands assist in managing Appium drivers and plugins.
+2. The [Extension](./extensions) (`driver` and `plugin`) subcommands assist in managing Appium
+ drivers and plugins.

MODIFY
packages/appium/docs/en/guides/managing-exts.md
packages/appium/docs/en/guides/managing-exts.md
@@ -3,27 +3,29 @@ title: Managing Appium Drivers and Plugins
---
To do anything useful with Appium, you need to have at least one [Driver](../intro/drivers.md)
-installed, otherwise Appium won't know how to automate anything. And there is a whole
-[Ecosystem](../ecosystem/index.md) of drivers and plugins out there which enable you to get your
-job done with Appium. This guide helps explain how to manage these drivers and plugins. There are
+installed, otherwise Appium won't know how to automate anything. There is an entire
+[Ecosystem](../ecosystem/index.md) of drivers and plugins out there!
+
+This guide helps explain how to manage these drivers and plugins. There are
two basic strategies: using Appium's extension CLI interface, or managing extensions yourself in an
-NPM-based project.
+npm-based project.
+
+> Note: Alternative package managers are not supported by Appium at the time of this writing.
## Using Appium's Extension CLI
With Appium's [Extension CLI](../cli/extensions.md), you let Appium manage drivers and plugins for
-you, and simply use CLI commands to tell Appium which extensions you would like to install, update,
+you. You will use CLI commands to tell Appium which extensions you would like to install, update,
or remove. Here's an example of how you might install a driver using the CLI:
```bash
appium driver install xcuitest
```
-This simple command will install the latest version of the [XCUITest
-Driver](https://github.com/appium/appium-xcuitest-driver). The Extension CLI comes with a variety
+This command will install the latest version of the [XCUITest Driver](https://github.com/appium/appium-xcuitest-driver). The Extension CLI comes with a variety
of commands and parameters; see the documentation for that command for all the specifics.
-The all-important question when Appium is managing your extensions for you is: where do they live?
+The all-important question when Appium is managing your extensions for you is: where are they installed?
Appium manages extensions in a directory specified by the `APPIUM_HOME` environment variable. You
can set that variable to anything you like, and Appium will manage its extensions there. You can
therefore also use the `APPIUM_HOME` environment variable to manage different sets of extensions,
@@ -31,7 +33,7 @@ for example if you want to have the same driver installed at conflicting version
```bash
APPIUM_HOME=/path/to/home1 appium driver install xcuitest@4.11.1
-APPIUM_HOME=/path/to/home2 appium driver install xcuitest@beta
+APPIUM_HOME=/path/to/home2 appium driver install xcuitest@4.11.2
```
Running these commands will result in two separate `APPIUM_HOME` directories being created and
@@ -40,26 +42,26 @@ environment variables to direct Appium which version to use on launch:
```bash
APPIUM_HOME=/path/to/home1 appium # use xcuitest driver 4.11.1
-APPIUM_HOME=/path/to/home2 appium # use the xcuitest driver beta
+APPIUM_HOME=/path/to/home2 appium # use xcuitest driver 4.11.2
```
You don't need to set `APPIUM_HOME` if you don't want to! By default, Appium will set `APPIUM_HOME`
-to the directory `.appium` in your user home dir.
+to the directory `.appium` in your user home directory.
-## NPM DIY
+## Do-It-Yourself with `npm`
Because Appium and Appium drivers are Node.js programs, if you are integrating your Appium scripts
-into your own Node.js project, there is an alternative way to manage drivers and plugins: via NPM.
+into your own Node.js project, there is an alternative way to manage drivers and plugins: via `npm`, like any other dependency.
Basically, whenever you run Appium, if you have not explicitly set `APPIUM_HOME`, it will:
-1. Try to determine whether it is inside an NPM project by getting the project path from `npm list`.
+1. Try to determine whether the _current directory_ is inside an `npm` package.
1. If so, it will check whether `appium` is a dependency (dev, prod, or peer) in the project's
`package.json`
-1. If so, Appium will ignore `APPIUM_HOME` entirely, and load drivers and plugins defined in that
+1. If so, _unless you have specified `APPIUM_HOME` in your environment_, Appium will ignore load drivers and plugins defined in that
`package.json` file instead.
-This means you are freely able to add Appium drivers and plugins as regular NPM dependencies. For
-example, if your project has a `package.json` including the following portion:
+This means you are freely able to add Appium drivers and plugins as regular package dependencies or dev dependencies. For
+example, if your project has a `package.json` which includes the following:
```json
{
@@ -74,6 +76,6 @@ Then, if you run `npx appium` inside your project, Appium will detect that it is
the project, and will load the XCUITest driver which is also listed as a dev dependency for the
project.
-Again, this strategy is *only* recommended if you are already using Node/NPM for your project.
+This strategy is *only* recommended if you are already using `npm` for your project.
Otherwise, it is recommended that you use Appium's Extension CLI and, if necessary, adjust
`APPIUM_HOME` to change the location of stored extensions.

MODIFY
packages/appium/docs/en/guides/security.md
packages/appium/docs/en/guides/security.md
title: Appium Server Security
---
-TODO
+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, you can only safely enable all Appium's features if
+all the following are true:
+
+- You're running your own Appium server locally or within a protected internal network
+- You're not sharing it with any untrusted parties
+- You don't expose Appium's port(s) to the wider internet
+
+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 _explicitly opt-in_ to these features.
+(Third-party driver and plugin authors can also [hide behaviour behind security
+flags](../ecosystem/build-drivers.md).)
+
+For security reasons, Appium client sessions can _not_ request feature enablement via capabilities;
+this is the responsibility of the server admin who configures and launches the Appium server.
+
+## Security Server Args
+
+The [Server CLI Args](../cli/args.md) doc outlines three relevant arguments which may be passed to
+Appium when starting it from the command line:
+
+|Parameter|Description|
+|----|----|
+|`--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. Thus
+you should read through the documentation for a particular driver to know which feature names it
+might use. Here is an incomplete list of examples from some of Appium's official drivers:
+
+|Feature Name|Description|Supported Extension(s)|
+|------------|-----------|-------|
+|`get_server_logs`|Allows retrieving of Appium server logs via the Webdriver log interface|IOS, XCUITest, Android, UiAutomator2, Espresso|
+|`adb_shell`|Allows execution of arbitrary shell commands via ADB, using the `mobile: shell` command|Android, UiAutomator2, Espresso|
+|`record_audio`|Allow recording of host machine audio inputs|XCUITest|
+|`execute_driver_script`| Allows to send a request which has multiple Appium commands.|Execute Driver Plugin|
+
+## Examples
+
+To turn on the `get_server_logs` feature for my Appium server, I could start it like this:
+
+```bash
+appium --allow-insecure=get_server_logs
+```
+
+To turn on multiple features:
+
+```bash
+appium --allow-insecure=get_server_logs,record_audio
+```
+
+To allow all features except one:
+
+```bash
+appium --relaxed-security --deny-insecure=adb_shell
+```

docs(appium): add server security doc