Add upstream IP validation for X-Forwarded-For header processing

[Copilot]

The X-Forwarded-For header was evaluated unconditionally, allowing trivial IP spoofing. An attacker from 123.123.123.123 could set X-Forwarded-For: 10.0.1.2 to bypass rules restricting access to 10.0.1.2.

Changes

Configuration

• Added use_xff boolean (default: false) to explicitly enable XFF processing
• Added xff_upstream_ip string for trusted proxy IP/CIDR
• Server fails at startup if use_xff=true without xff_upstream_ip configured

Validation Logic

• XFF header evaluated only when request originates from xff_upstream_ip
• Requests from upstream without XFF header are denied
• Requests from non-upstream IPs use direct connection IP (XFF ignored)
• Direct connections from allowed IPs always work regardless of XFF configuration

Configuration Example

config:
  hostname: 0.0.0.0
  listen_port: 8080
  use_xff: true
  xff_upstream_ip: 10.0.1.2  # Load balancer IP

With source_ip: [10.0.1.9] in a rule:

• Request from 10.0.1.2 with X-Forwarded-For: 10.0.1.9 → allowed
• Request from 10.0.1.2 without XFF header → denied
• Request from 10.0.1.9 directly → allowed
• Request from 123.123.123.123 with X-Forwarded-For: 10.0.1.9 → denied

Testing

Added test coverage for three scenarios:

1. XFF disabled (default) - direct IPs only, XFF ignored
2. XFF enabled without upstream IP - startup failure
3. XFF enabled with upstream IP - validated XFF processing

Original prompt

The current implementation will accept the X_FORWARDED_FOR header if it is present, regardless of the source. We need to enhance the logic around this to add an additional configuration parameter that will define the source IP that this would be accepted from, and ensure that the header is not evaluated in any other scenario.

For example, if this project is running at 10.0.1.1 and the rule is configured to accept traffic from 10.0.1.2, this will currently evaluate to true if the request's source IP is 10.0.1.2 but will also evaluate to true if the request is from 123.123.123.123 but also includes the X_FORWARDED_FOR header with a value of 10.0.1.2.

We need to be careful with how this is implemented, likely with warnings included in documentation, that if this is run from behind a load balancer/proxy/etc that would add X_FORWARDED_FOR then an expected upstream source IP must also be be present.

Implementation for this should add configuration options, tests, and handling for a BOOL config that confirms whether or not X_FORWARDED_FOR will be evaluated, and a new key called XFF_UPSTREAM_IP that should be set to the expected source IP that will appear for the request including the X_FORWARDED_FOR header.

Scenario 1:

• X_FORWARDED_FOR is set to False
• Valid IPs are 10.0.1.2 and 10.0.1.3
• Requests from 10.0.1.2 and 10.0.1.3 will succeed
• Requets from 10.0.1.4, etc will fail

Scenario 2:

• X_FORWARDED_FOR is set to True
• XFF_UPSTREAM_IP is unset
• The server should fail to start with a FATAL error as the configuration is invalid.

Scenario 3:

• X_FORWARDED_FOR is set to True
• XFF_UPSTREAM_IP is set to 10.0.1.2
• Valid IPs are set to 10.0.1.9 and 10.0.1.10
• Requests from 10.0.1.2 that do not include the X_FORWARDED_FOR header should fail
• Requets from 10.0.1.2 that do include the X_FORWARDED_FOR header but do not have a value of 10.0.1.9 or 10.0.1.10 should fail
• Requests from 10.0.1.2 that do include the X_FORWARDED_FOR header and do include a value of 10.0.1.9 or 10.0.1.10 should succeed
• Requests directly from 10.0.1.9 or 10.0.1.10 should succeed regardless of X_FORWARDED_FOR header presence

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.