Implement canonical _purge on Microsoft.Windows/FirewallRuleList for authoritative rule management

[boaz-raz]

Summary of the new feature / enhancement

The Microsoft.Windows/FirewallRuleList resource (v0.1.0) supports per-rule _exist: false to remove named rules, but has no way to make the declared rules list authoritative — i.e., remove/disable rules that aren't declared (drift).

The canonical resource-level _purge property (semantics settled in #790) is the natural fit, but FirewallRuleList doesn't implement it. Inspecting the resource schema on dsc 3.2.1 and 3.2.2 shows no _purge (and additionalProperties: false), and the 3.3.0-preview.2 changelog adds --what-if/docs/elevation fixes but not _purge.

Use case

We're replacing legacy netsh advfirewall reset-style enforcement with DSC across ~1,500 Windows servers. We need each host's local inbound firewall to equal exactly the declared rules (Puppet-style purge of drift).

Today we work around this with a Microsoft.DSC.Transitional/PowerShellScript resource that enumerates Get-NetFirewallRule -PolicyStore PersistentStore and disables anything not in a hand-maintained allowlist. That allowlist is fragile (must be kept in sync with the declared rules by hand) and doesn't scale well. _exist: false doesn't help here because it requires knowing each undeclared rule's name in advance — drift is precisely the unknown case.

Proposed technical implementation details (optional)

Implement resource-level _purge: true on Microsoft.Windows/FirewallRuleList so the declared rules array is treated as the complete/authoritative set, consistent with the canonical _purge semantics agreed in #790.

Two questions on the intended behavior:

1. Disable vs. delete — would _purge delete undeclared rules, or could it support disabling them? We rely on disable (reversible, avoids churn on OS-regenerated built-in rules) rather than deletion.
2. Policy store scope — which store would _purge operate on? It's important that GPO-delivered rules can be excluded, so management-plane access (WinRM/RDP, delivered via GPO in a separate store) is never at risk.

Refs: #790 (canonical _purge semantics).

[Gijsreyn]

@boaz-raz - interesting raise for this resource. I agree that this will be a good candidate for the canonical _purge property with one important design question around "removing an authoritative set" and what it should mean.

Looking at the current resource behavior, the named rule covers _exist: false already, indeed, meaning "remove this specific rule if it exists." For _purge, I think the cleanest model is:

$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Local inbound firewall rules
  type: Microsoft.Windows/FirewallRuleList
  properties:
    _purge: true
    rules:
    - name: HTTPS In
      direction: Inbound
      action: Allow
      protocol: 6
      localPorts: '443'
      enabled: true
      profiles:
      - Domain
    - name: Health In
      direction: Inbound
      action: Allow
      protocol: 6
      localPorts: '8443'
      enabled: true
      profiles:
      - Domain

With _purge: false or omitted, FirewallRuleList would keep today's behavior and ignore undeclared rules. With _purge: true, the root rules array would become authoritative for the target scope, so undeclared in-scope rules would drift.

Disable vs. delete

Strictly speaking, canonical _purge means unmanaged entries are removed. For this resource, the most direct interpretation is that undeclared rules are deleted, matching the existing _exist: false behavior for a named rule.

That said, firewall rules are a case where disabling can be operationally preferable to deletion. Disabling is reversible + it still removes traffic enforcement.

I think that is worth considering as a FirewallRuleList-specific extension, but I would keep it explicit so _purge itself remains aligned with the canonical semantics.

One possible shape would be:

properties:
  _purge: true
  purgeAction: Disable
  rules:
  - name: Contoso App HTTPS In
    direction: Inbound
    action: Allow
    protocol: 6
    localPorts: '443'
    enabled: true

The semantics could be:

• _purge: true with the default action deletes undeclared in-scope rules.
• _purge: true with purgeAction: Disable sets undeclared enabled rules to enabled: false.
• _purge: false or omitted preserves undeclared rules.
• A declared rule with _exist: false continues to delete that named rule, regardless of purgeAction.

The important detail is that disable mode should treat only undeclared enabled rules as drift. If an undeclared rule is already disabled, it should not keep causing test to fail forever, because it no longer affects traffic.

If the project wants to avoid adding a non-canonical extension initially, I think a good first step would be to implement _purge with delete semantics and track disable semantics as a follow-up design decision. But the user scenario in this issue makes a strong case for supporting disable mode eventually.

Policy store scope

Coming to the policy store scope. I think _purge should be scoped to local persistent rules only. In PowerShell terms, the behavior should align with:

Get-NetFirewallRule -PolicyStore PersistentStore

It should not operate on ActiveStore, RSOP, GPO-delivered rules, system defaults, static service store rules, or any other effective/non-local source.

The implementation should verify that the current Windows Firewall API path can reliably enumerate and mutate only the local persistent store. If the current COM API path cannot make that distinction safely, the purge path may need to use a store-aware API for discovery and mutation, or explicitly filter rules by policy-store source before taking action.

Resource behavior

For the things mentioned above, for this to work with DSC's synthetic test behavior, get needs to become purge-aware. When _purge: true, get should return enough actual state to show undeclared in-scope drift; otherwise, dsc config test cannot detect extra local firewall rules.

For example:

• In delete mode, any undeclared in-scope rule should appear as drift.
• In disable mode, undeclared enabled rules should appear as drift.
• In disable mode, undeclared disabled rules should be ignored for convergence.
• _purge should remain write-only and should not appear in the output state.

what-if should also report purge actions without mutation, for example:

• Would remove undeclared firewall rule 'ExampleRule'
• Would disable undeclared firewall rule 'ExampleRule'

Open questions / design points

Questions that came up while looking at it for the DSC working group (probably):

1. Should the initial implementation support only canonical delete semantics, or should it include an explicit disable mode because this is a firewall-specific operational need?

For example, suppose the local persistent store currently has two enabled inbound rules: HTTPS In and Unexpected Vendor Rule. The desired state declares only HTTPS In with _purge: true.

With canonical delete semantics, set would remove Unexpected Vendor Rule from the local persistent store. A later export would no longer show that rule.

With disable mode, set would keep Unexpected Vendor Rule in the local persistent store but change it to enabled: false. A later export could still show the rule object, but it would no longer affect traffic and should not be treated as drift unless it becomes enabled again.

2. If disable mode is accepted, should the property be named purgeAction, _purgeAction, or something else?
3. Should _purge: true with an empty rules array mean "no local persistent rules are allowed," or should that remain invalid because rules is currently required to contain at least one entry for set/get operations?
4. What API path can guarantee that purge only touches local persistent firewall rules and never GPO/RSOP/effective-policy rules?

Refs: PowerShell/DSC#790, Get-NetFirewallRule -PolicyStore.