Skip to content

feat(start-wrt): allow IPv6 router advertisements per device - #4370

Merged
Dominion5254 merged 4 commits into
masterfrom
wrt/lan-guard-ra-lifetime
Oct 24, 2026
Merged

Dominion5254 merged 4 commits into
masterfrom
wrt/lan-guard-ra-lifetime

Conversation

@Dominion5254

@Dominion5254 Dominion5254 commented Oct 23, 2026 •

Copy link
Copy Markdown
Member

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 ::/0 Route 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.

  • Permission: _allow_ra on the device's DHCP host entry, set through the new devices.set-router-advertisements RPC. 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.
  • Enforcement:
    • kmod-nft-bridge is added to the image, so the bridge-family guard matches on meta l4proto, which the kernel resolves past the IPv6 extension-header chain (RFC 7113).
    • RAs are matched as meta l4proto ipv6-icmp icmpv6 type nd-router-advert from a source MAC outside the ra_allow set.
    • The DHCPv4 and DHCPv6 reply rules use meta l4proto udp too. The DHCPv6 rule had the same evasion: it checked only the fixed Next Header.
    • The K1 kernel config already builds the package's three modules (=m), so it changes no kernel config. The guard file states the dependency, since a failed include leaves fw4 with no ruleset.
  • Allow list: the daemon renders 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.
  • Failure and retry: every effectful permission request reloads the firewall, including a revoke for a device with no host entry, so repeating a request whose reload failed applies it. A failed reload is an error even though the setting is saved. Forget completes its cleanup, records the failure in the activity log, and returns the error.
  • MAC spoofing: authorization is per device, not per port or interface, so other devices behind a shared port are not trusted. A MAC can be copied by another device on the LAN; the device docs say so.
  • Unchanged: the router's own RA output.
  • Refactor: the locked atomic nft include writer from the IPv6 MAC binding becomes the shared published_ports::sync_nft_include.
  • Docs and contract: API_CONTRACT (including the failure and retry semantics), regenerated bindings, live and mock API, all five locales, devices.md / lan.md / backups.md, and the unreleased fragment are updated.

