Windows support for Network Devices — `dg` as a Windows service

[kchudy]

Epic: Windows support for Network Devices — dg.exe as a Windows Service

Background

Customers with AD-joined Windows fleets need a machine-owned, always-on tunnel: up before logon, kept after logoff, invisible to the user, with an ACL allowlist for the pre-logon phase and a per-device opt-out. Network Devices already provide the right identity model — admin-managed, machine-enrolled (no user account or user enrollment flow), usable as an ACL source, fixed IP assigned by the admin — but the CLI client (dg) that drives them ships only for Linux (deb/rpm/tar.gz; requires root, resolvconf, ip, and systemd). Service Locations are Windows-only but user-enrolled, configured per location rather than per device, and cannot change policy at logon. The gap is a Windows dg client that runs as a system service.

Goal

A Windows machine can be enrolled as a Network Device — by the admin, before the machine is handed to a user — and hold its tunnel from boot, across logon/logoff and network changes, without any user interaction or visible UI, receiving config updates automatically.

Design decisions

• Separate deliverables. dg.exe (CLI for network devices on Windows) ships as its own MSI, independent of the Desktop Client. A machine may have either or both installed.
• Separate Windows Service. dg.exe runs under its own service (Defguard Network Device, LocalSystem, Automatic start). It is distinct from the existing Windows service the Desktop Client uses for Service Locations; the two do not share configuration or state.
• Config-file driven enrollment. dg.exe looks for a JSON config file (default %ProgramData%\defguard\dg.json) containing at minimum enrollment_url and enrollment_token. On first start the service enrolls using it; after enrollment the file holds the resulting network configuration and device key.
• MSI behaviour. The MSI accepts enrollment parameters as properties (ENROLLMENT_URL, ENROLLMENT_TOKEN, optional CONFIG_PATH). If passed, the MSI writes the JSON config from them and the service enrolls on first start. If no parameters are passed, the MSI installs the binary and service only and the service assumes a config file is already in place (pre-staged by imaging, GPO file copy, or Intune).
• Bulk operations on Network Devices (Core UI + API): bulk create (from a list of names, one location, IP auto/explicit), bulk re-enrol (regenerate tokens), download tokens (CSV/JSON of device → token), bulk delete.
• Provisioning flow for the customer. Admin bulk-creates devices → downloads tokens → feeds each machine's token to the MSI (msiexec … ENROLLMENT_TOKEN=…) via imaging/GPO/Intune, or pre-stages the JSON config and installs the MSI without args.

Scope

1. Windows build of dg.exe (x64; ARM64 optional) using WireGuard-NT/wintun; DNS servers and search domains applied via Windows APIs.
2. Defguard Network Device Windows Service: starts before user logon, survives logoff, reconnects on network/interface change, independent of the Service Locations service.
3. MSI installer implementing the config-file/parameter behaviour above; silent install supported; installer creates and starts the service.
4. Config polling on Windows at parity with Linux (Enterprise: periodically fetch and apply the latest network config).
5. CLI surface available to a local administrator for intervention: dg enroll, dg status, dg start|stop, dg logs, plus standard sc/services.msc control and Windows Event Log output.
6. Bulk operations for network devices in Core (create, re-enrol, download tokens, delete), UI and REST.
7. Documentation: Windows CLI section, imaging/GPO/Intune deployment guide, admin intervention runbook, device-tunnel + user-tunnel coexistence guidance.

Out of scope

MFA for network devices; device posture checks for network devices; Desktop Client UI for network devices; macOS dg. Consequently a pre-logon location based on network devices cannot require MFA or posture.

Known limitations (to state in docs and to the customer)

• Per-device ACL assignment. Network devices are not groupable; in Firewall rules the admin either uses the "all network devices" toggle or selects devices one by one. For a fleet with differentiated policies this is manual. Follow-up: network-device groups/tags (see D4).
• No user association. A network device is a machine identity; Core does not know who uses it. Ownership must be tracked via the device Description field and the customer's CMDB/asset inventory. Activity logs show the device, not a person.
• No MFA, no posture on the network-device location (see Out of scope). The pre-logon tunnel is therefore protected only by the device key and the ACL allowlist.

Pre-shipping enrollment and admin control (answers to review questions)

