Skip to content

feat(server): log real client IP behind trusted reverse proxies - #607

Merged
fank merged 5 commits into
feat/access-log-levelfrom
feat/real-ip-trusted-proxies
Nov 14, 2026
Merged

fank merged 5 commits into
feat/access-log-levelfrom
feat/real-ip-trusted-proxies

Conversation

@smitt14ua

@smitt14ua smitt14ua commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Behind a reverse proxy every request is logged with the proxy's address. This adds Gin-style trusted proxies:

  • trustedProxies / OCAP_TRUSTEDPROXIES: IPs or CIDR ranges. Empty by default, so forwarding headers are ignored and nothing changes for existing setups. Invalid entries stop the server at startup.
  • remoteIPHeaders / OCAP_REMOTEIPHEADERS: default X-Forwarded-For, X-Real-IP, tried in order.
  • When the direct peer is trusted, RealIPMiddleware replaces r.RemoteAddr with the client address before anything else runs, so the access log and handlers (e.g. the upload rejected warning) see the client.
  • X-Forwarded-For is read right to left: trusted entries are skipped and the first untrusted one is the client, since entries further left can be sent by the client.
  • README documents the Cloudflare → Traefik → OCAP case: trusting Cloudflare's ranges with X-Forwarded-For is safe without a firewall; CF-Connecting-IP is only safe when nothing but Cloudflare can reach the proxy.

Stacked on #606 (access log). It will retarget to main once that merges.

Test plan

  • go test ./internal/server ./cmd/... (table tests: untrusted peer, spoofed left entries, multiple header lines, malformed header fallback, IPv4-mapped addresses, custom header)
  • Ran the server locally with OCAP_TRUSTEDPROXIES=127.0.0.1: X-Forwarded-For: 9.9.9.9, 203.0.113.7 logged as remote_addr: 203.0.113.7

Add trustedProxies (OCAP_TRUSTEDPROXIES) and remoteIPHeaders
(OCAP_REMOTEIPHEADERS, default X-Forwarded-For, X-Real-IP). When the
direct peer is a trusted proxy, RemoteAddr is replaced with the client
address from the headers, X-Forwarded-For read right to left so entries
the client sent itself are skipped, and the access log adds the proxy as
proxy_addr. No proxy is trusted by default, so headers are ignored.
With a single reverse proxy it is the same address on every line.
@smitt14ua
smitt14ua force-pushed the feat/real-ip-trusted-proxies branch from b7f8c56 to e8ea50f Compare November 13, 2026 23:34
@smitt14ua
smitt14ua marked this pull request as ready for review November 13, 2026 23:49
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Caution

No coverage from the go.yml workflow was found on feat/access-log-level, so this report only shows the current coverage of the changed files

Merging this branch will increase overall coverage

Impacted Packages Coverage Δ 🤖
github.com/OCAP2/web/cmd/ocap-webserver 24.79% (+24.79%) 🌟
github.com/OCAP2/web/internal/server 92.26% (+92.26%) 🌟
Coverage details
Changed File Coverage Δ Total Covered Missed 🤖
github.com/OCAP2/web/cmd/ocap-webserver/main.go 0.00% (ø) 87 (+87) 0 87 (+87)
github.com/OCAP2/web/internal/server/realip.go 98.18% (+98.18%) 55 (+55) 54 (+54) 1 (+1) 🌟
github.com/OCAP2/web/internal/server/setting.go 92.93% (+92.93%) 99 (+99) 92 (+92) 7 (+7) 🌟

Please note that the "Total", "Covered", and "Missed" counts above refer to code statements instead of lines of code. The value in brackets refers to the test coverage of that file in the old version of the code.

Changed unit test files:

  • github.com/OCAP2/web/internal/server/accesslog_test.go
  • github.com/OCAP2/web/internal/server/realip_test.go
  • github.com/OCAP2/web/internal/server/setting_test.go

@smitt14ua
smitt14ua requested a review from fank November 13, 2026 23:57
@fank

fank commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Ratatoskr reviewed this pull request.

Changes requested on daf936c0. See the review.

Finished 2026-11-14 00:01 UTC.

@fank fank left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

REQUEST_CHANGES — 1 correctness finding.

Review details

Required correction

[P2] Normalize IPv4-mapped CIDRs consistently with addresses — internal/server/realip.go:24–29

The CIDR branch preserves IPv4-mapped IPv6 prefixes, but isTrusted always unmaps addresses to IPv4 before calling Contains. Consequently, accepted settings such as ::ffff:172.18.0.2/128 or ::ffff:172.18.0.0/112 never trust the corresponding proxy. With peer [::ffff:172.18.0.2]:4000 and X-Forwarded-For: 1.2.3.4, both leave RemoteAddr as the proxy, whereas the equivalent bare setting ::ffff:172.18.0.2 correctly produces 1.2.3.4. This silently defeats client-IP logging for these valid CIDR configurations, and also prevents matching such intermediate hops.

Normalize mapped IPv4 prefixes consistently (including the prefix-length adjustment), or otherwise preserve equivalent matching semantics. Add middleware regression coverage for mapped /128 and subnet prefixes; the existing mapped-address test uses an ordinary IPv4 trusted entry and misses this case.

