new config option: trustProxy

Author: lfortin

README.md

@@ -190,6 +190,18 @@ An updater function can also be passed to the `env` option to update the environ
 }
 ```
 
+### trustProxy
+
+Set to `true` to trust proxy-related HTTP headers (`X-Forwarded-For`, `X-Forwarded-Proto`, and `Host`). This affects CGI environment variables such as:
+
+- `REMOTE_ADDR` — will use the leftmost IP in `X-Forwarded-For`
+- `HTTPS` — will be `"on"` if `X-Forwarded-Proto` is `"https"`
+- `SERVER_NAME` and `SERVER_PORT` — will be parsed from the `Host` header
+
+Default: `false`
+
+> ⚠️ **Important:** Only enable this if you are **running behind a trusted reverse proxy** (like Nginx or a load balancer). Enabling `trustProxy` when exposed to the public internet can allow **header spoofing** by clients.
+
 # Start a CGI Server from the Command Line
 
 The command `cgi-server` can be used to run an HTTP server to serve CGI scripts.
@@ -303,20 +315,6 @@ http {
 }
 ```
 
-### ⚠️ Note on Proxy Headers and CGI Environment Variables
-
-If you run `cgi-core` behind a reverse proxy (such as **Nginx**), certain CGI environment variables may be influenced by proxy headers, including:
-
-- `REMOTE_ADDR` — may reflect the proxy's IP unless `X-Forwarded-For` is set
-- `HTTPS` — determined by `X-Forwarded-Proto` if TLS is terminated at the proxy
-- `SERVER_NAME` — usually derived from the `Host` header sent by the proxy
-
-By default, `cgi-core` **does not validate proxy headers**. If untrusted clients can set headers like `X-Forwarded-For`, this could result in spoofed values being passed to your CGI scripts.
-
-🔐 **Important**: Make sure your reverse proxy is properly configured and only accepts requests from trusted sources. If needed, filter or overwrite proxy headers before they reach your Node.js server.
-
-_You may choose to implement your own logic for handling trusted proxies or wait for future support of a `trustProxy` option._
-
 # License
 
 `cgi-core` is released under the [MIT License](https://github.com/lfortin/node-cgi-core/blob/master/LICENSE).

bin/cgi-server.mjs

@@ -68,6 +68,9 @@ const options = {
     type: "boolean",
     short: "l",
   },
+  trustProxy: {
+    type: "boolean",
+  },
   port: {
     type: "string",
     short: "p",
@@ -91,16 +94,20 @@ if (values.help) {
 
   -h, --help                    Display help
   -v, --version                 Display cgi-core version string
+
   --urlPath <urlPath>           Set base url path for routing
   --filePath <filePath>         Set file path where the CGI scripts are located
+  -p, --port <port>             Set the port to listen on
+
   --indexExtension <extension>  Set file extension to lookup for index files
   --maxBuffer <bytes>           Set the allowed HTTP request and response payloads size in bytes
   --requestChunkSize <bytes>    Set the HTTP request payload data chunks size in bytes
   --responseChunkSize <bytes>   Set the HTTP response payload data chunks size in bytes
   --requestTimeout <ms>         Set the HTTP request timeout delay in milliseconds
+  --trustProxy                  Trust proxy headers (X-Forwarded-For, etc.)
+
   -d, --debugOutput             Output errors for HTTP status 500
   -l, --logRequests             Log HTTP requests to STDOUT
-  -p, --port <port>             Set the port to listen on
     `);
   process.exit();
 }

cgi-core.d.ts

@@ -41,6 +41,7 @@ export interface Config {
   requestTimeout: number;
   forceKillDelay: number;
   requireExecBit: boolean;
+  trustProxy: boolean;
   statusPages: StatusPages;
   env: EnvVars | EnvUpdaterFunction;
 }

cgi-core.js

@@ -109,6 +109,7 @@ function createHandler(configOptions = {}) {
         filePath,
         fullFilePath,
         env: config.env,
+        trustProxy: config.trustProxy,
       });
     } catch (err) {
       if (err.code === "ENOENT") {

lib/constants.js

@@ -70,6 +70,7 @@ const DEFAULT_CONFIG = {
   requestTimeout: 30000,
   forceKillDelay: 1000,
   requireExecBit: false,
+  trustProxy: false,
   statusPages: {},
   env: {},
 };

lib/util.js

@@ -86,6 +86,8 @@ function getExecPath(filePath, extensions) {
 }
 
 function createEnvObject(req, extraInfo) {
+  const { trustProxy } = extraInfo;
+
   const env = {};
   for (const header of Object.keys(req.headers)) {
     const snakeCase = header.replace(/\-/g, "_").toUpperCase();
@@ -118,35 +120,37 @@ function createEnvObject(req, extraInfo) {
     env.PATH_INFO = `${separator}${pathInfo}`.replace(/\/+/g, "/");
   }
 
-  // REMOTE_ADDR may be affected by proxy headers (e.g., X-Forwarded-For).
-  // We default to using the first IP from X-Forwarded-For if present.
-  // IMPORTANT: These headers are untrusted by default — ensure your reverse proxy is secured.
-  const forwardedFor = req.headers["x-forwarded-for"];
-  const clientIp = forwardedFor
-    ? forwardedFor.split(",")[0].trim()
-    : req.socket?.remoteAddress || req.connection?.remoteAddress;
+  // REMOTE_ADDR may be affected by X-Forwarded-For
+  const clientIp =
+    trustProxy && req.headers["x-forwarded-for"]
+      ? req.headers["x-forwarded-for"].split(",")[0].trim()
+      : req.socket?.remoteAddress || req.connection?.remoteAddress;
   env.REMOTE_ADDR = clientIp;
 
-  env.SERVER_PORT = req.socket?.localPort || req.connection?.localPort;
+  // HTTPS is set to "on" if the connection is encrypted or proxied via X-Forwarded-Proto
+  if (
+    (trustProxy && req.headers["x-forwarded-proto"] === "https") ||
+    req.socket?.encrypted
+  ) {
+    env.HTTPS = "on";
+  }
 
-  // SERVER_NAME may reflect the Host header, which can be manipulated by clients.
-  // This is common practice behind proxies, but security-sensitive scripts should treat with caution.
-  if (req.headers["host"]) {
-    env.SERVER_NAME = req.headers["host"].split(":")[0];
+  // SERVER_NAME may reflect the Host header
+  if (trustProxy && req.headers["host"]) {
+    const [name, port] = req.headers["host"].split(":");
+    env.SERVER_NAME = name;
+    env.SERVER_PORT = port || (env.HTTPS === "on" ? "443" : "80");
   } else if (req.socket?.localAddress) {
-    env.SERVER_NAME = req.socket.localAddress;
+    env.SERVER_NAME = req.socket?.localAddress;
+    env.SERVER_PORT = String(
+      req.socket?.localPort || req.connection?.localPort
+    );
   }
 
   if (req.headers["authorization"]) {
     env.AUTH_TYPE = req.headers["authorization"].split(" ")[0];
   }
 
-  // HTTPS is set to "on" if the connection is encrypted or proxied via X-Forwarded-Proto.
-  // Only use this logic if your reverse proxy is configured correctly and trusted.
-  if (req.headers["x-forwarded-proto"] === "https" || req.socket?.encrypted) {
-    env.HTTPS = "on";
-  }
-
   if (extraInfo.env) {
     if (typeof extraInfo.env === "function") {
       Object.assign(env, extraInfo.env(env, req));

test/spec-runner.js

@@ -103,15 +103,18 @@ script.cgi`);
       const req = {
         url: "/cgi-bin/script.cgi/extra/path?param1=test&param2=test",
         socket: {
-          remoteAddress: "127.0.0.1",
+          remoteAddress: "100.100.100.100",
           localAddress: "127.0.0.1",
-          localPort: 3001,
+          localPort: "3001",
         },
         headers: {
           "content-type": "application/json",
           "content-length": 1024,
           cookie: "yummy_cookie=choco; tasty_cookie=strawberry",
           authorization: "Bearer [token]",
+          "x-forwarded-for": "200.200.200.200",
+          "x-forwarded-proto": "https",
+          host: "www.example.org:3002",
         },
         method: "GET",
         httpVersion: "1.1",
@@ -121,6 +124,7 @@ script.cgi`);
         filePath: "files/script.cgi",
         fullFilePath: "/home/username/cgi-bin/files/script.cgi",
         env: { ANOTHER_VAR: "another value" },
+        trustProxy: false,
       };
       let env = createEnvObject(req, extraInfo);
 
@@ -149,29 +153,56 @@ script.cgi`);
         env.SCRIPT_FILENAME,
         "/home/username/cgi-bin/files/script.cgi"
       );
-      assert.strictEqual(env.REMOTE_ADDR, "127.0.0.1");
-      assert.strictEqual(env.SERVER_PORT, 3001);
+      assert.strictEqual(env.HTTP_HOST, "www.example.org:3002");
+      assert.strictEqual(env.REMOTE_ADDR, "100.100.100.100");
+      assert.strictEqual(env.SERVER_PORT, "3001");
       assert.strictEqual(env.SERVER_NAME, "127.0.0.1");
+      assert.notStrictEqual(env.HTTPS, "on");
       assert.strictEqual(env.AUTH_TYPE, "Bearer");
       assert.strictEqual(env.SCRIPT_NAME, "/files/script.cgi");
       assert.strictEqual(env.ANOTHER_VAR, "another value");
 
-      extraInfo.env = function (env, req) {
-        return {
-          UNIQUE_ID: req.uniqueId,
-        };
-      };
-      req.headers["x-forwarded-for"] = "127.0.0.1";
-      req.headers["x-forwarded-proto"] = "https";
-      req.headers["host"] = "www.example.org:3001";
-      env = createEnvObject(req, extraInfo);
-      assert.strictEqual(env.HTTP_HOST, "www.example.org:3001");
-      assert.strictEqual(env.REMOTE_ADDR, "127.0.0.1");
-      assert.strictEqual(env.SERVER_PORT, 3001);
+      env = createEnvObject(
+        req,
+        Object.assign({}, extraInfo, {
+          trustProxy: true,
+          env: function (env, req) {
+            return {
+              UNIQUE_ID: req.uniqueId,
+            };
+          },
+        })
+      );
+
+      assert.strictEqual(env.REMOTE_ADDR, "200.200.200.200");
+      assert.strictEqual(env.SERVER_PORT, "3002");
       assert.strictEqual(env.SERVER_NAME, "www.example.org");
       assert.strictEqual(env.HTTPS, "on");
       assert.strictEqual(env.UNIQUE_ID, req.uniqueId);
     });
