feat(gateway): trust forwarded IPs only from trusted proxies

[seonghobae]

Security outcome

• trust X-Forwarded-For and X-Real-IP only when the direct peer is inside an explicitly configured TRUSTED_PROXY_CIDRS range
• default gateway rate limiting, DNSBL matching and security-event attribution to the direct peer when no trusted proxy authorizes forwarded identity
• parse trusted proxy chains right-to-left, normalize IPv4-mapped peers, and fail closed on malformed or ambiguous client identity
• keep the same identity contract covered by unit/property/libFuzzer tests and operational guidance

Current integration state

Exact current head is 72ac1a2a2902a10aabc6e20169b9ae89adb5f9c8, stacked on runner-acquisition prerequisite #145 at 2d41c4079f9a4465c3142a0aa2dd5895cb11f793. The non-destructive merge preserves the trusted-proxy delta and #145's explicit hosted-runner contract. The only overlapping file, .github/workflows/fuzz.yml, was semantically combined: ubuntu-24.04 is pinned while fuzz_trusted_forwarded_client_ip remains in the matrix. The PR base is temporarily #145's branch so the effective review diff remains the trusted-proxy slice.

All previously returned review threads are resolved on the predecessor lineage, including right-to-left forwarding-chain handling, malformed-chain fail-closed behavior, public serving with connection metadata, registry/bootstrap ownership, IPv4-mapped proxy normalization, fuzz-oracle parity, fuzz CI coverage, and admin-secret provenance. Their old check results do not transfer to this new exact head.

Fresh repository and central gates must be regenerated on 72ac1a2…. Queued, stale or predecessor evidence is non-passing. After #145 reaches protected main, retarget this PR to fresh main and reacquire the then-live exact-head gates.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6a21349e-c335-4884-b6df-56b09b0bc5e3

📥 Commits

Reviewing files that changed from the base of the PR and between b009e87 and b92c55b.

📒 Files selected for processing (2)

• fuzz/fuzz_targets/fuzz_trusted_forwarded_client_ip.rs
• tests/fuzz_invariants.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• fuzz/fuzz_targets/fuzz_trusted_forwarded_client_ip.rs
• tests/fuzz_invariants.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

신뢰 프록시 CIDR을 크레덴셜 레지스트리에서 초기화합니다. 게이트웨이는 신뢰된 피어의 전달 헤더만 사용하고 오른쪽부터 첫 비신뢰 주소를 선택합니다. IPv4-mapped 주소와 종료 신호 오류 처리를 보강했습니다.

Changes

신뢰 클라이언트 IP 귀속

Layer / File(s)	Summary
신뢰 프록시 설정과 CIDR 판정 src/credentials.rs, src/lib.rs	trusted_proxy_cidrs 크레덴셜을 환경 변수와 파일에서 부트스트랩합니다. IpNet::contains는 IPv4-mapped IPv6 주소를 IPv4로 정규화합니다.
게이트웨이 피어 주소 기반 IP 귀속 src/lib.rs, docs/runbooks/operations.md	게이트웨이가 ConnectInfo<SocketAddr>를 요구합니다. 신뢰된 피어의 전달 헤더를 오른쪽부터 검사하고 X-Real-IP를 폴백으로 사용합니다. 운영 문서에 헤더 정규화와 관련 표준을 추가했습니다.
게이트웨이 검증과 회귀 테스트 src/lib.rs, tests/fuzz_invariants.rs, fuzz/Cargo.toml, fuzz/fuzz_targets/fuzz_trusted_forwarded_client_ip.rs	비신뢰 피어의 헤더 무시, 신뢰 프록시 체인 처리, 연결 정보 누락 오류, 실제 TCP 피어 주소, IPv4-mapped 주소를 검증합니다. 프로퍼티 테스트와 퍼즈 타깃을 추가했습니다.
종료 신호 설정 오류 전파 src/main.rs	종료 신호 퓨처를 시작 전에 arm합니다. Unix와 비-Unix 신호 핸들러의 등록 오류를 전파하고 관련 테스트를 추가했습니다.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🔵 Low · up to b92c5

The gateway now trusts forwarded client addresses only from configured trusted proxies and otherwise uses the direct peer for rate limiting, DNSBL matching, and event attribution. The change is mergeable with owner follow-up because the client-attribution behavior still needs the required supporting research citations and source references.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Gateway
  participant ConnectInfo
  participant AppState
  Client->>Gateway: 요청과 전달 헤더 전송
  Gateway->>ConnectInfo: 피어 SocketAddr 추출
  Gateway->>AppState: trusted_proxies 조회
  AppState-->>Gateway: 신뢰 프록시 CIDR 반환
  Gateway->>Gateway: 전달 체인을 오른쪽부터 검사
  Gateway-->>Client: 판정된 클라이언트 IP로 요청 처리

Loading

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	신뢰된 프록시 CIDR 확인, 오른쪽에서 왼쪽으로의 결정적 체인 처리, 비신뢰 피어의 스푸핑 방지, IPv4-mapped 주소 처리는 구현과 테스트에 반영되었습니다. 그러나 #83의 분산 admission control, 메모리·카디널리티 제한, TTL eviction, 전역 quota, overload 및 backpressure 처리, degradatio…	#83의 미충족 요구사항을 구현하거나 별도의 후속 이슈로 분리하고, 해당 범위를 제외하도록 이슈를 갱신하십시오. 최소한 bounded local limiter, distributed quota authority 연동, overload/backpressure 정책, fail-open/fail-closed 정책, 안정적인 rejection 응답과 메트릭을 추가로 검증해야 합니다.
Out of Scope Changes check	⚠️ Warning	신뢰된 클라이언트 IP 처리와 관련된 코드, 문서, 퍼즈 테스트, 프로퍼티 테스트는 범위에 맞습니다. 그러나 shutdown_signal, SIGTERM 핸들러, arm_shutdown_future, readiness 이전 신호 등록 변경은 #83의 trusted client attribution 또는 admission-control 요구사항과 직접…	셧다운 변경을 별도의 관련 이슈로 분리하거나 별도 pull request로 이동하십시오. 현재 pull request에 유지하려면 #83과의 명확한 요구사항 연결 및 수용 기준을 추가하십시오.
Docstring Coverage	⚠️ Warning	Docstring coverage is 64.13% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 92 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 신뢰된 프록시에서만 전달된 IP를 신뢰하도록 변경하는 핵심 기능을 정확하고 간결하게 설명합니다.

Full details: Linked Issues check

Explanation

신뢰된 프록시 CIDR 확인, 오른쪽에서 왼쪽으로의 결정적 체인 처리, 비신뢰 피어의 스푸핑 방지, IPv4-mapped 주소 처리는 구현과 테스트에 반영되었습니다. 그러나 #83의 분산 admission control, 메모리·카디널리티 제한, TTL eviction, 전역 quota, overload 및 backpressure 처리, degradation 정책, 안정적인 429 응답, 메트릭, 관련 검증 항목은 이 변경에서 확인되지 않습니다. 또한 #83이 요구하는 Forwarded 헤더 처리는 요약에 명시되지 않았습니다.

Full details: Out of Scope Changes check

Explanation

신뢰된 클라이언트 IP 처리와 관련된 코드, 문서, 퍼즈 테스트, 프로퍼티 테스트는 범위에 맞습니다. 그러나 shutdown_signal, SIGTERM 핸들러, arm_shutdown_future, readiness 이전 신호 등록 변경은 #83의 trusted client attribution 또는 admission-control 요구사항과 직접 연결되지 않아 범위 밖 변경으로 보입니다.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/trusted-proxy-admission

---

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.}

[devin-ai-integration]

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

Devin Review found 0 new potential issues.

[seonghobae]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.