Can the admin enroll the device before shipping it to the user? — Yes, by design. Enrollment is machine-based and token-based; no user session or account is involved. In the imaging/pre-staging step the admin installs the MSI with that machine's token (or pre-stages the JSON config), the service enrolls, and the device key and network config are stored on disk. The token is single-use and consumed at enrollment, so the shipped machine carries no reusable secret; it connects at first boot at the customer site as soon as it has internet access. Constraint: enrollment requires reachability to Defguard Edge and a correct clock at pre-staging time.

Can the admin control the binary when auto-enrollment failed? — Yes, with two channels.

• Local/out-of-band: dg.exe remains a normal CLI. A local administrator (console, imaging bench, or existing endpoint-management remote shell) can inspect dg status and the Event Log, fix or replace %ProgramData%\defguard\dg.json, re-run dg enroll -u … -t … with a fresh token (bulk re-enrol → download tokens), and restart the service via dg start or sc start DefguardNetworkDevice.
• Remote via management tooling: because a failed enrollment means no Defguard tunnel exists yet, remote intervention relies on the customer's existing tooling (Intune/SCCM/GPO scripts running as SYSTEM) to push a new config file or re-run the MSI. The MSI must be idempotent so re-running it with new parameters replaces the config and re-triggers enrollment.
• The service must fail loudly and recoverably: clear Event Log error with reason (token expired, Edge unreachable, clock skew), automatic retry with back-off while the config is unchanged, and immediate retry when the config file changes.

Acceptance criteria

• AC1 msiexec /i dg.msi /qn ENROLLMENT_URL=… ENROLLMENT_TOKEN=… on a clean Windows 10/11 Pro and Server 2019/2022 machine results in an enrolled, connected network device with no user session ever opened.
• AC1b msiexec /i dg.msi /qn with a pre-staged %ProgramData%\defguard\dg.json produces the same result; with neither parameters nor config file the service starts, logs "no configuration", and retries when a config file appears.
• AC2 After reboot the peer handshakes and the assigned IP responds from the gateway side before the logon screen is dismissed; the tunnel stays up after logon and after logoff.
• AC3 Switching networks (Wi-Fi ↔ wired, new DHCP lease) re-establishes the tunnel within 60 s with no restart.
• AC4 Changing the location's Allowed IPs or DNS in Core is applied on the device within the polling interval, with no logged-in user.
• AC5 No tray icon, window, or toast is shown; the tunnel is not listed in the Desktop Client if installed alongside; both services coexist without interfering.
• AC6 The device appears in the location's Network overview and is selectable as an ACL source; a Default-Deny location with an allowlist rule restricts it to exactly those destinations (verified with nft counters on the gateway).
• AC7 A device pre-enrolled on an imaging bench, powered off, and booted at a different site connects at first boot without intervention.
• AC8 With an expired token, the service logs a clear error and, after the admin replaces the config with a fresh token (locally or via a SYSTEM script) and restarts the service, enrollment succeeds — no reinstall required.
• AC9 Bulk create of N devices returns N tokens; "download tokens" yields a file usable directly by the deployment scripts; bulk re-enrol invalidates old tokens; bulk delete removes peers from the gateway.
• AC10 Machine identity is a software-stored WireGuard key pair; no TPM / secure-enclave requirement.
• AC11 A machine with no network device created (opt-out) is unaffected by the deployment.

Dependencies / linked tickets

• D1 Bulk network-device operations in Core (create, re-enrol, download tokens, delete) — UI and REST.
• D2 Confirm or implement an ACL rule whose destination is the client subnet, so Support engineers' network devices can reach machines inbound under Default Deny (today the gateway drops unsolicited traffic and only accepts established/related return traffic).
• D3 Documented routing/DNS precedence when a device tunnel (0.0.0.0/0) and a user tunnel (split) coexist on one machine.
• D4 Network-device groups or tags selectable as ACL sources, to avoid one-by-one assignment.

Open questions

• Q1 Token distribution at fleet scale: MSI property fed by the deployment tool vs pre-staged JSON via GPO file copy vs AD computer attribute — which to document as the primary path.
• Q2 Should the network-device service refuse to start, or only warn, if the Desktop Client already owns a full-tunnel location?
• Q3 Driver distribution: bundle WireGuard-NT in the MSI or require WireGuard for Windows to be present?
• Q4 Retry policy defaults (interval, max attempts) for failed enrollment; whether to expose them in dg.json.

Estimate hint

Client-side: Windows build + service + MSI ≈ one sprint each; bulk operations in Core ≈ one sprint; docs ≈ 3 days. D2/D4 are Core/Gateway work tracked separately.

Target architecture (for context)

Windows machine
 ├─ dg.exe  (Windows Service "Defguard Network Device", SYSTEM, boot)  ── machine identity ──▶ Location "DEVICES"
 │     config: %ProgramData%\defguard\dg.json
 │     Allowed IPs 0.0.0.0/0 (full tunnel), Firewall = Default Deny + allowlist rules
 └─ Defguard Desktop Client (separate MSI, separate service, user session, optional) ── user identity ──▶ Location "USERS"
       Allowed IPs = internal subnets only, user/group ACLs

Until Scope items 1–3 ship, the only Windows path is the "Manual WireGuard Client" option for network devices: export the .conf and run it with WireGuard for Windows in tunnel-as-service mode — no config polling, no re-enrollment, and each machine's key/config must be distributed out-of-band.

Proposed admin process (target state)

Steps 1–3 are done once; steps 4–5 are done per batch of machines.

0. Prerequisites

• Enterprise license (config polling); Firewall/ACL module (Business or Enterprise).
• Gateway on Linux with nftables (kernel ≥ 5.10), running with masquerading enabled (--masquerade / DEFGUARD_MASQUERADE=true) or with NAT configured manually — required for the full tunnel. If Docker runs on the gateway host, set DEFGUARD_FW_PRIORITY=-1.
• Inventory: hostnames that must be always-on; hostnames that are exceptions (Cisco VPN) and must not get a device; an owner/asset record per hostname (Core will not know who uses the device).

1. Create the DEVICES location

• Gateway VPN address/mask sized for one IP per machine, e.g. 10.90.0.1/22; public gateway DNS name and UDP port.
• Allowed IPs 0.0.0.0/0 (full tunnel so corporate web filtering applies).
• DNS: internal DNS servers plus the AD search domain.
• Keep-alive interval set (e.g. 25 s) so NAT'd machines stay reachable inbound.
• MFA off and no posture requirement (not supported for network devices). Location type: regular (not a Service Location).
• Firewall: Default Deny.

2. Define the phase-1 allowlist

Create reusable Destinations for DomainControllers, AVServers, WSUS, PKI with exact IPs/CIDRs, ports and protocols (e.g. DC: TCP/UDP 53, 88, 135, 389, 445, 464, 636, 3268–3269 and the RPC dynamic range; WSUS: TCP 8530/8531; PKI: TCP 80/443 to CA/OCSP/CRL hosts; AV: vendor ports).

3. Create ACL rules scoped to DEVICES

1. Devices-Phase1 — source: all network devices (avoids one-by-one selection; if some devices need a different policy, select them individually or wait for D4); destinations: the four objects above.
2. Support-Inbound — source: Support engineers' network devices; destination: 10.90.0.0/22 on RDP 3389 / WinRM 5985–5986 / SMB 445 as needed (depends on D2).
3. Optional Devices-Egress — destination: the web-filter/egress appliance range, if the filter is an explicit target rather than the default route.

Deploy pending changes and verify on the gateway with nft list table inet DEFGUARD-<iface>.

4. Bulk-create Network Devices and download tokens

Network devices → Bulk create: upload/paste the hostname list, choose DEVICES, let Core assign IPs (or supply them), set Description = asset tag / owner. Then Download tokens to get a hostname,ip,enrollment_url,token file. Record the IPs in the CMDB — this is the address Support connects to. Skip exception machines.

5. Pre-stage / deploy dg.exe

Choose one:

• Imaging bench (pre-ship): for each machine run msiexec /i dg.msi /qn ENROLLMENT_URL=<url> ENROLLMENT_TOKEN=<token>; the MSI writes dg.json, creates and starts the service, and enrollment completes on the bench (needs Edge reachability and NTP). Power off and ship. The machine connects at first boot at the user's site.
• Already-deployed fleet: push the MSI via GPO/Intune with the same properties resolved per machine from the token file, or copy dg.json per machine first and push msiexec /i dg.msi /qn without properties.

Verify: at the logon screen the machine's fixed IP answers from the corporate side; no UI is visible.

6. Keep the USERS location for interactive sessions

The existing user-identity location remains (Desktop Client, separate MSI and service), with Allowed IPs limited to internal subnets (split tunnel) so the device tunnel keeps the default route. User/group ACL rules live only on USERS.

7. Verify

Requirement	Check
Up before logon, kept after logoff, invisible	Reboot to the logon screen: ping/RDP to the fixed IP from a Support host succeeds; no client UI; log off and re-check.
Full tunnel + web filtering	Browse an external site from the machine; traffic appears in the corporate filter logs; device listed in the location's Network overview.
File shares	\\fileserver\share reachable only when a rule allows it; blocked otherwise.
Phase-1 allowlist	Before logon only DC/AV/WSUS/PKI reachable; other destinations dropped (nft counters).
Inbound Support	RDP/WinRM from a Support engineer's network device to the fixed IP.
Per-device exception	Exception machine has no network device and connects only via Cisco / Desktop Client.
Pre-shipped enrollment	Machine enrolled on the bench connects at first boot elsewhere with no intervention.
No TPM	Key pair generated by dg.exe, stored on disk; Core never holds the private key.

8. Operate and intervene

• Config changes (new WSUS server, new Allowed IPs): edit the Destination/location → Deploy; machines pick it up via polling.
• Failed enrollment: check Event Log / dg status; Bulk re-enrol the affected devices → Download tokens → replace dg.json (locally or via SYSTEM script) → dg start or sc start DefguardNetworkDevice. No reinstall needed.
• Rotate keys: bulk re-enrol → redeploy tokens as above.
• Decommission: Bulk delete; peers are removed from the gateway; uninstall the MSI via GPO/Intune.
• Monitor: Network overview per location shows active network devices; cross-reference with the CMDB for ownership.

[kchudy]

1. In the Firewall admin'd have to assign every network device one by one.
2. The admin will not know who uses the network device.
3. The pre-logon location using network devices cannot have MFA and device postures.
4. We will ship dg.exe (CLI for network devices on Windows) and Desktop Client separately.
5. The dg.exe will run as a Windows Service (separate from the current Windows Service used for Service Locations). Check if the admin can enroll the device before shipping the device to the users. The shipped MSI will create the Windows Service.
6. dg.exe will look for config json file to enroll the device.
7. The MSI will access args with enrolment parameters. The MSI will create config file based on params and use it. If no args passed the service will assume the config file is already in place.
8. We will add bulk operations to the network devices: bulk create, bulk re-enrol, download tokens, delete.
9. Client can use the downloaded tokens to provision devices: downloaded tokens and MSI with args.
10. Check if the admin can control the binary on the machine, for example when the auto enrolment process failed and he need to intervene.

[kchudy]

Alternative 1 (assessed, not pursued): user-enrollment-triggered Network Device creation

Related to: Epic "Windows support for Network Devices — dg.exe as a Windows Service" (windows-network-devices-spec.md)
Status: assessed; decision — do not pursue. Kept as a decision record.

The idea

When the admin enrolls a user, a checkbox "Add this user device as a network device" is available. When the first user enrolls on a given machine with such a flagged enrollment, Core creates a Network Device for that machine. That network device is used for the always-on (pre-logon) connection.

What it actually is

The checkbox does not convert the user's device into a network device. It creates a second, machine-scoped identity on the same PC as a side effect of the first user enrollment. The machine still ends up with two peers, exactly as in the main spec:

• user device → USERS location (Desktop Client, user identity)
• network device → DEVICES location (always-on service, machine identity)

What changes is how the network device is created and how its token reaches the machine. Instead of the admin bulk-creating devices and distributing tokens via MSI parameters or pre-staged config files, Core creates the device when the user enrollment completes, returns the network-device enrollment token to the client over the already-authenticated enrollment session, and the client hands it to the local dg.exe service, which enrolls exactly as in the main spec.

In other words: this is a third token-delivery and inventory mechanism on top of the same service, config file and network-device model — not a different architecture.

Fit against the client requirements

Requirement	Verdict	Reason
1 — tunnel up before any logon, kept after logoff, no user involvement, invisible	Partial	After bootstrap it behaves identically to the main spec. But the tunnel cannot exist until a user has logged on and completed enrollment on that machine. This inverts the client's rationale for requirement 3 (pre-logon reachability to DCs so a first domain logon can succeed): a user must first log on to create the thing that was meant to make logon possible. It works only if the first logon happens on the corporate LAN or on an imaging bench. It also fails "admin enrolls the device before shipping it" unless the admin logs on interactively with a staging account on every machine — which leaves a staging user device on each PC and is precisely the user involvement the requirement excludes.
2 — inbound Support reachability, full tunnel, file shares	Met	Same DEVICES location, same fixed IP (auto-assigned at creation, looked up in Core), same ACLs. No difference from the main spec.
3 — pre-logon allowlist (DC, AV, WSUS, PKI)	Met	Same Default Deny + allowlist with "all network devices" as source; same one-by-one selection limitation. Bonus: Core records which user triggered creation, partly addressing "the admin will not know who uses the device" (first user only on shared PCs).
4a — per-device exception	Met only if the flag is per device-enrollment token, not per user account	"When enrolling a user" is account-level; a user with an always-on laptop and a Cisco-VPN desktop cannot be split at that level. The flag must live on each device-enrollment token. Even then control is indirect: the admin decides at token time, but the token says nothing about which machine it is redeemed on.
4b — no TPM dependency	Met	Same software key model.

A risk the main spec does not have

A flagged token redeemed from the wrong machine creates a privileged, full-tunnel, phase-1-allowlisted machine identity on whatever PC the user enrolls from — including a personal one. The main spec never has this problem because the admin places the token on a specific machine. This path would need a managed-machine guard (domain-join check, MSI-installed machine flag, or an AD computer-object lookup on hostname) before Core creates the device. Without it, it should not ship.

Comparison with the main spec

Dimension	Main spec (admin pre-stages)	Alternative 1 (user-enrollment-triggered)
Bootstrap with no user ever logging on (new/shipped machines, kiosks)	✅	❌
Admin enrolls before shipping	✅ (AC7)	❌ without a staging logon
Rollout to the existing fleet already in users' hands	Hostname inventory + token file + GPO/Intune push per machine	✅ Rides on the enrollment the user does anyway; no inventory, no secrets in GPO/CSV
Secret handling	Tokens exported to a file and moved through deployment tooling	Token never leaves an authenticated session
Inventory / naming	Admin supplies names; reimage collisions under admin control	Client reports hostname/machine ID; Core must dedupe (second user on same PC → reuse) and handle reimaged duplicates
Who uses the device	Unknown to Core (CMDB only)	First enrolling user recorded — partial improvement
Per-device exception	By omission from the hostname list — direct	By not flagging the token — indirect; redeemed-anywhere risk
Recovery after failed/broken enrollment	Admin-only via SYSTEM script or local CLI (AC8)	Needs a new flagged token and a user in-session to redeem it, or falls back to the main-spec admin path
Coupling	dg.exe and Desktop Client deliberately separate	Desktop Client must hand a token to the machine service (privileged IPC/file handoff) — re-couples the deliverables
Core work	Bulk create / re-enrol / download tokens / delete	Enrollment-flow change + dedupe + guard; bulk re-enrol/delete still needed
Shared PCs	Neutral	"First user" semantics; later enrollments must detect the existing device

Design issues that would have to be settled if revived

1. Granularity — flag per device-enrollment token, not per user account.
2. Managed-machine guard — before creating a privileged identity.
3. Dedupe key — a stable machine identifier (hostname + Windows MachineGuid; no TPM) so repeat enrollments reuse the existing device and reimages replace rather than duplicate.
4. Handoff — Core returns the network-device token in the enrollment response → client writes dg.json (or invokes dg enroll) through an elevated channel → dg.exe service enrolls as in the main spec. Must reuse that path, not create a parallel one.
5. Location binding — the flag must carry (or default to) the designated device location.
6. UI wording — "Add this device as a network device" is misleading; it creates an additional always-on machine identity for the PC.

Verdict

Alternative 1 does not replace the main spec: it fails the parts of requirement 1 the client calls load-bearing (before any logon, no user involvement) for first-time machines, and it fails pre-ship enrollment by the admin. It would be a reasonable complementary path for the existing fleet (no inventory, no token files, user association), sharing the same service, config file and network-device model, and it would amount to a third answer to the main spec's Q1 (token delivery).

Decision: not pursued. The main spec remains the single approach.

[kchudy]

Questions:

• How does the admin install dg.exe?
• How does the admin pass the token for the device?