+    it("should fall back gracefully without host or proxy headers", async () => {
+      const req = {
+        url: "/cgi-bin/test.cgi",
+        method: "GET",
+        httpVersion: "1.1",
+        headers: {},
+        socket: {
+          localAddress: "127.0.0.1",
+          localPort: "8080",
+          remoteAddress: "192.168.1.10",
+        },
+      };
+      const extraInfo = {
+        filePath: "test.cgi",
+        fullFilePath: "/var/www/cgi-bin/test.cgi",
+        trustProxy: true,
+      };
+
+      const env = createEnvObject(req, extraInfo);
+      assert.strictEqual(env.SERVER_NAME, "127.0.0.1");
+      assert.strictEqual(env.SERVER_PORT, "8080");
+      assert.strictEqual(env.REMOTE_ADDR, "192.168.1.10");
+    });
   });
   describe("parseResponse", () => {
     it("should return a parsed response", async () => {
@@ -342,7 +373,10 @@ script.cgi`);
   });
   describe("isAbsoluteWindowsPath", () => {
     it("should return true", async () => {
-      assert.strictEqual(isAbsoluteWindowsPath("C:\\Program Files\\perl"), true);
+      assert.strictEqual(
+        isAbsoluteWindowsPath("C:\\Program Files\\perl"),
+        true
+      );
       assert.strictEqual(isAbsoluteWindowsPath("C:/Program Files/perl"), true);
       assert.strictEqual(isAbsoluteWindowsPath("\\\\volume\\perl"), true);
     });