Repository navigation
feat(start-wrt): allow IPv6 router advertisements per device - #4370
Conversation
helix-white
left a comment
There was a problem hiding this comment.
Approved at 8099c47. No correctness regressions found; merge-tree and GitHub both report a clean merge into master.
The existing bridge-forward guard now passes router advertisements with zero router lifetime, restoring delivery of Thread route advertisements between bridge ports. Nonzero-lifetime RAs remain blocked; DHCP/DHCPv6 filtering and the router's own output path are unchanged. This extends the existing raw-payload rule without adding state or dependencies. The documentation and unreleased fragment match the narrower policy.
The deliberate tradeoff is that lifetime-zero RAs can advertise prefixes, specific routes, and DNS information. This is default-router filtering, not blanket protection against foreign RA configuration.
Implementation diff: +1 / −1 lines in 1 files (excludes lockfiles, tests, docs, release notes, and changelog).
Verification: I checked the 48-bit offset and 16-bit width against the Router Lifetime wire field, traced the existing fw4 image-staging path, and ran nft --check --file projects/start-wrt/backend/nftables/ruleset-pre/10-startwrt-lan-dhcp-guard.nft successfully inside an isolated user/network namespace. git diff --check also passed. I reused the author's recorded K1 tests covering lifetime-zero passage, drops for lifetimes 1/256/1800, the unguarded control, router-originated RAs, and DHCP filtering rather than repeating them. Real Thread/Matter interoperability is not verified. Prettier and changelog/version CI passed; other CI checks were still pending at inspection, and approval does not imply those checks passed.
Helix-Harness: pi
Helix-Model: openai-codex/gpt-6.1-sol
|
Following discussion with @dr-bonez, I recommend replacing the blanket lifetime-zero exemption with an explicit, default-off per-device “Allow IPv6 router advertisements” permission. Enable it for a Thread border router; continue blocking forwarded RAs from other LAN devices regardless of Router Lifetime. Keep DHCP/DHCPv6 filtering and the router's own RA output unchanged. This follows the authorization model in RFC 6105 RA Guard. Enforcement must account for RFC 7113 extension-header and fragmentation evasions rather than inspecting only the fixed IPv6 Next Header field. The permission should warn that it grants IPv6 routing/configuration authority, not merely Thread access: an authorized device may advertise default routes, other prefixes/routes, and DNS configuration. MAC-based device authorization is spoofable; trusting an entire shared port or Wi-Fi interface would authorize other devices behind it as well. Correction to my earlier approval: calling this “default-router filtering” was too strong. RFC 4191 §3.1 specifies that a |
The LAN guard dropped every router advertisement switched between bridge ports, which also cut off Thread border routers (Apple TV, HomePod, Nest Hub, Home Assistant OTBR) announcing the Thread route to controllers on another port or band. Exempting RAs with router lifetime 0 was not a safe answer: a ::/0 Route Information Option (RFC 4191) still installs a default route on hosts that process it. Replace the exemption with a default-off per-device "Allow IPv6 router advertisements" permission, following RFC 6105's authorization model: - `_allow_ra` on the device's DHCP host entry, set through the new `devices.set-router-advertisements` RPC and a confirm-gated switch on the device page that warns it grants addressing, routing, DNS and default-gateway authority. - The guard table declares an `ra_allow` ether_addr set and drops RAs whose source MAC is outside it. The daemon renders the set into ruleset-pre/11-startwrt-lan-ra-allow.nft, which also declares the set so it loads against a guard file without one, on each toggle, on forget (ahead of the dnsmasq restart the flush waits on), and at boot, since sysupgrade does not keep /usr/share. - RFC 7113: an RA behind extension headers is matched by a first Next Header of 0/43/44/51/60, hop limit 255 and ICMPv6 type 134 at @th, which the kernel resolves past the header chain. This covers stacked headers rather than one rule per header type. `meta l4proto` remains unavailable in the bridge family without kmod-nft-bridge. The nft include writer from the IPv6 MAC binding becomes the shared `sync_nft_include`. DHCP and DHCPv6 filtering and the router's own RA output are unchanged. Benched on the K1 with two synthetic LAN clients and a raw AF_PACKET RA sender: - not allowed: RAs with no extension header, HBH, DST, HBH+DST, and lifetime 0 all dropped; no address or default route formed - allowed via the UI's RPC: the same RAs passed and formed SLAAC addresses, so the receiver accepts header-wrapped RAs and the earlier drops were the guard's - revoke: dropped again immediately; forget: revoked within seconds, while dnsmasq was still restarting - the allow file deleted, then a reboot: boot heal rebuilt the file and the live set - bench.sh smoke green once dnsmasq was up (it starts about two minutes after boot on this bench)
8099c47 to
495d02e
Compare
helix-white
left a comment
There was a problem hiding this comment.
The explicit default-off permission and confirmation warning address the earlier security-policy concern. Requesting changes on two implementation defects at 495d02e:
-
[P2] The extension-header heuristic drops valid non-ICMP traffic (
backend/nftables/ruleset-pre/10-startwrt-lan-dhcp-guard.nft:22). It checks hop limit and the first transport byte without establishing that the transport is ICMPv6. A valid UDP packet with a Hop-by-Hop header, hop limit 255, and source port 34304 (0x8600) is therefore treated as an RA from an unauthorized device. I reproduced this on a Linux bridge: the RA drop counter increased and the UDP packet did not reach the following accept rule. Source ports 34304–34559 share the problem, as does TCP. The proposal enables the existing OpenWrtkmod-nft-bridgefacility and usesmeta l4proto ipv6-icmpplusicmpv6 type nd-router-advert, rather than approximating protocol identity. It also removes the comments made stale by adding that dependency. -
[P2] A failed firewall activation becomes a successful no-op on retry (
backend/ctrl/src/lan_guard.rs:63–67, with the related forget path indevices.rs:1977–1988). The include is written before activation, but activation only runs when file bytes change. If the activation commands cannot execute, a revoke can leave the old live authorization intact; retrying the same request sees matching file bytes, skips activation, and reports success. Forget additionally swallows activation failures, and an absent-host revoke returns before reconciliation. The proposal always awaits activation for an effectful permission request, including an absent-host revoke, and makes forget return activation errors after completing its network cleanup instead of logging success. This deliberately means an identical explicit request can reload the firewall: matching persisted intent is not proof of live enforcement.
Proposed changes: 495d02e...proposal/4370
Verification: merge-tree passed against current origin/master. In isolated user/network namespaces, the UDP regression fails against the reviewed rule and passes with the proposal; bare and Hop-by-Hop-wrapped RAs are dropped for unauthorized MACs and pass for authorized MACs (five passing packet cases). cargo test -p startwrt-core lan_guard::tests passed all three tests through helix-build. The new activation-failure/retry test also fails when the previous conditional-activation behavior is restored, confirming it distinguishes the fix. Pinned-nightly rustfmt checks and git diff --check passed. I reused the author's recorded full Rust suite, frontend typecheck/i18n checks, and K1 lifecycle evidence for the otherwise unchanged portions. The proposed module selection has not been verified in a rebuilt/flashed K1 image; no VM or full image build was run. Pending PR CI is not part of this verdict.
Helix-Harness: pi
Helix-Model: openai-codex/gpt-6.1-sol
Helix-Harness: pi Helix-Model: openai-codex/gpt-6.1-sol
…ailed forget With kmod-nft-bridge in the image, the DHCPv4 and DHCPv6 guard rules match on `meta l4proto udp`, which the kernel resolves past the IPv6 extension-header chain. The DHCPv6 rule checked only the fixed Next Header, so a reply behind a Hop-by-Hop header crossed the bridge (RFC 7113's evasion, the same class fixed for router advertisements). The guard file now states the module dependency, since a failed include leaves fw4 with no ruleset. Forget returned an allow-list reload failure without an activity entry; it now records that the device was forgotten but its router advertisements could not be revoked. API_CONTRACT states the reload-on-every-call and error semantics of devices.set-router-advertisements and devices.forget. devices.md no longer claims the guard covers the whole network: it sees traffic between the router's ports and Wi-Fi networks. Checked in a disposable container: the guard file plus a generated allow list load, and reload, on a 6.12 kernel. Across a two-namespace bridge, RAs plain and behind HBH were dropped from an unlisted MAC and passed from a listed one; UDP behind HBH from source port 34304 passed; DHCPv6 replies plain and behind HBH and a DHCPv4 reply were dropped; ordinary IPv4 UDP passed. cargo test -p startwrt-core passed 783 tests.
helix-white
left a comment
There was a problem hiding this comment.
Approved at a333294. Both points from my last review are resolved, and merge-tree reports a clean merge into master.
Before merge: the trust model is the one recommended on this thread. Granting the permission gives a device full IPv6 routing and DNS authority, not Thread-only authority, and the grant is keyed on a MAC address that another LAN device can copy. The confirmation dialog and devices.md both say so. The stricter alternative, which also filters RA contents (RIO prefixes, RDNSS), is not standardized and would need Thread-specific parsing. Is per-device trust sufficient for this release?
Summary
- A device gets a default-off Allow IPv6 router advertisements permission (
_allow_raon its DHCP host entry,devices.set-router-advertisements). The bridge guard drops forwarded RAs from any MAC outside thera_allowset, whatever the Router Lifetime value. Enabling the permission requires confirmation. kmod-nft-bridgeis added to the image, so the guard's RA, DHCPv4 and DHCPv6 rules usemeta l4proto, which resolves the protocol past IPv6 extension headers. Additional fix: before this change, a DHCPv6 reply behind a Hop-by-Hop header crossed the bridge; it is now dropped.- Every permission request reloads the firewall. A failed reload returns an error, and repeating the request applies it. Forget finishes its cleanup, logs a failed activity entry, and returns the reload error.
- The allow list is regenerated at boot because sysupgrade does not keep
/usr/share. The router's own RA output is unchanged.
Implementation diff: +379 / −39 lines in 21 files (excludes lockfiles, tests, docs, release notes, and changelog).
Approach
- The change extends the existing
startwrt_lan_guardbridge table rather than adding an RA daemon. It reuses the locked atomic nft include writer from the IPv6 MAC binding, now shared aspublished_ports::sync_nft_include. - Adding
kmod-nft-bridgereplaces the earlier raw-offset matching, which could not identify the transport protocol. It is a new image dependency; the K1 kernel config already builds the module. - 807ab14 is my proposal from the previous review, applied unchanged. a333294 is the author's: DHCP rules past extension headers, the forget activity entry, and contract and docs updates.
Residual gap: a fragmented RA whose ICMPv6 header is not in the first fragment still crosses the bridge, because meta l4proto cannot resolve it. Hosts implementing RFC 6980, including Linux, drop fragmented ND messages. This PR does not implement RFC 7113's drop of incomplete first fragments.
Testing
- I confirmed 807ab14 is identical to
proposal/4370, which I verified last round with packet tests in an isolated bridge namespace and thelan_guardtests. - In an isolated user/network namespace, the final
10-startwrt-lan-dhcp-guard.nftpassesnft -cand loads; the kernel canonicalizes the three rules as expected. - I built the mock demo UI at this head and captured the device-page permission and its confirmation dialog. Screenshots follow in a separate comment.
- I reused the author's recorded evidence rather than repeating it:
cargo test -p startwrt-corewith 783 tests passing; frontend typecheck, i18n and format checks; container packet cases on a 6.12 kernel; and the K1 image bench. The bench covered RA, UDP and DHCPv6 cases with and without extension headers, for listed and unlisted MACs, plus failed-reload retry, boot regeneration, and the UI flow. - Not verified: interoperability with a real Thread border router or Matter controller. Several CI checks were skipped and others passed; this verdict does not wait on the rest.
Helix-Harness: claude-code
Helix-Model: claude-opus-5-5
|
Screenshots for the approval above, from the mock demo UI built at a333294. |
|
@Dominion5254 This PR now conflicts with What the merge commit
Verification: merge-tree is clean against the current |
…fetime # Conflicts: # projects/start-wrt/API_CONTRACT.md
e1a7f37
helix-white
left a comment
There was a problem hiding this comment.
Approved at e1a7f37. Since my approval at a333294, the only new commit merges master (#4378, #4386). Merge-tree is clean against the current master, and GitHub reports the PR as mergeable.
The merge resolves the devices.forget contract conflict the same way as my proposal/4370: #4386's per-instance lease flush and dnsmasq reload, plus this PR's sentence on allow-list reload failure and retry. The only difference is the comment in forget, which now reads "before the potentially slow dnsmasq reload". That is accurate after #4386, and the RA revoke still runs before flush_device_from_network.
Before merge: this is the same trust-model question as before. A device granted the permission gets full IPv6 routing and DNS authority, not Thread-only authority, and the grant is keyed on a MAC address another LAN device can copy. @dr-bonez has since approved with that disclosed.
Summary
- A device gets a default-off Allow IPv6 router advertisements permission (
devices.set-router-advertisements). The bridge guard drops forwarded RAs from any MAC outsidera_allow, whatever the Router Lifetime value. Enabling the permission requires confirmation. kmod-nft-bridgeis added to the image, so the RA, DHCPv4 and DHCPv6 rules match withmeta l4proto, which resolves the protocol past IPv6 extension headers. Additional fix: before this change, a DHCPv6 reply behind a Hop-by-Hop header crossed the bridge; it is now dropped.- Every permission request reloads the firewall, and a failed reload returns an error that a retry fixes. Forget finishes its cleanup, logs a failed activity entry, and returns the reload error. The allow list is regenerated at boot.
Implementation diff: +379 / −39 lines in 21 files (excludes lockfiles, tests, docs, release notes, and changelog).
Residual gap: a fragmented RA whose ICMPv6 header is not in the first fragment still crosses the bridge. RFC 6980 hosts, including Linux, drop those.
Testing: For my resolution of the same merge (26b46f27f, identical to this head apart from that one comment), cargo test -p startwrt-core filtered to lan_guard and forget passed 6/6, so the merged crate builds. My earlier evidence still applies because the rest of the tree is unchanged: nft -c and a load of the guard file in an isolated namespace, packet cases on the earlier proposal, and the UI screenshots. I reused the author's recorded K1 bench and full Rust suite (783 tests). Not verified: interoperability with a real Thread border router or Matter controller. This verdict does not wait on CI.
Helix-Harness: claude-code
Helix-Model: claude-opus-5-5


Summary
The LAN guard (#4236, unreleased) dropped every router advertisement switched between bridge ports, which also cut off Thread border routers (Apple TV, HomePod, Nest Hub, Home Assistant OTBR) announcing the Thread route. An exemption for router lifetime 0 is not safe: a
::/0Route Information Option (RFC 4191 §3.1) still installs a default route on hosts that process it. This adds an explicit, default-off per-device Allow IPv6 router advertisements permission instead, following RFC 6105's authorization model._allow_raon the device's DHCP host entry, set through the newdevices.set-router-advertisementsRPC. The device page gets a switch under Permissions. Turning it on asks for confirmation and warns that the device can give other devices IPv6 addresses, routes, DNS servers and a default gateway, not merely Thread access.kmod-nft-bridgeis added to the image, so the bridge-family guard matches onmeta l4proto, which the kernel resolves past the IPv6 extension-header chain (RFC 7113).meta l4proto ipv6-icmp icmpv6 type nd-router-advertfrom a source MAC outside thera_allowset.meta l4proto udptoo. The DHCPv6 rule had the same evasion: it checked only the fixed Next Header.=m), so it changes no kernel config. The guard file states the dependency, since a failed include leaves fw4 with no ruleset.ruleset-pre/11-startwrt-lan-ra-allow.nft, which also declares the set. It is rewritten on each permission change, on forget (before the dnsmasq restart the flush waits on), and at boot, since sysupgrade does not keep/usr/share.published_ports::sync_nft_include.devices.md/lan.md/backups.md, and the unreleased fragment are updated.Commits: 495d02e (the permission), 807ab14 (helix-a's review corrections:
kmod-nft-bridgeandmeta l4protofor RAs, reload on every request, forget returns the error), a333294 (DHCP rules past extension headers, the forget activity entry, contract and docs).Not covered: an RA whose ICMPv6 header is pushed into a non-first fragment still crosses the bridge. RFC 6980 hosts drop fragmented ND messages.
Verification
cargo test -p startwrt-core: 783 passed, including helix-a's activation-failure retry testmake start-wrt-format,npm run check:wrt,npm run check:i18n:wrt, prettier: cleanK1 bench,
make start-wrt-imageat a333294 sysupgraded with settings kept:nft_meta_bridge,nft_reject_bridgeandnf_conntrack_bridgeloaded at boot; fw4 and the guard table loaded; the daemon matched the a333294 build.bench.sh smokegreen after the flash and again after a reboot./etc/init.d/firewallmade non-executable):Not exercised: a real Thread border router or Matter controller.
Outside this PR:
devices.forgettakes about 100 s on the bench, because its flush waits on a slow/etc/init.d/dnsmasq start. The revoke happens before that wait, at the start of the call.