Skip to content

v15.2 - Boot-safety emergency fix (90s window, DHCP exempt, emergency-reset)

Choose a tag to compare

View all tags
@ryderlacin-pixel ryderlacin-pixel released this 08 Jun 17:25
· 14 commits to main since this release
v15.2
883c662

v15.2 — Boot-safety emergency fix (post-mortem response)

Status: Production — replaces v15.1 after a confirmed boot deadlock on real hardware.

Incident summary (v15.1)

On a physical laptop, v15.1 worked at runtime but after reboot caused:

  1. Boot deadlock — catch-all KS-Block-* rules activated before DHCP and WireGuard handshake completed. DHCP could not finish; tunnel could not start; Test-SafeToOpen never opened the lock. GPO boot script did not clear existing block rules during fail-open hold.
  2. Physical NIC disappearance — Disable-AllIPv6Bindings ran netsh interface ipv6 set interface ... disabled on every connected adapter (Wi‑Fi/Ethernet), breaking NDIS bindings. ncpa.cpl appeared empty.

Recovery required Reset This PC on the affected machine.

This release is a surgical defensive patch — no architectural rewrite. The lib/ modular layout is preserved.

What changed (7 defensive measures)

1. Boot-safe window (90 seconds)

  • New Test-BootSafeWindow / Get-OsUptimeSeconds in lib/Install-SafeNetwork.ps1 and runtime C:\WireGuard\wg-safety.ps1 (generated).
  • Monitor, repair, watchdog, and GPO never apply catch-all blocks while OS uptime < 90s.
  • BootGrace reduced from 180s to 90s (aligned with safe window).

2. DHCP + gateway exemptions (before catch-all)

  • Firewall exemptions are written before KS-Block-* rules:
    • KS-DHCP-Out / KS-DHCP-In (UDP 67/68)
    • KS-DHCP-Bcast-Out (255.255.255.255:67)
    • KS-DHCP-Server-In
    • KS-Gateway-Out / KS-Gateway-In (dynamic default-route gateway + RFC1918)
  • Enable-KillSwitchBlock always refreshes exemptions first.

3. Tunnel-only IPv6 binding (physical NIC shield)

  • Disable-AllIPv6Bindings removed from physical adapters.
  • Replaced by Disable-TunnelIPv6BindingsOnly — only adapters matching WireGuard / wintun / AllDebrid.
  • Test-IsVirtualTunnelAdapter hardware whitelist; physical Intel/Realtek/MediaTek adapters cannot be mutated.

4. Emergency reset (one-click)

  • emergency-reset.bat at repo root (also deployed to C:\WireGuard\).
  • scripts/emergency-reset.ps1: removes all KS-* rules, netsh advfirewall reset, netsh int ip reset, netsh winsock reset, re-enables physical adapters and bindings.

5. Fail-open safeguard

  • install.ps1 parameter: [bool]$EnableFailsafe = $true (stored in registry).
  • Monitor catch → Invoke-FailOpenSafeguard (removes blocks, sets UnbrickUntil + BootGraceUntil).
  • Watchdog deep unbrick uses the same safeguard.

6. Dry-run mode

.\install.ps1 -DryRun
  • No firewall writes, no adapter binding changes.
  • Logs [DRY-RUN] Would run: ... for every destructive action.

7. Runtime safety module

  • wg-safety.ps1 deployed to C:\WireGuard\ and dot-sourced by monitor, repair, watchdog, GPO.
  • Centralizes Test-BlockAllowed, Enable-KillSwitchBlock, Disable-KillSwitchBlock, Invoke-FailOpenSafeguard.

GPO boot fix (critical)

v15.1 GPO only logged fail-open during BootGrace but left stale KS-Block-* rules active.

v15.2 GPO calls Disable-KillSwitchBlock immediately on boot, then sets grace period.

New / updated files

File Role
lib/Install-SafeNetwork.ps1 Installer + runtime safety primitives
emergency-reset.bat Admin one-click recovery launcher
scripts/emergency-reset.ps1 Recovery logic
C:\WireGuard\wg-safety.ps1 Generated runtime safety (on install)

Upgrade

# ALWAYS test in VM first:
.\install.ps1 -DryRun

# VM full install + reboot test, then physical machine:
.\install.ps1 -NoPause

From v15.1 on a working system (install lock keeps internet until STEP 19):

.\install.ps1 -NoPause

Safe testing procedure (mandatory)

  1. VM: .\install.ps1 -DryRun — verify logs, no network changes.
  2. VM: .\install.ps1 -NoPause — full install.
  3. VM: Reboot — confirm Wi‑Fi/Ethernet visible in ncpa.cpl, internet works within 90s, tunnel comes up.
  4. VM: .\scripts\test-suite.ps1 → 186+ PASS.
  5. Physical machine: only after VM reboot PASS.

Verification

.\scripts\test-suite.ps1          # 186+ offline assertions
.\scripts\ci.ps1

Check log after reboot:

Get-Content C:\WireGuard\killswitch.log -Tail 30
# Expect: "BootGrace until ... (uptime Xs, no block)" and no BLOCK before 90s

Breaking changes

None for normal runtime behavior after tunnel is healthy. Boot path is intentionally more permissive for the first 90 seconds.

Apology / accountability

v15.1 boot path was not safe on real hardware under slow DHCP / delayed tunnel start. v15.2 treats "never brick the user's network" as a hard invariant above kill-switch aggressiveness.

Assets 2
Loading