remote/doc/Security.md

   1 Security aspects of the Remote Agent
   2 ====================================
   3
   4 The Remote Agent is not a web-facing feature and as such has different
   5 security characteristics than traditional web platform APIs.  The
   6 primary consumers are out-of-process programs that connect to the
   7 agent via a remote protocol, but can theoretically be extended to
   8 facilitate browser-local clients communicating over IPDL.
   9
  10 Design considerations
  11 ---------------------
  12
  13 The Remote Agent allows consumers to interface with Firefox through
  14 an assorted set of domains for inspecting the state and controlling
  15 execution of documents running in web content, injecting arbitrary
  16 scripts to documents, do browser service instrumentation, simulation
  17 of user interaction for automation purposes, and for subscribing
  18 to updates in the browser such as network- and console logs.
  19
  20 The remote interfaces are served over an HTTP wire protocol, by a
  21 server listener hosted in the Firefox binary.  This can only be
  22 started by passing the `--remote-debugging-port`
  23 flag.  Connections are restricted to loopback devices
  24 (such as localhost and 127.0.0.1).
  25
  26 Since the Remote Agent is not an in-document web feature, the
  27 security concerns we have for this feature are essentially different
  28 to other web platform features.  The primary concern is that the
  29 HTTPD is not spun up without passing one of the command-line flags.
  30 It is out perception that if a malicious user has the capability
  31 to execute arbitrary shell commands, there is little we can do to
  32 prevent the browser being turned into an evil listening device.
  33
  34 User privacy concerns
  35 ---------------------
  36
  37 There are no user privacy concerns beyond the fact that the offered
  38 interfaces will give the client access to all browser internals,
  39 and thereby follows all browser-internal secrets.
  40
  41 How the Remote Agent works
  42 --------------------------
  43
  44 When the `--remote-debugging-port` flag is used,
  45 it spins up an HTTPD on the desired port, or defaults to
  46 localhost:9222.  The HTTPD serves WebSocket connections via
  47 `nsIWebSocket.createServerWebSocket` that clients connect to in
  48 order to give the agent remote instructions. Hereby the HTTPD only
  49 accepts system-local loopback connections from clients:
  50
  51     if (!LOOPBACKS.includes(host)) {
  52       throw new Error("Restricted to loopback devices");
  53     }
  54
  55 The Remote Agent implements a large subset of the Chrome DevTools
  56 Protocol (CDP).  This protocol allows a client to:
  57
  58 - take control over the user session for automation purposes, for
  59   example to simulate user interaction such as clicking and typing;
  60
  61 - instrument the browser for analytical reasons, such as intercepting
  62   network traffic;
  63
  64 - and extract information from the user session, including cookies
  65   and local strage.
  66
  67 There are no web-exposed features in the Remote Agent whatsoever.
  68
  69 Security model
  70 --------------
  71
  72 It shares the same security model as DevTools and Marionette, in
  73 that there is no other mechanism for enabling the Remote Agent than
  74 by passing a command-line flag.
  75
  76 It is our assumption that if an attacker has shell access to the
  77 user account, there is little we can do to prevent secrets from
  78 being accessed or leaked.
  79
  80 The Remote Agent is available on all release channels.
  81
  82 Remote Hosts and Origins
  83 ------------------------
  84
  85 By default RemoteAgent only accepts connections with no `Origin` header and a
  86 `Host` header set to an IP address or a localhost loopback address.
  87
  88 Other `Host` or `Origin` headers can be allowed by starting Firefox with the
  89 `--remote-allow-origins` and `--remote-allow-hosts` arguments:
  90
  91 - `--remote-allow-hosts` expects a comma separated list of hostnames
  92
  93 - `--remote-allow-origins` expects a comma separated list of origins
  94
  95 Note: Users are strongly discouraged from using the Remote Agent in a way that
  96 allows it to be accessed by untrusted hosts e.g. by binding it to a publicly
  97 routeable interface.
  98
  99 The Remote Agent does not provide message encryption, which means that all
 100 protocol messages are subject to eavesdropping and tampering. It also does not
 101 provide any authentication system. This is acceptable in an isolated test
 102 environment, but not to be used on an untrusted network such as the internet.
 103 People wishing to provide remote access to Firefox sessions via the Remote Agent
 104 must provide their own encryption, authentication, and authorization.
 105
 106 Security reviews
 107 ----------------
 108
 109 More details can be found in the security reviews conducted for Remote Agent and
 110 WebDriver BiDi:
 111
 112 - [Remote Agent security review] (November 2019)
 113
 114 - [WebDriver BiDi security review] (April 2022)
 115
 116 [Remote Agent security review]: https://bugzilla.mozilla.org/show_bug.cgi?id=1542229
 117 [WebDriver BiDi security review]: https://bugzilla.mozilla.org/show_bug.cgi?id=1753997