From f9fa3303d02f6ff49d10a11f671960a34e796a2f Mon Sep 17 00:00:00 2001
From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com>
Date: Sat, 9 May 2026 12:17:23 +0200
Subject: [PATCH 1/3] docs: Add reference documentation for
 Microsoft.Windows/FirewallRuleList

---
 .../examples/configure-firewall-rules.md      | 279 +++++++++
 .../examples/firewall.config.dsc.yaml         |  26 +
 .../examples/get-firewall-rules.md            | 191 ++++++
 .../Windows/FirewallRuleList/index.md         | 546 ++++++++++++++++++
 4 files changed, 1042 insertions(+)
 create mode 100644 docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/configure-firewall-rules.md
 create mode 100644 docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.config.dsc.yaml
 create mode 100644 docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md
 create mode 100644 docs/reference/resources/Microsoft/Windows/FirewallRuleList/index.md

diff --git a/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/configure-firewall-rules.md b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/configure-firewall-rules.md
new file mode 100644
index 000000000..0f552ab12
--- /dev/null
+++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/configure-firewall-rules.md
@@ -0,0 +1,279 @@
+---
+description: >
+  Example showing how to use the Microsoft.Windows/FirewallRuleList resource in a DSC configuration
+  document to create and enforce Windows Firewall rules.
+ms.date:     05/09/2026
+ms.topic:    reference
+title:       Configure firewall rules
+---
+
+# Configure firewall rules
+
+This example shows how you can use the `Microsoft.Windows/FirewallRuleList` resource in a DSC
+configuration document to create and enforce multiple Windows Firewall rules in a single operation.
+
+> [!IMPORTANT]
+> **Set** operations for this resource require an elevated (administrator) process context. Run
+> your terminal or PowerShell session as Administrator before using `dsc config set`.
+
+## Definition
+
+The configuration document for this example defines one instance of the `FirewallRuleList`
+resource that manages two rules:
+
+- **DscDemo - Custom App (TCP-In)** — allows inbound TCP traffic on port 8080 for a custom
+  application, active on the Domain and Private profiles.
+- **DscDemo - Block Telnet (TCP-Out)** — blocks all outbound TCP connections to port 23 (Telnet)
+  on all profiles.
+
+:::code language="yaml" source="firewall.config.dsc.yaml":::
+
+Copy the configuration document and save it as `firewall.config.dsc.yaml`.
+
+## Test the configuration
+
+To see whether the rules already exist, use the [dsc config test][01] command.
+
+```powershell
+dsc config test --file ./firewall.config.dsc.yaml
+```
+
+Because neither rule exists yet, both appear in the actual state with `_exist: false`. DSC
+computes the instance as out of desired state and lists `rules` in `differingProperties`.
+
+```yaml
+executionInformation:
+  duration: <time omitted>
+  endDatetime: <time omitted>
+  executionType: actual
+  operation: test
+  securityContext: elevated
+  startDatetime: <time omitted>
+  version: <redacted>
+metadata:
+  Microsoft.DSC:
+    duration: <time omitted>
+    endDatetime: <time omitted>
+    executionType: actual
+    operation: test
+    securityContext: elevated
+    startDatetime: <time omitted>
+    version: <redacted>
+results:
+- executionInformation:
+    duration: <time omitted>
+  metadata:
+    Microsoft.DSC:
+      duration: <time omitted>
+  name: Application firewall rules
+  type: Microsoft.Windows/FirewallRuleList
+  result:
+    desiredState:
+      rules:
+      - name: DscDemo - Custom App (TCP-In)
+        description: Allow inbound TCP traffic on port 8080 for the custom app.
+        protocol: 6
+        localPorts: '8080'
+        direction: Inbound
+        action: Allow
+        enabled: true
+        profiles:
+        - Domain
+        - Private
+      - name: DscDemo - Block Telnet (TCP-Out)
+        description: Block all outbound Telnet connections.
+        protocol: 6
+        remotePorts: '23'
+        direction: Outbound
+        action: Block
+        enabled: true
+        profiles:
+        - All
+    actualState:
+      rules:
+      - name: DscDemo - Custom App (TCP-In)
+        _exist: false
+        description: Allow inbound TCP traffic on port 8080 for the custom app.
+        protocol: 6
+        localPorts: '8080'
+        direction: Inbound
+        action: Allow
+        enabled: true
+        profiles:
+        - Domain
+        - Private
+      - name: DscDemo - Block Telnet (TCP-Out)
+        _exist: false
+        description: Block all outbound Telnet connections.
+        protocol: 6
+        remotePorts: '23'
+        direction: Outbound
+        action: Block
+        enabled: true
+        profiles:
+        - All
+    inDesiredState: false
+    differingProperties:
+    - rules
+messages: []
+hadErrors: false
+```
+
+Neither rule exists in the firewall store, so both entries in `actualState` show `_exist: false`.
+Because the actual state differs from the desired state, `inDesiredState` is `false` and `rules`
+is listed in `differingProperties`.
+
+## Set the configuration
+
+To enforce the desired state and create both rules, use the [dsc config set][02] command.
+
+```powershell
+dsc config set --file ./firewall.config.dsc.yaml
+```
+
+DSC performs a synthetic test, determines that both rules are missing, and calls the resource's
+set operation. The resource creates both rules and returns the new state. The `afterState` shows
+the full configuration of each rule as read back from the Windows Firewall store, including
+properties filled in by Windows defaults such as `interfaceTypes` and `edgeTraversal`.
+
+```yaml
+executionInformation:
+  duration: <time omitted>
+  endDatetime: <time omitted>
+  executionType: actual
+  operation: set
+  securityContext: elevated
+  startDatetime: <time omitted>
+  version: <redacted>
+metadata:
+  Microsoft.DSC:
+    duration: <time omitted>
+    endDatetime: <time omitted>
+    executionType: actual
+    operation: set
+    securityContext: elevated
+    startDatetime: <time omitted>
+    version: <redacted>
+results:
+- executionInformation:
+    duration: <time omitted>
+  metadata:
+    Microsoft.DSC:
+      duration: <time omitted>
+  name: Application firewall rules
+  type: Microsoft.Windows/FirewallRuleList
+  result:
+    beforeState:
+      rules:
+      - name: DscDemo - Custom App (TCP-In)
+        _exist: false
+        description: Allow inbound TCP traffic on port 8080 for the custom app.
+        protocol: 6
+        localPorts: '8080'
+        direction: Inbound
+        action: Allow
+        enabled: true
+        profiles:
+        - Domain
+        - Private
+      - name: DscDemo - Block Telnet (TCP-Out)
+        _exist: false
+        description: Block all outbound Telnet connections.
+        protocol: 6
+        remotePorts: '23'
+        direction: Outbound
+        action: Block
+        enabled: true
+        profiles:
+        - All
+    afterState:
+      rules:
+      - name: DscDemo - Custom App (TCP-In)
+        description: Allow inbound TCP traffic on port 8080 for the custom app.
+        protocol: 6
+        localPorts: '8080'
+        remotePorts: '*'
+        localAddresses: '*'
+        remoteAddresses: '*'
+        direction: Inbound
+        action: Allow
+        enabled: true
+        profiles:
+        - Domain
+        - Private
+        interfaceTypes:
+        - All
+        edgeTraversal: false
+      - name: DscDemo - Block Telnet (TCP-Out)
+        description: Block all outbound Telnet connections.
+        protocol: 6
+        localPorts: '*'
+        remotePorts: '23'
+        localAddresses: '*'
+        remoteAddresses: '*'
+        direction: Outbound
+        action: Block
+        enabled: true
+        profiles:
+        - All
+        interfaceTypes:
+        - All
+        edgeTraversal: false
+    changedProperties:
+    - rules
+messages: []
+hadErrors: false
+```
+
+Both rules were created. The `beforeState` shows both rules with `_exist: false`, confirming they
+didn't exist before the operation. The `afterState` shows the complete configuration read back
+from the firewall store after creation, including `interfaceTypes: [All]` and
+`edgeTraversal: false` filled in by Windows. `changedProperties` lists `rules` because the rules
+array changed.
+
+## Remove a rule
+
+To remove a rule, set `_exist: false` on the specific entry and run `dsc resource set`.
+The following snippet removes the Telnet block rule while leaving the custom app rule in place.
+
+```powershell
+$desired = @'
+{
+  "rules": [
+    { "name": "DscDemo - Block Telnet (TCP-Out)", "_exist": false }
+  ]
+}
+'@
+
+dsc resource set --resource Microsoft.Windows/FirewallRuleList --input $desired
+```
+
+```yaml
+beforeState:
+  rules:
+  - name: DscDemo - Block Telnet (TCP-Out)
+    description: Block all outbound Telnet connections.
+    protocol: 6
+    remotePorts: "23"
+    direction: Outbound
+    action: Block
+    enabled: true
+    profiles:
+    - All
+    interfaceTypes:
+    - All
+    edgeTraversal: false
+afterState:
+  rules:
+  - name: DscDemo - Block Telnet (TCP-Out)
+    _exist: false
+changedProperties:
+- rules
+```
+
+The rule was removed. The `afterState` for the entry shows `_exist: false`, confirming the rule
+no longer exists in the Windows Firewall store.
+
+<!-- Link definitions -->
+[01]: ../../../../../cli/config/test.md
+[02]: ../../../../../cli/config/set.md
diff --git a/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.config.dsc.yaml b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.config.dsc.yaml
new file mode 100644
index 000000000..a42854a88
--- /dev/null
+++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.config.dsc.yaml
@@ -0,0 +1,26 @@
+# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
+resources:
+  - name: Application firewall rules
+    type: Microsoft.Windows/FirewallRuleList
+    properties:
+      rules:
+        - name: DscDemo - Custom App (TCP-In)
+          description: Allow inbound TCP traffic on port 8080 for the custom app.
+          protocol: 6
+          localPorts: '8080'
+          direction: Inbound
+          action: Allow
+          enabled: true
+          profiles:
+            - Domain
+            - Private
+        - name: DscDemo - Block Telnet (TCP-Out)
+          description: Block all outbound Telnet connections.
+          protocol: 6
+          remotePorts: '23'
+          direction: Outbound
+          action: Block
+          enabled: true
+          profiles:
+            - All
diff --git a/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md
new file mode 100644
index 000000000..b15c2cbb0
--- /dev/null
+++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md
@@ -0,0 +1,191 @@
+---
+description: >
+  Examples showing how to use the Microsoft.Windows/FirewallRuleList resource with DSC to retrieve
+  and modify the state of Windows Firewall rules.
+ms.date:     05/09/2026
+ms.topic:    reference
+title:       Get firewall rule state
+---
+
+# Get firewall rule state
+
+This example shows how you can use the `Microsoft.Windows/FirewallRuleList` resource to retrieve
+the current state of a Windows Firewall rule and toggle it with `dsc resource` commands.
+
+The example uses the built-in "Remote Desktop - User Mode (TCP-In)" rule, which is present on
+every Windows installation and controls whether Remote Desktop connections are allowed.
+
+## Get the state of a firewall rule
+
+The following snippet retrieves the current state of the Remote Desktop inbound rule.
+
+```powershell
+$instance = '{"rules":[{"name":"Remote Desktop - User Mode (TCP-In)"}]}'
+
+dsc resource get --resource Microsoft.Windows/FirewallRuleList --input $instance
+```
+
+When the rule exists, DSC returns its full configuration. Notice that `_exist` is absent from the
+actual state — for this resource, an absent `_exist` means the rule is present.
+
+```yaml
+actualState:
+  rules:
+  - name: Remote Desktop - User Mode (TCP-In)
+    description: Inbound rule for the Remote Desktop service to allow RDP traffic. [TCP 3389]
+    protocol: 6
+    localPorts: "3389"
+    direction: Inbound
+    action: Allow
+    enabled: false
+    profiles:
+    - Domain
+    - Private
+    grouping: Remote Desktop
+    interfaceTypes:
+    - All
+    edgeTraversal: false
+```
+
+The rule exists but `enabled: false` means it is currently inactive and not filtering traffic.
+
+## Get the state of a rule that doesn't exist
+
+When the named rule is not registered in the Windows Firewall store, the resource returns
+`_exist: false` and omits all other properties.
+
+```powershell
+$instance = '{"rules":[{"name":"DscDemo - Custom App (TCP-In)"}]}'
+
+dsc resource get --resource Microsoft.Windows/FirewallRuleList --input $instance
+```
+
+```yaml
+actualState:
+  rules:
+  - name: DscDemo - Custom App (TCP-In)
+    _exist: false
+```
+
+## Enable a firewall rule
+
+To enable the Remote Desktop rule, use the [dsc resource set][01] command with `enabled: true`.
+This operation requires an elevated (administrator) terminal.
+
+```powershell
+$desired = '{"rules":[{"name":"Remote Desktop - User Mode (TCP-In)","enabled":true}]}'
+
+dsc resource set --resource Microsoft.Windows/FirewallRuleList --input $desired
+```
+
+DSC first tests the current state and then calls the resource's set operation because the rule
+is not in the desired state. The output shows the state before and after the change.
+
+```yaml
+beforeState:
+  rules:
+  - name: Remote Desktop - User Mode (TCP-In)
+    description: Inbound rule for the Remote Desktop service to allow RDP traffic. [TCP 3389]
+    protocol: 6
+    localPorts: "3389"
+    direction: Inbound
+    action: Allow
+    enabled: false
+    profiles:
+    - Domain
+    - Private
+    grouping: Remote Desktop
+    interfaceTypes:
+    - All
+    edgeTraversal: false
+afterState:
+  rules:
+  - name: Remote Desktop - User Mode (TCP-In)
+    description: Inbound rule for the Remote Desktop service to allow RDP traffic. [TCP 3389]
+    protocol: 6
+    localPorts: "3389"
+    direction: Inbound
+    action: Allow
+    enabled: true
+    profiles:
+    - Domain
+    - Private
+    grouping: Remote Desktop
+    interfaceTypes:
+    - All
+    edgeTraversal: false
+changedProperties:
+- rules
+```
+
+The `changedProperties` field lists `rules` because the `enabled` property of the rule changed.
+
+## Query multiple rules at once
+
+A single **Get** call can retrieve the state of multiple rules by listing them all in the `rules`
+array.
+
+```powershell
+$instance = @'
+{
+  "rules": [
+    { "name": "Remote Desktop - User Mode (TCP-In)" },
+    { "name": "Remote Desktop - User Mode (UDP-In)" }
+  ]
+}
+'@
+
+dsc resource get --resource Microsoft.Windows/FirewallRuleList --input $instance
+```
+
+```yaml
+actualState:
+  rules:
+  - name: Remote Desktop - User Mode (TCP-In)
+    description: Inbound rule for the Remote Desktop service to allow RDP traffic. [TCP 3389]
+    protocol: 6
+    localPorts: "3389"
+    direction: Inbound
+    action: Allow
+    enabled: true
+    profiles:
+    - Domain
+    - Private
+    grouping: Remote Desktop
+    interfaceTypes:
+    - All
+    edgeTraversal: false
+  - name: Remote Desktop - User Mode (UDP-In)
+    description: Inbound rule for the Remote Desktop service to allow RDP traffic. [UDP 3389]
+    protocol: 17
+    localPorts: "3389"
+    direction: Inbound
+    action: Allow
+    enabled: true
+    profiles:
+    - Domain
+    - Private
+    grouping: Remote Desktop
+    interfaceTypes:
+    - All
+    edgeTraversal: false
+```
+
+## Export all inbound allow rules
+
+The [dsc resource export][02] command returns all registered firewall rules. You can pass an
+optional filter to narrow the results. The following snippet exports only inbound rules with
+the `Allow` action.
+
+```powershell
+$filter = '{"rules":[{"direction":"Inbound","action":"Allow"}]}'
+
+dsc resource export --resource Microsoft.Windows/FirewallRuleList --input $filter
+```
+
+DSC emits one JSON object for each matching rule. Properties within a single filter entry are
+ANDed together; multiple filter entries are ORed. This call requires an elevated terminal.
+
+<!-- Link definitions -->
+[01]: ../../../../../cli/resource/set.md
+[02]: ../../../../../cli/resource/export.md
diff --git a/docs/reference/resources/Microsoft/Windows/FirewallRuleList/index.md b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/index.md
new file mode 100644
index 000000000..fb40ce48b
--- /dev/null
+++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/index.md
@@ -0,0 +1,546 @@
+---
+description: Microsoft.Windows/FirewallRuleList resource reference documentation
+ms.date:     05/09/2026
+ms.topic:    reference
+title:       Microsoft.Windows/FirewallRuleList
+---
+
+# Microsoft.Windows/FirewallRuleList
+
+## Synopsis
+
+Manage Windows Firewall rules using the netfw.h APIs.
+
+## Metadata
+
+```yaml
+Version    : 0.1.0
+Kind       : resource
+Tags       : [Windows, Firewall]
+Author     : Microsoft
+```
+
+## Instance definition syntax
+
+```yaml
+resources:
+  - name: <instance name>
+    type: Microsoft.Windows/FirewallRuleList
+    properties:
+      rules:
+        - name: string
+          # Rule properties
+          action:
+          applicationName:
+          description:
+          direction:
+          edgeTraversal:
+          enabled:
+          grouping:
+          interfaceTypes:
+          localAddresses:
+          localPorts:
+          profiles:
+          protocol:
+          remoteAddresses:
+          remotePorts:
+          serviceName:
+          _exist:
+```
+
+## Description
+
+The `Microsoft.Windows/FirewallRuleList` resource enables you to idempotently manage Windows
+Firewall rules through the `netfw.h` COM APIs. A single instance of the resource manages an array
+of rules, allowing you to create, update, or remove multiple rules in one operation.
+
+The resource can:
+
+- Retrieve the full configuration of one or more named firewall rules.
+- Create rules that don't exist, update properties of rules that do, and remove rules by setting
+  `_exist: false`.
+- Export all registered firewall rules, with optional AND/OR filtering by rule properties.
+
+> [!NOTE]
+> This resource is installed with DSC itself on Windows systems.
+>
+> You can update this resource by updating DSC. When you update DSC, the updated version of this
+> resource is automatically available.
+
+> [!IMPORTANT]
+> The `_exist` property on a rule item behaves differently from most DSC resources. When a rule
+> exists in the Windows Firewall store, `_exist` is **omitted** from the returned state (absent
+> means present). When a rule is not found, `_exist: false` appears in the response. This means
+> that a missing `_exist` field in the actual state always indicates the rule exists.
+
+## Requirements
+
+- The resource is only usable on a Windows system.
+- **Set** operations require an elevated (administrator) process context. Running `dsc` without
+  elevation causes an access-denied error from the Windows Firewall COM APIs.
+
+## Capabilities
+
+The resource has the following capabilities:
+
+- `get` - You can use the resource to retrieve the actual state of one or more firewall rules.
+- `set` - You can use the resource to enforce the desired state of one or more firewall rules,
+  including creating and removing rules.
+- `export` - You can use the resource to export all firewall rules registered on the system,
+  with optional filtering.
+
+This resource uses the synthetic test functionality of DSC to determine whether an instance is in
+the desired state. For more information about resource capabilities, see
+[DSC resource capabilities][01].
+
+## Examples
+
+1. [Get firewall rule state][03] - Shows how to retrieve the current state of a Windows Firewall
+   rule and toggle it with the `dsc resource` commands.
+1. [Configure firewall rules][04] - Shows how to create and manage multiple Windows Firewall rules
+   using a DSC configuration document.
+
+## Properties
+
+The `Microsoft.Windows/FirewallRuleList` instance has one required property at the root level.
+
+- **Required properties:** <a id="required-properties"></a>
+
+  - [rules](#rules) - An array of firewall rule objects to get, set, or use as export filters.
+
+### rules
+
+<details><summary>Expand for <code>rules</code> property metadata</summary>
+
+```yaml
+Type        : array
+IsRequired  : true
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+An array of firewall rule objects. For **Get** and **Set** operations, each entry in the array
+must include a [name](#name) property that identifies the rule. For **Export**, each entry acts
+as a filter — all properties within a single entry are ANDed together, and multiple entries are
+ORed. The array must contain at least one entry for **Get** and **Set** operations.
+
+Each entry in the `rules` array supports the following properties.
+
+### name
+
+<details><summary>Expand for <code>name</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : true for get and set
+IsKey       : true (within the rules array)
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+The Windows Firewall rule name as registered in the firewall store. This is the exact name shown
+in the Windows Firewall console. Name matching is case-insensitive. Wildcard patterns using `*`
+are supported for **Export** filter entries.
+
+### _exist
+
+<details><summary>Expand for <code>_exist</code> property metadata</summary>
+
+```yaml
+Type        : boolean
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false (writable for set to remove a rule)
+IsWriteOnly : false
+```
+
+</details>
+
+Indicates whether a firewall rule exists. The behavior of this property differs from most DSC
+resources:
+
+- When a rule **exists**, `_exist` is **omitted** from the returned state. Absence means the rule
+  is present.
+- When a rule is **not found**, `_exist: false` appears in the response.
+- In a **Set** operation, set `_exist: false` on a rule entry to remove the rule if it exists.
+
+### description
+
+<details><summary>Expand for <code>description</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+A human-readable description of the firewall rule shown in the Windows Firewall console.
+
+### applicationName
+
+<details><summary>Expand for <code>applicationName</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+The fully qualified path to the application executable associated with the rule — for example,
+`C:\Program Files\MyApp\myapp.exe`. When specified, the rule only applies to traffic from or
+to that application.
+
+### serviceName
+
+<details><summary>Expand for <code>serviceName</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+The Windows service short name associated with the rule. When specified, the rule only applies
+to traffic from or to that service.
+
+### protocol
+
+<details><summary>Expand for <code>protocol</code> property metadata</summary>
+
+```yaml
+Type                  : integer
+IsRequired            : false
+IsKey                 : false
+IsReadOnly            : false
+IsWriteOnly           : false
+InclusiveMinimumValue : 0
+InclusiveMaximumValue : 256
+```
+
+</details>
+
+The IANA IP protocol number for the rule. The following values are commonly used:
+
+| Value | Protocol            |
+|------:|:--------------------|
+|   `1` | ICMPv4              |
+|   `6` | TCP                 |
+|  `17` | UDP                 |
+|  `58` | ICMPv6              |
+| `256` | Any (all protocols) |
+
+### localPorts
+
+<details><summary>Expand for <code>localPorts</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+A comma-separated list of local port numbers or ranges for the rule — for example, `80,443` or
+`8000-8080`. Only valid when `protocol` is `6` (TCP) or `17` (UDP).
+
+### remotePorts
+
+<details><summary>Expand for <code>remotePorts</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+A comma-separated list of remote port numbers or ranges for the rule. Only valid when `protocol`
+is `6` (TCP) or `17` (UDP).
+
+### localAddresses
+
+<details><summary>Expand for <code>localAddresses</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+A comma-separated list of local IP addresses or subnets in CIDR notation for the rule — for
+example, `192.168.1.0/24,10.0.0.1`.
+
+### remoteAddresses
+
+<details><summary>Expand for <code>remoteAddresses</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+A comma-separated list of remote IP addresses or subnets in CIDR notation for the rule.
+
+### direction
+
+<details><summary>Expand for <code>direction</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+Enum        : [Inbound, Outbound]
+```
+
+</details>
+
+The direction of network traffic the rule applies to.
+
+| Value      | Description                           |
+|:-----------|:--------------------------------------|
+| `Inbound`  | The rule applies to incoming traffic. |
+| `Outbound` | The rule applies to outgoing traffic. |
+
+### action
+
+<details><summary>Expand for <code>action</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+Enum        : [Allow, Block]
+```
+
+</details>
+
+The action taken by the rule when traffic matches.
+
+| Value   | Description                                 |
+|:--------|:--------------------------------------------|
+| `Allow` | Matching traffic is permitted.              |
+| `Block` | Matching traffic is denied.                 |
+
+### enabled
+
+<details><summary>Expand for <code>enabled</code> property metadata</summary>
+
+```yaml
+Type        : boolean
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+Indicates whether the firewall rule is active. A rule that exists but has `enabled: false` does
+not affect network traffic.
+
+### profiles
+
+<details><summary>Expand for <code>profiles</code> property metadata</summary>
+
+```yaml
+Type              : array
+ItemsType         : string
+ItemsMustBeUnique : false
+IsRequired        : false
+IsKey             : false
+IsReadOnly        : false
+IsWriteOnly       : false
+Enum              : [Domain, Private, Public, All]
+```
+
+</details>
+
+The network location profiles for which the rule is active. Specifying `All` is equivalent to
+specifying all three individual profiles. When all three individual profiles (`Domain`, `Private`,
+`Public`) are set, the resource normalizes them to `All`.
+
+### grouping
+
+<details><summary>Expand for <code>grouping</code> property metadata</summary>
+
+```yaml
+Type        : string
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+The grouping string that associates the rule with a named feature or application group, shown in
+the Windows Firewall console as the **Program** or **Group** column.
+
+### interfaceTypes
+
+<details><summary>Expand for <code>interfaceTypes</code> property metadata</summary>
+
+```yaml
+Type              : array
+ItemsType         : string
+ItemsMustBeUnique : false
+IsRequired        : false
+IsKey             : false
+IsReadOnly        : false
+IsWriteOnly       : false
+Enum              : [RemoteAccess, Wireless, Lan, All]
+```
+
+</details>
+
+The network interface types for which the rule applies. Specifying `All` is equivalent to
+specifying all interface types.
+
+| Value          | Description                                    |
+|:---------------|:-----------------------------------------------|
+| `RemoteAccess` | The rule applies to remote access connections. |
+| `Wireless`     | The rule applies to wireless connections.      |
+| `Lan`          | The rule applies to LAN connections.           |
+| `All`          | The rule applies to all interface types.       |
+
+### edgeTraversal
+
+<details><summary>Expand for <code>edgeTraversal</code> property metadata</summary>
+
+```yaml
+Type        : boolean
+IsRequired  : false
+IsKey       : false
+IsReadOnly  : false
+IsWriteOnly : false
+```
+
+</details>
+
+Indicates whether edge traversal is enabled for the rule. When `true`, traffic routed through
+Network Address Translation (NAT) edge devices can pass through this rule.
+
+## Instance validating schema
+
+The following snippet contains the JSON Schema that validates an instance of the resource.
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["rules"],
+  "properties": {
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name":            { "type": "string" },
+          "_exist":          { "type": "boolean" },
+          "description":     { "type": "string" },
+          "applicationName": { "type": "string" },
+          "serviceName":     { "type": "string" },
+          "protocol":        { "type": "integer" },
+          "localPorts":      { "type": "string" },
+          "remotePorts":     { "type": "string" },
+          "localAddresses":  { "type": "string" },
+          "remoteAddresses": { "type": "string" },
+          "direction":       { "type": "string", "enum": ["Inbound", "Outbound"] },
+          "action":          { "type": "string", "enum": ["Allow", "Block"] },
+          "enabled":         { "type": "boolean" },
+          "profiles": {
+            "type": "array",
+            "items": { "type": "string", "enum": ["Domain", "Private", "Public", "All"] }
+          },
+          "grouping": { "type": "string" },
+          "interfaceTypes": {
+            "type": "array",
+            "items": { "type": "string", "enum": ["RemoteAccess", "Wireless", "Lan", "All"] }
+          },
+          "edgeTraversal": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}
+```
+
+## Exit codes
+
+The resource returns the following exit codes from operations:
+
+- [0](#exit-code-0) - Success
+- [1](#exit-code-1) - Invalid arguments
+- [2](#exit-code-2) - Invalid input
+- [3](#exit-code-3) - Firewall error
+
+### Exit code 0
+
+Indicates the resource operation completed without errors.
+
+### Exit code 1
+
+Indicates the resource operation failed because required arguments were missing or the operation
+name was not recognized.
+
+### Exit code 2
+
+Indicates the resource operation failed because the JSON input could not be deserialized into a
+valid `FirewallRuleList` instance.
+
+### Exit code 3
+
+Indicates the resource operation failed due to an error raised by the Windows Firewall COM API,
+or the result could not be serialized.
+
+## See also
+
+- [Microsoft.Windows/Registry resource][05]
+- [Microsoft.Windows/Service resource][06]
+- [DSC resource capabilities][01]
+- [DSC resource properties][02]
+
+<!-- Link definitions -->
+[01]: ../../../../../concepts/resources/capabilities.md
+[02]: ../../../../../concepts/resources/properties.md
+[03]: ./examples/get-firewall-rules.md
+[04]: ./examples/configure-firewall-rules.md
+[05]: ../Registry/index.md
+[06]: ../Service/index.md

From 922e1aa8389a22a00a17d104f3f664dc96e0b62b Mon Sep 17 00:00:00 2001
From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com>
Date: Sat, 9 May 2026 13:31:48 +0200
Subject: [PATCH 2/3] Update resource manifest

---
 resources/windows_firewall/windows_firewall.dsc.resource.json | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/resources/windows_firewall/windows_firewall.dsc.resource.json b/resources/windows_firewall/windows_firewall.dsc.resource.json
index fcc828dd1..24c399f23 100644
--- a/resources/windows_firewall/windows_firewall.dsc.resource.json
+++ b/resources/windows_firewall/windows_firewall.dsc.resource.json
@@ -94,7 +94,9 @@
                             "protocol": {
                                 "type": "integer",
                                 "title": "Protocol",
-                                "description": "The IP protocol number for the rule. Common values are 256 (Any), 6 (TCP), 17 (UDP), 1 (ICMPv4), and 58 (ICMPv6)."
+                                "description": "The IP protocol number for the rule. Common values are 256 (Any), 6 (TCP), 17 (UDP), 1 (ICMPv4), and 58 (ICMPv6). The maximum value of 256 corresponds to NET_FW_IP_PROTOCOL_ANY in the Windows Firewall COM API. See https://learn.microsoft.com/windows/win32/api/icftypes/ne-icftypes-net_fw_ip_protocol",
+                                "minimum": 0,
+                                "maximum": 256
                             },
                             "localPorts": {
                                 "type": "string",

From 5f6bdabf8f3b011c7efbaa5496976acc5e29e104 Mon Sep 17 00:00:00 2001
From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com>
Date: Sat, 9 May 2026 13:33:35 +0200
Subject: [PATCH 3/3] Take Copilot suggestion

---
 .../Windows/FirewallRuleList/examples/get-firewall-rules.md    | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md
index b15c2cbb0..65eaf16d4 100644
--- a/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md
+++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md
@@ -52,7 +52,8 @@ The rule exists but `enabled: false` means it is currently inactive and not filt
 ## Get the state of a rule that doesn't exist
 
 When the named rule is not registered in the Windows Firewall store, the resource returns
-`_exist: false` and omits all other properties.
+`_exist: false` and omits any properties that were not provided in the
+input.
 
 ```powershell
 $instance = '{"rules":[{"name":"DscDemo - Custom App (TCP-In)"}]}'