Edit

Microsoft.Windows/FirewallRuleList

Synopsis

Manage Windows Firewall rules using the netfw.h APIs.

Metadata

Version    : 0.1.0
Kind       : resource
Tags       : [Windows, Firewall]
Author     : Microsoft

Instance definition syntax

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.

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.

The resource is installed with DSC itself on Windows systems.

Note

You can update this resource by updating DSC. When you update DSC, the updated version of this resource is automatically available.

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.

Examples

  1. Get firewall rule state - Shows how to retrieve the current state of a Windows Firewall rule and toggle it with the dsc resource commands.
  2. Configure firewall rules - 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 - An array of firewall rule objects to get, set, or use as export filters.

rules

Expand for rules property metadata 
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 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 
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 
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 
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 
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 
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 
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 
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 
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 
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 
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 
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 
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 
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 
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 
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 
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 
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.

{
  "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 - Success
  • 1 - Invalid arguments
  • 2 - Invalid input
  • 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

  • Last updated on