doc: clarify proxy threat model

mcollina · aduh95 · commit 618b22c2b228 · 2026-07-21T19:00:53.000+02:00
Signed-off-by: Matteo Collina <hello@matteocollina.com> PR-URL: #64366 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
diff --git a/SECURITY.md b/SECURITY.md
@@ -221,6 +221,16 @@ then untrusted input must not lead to arbitrary JavaScript code execution.
 * The developers and infrastructure that run it.
 * The operating system that Node.js is running under and its configuration,
   along with anything under the control of the operating system.
+* The deployment network environment for the privacy of traffic and routing
+  decisions, including internal networks through which Node.js traffic passes
+  and configured HTTP(S) proxy servers. Built-in proxy support is intended to
+  route traffic through proxies authorized for the deployment, often because a
+  firewall requires one to access external networks. It is not intended to hide
+  traffic from network operators or authorities governing the deployment.
+  Untrusted or unauthorized proxies, as well as deployment policy or legal
+  compliance controls around proxy use, are the responsibility of the deployment
+  operator and are outside this threat model. This does not change that data
+  parsed from network protocol peers is untrusted as described above.
 * The code it is asked to run, including JavaScript, WASM and native code, even
   if said code is dynamically loaded, e.g., all dependencies installed from the
   npm registry or libraries loaded via `node:ffi`.
@@ -301,6 +311,19 @@ the community they pose.
   client consuming unsolicited or misordered responses within the same HTTP/1.1 connection
   reuse lifecycle are generally not considered Node.js vulnerabilities.
 
+#### Unauthorized or untrusted HTTP proxy deployments
+
+* Built-in HTTP proxy support is intended for routing outbound requests through
+  a proxy authorized by the deployment, for example because a firewall requires
+  one to reach external networks. It is not an anonymity, traffic-hiding, or
+  policy-evasion feature.
+* Reports that depend on using an unauthorized proxy, expecting Node.js to
+  provide privacy from a configured proxy or internal network, or expecting
+  Node.js to enforce deployment-specific network policy or legal requirements
+  are not considered Node.js vulnerabilities. Deployment operators are
+  responsible for hardening such environments and controlling which proxy
+  settings are allowed.
+
 #### Malicious Third-Party Modules (CWE-1357)
 
 * Code is trusted by Node.js. Therefore any scenario that requires a malicious
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -3389,9 +3389,14 @@ added:
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4072,9 +4077,14 @@ added:
 > Stability: 1.1 - Active Development
 
 When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
 
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See [Built-in Proxy Support][].
+
 This can also be enabled using the [`--use-env-proxy`][] command-line flag.
 When both are set, `--use-env-proxy` takes precedence.
 
@@ -4380,6 +4390,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 <!-- v8-options end -->
 
 [#42511]: https://github.com/nodejs/node/issues/42511
+[Built-in Proxy Support]: http.md#built-in-proxy-support
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [Chromium's policy for locally trusted certificates]: https://chromium.googlesource.com/chromium/src/+/main/net/data/ssl/chrome_root_store/faq.md#does-the-chrome-certificate-verifier-consider-local-trust-decisions
 [CommonJS module]: modules.md
diff --git a/doc/api/http.md b/doc/api/http.md
@@ -4553,6 +4553,22 @@ support.
 
 If the request is made to a Unix domain socket, the proxy settings will be ignored.
 
+### Proxy security considerations
+
+Built-in proxy support routes outbound requests through an HTTP(S) proxy, often
+because a firewall requires one to access external networks. It is not an
+anonymity or traffic-hiding feature and does not attempt to hide traffic from
+the proxy, the local network, network operators, or authorities that govern the
+deployment.
+
+Configure only proxies that are trusted and authorized for the deployment. A
+proxy can observe connection metadata; for plain HTTP requests, or when TLS is
+terminated or intercepted by the proxy, it can also observe request and response
+contents. Node.js does not support treating an untrusted proxy as a privacy
+boundary. Deployment operators are responsible for controlling proxy
+configuration and for meeting deployment-specific network policy and legal
+requirements.
+
 ### Proxy URL Format
 
 Proxy URLs can use either HTTP or HTTPS protocols:
diff --git a/doc/node.1 b/doc/node.1
@@ -1648,8 +1648,12 @@ See \fBSSL_CERT_DIR\fR and \fBSSL_CERT_FILE\fR.
 .
 .It Fl -use-env-proxy
 When enabled, Node.js parses the \fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR and \fBNO_PROXY\fR
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See Built-in Proxy Support.
 This is equivalent to setting the \fBNODE_USE_ENV_PROXY=1\fR environment variable.
 When both are set, \fB--use-env-proxy\fR takes precedence.
 .
@@ -2310,8 +2314,12 @@ variable is strongly discouraged.
 .It Ev NODE_USE_ENV_PROXY Ar 1
 
 When enabled, Node.js parses the \fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR and \fBNO_PROXY\fR
-environment variables during startup, and tunnels requests over the
+environment variables during startup, and routes requests through the
 specified proxy.
+Use this only with proxies that are trusted and authorized for the deployment.
+Proxy support is intended for reaching external networks through authorized
+proxy servers, for example when a firewall requires one. It is not for hiding
+traffic or evading network policy. See Built-in Proxy Support.
 This can also be enabled using the \fB--use-env-proxy\fR command-line flag.
 When both are set, \fB--use-env-proxy\fR takes precedence.
 .
