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..873de10dc --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/configure-firewall-rules.md @@ -0,0 +1,216 @@ +--- +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 +``` + +```yaml +executionInformation: + # Elided for brevity +metadata: + # Elided for brevity +results: +- executionInformation: + duration: PT0.0888807S + metadata: + Microsoft.DSC: + duration: PT0.0888807S + 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 +``` + +```yaml +executionInformation: + # Elided for brevity +metadata: + # Elided for brevity +results: +- executionInformation: + duration: PT0.288497S + metadata: + Microsoft.DSC: + duration: PT0.288497S + 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. + +## Cleanup + +To return your system to its original state: + +1. Save the following configuration as `firewall.cleanup.config.dsc.yaml`. + + :::code language="yaml" source="firewall.cleanup.config.dsc.yaml"::: + +2. Use the **Set** operation on the cleanup configuration document. + + ```powershell + dsc config set --file ./firewall.cleanup.config.dsc.yaml + ``` + + +[01]: ../../../../../cli/config/test.md +[02]: ../../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.cleanup.config.dsc.yaml b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.cleanup.config.dsc.yaml new file mode 100644 index 000000000..aa64c1ed0 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/firewall.cleanup.config.dsc.yaml @@ -0,0 +1,11 @@ +# 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: Cleanup application firewall rules + type: Microsoft.Windows/FirewallRuleList + properties: + rules: + - name: Remove 'DscDemo - Custom App (TCP-In)' + _exist: false + - name: Remove 'DscDemo - Block Telnet (TCP-Out)' + _exist: false 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..6b689c842 --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/examples/get-firewall-rules.md @@ -0,0 +1,204 @@ +--- +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)' }) +} | ConvertTo-Json -Compress + +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 any properties that were not provided in the +input. + +```powershell +$instance = @{ + rules = @(@{ name = 'DscDemo - Custom App (TCP-In)' }) +} | ConvertTo-Json -Compress + +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 + }) +} | ConvertTo-Json -Compress + +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)' } + ) +} | ConvertTo-Json -Compress + +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' + }) +} | ConvertTo-Json -Compress + +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. + + +[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..860f1a34d --- /dev/null +++ b/docs/reference/resources/Microsoft/Windows/FirewallRuleList/index.md @@ -0,0 +1,547 @@ +--- +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: + 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 Windows systems. +- **Set** and **Export** operations require an elevated (administrator) process context. Invoking + the resource for these operations in a non-elevated process context causes the resource to raise + an error. + +## 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:** + + - [rules](#rules) - An array of firewall rule objects to get, set, or use as export filters. + +### rules + +
Expand for rules property metadata + +```yaml +Type : array +IsRequired : true +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +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 + +
Expand for name property metadata + +```yaml +Type : string +IsRequired : true for get and set +IsKey : true (within the rules array) +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +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 + +
Expand for _exist property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false (writable for set to remove a rule) +IsWriteOnly : false +``` + +
+ +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 + +
Expand for description property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +A human-readable description of the firewall rule shown in the Windows Firewall console. + +### applicationName + +
Expand for applicationName property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +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 + +
Expand for serviceName property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +The Windows service short name associated with the rule. When specified, the rule only applies +to traffic from or to that service. + +### protocol + +
Expand for protocol property metadata + +```yaml +Type : integer +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +InclusiveMinimumValue : 0 +InclusiveMaximumValue : 256 +``` + +
+ +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 + +
Expand for localPorts property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +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 + +
Expand for remotePorts property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +A comma-separated list of remote port numbers or ranges for the rule. Only valid when `protocol` +is `6` (TCP) or `17` (UDP). + +### localAddresses + +
Expand for localAddresses property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +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 + +
Expand for remoteAddresses property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +A comma-separated list of remote IP addresses or subnets in CIDR notation for the rule. + +### direction + +
Expand for direction property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +Enum : [Inbound, Outbound] +``` + +
+ +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 + +
Expand for action property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +Enum : [Allow, Block] +``` + +
+ +The action taken by the rule when traffic matches. + +| Value | Description | +|:--------|:--------------------------------------------| +| `Allow` | Matching traffic is permitted. | +| `Block` | Matching traffic is denied. | + +### enabled + +
Expand for enabled property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +Indicates whether the firewall rule is active. A rule that exists but has `enabled: false` doesn't +affect network traffic. + +### profiles + +
Expand for profiles property metadata + +```yaml +Type : array +ItemsType : string +ItemsMustBeUnique : false +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +Enum : [Domain, Private, Public, All] +``` + +
+ +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 + +
Expand for grouping property metadata + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +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 + +
Expand for interfaceTypes property metadata + +```yaml +Type : array +ItemsType : string +ItemsMustBeUnique : false +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +Enum : [RemoteAccess, Wireless, Lan, All] +``` + +
+ +The network interface types for which the rule applies. Specifying `All` is equivalent to +specifying every interface type. + +| 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 + +
Expand for edgeTraversal property metadata + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +IsWriteOnly : false +``` + +
+ +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] + + +[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 diff --git a/resources/windows_firewall/windows_firewall.dsc.resource.json b/resources/windows_firewall/windows_firewall.dsc.resource.json index b3078fa5e..24c1399f7 100644 --- a/resources/windows_firewall/windows_firewall.dsc.resource.json +++ b/resources/windows_firewall/windows_firewall.dsc.resource.json @@ -93,7 +93,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",