🐛 fix(proxy): correctly classify IPv6 transition addresses in upstream validation

[gaby]

Description

By default the proxy middleware only connects upstreams to public addresses and refuses non-public ones (loopback, unspecified, RFC 1918 private, link-local, multicast, and RFC 6598 CGNAT). That decision is made in isBlockedIP.

Several IPv6 "transition" formats embed an IPv4 address inside an IPv6 literal (6to4, Teredo, the NAT64 prefixes, ISATAP, SIIT, and the IPv4-compatible/mapped forms). isBlockedIP only recognized two of them — IPv4-compatible ::a.b.c.d and the NAT64 well-known prefix 64:ff9b::/96 — so the remaining forms were classified inconsistently with the IPv4 they wrap. For example ::ffff:0:7f00:1 and 2002:7f00:1:: both encode 127.0.0.1, yet were treated as ordinary public IPv6 while the bare 127.0.0.1 was correctly refused.

This PR makes the classifier handle the full set of well-known, fixed-prefix embeddings so the same result is produced regardless of which IPv6 form is used to write the address.

Changes introduced

• Added isBlockedIPv6TransitionRange to reject the deprecated / local-use ranges in their entirety, where the embedded IPv4 offset is operator-dependent and there is no legitimate use as an upstream: 6to4 2002::/16 (RFC 3056, deprecated by RFC 7526), Teredo 2001:0000::/32 (RFC 4380), and the NAT64 local-use prefix 64:ff9b:1::/48 (RFC 8215, local-use only).
• Extended embeddedIPv4 to unwrap the embedded IPv4 (and re-apply the same classification) for the forms whose offset is fixed and unambiguous and may legitimately be public: NAT64 well-known prefix 64:ff9b::/96 (RFC 6052), ISATAP (RFC 5214), SIIT IPv4-translated ::ffff:0:0/96 (RFC 2765), and IPv4-compatible ::a.b.c.d (RFC 4291). The IPv4-mapped form ::ffff:a.b.c.d continues to be handled directly since net.IP.To4 surfaces it.
• Extended Test_Security_IsBlockedIP with cases for every form above — non-public embeddings are refused, public embeddings (e.g. 8.8.8.8 wrapped as 6to4/NAT64/ISATAP/SIIT) remain allowed.

Behavior note: an upstream literal in the wholesale-blocked ranges (6to4, Teredo, NAT64 local-use) that wraps a public IPv4 is now refused. These are deprecated tunneling / local-use ranges that do not appear as real upstream targets, so this should not affect legitimate usage.

• Benchmarks: no change to hot paths; classification is a handful of extra byte comparisons on the existing validation path.
• Documentation Update: no user-facing API change.
• Changelog/What's New: worth a line under bug fixes.
• Migration Guide: not needed.
• API Alignment with Express: n/a.
• API Longevity: no signature changes; internal helpers only.
• Examples: n/a.

Type of change

• Code consistency (non-breaking change which improves code reliability and robustness)

Checklist

• Conducted a self-review of the code and provided comments for complex or critical parts.
• Added or updated unit tests to validate the effectiveness of the changes.
• Ensured that new and existing unit tests pass locally with the changes (go test ./middleware/proxy/, including -race).
• No new dependencies introduced.

🤖 Generated with Claude Code

[coderabbitai]

Walkthrough

The proxy SSRF blocklist now blocks additional IPv6 transition ranges, unwraps more fixed-offset embedded IPv4 forms, and recursively validates extracted addresses. Tests expand coverage for NAT64, 6to4, Teredo, ISATAP, and SIIT variants.

Changes

SSRF IP blocklist

Layer / File(s)	Summary
IPv6 transition blocking and validation middleware/proxy/security.go, middleware/proxy/security_test.go	isBlockedIP blocks deprecated or local-use IPv6 transition ranges, recognizes additional fixed-offset IPv4 wrappers, recursively checks embedded IPv4 addresses, and adds corresponding block/allow test cases.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• gofiber/fiber#4405: Updates the same proxy SSRF blocking logic and IPv4/IPv6 special-prefix handling.
• gofiber/fiber#4518: Modifies related NAT64 and IPv6 embedded-address unwrapping behavior and tests.

Suggested reviewers: renewerner87

Poem

I’m a rabbit guarding the IP gate,
Blocking tricky tunnels before they navigate.
Six-to-four and Teredo now meet the wall,
Wrapped IPv4 addresses are checked too, all.
Binky, binky—safer routes for all!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly states the proxy fix and accurately reflects the IPv6 transition address classification change.
Description check	✅ Passed	The description follows the template well and covers the problem, changes, type, and checklist with only minor non-critical gaps.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/proxy-ssrf-ipv6-bypass-v5synf

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}