Server Startup Flags

## What an "insecure feature" is An Appium server is an HTTP service that does whatever an arriving session asks of it. Most of what a session asks is bounded by the app under test: find an element, tap it, read its text. A handful of driver capabilities are not — they reach past the app into the device itself, or into the server's own bookkeeping. Appium calls those **insecure features**, and none of them is available until the operator turns it on when the server starts. Two consequences follow from that design: - The grant lives on the **server command line**, not in a session's capabilities, so a client cannot talk its way into a privilege the box did not offer. - The grant is made once for the whole process, so it applies to every suite that box serves — which is exactly why Appium 3 tightened how a grant is spelled. ## The value shape: scope, colon, feature In Appium 3 every `--allow-insecure` value is two parts joined by a colon: - the **scope** — either the name of the driver that owns the feature, or `*` meaning every driver; - the **feature name** itself. A bare feature name is not accepted and is not silently dropped: the server throws at startup. That is deliberate. Under the looser spelling an operator typed a feature name and got a grant across everything installed; the scoped form makes you say *whose* feature you meant, and it fails loudly when you do not, instead of over-granting quietly. So the Android lane's device-shell access — a UiAutomator2 driver feature — is granted as `--allow-insecure=uiautomator2:adb_shell`, and the same feature across every installed driver as `--allow-insecure=*:adb_shell`. ## Driver scope versus server scope The scope is not decorative; it has to match where the feature actually lives. | Feature | Who owns it | How it must be written | |---|---|---| | `adb_shell` | the Android UiAutomator2 driver | `uiautomator2:adb_shell`, or `*:adb_shell` for every driver | | `session_discovery` | the Appium server itself | `*:session_discovery` — no driver prefix reaches it | `session_discovery` is the one that catches people. It gates the server's own `GET /appium/sessions` listing, which is a server-level facility rather than any driver's, so there is no driver name that could scope it. It has to carry the `*` scope. Writing `uiautomator2:session_discovery` or `xcuitest:session_discovery` produces a value that is well-formed and that does not turn the feature on. ## The flags that live beside it - `--deny-insecure` takes values in the same scoped shape and names features this box should refuse. It exists so an operator can write a decision down rather than rely on nobody granting it later. - `--relaxed-security` is the blanket switch, unchanged in Appium 3, and it is not a synonym for a scoped grant. It is the "this box is trusted" setting, and on a machine several teams share that is a far larger promise than one feature for one driver. For an unattended box running an allotment watering-rota suite, the honest line is the narrow one. If the Android lane's fixture step needs a device shell, grant `uiautomator2:adb_shell` and nothing else; the Apple lane's XCUITest driver gains nothing from that value, which is precisely the point of scoping it. ## Mistakes the scoped form is meant to catch 1. **Assuming one installed driver makes the scope optional.** It does not. The prefix is required regardless of what is installed, so a box carrying only the Android driver still has to name it. 2. **Expecting a warning instead of a failure.** An unscoped value stops the server rather than starting it half-configured, so the box fails at start rather than an hour into a run. 3. **Scoping a server feature to a driver.** Session discovery is the standing example, and the symptom is a feature that stays off with no complaint from the flag parser. 4. **Reaching for `--relaxed-security` because one command was refused.** That turns on far more than the command needed, for every driver on the box. ## What the grant does not do Granting a feature does not make anything happen by itself; it only stops the server refusing when a session asks. Which driver command a given feature unlocks, and what that command then does on an Android device or on an Apple one, is a separate matter from the flag that permits it. Nor is the grant negotiable per session. Two suites sharing one server share one privilege set, so what the box allows is a property of the box rather than of whoever connects to it next. That is the real reason to keep the value narrow: the next caller is not necessarily the suite you had in mind when you wrote the line.