Commits: 495d02e (the permission), 807ab14 (helix-a's review corrections: kmod-nft-bridge and meta l4proto for 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 test
  • make start-wrt-format, npm run check:wrt, npm run check:i18n:wrt, prettier: clean
  • Container on a 6.12 kernel: the guard file plus a generated allow list load and reload. Across a two-namespace bridge, nine packet cases behaved as expected.

K1 bench, make start-wrt-image at a333294 sysupgraded with settings kept:

  • Image: nft_meta_bridge, nft_reject_bridge and nf_conntrack_bridge loaded at boot; fw4 and the guard table loaded; the daemon matched the a333294 build. bench.sh smoke green after the flash and again after a reboot.
  • Unlisted MAC:
    • RAs plain, behind HBH, behind DST, and behind HBH+DST were dropped, with no address formed.
    • UDP from source port 34304, plain and behind HBH, reached the receiver; the guard counters did not move. This is the false-positive case from review.
    • DHCPv6 replies, plain and behind HBH, were dropped.
  • Listed MAC (granted through the UI's RPC path): RAs passed in every layout and formed SLAAC addresses. Its DHCPv6 replies were still dropped.
  • Failed reload (/etc/init.d/firewall made non-executable):
    • Revoke returned an error and the MAC stayed in the live set, so its RAs still passed. The identical revoke after restoring the script succeeded and its RAs were dropped.
    • Forget the same way: an error plus the activity entry, then a successful retry that emptied the set.
  • Boot heal: with the allow list deleted, a reboot rebuilt it, and enforcement was correct in both directions.
  • UI, headless Chromium against the router: enabling the switch opens the confirmation with the full warning, and Cancel leaves it off. Allow plus Save added the MAC to the live set. Disabling does not prompt, and Save removed it.

Not exercised: a real Thread border router or Matter controller.

Outside this PR: devices.forget takes 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.

helix-white
helix-white previously approved these changes Oct 23, 2026

@helix-white helix-white 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.

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

@helix-white

Copy link
Copy Markdown
Member

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 ::/0 Route Information Option overrides the header's preference and lifetime on hosts implementing that route-processing model. A zero Router Lifetime therefore does not reliably prevent a foreign default gateway. My earlier approval should not be treated as security-policy sign-off for the lifetime-only exemption; I recommend resolving this before merge.

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)
@Dominion5254
Dominion5254 force-pushed the wrt/lan-guard-ra-lifetime branch from 8099c47 to 495d02e Compare October 24, 2026 00:57
@Dominion5254 Dominion5254 changed the title fix(start-wrt): pass router advertisements that offer no default route feat(start-wrt): allow IPv6 router advertisements per device Oct 24, 2026

@helix-white helix-white 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.

The explicit default-off permission and confirmation warning address the earlier security-policy concern. Requesting changes on two implementation defects at 495d02e:

  1. [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 OpenWrt kmod-nft-bridge facility and uses meta l4proto ipv6-icmp plus icmpv6 type nd-router-advert, rather than approximating protocol identity. It also removes the comments made stale by adding that dependency.

  2. [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 in devices.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-white and others added 2 commits October 23, 2026 19:19
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
helix-white previously approved these changes Oct 24, 2026

@helix-white helix-white 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.

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_ra on its DHCP host entry, devices.set-router-advertisements). The bridge guard drops forwarded RAs from any MAC outside the ra_allow set, whatever the Router Lifetime value. Enabling the permission requires confirmation.
  • kmod-nft-bridge is added to the image, so the guard's RA, DHCPv4 and DHCPv6 rules use meta 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_guard bridge table rather than adding an RA daemon. It reuses the locked atomic nft include writer from the IPv6 MAC binding, now shared as published_ports::sync_nft_include.
  • Adding kmod-nft-bridge replaces 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 the lan_guard tests.
  • In an isolated user/network namespace, the final 10-startwrt-lan-dhcp-guard.nft passes nft -c and 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-core with 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

@helix-white

Copy link
Copy Markdown
Member

Screenshots for the approval above, from the mock demo UI built at a333294.

Device page: the new default-off Allow IPv6 router advertisements permission

Enabling it asks for confirmation and warns of full IPv6 routing and DNS authority

@helix-white

Copy link
Copy Markdown
Member

@Dominion5254 This PR now conflicts with master after #4386 (reload dnsmasq instead of restarting it). The conflict is a single text conflict in projects/start-wrt/API_CONTRACT.md, in the devices.forget description. I'm reviewing this PR rather than authoring it, so I haven't pushed to your branch. The resolved merge is on proposal/4370, which is a direct descendant of the PR head a33329402. To take it, fast-forward your branch:

git fetch origin proposal/4370 && git merge --ff-only FETCH_HEAD && git push

What the merge commit 26b46f27f changes:

  • API_CONTRACT.md: keeps fix(start-wrt): reload dnsmasq instead of restarting it #4386's lease-flush wording (the instance holding the lease is stopped by name, then dnsmasq reloads). It appends this PR's sentence on allow-list reload failure and retry.
  • devices.rs, forget: the code merged cleanly. I changed the comment "before the potentially slow dnsmasq restart" to "before the potentially slow lease flush", because forget no longer restarts dnsmasq. The ordering itself is unchanged: the RA revoke still runs before flush_device_from_network.

Verification: merge-tree is clean against the current master (22b09c96f). cargo test -p startwrt-core filtered to lan_guard and forget passed 6/6 on the merged tree, which also confirms the merged crate builds. My approval covers this code; once the branch is updated, nothing else needs review from me.

dr-bonez
dr-bonez previously approved these changes Oct 24, 2026
…fetime

# Conflicts:
#	projects/start-wrt/API_CONTRACT.md
@Dominion5254
Dominion5254 dismissed stale reviews from dr-bonez and helix-white via e1a7f37 October 24, 2026 15:12

@helix-white helix-white 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.

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 outside ra_allow, whatever the Router Lifetime value. Enabling the permission requires confirmation.
  • kmod-nft-bridge is added to the image, so the RA, DHCPv4 and DHCPv6 rules match with meta 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

@Dominion5254
Dominion5254 merged commit 7a47f75 into master Oct 24, 2026
11 checks passed
@Dominion5254
Dominion5254 deleted the wrt/lan-guard-ra-lifetime branch October 24, 2026 15:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants