Feature gap: SYN cookie flood protection implemented in eBPF, missing from userspace-dp

[psaab]

Gap

The eBPF dataplane implements SYN cookie flood protection using kernel kfuncs (bpf_tcp_raw_gen_syncookie_ipv4/v6, bpf_tcp_raw_check_syncookie_ipv4/v6): under SYN flood, XDP generates a SYN-ACK with a cryptographic cookie, replies via XDP_TX, and validates the returning ACK before admitting the connection. The userspace dataplane has no equivalent. Configs with set security flow syn-flood-protection-mode syn-cookie are explicitly rejected by the userspace capability gate, forcing fallback to the eBPF dataplane.

eBPF implementation (source of truth)

• bpf/xdp/xdp_screen.c:21-26 — declares kernel kfunc helpers
• bpf/xdp/xdp_screen.c:138 — bpf_tcp_raw_gen_syncookie_ipv4(iph, tcph, ...) mints cookie
• bpf/xdp/xdp_screen.c:254 — return XDP_TX reflects the SYN-ACK back to the client
• bpf/xdp/xdp_screen.c:419 — bpf_tcp_raw_check_syncookie_ipv4(iph, tcph) validates returning ACK
• bpf/headers/xpf_common.h:311 — SCREEN_SYN_COOKIE (1 << 14) flag and synproxy_active state in struct flood_state
• pkg/dataplane/userspace/snapshot.go:1518-1521 — userspaceSupportsScreenProfiles() returns false when SynFloodProtectionMode == \"syn-cookie\"

Userspace-dp gap

Searched: grep -rn 'syn_cookie\\|SYN_COOKIE\\|syncookie\\|synproxy' userspace-dp/src/ — zero matches.

userspace-dp/src/screen.rs implements synproxy_active=false only — SynProfile::syn_flood_threshold triggers a drop rather than a cookie reply.

Recommended fix

Implement RFC 4987-style SYN cookie keyed-MAC handling in userspace-dp/src/screen.rs:

1. Per-zone SipHash/keyed-MAC secret + 64-second rotation
2. On SYN-flood detection: mint cookie from (src_ip, src_port, dst_ip, dst_port, mss_idx, t), build SYN-ACK frame, hand to TX completion pipeline for reply
3. On returning ACK from suspect source: validate cookie, on success synthesize the SYN as if it arrived, install session
4. Remove SynFloodProtectionMode == \"syn-cookie\" gate in pkg/dataplane/userspace/snapshot.go:1518

Alternative: punt SYN-flood traffic to kernel tcp_syncookies=2 mode via a TC redirect — operationally simpler but loses XDP-rate processing.

Blocker for #1373

This must land before Phase 4 (BPF source removal) of #1373 (retire eBPF dataplane). Currently the userspace capability gate falls back to the eBPF dataplane when this config is set; once eBPF is removed the fallback target disappears.

---

Refined contract (added 2026-05-17 after triple-review of #1384)

See docs/pr/1373-retire-ebpf-dataplane/plan-1374-syn-cookies.md for the full implementation contract refined through 4 rounds of Claude+Codex+Gemini Pro 3 review. New since the original issue body:

• Epoch contract: transmit epoch & 0x1f (5 bits); MAC and secret derivation use the full monotonic epoch. Validation tries current + previous full epochs whose low 5 bits match the transmitted field. A cookie minted 32 epochs ago has matching low bits but must reject because its full epoch is outside the validation window.
• Epoch publication must be generation-atomic with the secret snapshot — workers must not see new full epoch with old per-zone secret or vice versa.
• Risks called out: replay/wrap (32-epoch ambiguity), failover skew (bounded monotonic-epoch skew across HA peers), budget starvation (reply budget must not drain forwarding frames), validated-client cache pressure (no eviction by attacker-generated valid-looking ACKs).
• Required tests added: screen::syn_cookie_epoch_low_bits_wrap_rejects_32_epoch_old_cookie, screen::syn_cookie_validation_tries_current_and_previous_full_epoch, screen::syn_cookie_budget_drop_does_not_starve_tx, plus deriveUserspaceCapabilities() admit-only-after-wired Go gate.

[psaab]

Implementation contract

Acceptance criteria

1. `userspace-dp/src/screen.rs` implements RFC 4987 SYN cookie mint + validate using HMAC-SHA1 (or HMAC-SHA256) with per-zone secret + 64-second rotation.
2. Cookie payload encodes `(src_ip, src_port, dst_ip, dst_port, mss_idx, t_high_bits)` so validation can confirm the SYN-ACK was originated by this dataplane and the returning ACK matches.
3. On SYN-flood detection (existing threshold logic): mint cookie, build SYN-ACK frame in UMEM, push to TX completion pipeline for reply.
4. On returning ACK from a flood-suspect source: validate cookie. On success, synthesize the SYN as if it arrived, install session.
5. Capability gate at `pkg/dataplane/userspace/snapshot.go:1518-1521` for `SynFloodProtectionMode == "syn-cookie"` is removed.
6. Failed validation drops the packet (no session created); validation failures counted in a screen-drop counter.

Test plan

• Cargo: `screen::syn_cookie_mint_validate_roundtrip` — mint cookie for known tuple, immediately validate, assert match.
• Cargo: `screen::syn_cookie_validate_rejects_modified_tuple` — flip a bit in src_port, assert validation fails.
• Cargo: `screen::syn_cookie_validate_rejects_stale_secret` — advance time past 2 × 64-second rotation, assert old cookie fails validation.
• Cargo: `screen::syn_cookie_chosen_when_threshold_exceeded` — drive incoming SYN rate above threshold, assert SYN-ACK frame is emitted (not just a drop).
• Integration: lab SYN flood via hping3 against userspace cluster with `syn-flood-protection-mode syn-cookie` configured; verify (a) SYN-ACK replies are sent at SYN-flood rate, (b) legitimate ACKs admit sessions, (c) random ACKs from unrelated sources are dropped.
• Smoke: existing screen smoke (other 11 checks) still passes.

Dependencies

#1381 should land first — capability gate removal is cleanest after the userspace `Manager` has its own interface and can independently report the capability without inheriting from the embedded eBPF Manager.

Size estimate

L (1-2 weeks). Cookie crypto + UMEM TX frame construction + session synthesis on ACK + integration testing. The TX-frame-build-on-screen-decision path is new; it needs careful UMEM ownership handling.

[psaab]

Plan-review round 1 — PLAN-NEEDS-MAJOR

Reviewer	Verdict
Codex	PLAN-NEEDS-MAJOR (10 concrete gaps + ACK semantic divergence)
Gemini Pro 3	PLAN-KILL (overreaches on HMAC perf + TX completion)

Convergent substantive findings

1. HMAC vs Mpps is a real concern but not fatal. Linux kernel SYN cookies use SipHash (not HMAC-SHA1/256). Existing eBPF uses kernel kfunc bpf_tcp_raw_gen_syncookie_ipv4 which internally uses SipHash. Plan v2 should specify SipHash, not HMAC-SHA1, with explicit per-zone secret rotation.
2. ACK path diverges from existing eBPF contract. Per docs/syn-cookie-flood-protection.md:28 and xdp_screen.c:839, eBPF validates the cookie ACK, marks the client validated, sends RST, then lets the client retransmit SYN through normal session creation. The plan's "validate ACK then synthesize SYN + install session" is a larger semantic change. Pick: match eBPF (RST + retransmit) OR explicit redesign with full conntrack/policy/NAT/FIB design.
3. HA secret sync is missing. Per-zone secret rotated locally → failover invalidates in-flight cookies. Needs cluster-consistent secrets with overlap OR config-synced rotation.
4. UMEM TX backpressure under flood. TX frames are a shared reserved pool (worker/mod.rs:255); TX can stall when no free frame (tx/transmit.rs:84). Plan must define a hard cookie-reply budget that prefers dropping flood SYNs over starving legitimate TX. Codex notes this; Gemini correctly flags it as architecturally important.
5. Cookie field budget = 32 bits TCP ISN. Stronger HMAC doesn't add transmitted bits — PRF quality only. Plan needs explicit bit layout: epoch bits + MSS index + MAC bits.
6. Time handling: monotonic 64s epoch with current+previous secret overlap. Cannot rely on wall clock (NTP jumps invalidate).
7. Existing eBPF parity tests must port: SCREEN_SYN_COOKIE flag (xpf_common.h:311), synproxy_active state, sent/valid/invalid/bypass counters.
8. Capability gate today: pkg/dataplane/userspace/snapshot.go:1509-1521 rejects SynFloodProtectionMode=syn-cookie; manager_test.go:2425 pins the rejection. Plan v2 must remove BOTH.

Gemini KILL — over-claims

• "In-place RX→TX bounce required, TX completion pipeline reply unacceptable" — Gemini's framing here is too strong. The userspace dataplane DOES have a TX completion pipeline that supports reply-to-source patterns (used for ICMP-TE today). Plan v2 should profile the actual cost rather than asserting it's infeasible.
• HMAC vs SipHash concern is valid (see point 1) but Gemini frames it as a kill rather than a plan refinement.

Recommended plan v2

• Crypto: SipHash-1-3 (not HMAC-SHA1), per-zone secret rotated 64s
• ACK semantics: match eBPF (validate cookie → RST → client retransmits) — simpler conntrack/policy implications than session-synthesis
• HA: cluster-consistent secrets via config-sync OR derive secret deterministically from (zone_id, epoch, master_key) where master_key is HA-synced
• TX budget: hard cap on cookie-reply frame allocation per binding; flood-shape rejects over-budget SYNs
• Cookie layout: explicit 32-bit ISN spec: [5 bits epoch] [3 bits MSS index] [24 bits MAC]
• Tests: cookie mint+validate roundtrip, MSS-index encoding parity with eBPF, NTP-rollback handling, validated-client LRU cache

Size: L (1-2 weeks) if scope stays at RST-and-retransmit semantics; XL (2-3 weeks) if session-synthesis path is kept.

Codex task: `task-mp8rg8b4-k0nxm7`. Gemini Pro 3 task: `task-mp8rgiwg-8li50m`.

[psaab]

Update after #1393: keep open, but narrow to runtime SYN-cookie integration. Landed: deterministic userspace cookie codec/layout and tests. Remaining: SYN-ACK TX emission with bounded budget, returning ACK validation/RST path, HA-safe secret publication, bounded validated-client cache, counters/status, and removal of the userspace capability gate.