Verification

Reviewed head daf936c000488cf356a19c02b047d0d5806ea4f8 against base 1db4f51e48526639c41e373b4c9a5cff6e196370, surrounding configuration/logging code, and Fuego's actual middleware wrapping order.

Using the installed Go 1.27.2 toolchain executable:

  • go test ./internal/server -run '^(TestParseTrustedProxies|TestRealIPMiddleware|TestAccessLogMiddleware|TestNewSetting_LoggingAndProxies)$' -count=1 — passed.
  • go test ./cmd/... — passed.
  • Isolated reproduction using an unchanged copy of realip.go outside the checkout: bare mapped IP passed; equivalent mapped /128 and /112 cases failed with the proxy address instead of 1.2.3.4.
  • go test ./... — failed locally because SQLite requires CGO; retry with CGO_ENABLED=1 could not build because gcc is unavailable. These environment limitations are not additional findings.
  • GitHub test and coverage checks passed at review time.

Earlier discussions

GraphQL enumeration returned no review threads (no additional thread/comment pages). Resolved: 0; still-open earlier discussions: 0; skipped: 0. No discussion mutations performed. Checkout left unchanged.

Addresses are unmapped before matching, but a trusted proxy given as an
IPv4-mapped CIDR (::ffff:172.18.0.0/112) stayed an IPv6 prefix and never
matched. Convert it to the equivalent IPv4 prefix; reject mapped
prefixes shorter than /96, which cover more than the mapped range.
@smitt14ua

Copy link
Copy Markdown
Contributor Author

Thanks, good catch. Fixed in 2590a67.

  • ParseTrustedProxies now converts an IPv4-mapped prefix to the equivalent IPv4 prefix (/128 → /32, /112 → /16, /96 → /0), matching how addresses are unmapped before Contains.
  • A mapped prefix shorter than /96 is rejected at startup: it covers more than the mapped range, so it's almost certainly a config mistake.
  • Added regression tests: parsing of mapped /128, /112, /96 and the /95 error, plus middleware cases with a mapped /128 entry and a mapped subnet entry.

@smitt14ua
smitt14ua requested a review from fank November 14, 2026 00:09
@fank

fank commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Ratatoskr reviewed this pull request.

Approved on 2590a672. See the review.

Finished 2026-11-14 00:12 UTC.

@fank fank left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APPROVE — 0 blocking findings.

Review details

Reviewed head 2590a672b4d15178912f465b35181c870e42ad02 against feat/access-log-level, including configuration loading, proxy-chain parsing, downstream consumers of RemoteAddr, and Fuego v0.21.0's actual global middleware ordering. No actionable correctness or safety defects found.

Checks:

  • Passed: /home/fkinder/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.27.2.linux-amd64/bin/go test ./internal/server -run 'Test(ParseTrustedProxies|RealIPMiddleware|AccessLogMiddleware|NewSetting_LoggingAndProxies)$' -count=1.
  • Attempted the same Go binary with test ./...: database-dependent tests failed because CGO is disabled and SQLite requires it; no local C compiler is available. This is an environment limitation, not an identified PR defect. The command package passed.
  • GitHub's test and coverage checks report success.
  • GitHub GraphQL review-thread enumeration returned no threads (pagination complete); none required replies or resolution.

@fank
fank merged commit 5b37537 into feat/access-log-level Nov 14, 2026
2 checks passed
@fank
fank deleted the feat/real-ip-trusted-proxies branch November 14, 2026 00:37
fank pushed a commit that referenced this pull request Nov 14, 2026
)

* feat(server): log healthcheck at debug level, add logLevel setting

Replace fuego's request logging with an access log middleware that keeps
its fields and X-Request-ID but logs the healthcheck polled by Docker at
debug level. Add logLevel (OCAP_LOGLEVEL, default info): the slog handler
was created without options, so debug records were always dropped.

* feat(server): log real client IP behind trusted reverse proxies (#607)

* feat(server): log real client IP behind trusted reverse proxies

Add trustedProxies (OCAP_TRUSTEDPROXIES) and remoteIPHeaders
(OCAP_REMOTEIPHEADERS, default X-Forwarded-For, X-Real-IP). When the
direct peer is a trusted proxy, RemoteAddr is replaced with the client
address from the headers, X-Forwarded-For read right to left so entries
the client sent itself are skipped, and the access log adds the proxy as
proxy_addr. No proxy is trusted by default, so headers are ignored.

* docs: explain trusting Cloudflare behind another reverse proxy

* refactor(server): drop proxy_addr from the access log

With a single reverse proxy it is the same address on every line.

* style: gofmt realip_test.go

* fix(server): match IPv4-mapped trusted proxy prefixes

Addresses are unmapped before matching, but a trusted proxy given as an
IPv4-mapped CIDR (::ffff:172.18.0.0/112) stayed an IPv6 prefix and never
matched. Convert it to the equivalent IPv4 prefix; reject mapped
prefixes shorter than /96, which cover more than the mapped range.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants