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 (@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.

[boaz-raz]

Thanks Gijs Reijn (@Gijsreyn) — this is exactly the design discussion I was hoping for, and your scoping instinct matches the constraint that makes this safe at our scale.

On delete vs. disable — I've come around to canonical delete as the default. My first instinct was disable (our current netsh enforcement uses set rule ... enable=no, and our DSC stop-gap reconciler disables). But you're right that _purge should keep its canonical meaning, and the precedent is clear: Puppet's resources { 'firewall': purge => true } deletes unmanaged rules. Forking _purge to mean "disable" for this one resource would make firewall the odd one out — and firewall config is exactly where you want the mental model to be boring and predictable. So: _purge: true = delete undeclared in-scope rules, aligned with every other _purge.

That said, I'd argue hard for disable as an explicit opt-in (purgeAction: Disable) — not a competing default, but for two concrete reasons:

1. Migration ramp. Turning authoritative purge on across ~1,500 hosts is the scary part. Disable-first lets us flip it on, watch what test/what-if would remove, and roll back instantly before committing to deletion. Delete-only has no soft landing.
2. OS-regenerated built-ins. Windows recreates built-in inbound rules on servicing/feature changes. Under pure delete the resource deletes them every run — a perpetual fight with the OS and constant changed churn in reporting. Disable converges: a disabled built-in stays disabled and (per your idempotency point) shouldn't re-flag as drift. This is precisely why our netsh predecessor used enable=no, never delete.

Your three-state model (_purge:true=delete, +purgeAction:Disable=disable, omitted=preserve) is exactly right, and "only undeclared enabled rules count as drift in disable mode" is the linchpin — please keep it.

Store scope — strong +1, this is the adoption gate. PersistentStore only; never ActiveStore / RSOP / GPO-delivered / service / system-default. For us the management plane (WinRM 5985/5986, RDP 3389) is GPO-delivered into a separate store specifically so an authoritative local purge can't lock us out — that's the safety property the whole rollout rests on. I'd ask this be a tested guarantee (an integration test asserting a GPO-delivered rule survives _purge:true), not just documented intent.

The design point I think most needs nailing down: what defines "in-scope"? Firewall rules have dimensions (direction, profile) that type-level Puppet purge doesn't. We manage inbound only — a _purge:true that also swept local outbound rules we never declared would be a nasty surprise. I'd propose the authoritative scope be constrainable (minimally by direction, ideally profiles), or failing an explicit knob, that scope be implicitly defined by the dimensions present in the declared rules set. Without this, "authoritative" is ambiguous and people will get burned purging a dimension they never touched.

Open questions:

• Q3 (empty rules + _purge:true): please make it valid = "no local persistent rules in scope are allowed," not an error. That's the clean way to express "GPO delivers the baseline; locally, deny everything" — our exact posture. Requiring ≥1 rule is an arbitrary special case.
• Q1: ship canonical delete first; track purgeAction: Disable as the fast follow.
• Q4: agree the implementation must filter by policy-store source, not effective state.

For context on stakes: we currently do this with a PowerShellScript reconciler that enumerates PersistentStore and disables/deletes the non-allowlisted set — works, but it's a workaround with no real inDesiredState/changedProperties and the allowlist lives in a templated script body. A native _purge with these semantics is strictly better; we'd retire the reconciler the day it ships, and I'm happy to test a pre-release against a real fleet.

[Gijsreyn]

Boaz Raz (@boaz-raz) - so my understanding of what you're asking for (and giving myself a short summary) is that the resource should gain an authoritative mode for local firewall rules, as the existing model is mostly clear now. That can create, update, or remove rules that are explicitly named in the rules array, and with _exist: false already covering the case where a known named rule should be removed.

What it doesn't do today is compare the declared list against the existing local firewall rules and treat undeclared rules as drift. That is the gap _purge would fill. With _purge: true, the declared rules array would become the complete allowed set for a defined scope, and undeclared in-scope rules would be reconciled.

Answering the open questions from my side:

1. I agree that the initial behavior should follow canonical _purge semantics. _purge: true should delete undeclared in-scope rules by default. That keeps this resource aligned with the canonical DSC model and with Puppet-style purge behavior.
2. I also agree there is a strong operational case for disable mode, but I would keep it explicit rather than changing what _purge means. A shape like purgeAction: Disable makes sense as a resource-specific option, with the default effectively being purgeAction: Delete. In disable mode, only undeclared enabled rules should count as drift. If an undeclared rule is already disabled, it should not keep causing test to fail because it no longer affects traffic.
3. I agree that _purge: true with rules: [] should be valid, as long as the purge scope is clear. That should mean "no local persistent rules are allowed in this scope." (currently this is not the case)
4. I agree that purge must be limited to local persistent rules only. The behavior should align with Get-NetFirewallRule -PolicyStore PersistentStore and must not touch ActiveStore, RSOP, GPO-delivered rules, service rules, system-default rules, or effective policy.
5. The main design point still to nail down is what "in scope" means. Since you manage inbound rules only, _purge: true should not unexpectedly delete outbound rules. I think scope should probably be explicit, at least by direction and ideally by profiles, because deriving scope from the declared rules gets difficult when rules: [] is valid.

So the model I would propose is: omitted _purge preserves today's behavior, _purge: true deletes undeclared rules in an explicitly defined local persistent scope, and purgeAction: Disable can be considered as an explicit follow-up mode for environments that need a softer migration path. But that's just my take on it 😄

[boaz-raz]

That model works for us across the board, Gijs Reijn (@Gijsreyn) — omitted = preserve, _purge: true = delete in an explicitly-defined local-persistent scope, purgeAction: Disable as the explicit softer-migration follow-up. 👍

And good call on point 5 — you're right that once rules: [] is valid, scope can't be inferred from the declared set, so an explicit scope (direction, and ideally profiles) is the only coherent option. That maps cleanly onto our side: we'd declare an inbound scope and never have purge reach outbound rules we don't manage.

So from our end the design is settled — the open work is just Working Group sign-off and implementation. Standing offer holds: once there's a pre-release build (even behind a flag), I'm happy to run it against a real fleet and report back on the PersistentStore-isolation and scope behavior in practice. Thanks for the thorough back-and-forth on this. 🙏

[SteveL-MSFT]

As noted, _purge currently is strictly for remove meaning that if you use _purge: true, then what remains is only what you specify in the config. Disabling is an interesting case that won't apply generally, but I'm sure can be applied in many cases, so I wonder if instead of overloading _purge, we should have a different canonical property instead _disableUnspecified (something like that). This will make it easier to discover which resources support this since it would be part of their JSONSchema. This also means that using _purge: true and _disableUnspecified: true together would be an error that the engine can catch as I can't think of a scenario where both would make sense by definition.

[theJasonHelmick]

The DSC WG discussed this:

• This capability should be resource specific.
• Firewall rule list should have a unspecifiedRulesAction which is an Enum. Values are Ignore, Remove, Disable. The default is to Ignore.

[boaz-raz]

Following up on the standing offer to test this against a real fleet — Steve Lee (@SteveL-MSFT), Gijs Reijn (@Gijsreyn), Jason Helmick (@theJasonHelmick), thanks for shipping it in #1599. Validated 3.3.0-preview.4 / FirewallRuleList v0.2.0 on Windows Server 2025 hosts, including a real (non---what-if) disable run. Reporting back.

Confirmed working:

• Local-store isolation holds. GPO-delivered rules are never enumerated or touched — verified under a real set in disable mode, with GPO rule count and enabled count identical before and after. This was the adoption gate for us, so this is the important one. One ask: since it holds as a consequence of the COM enumeration rather than as an explicit guarantee, a regression test asserting a GPO-delivered rule survives unspecifiedRulesAction: remove would let us depend on it across releases.
• disable idempotency works exactly as specified — already-disabled undeclared rules are skipped, and a second set makes no further rule changes. This was the linchpin behaviour discussed above and it landed correctly.
• --what-if reports without mutating, with clear per-rule messages. This made it possible to evaluate authoritative mode safely before enabling it, which we appreciated.

Two things from the discussion above didn't make it into the implementation, so I've filed them separately rather than reopening here:

• Scope containment by direction/profiles — currently a config declaring only inbound rules will sweep the host's built-in outbound rules under remove. This was the point flagged above as most needing resolution, and it looks like it wasn't carried into the WG note rather than being decided against. → Microsoft.Windows/FirewallRuleList: unspecifiedRulesAction needs an explicit scope, and should accept rules: [] #1667
• rules: [] being valid, per the agreement above that it should mean "nothing permitted in scope". → Microsoft.Windows/FirewallRuleList: unspecifiedRulesAction needs an explicit scope, and should accept rules: [] #1667

And one defect: unspecifiedRulesAction is always reported as a differing/changed property, so test never reports converged and set reports a change on every run — reproducible with unspecifiedRulesAction: ignore, which is documented as a no-op. → #1666

Happy to test any of these once addressed. Thanks again for the thorough design discussion on this one — the parts that landed, landed well.