DSCResources/DSC_Firewall/DSC_Firewall.psm1

$modulePath = Join-Path -Path (Split-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -Parent) -ChildPath 'Modules'

# Import the Networking Common Modules
Import-Module -Name (Join-Path -Path $modulePath `
        -ChildPath (Join-Path -Path 'NetworkingDsc.Common' `
            -ChildPath 'NetworkingDsc.Common.psm1'))

Import-Module -Name (Join-Path -Path $modulePath -ChildPath 'DscResource.Common')

# Import Localization Strings
$script:localizedData = Get-LocalizedData -DefaultUICulture 'en-US'

<#
    This is an array of all the parameters used by this resource
    It can be used by several of the functions to reduce the amount of code required
    Each element contains 3 properties:
    Name: The parameter name
    Source: The source where the existing parameter can be pulled from
    Type: This is the content type of the paramater (it is either array or string or blank)
    A blank type means it will not be compared
    data ParameterList
    Delimiter: Only required for Profile parameter, because Get-NetFirewall rule doesn't
    return the profile as an array, but a comma delimited string. Setting this value causes
    the functions to first split the parameter into an array.
#>

$script:resourceData = Import-LocalizedData `
    -BaseDirectory $PSScriptRoot `
    -FileName 'DSC_Firewall.data.psd1'
$script:parameterList = $script:resourceData.ParameterList

<#
    .SYNOPSIS
    Returns the current state of the Firewall Rule.
 
    .PARAMETER Name
    Name of the firewall rule.
#>

function Get-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        # Name of the Firewall Rule
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Name
    )

    $ErrorActionPreference = 'Stop'
    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.GettingFirewallRuleMessage) -f $Name
        ) -join '')

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.FindFirewallRuleMessage) -f $Name
        ) -join '')

    $firewallRule = Get-FirewallRule -Name $Name

    if (-not $firewallRule)
    {
        Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                $($script:localizedData.FirewallRuleDoesNotExistMessage) -f $Name
            ) -join '')
        return @{
            Ensure = 'Absent'
            Name   = $Name
        }
    }

    $properties = Get-FirewallRuleProperty -FirewallRule $firewallRule

    $result = @{
        Ensure = 'Present'
    }

    <#
        Populate the properties for get target resource by looping through
        the parameter array list and adding the values to
    #>

    foreach ($parameter in $script:parameterList)
    {
        if ($parameter.Type -in @('Array', 'ArrayIP'))
        {
            $parameterValue = @(Get-FirewallPropertyValue `
                    -FirewallRule $firewallRule `
                    -Properties $properties `
                    -Parameter $parameter)
            if ($parameter.Delimiter)
            {
                $parameterValue = $parameterValue -split $parameter.Delimiter
            }

            $result += @{
                $parameter.Name = $parameterValue
            }

            Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                    $($script:localizedData.FirewallParameterValueMessage) -f `
                        $Name, $parameter.Name, ($parameterValue -join ',')
                ) -join '')
        }
        else
        {
            $parameterValue = Get-FirewallPropertyValue `
                -FirewallRule $firewallRule `
                -Properties $properties `
                -Parameter $parameter

            $result += @{
                $parameter.Name = $parameterValue
            }

            Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                    $($script:localizedData.FirewallParameterValueMessage) -f `
                        $Name, $parameter.Name, $parameterValue
                ) -join '')
        }
    }
    return $result
}

<#
    .SYNOPSIS
    Create, update or delete the Firewall Rule.
 
    .PARAMETER Name
    Name of the firewall rule.
 
    .PARAMETER DisplayName
    Localized, user-facing name of the firewall rule being created.
 
    .PARAMETER Group
    Name of the firewall group where we want to put the firewall rule.
 
    .PARAMETER Ensure
    Ensure that the firewall rule exists.
 
    .PARAMETER Enabled
    Enable or Disable the supplied configuration.
 
    .PARAMETER Action
    Allow or Block the supplied configuration.
 
    .PARAMETER Profile
    Specifies one or more profiles to which the rule is assigned.
 
    .PARAMETER Direction
    Direction of the connection.
 
    .PARAMETER RemotePort
    Specific port used for filter. Specified by port number, range, or keyword.
 
    .PARAMETER LocalPort
    Local port used for the filter.
 
    .PARAMETER Protocol
    Specific protocol for filter. Specified by name, number, or range.
 
    .PARAMETER Description
    Documentation for the rule.
 
    .PARAMETER Program
    Path and filename of the program for which the rule is applied.
 
    .PARAMETER Service
    Specifies the short name of a Windows service to which the firewall rule applies.
 
    .PARAMETER Authentication
    Specifies that authentication is required on firewall rules.
 
    .PARAMETER Encryption
    Specifies that encryption in authentication is required on firewall rules.
 
    .PARAMETER InterfaceAlias
    Specifies the alias of the interface that applies to the traffic.
 
    .PARAMETER InterfaceType
    Specifies that only network connections made through the indicated interface types are subject
    to the requirements of this rule.
 
    .PARAMETER LocalAddress
    Specifies that network packets with matching IP addresses match this rule. This parameter value
    is the first end point of an IPsec rule and specifies the computers that are subject to the
    requirements of this rule. This parameter value is an IPv4 or IPv6 address, hostname, subnet,
    range, or the following keyword: Any.
 
    .PARAMETER LocalUser
    Specifies the principals to which network traffic this firewall rule applies. The principals,
    represented by security identifiers (SIDs) in the security descriptor definition language (SDDL)
    string, are services, users, application containers, or any SID to which network traffic is
    associated.
 
    .PARAMETER Package
    Specifies the Windows Store application to which the firewall rule applies. This parameter is
    specified as a security identifier (SID).
 
    .PARAMETER Platform
    Specifies which version of Windows the associated rule applies.
 
    .PARAMETER RemoteAddress
    Specifies that network packets with matching IP addresses match this rule. This parameter value
    is the second end point of an IPsec rule and specifies the computers that are subject to the
    requirements of this rule. This parameter value is an IPv4 or IPv6 address, hostname, subnet,
    range, or the following keyword: Any
 
    .PARAMETER RemoteMachine
    Specifies that matching IPsec rules of the indicated computer accounts are created. This
    parameter specifies that only network packets that are authenticated as incoming from or
    outgoing to a computer identified in the list of computer accounts (SID) match this rule.
    This parameter value is specified as an SDDL string.
 
    .PARAMETER RemoteUser
    Specifies that matching IPsec rules of the indicated user accounts are created. This parameter
    specifies that only network packets that are authenticated as incoming from or outgoing to a
    user identified in the list of user accounts match this rule. This parameter value is specified
    as an SDDL string.
 
    .PARAMETER DynamicTransport
    Specifies a dynamic transport.
 
    .PARAMETER EdgeTraversalPolicy
    Specifies that matching firewall rules of the indicated edge traversal policy are created.
 
    .PARAMETER IcmpType
    Specifies the ICMP type codes.
 
    .PARAMETER LocalOnlyMapping
    Indicates that matching firewall rules of the indicated value are created.
 
    .PARAMETER LooseSourceMapping
    Indicates that matching firewall rules of the indicated value are created.
 
    .PARAMETER OverrideBlockRules
    Indicates that matching network traffic that would otherwise be blocked are allowed.
 
    .PARAMETER Owner
    Specifies that matching firewall rules of the indicated owner are created.
#>

function Set-TargetResource
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Name,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $DisplayName,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Group,

        [Parameter()]
        [ValidateSet('Present', 'Absent')]
        [String]
        $Ensure = 'Present',

        [Parameter()]
        [ValidateSet('True', 'False')]
        [String]
        $Enabled,

        [Parameter()]
        [ValidateSet('NotConfigured', 'Allow', 'Block')]
        [String]
        $Action,

        [Parameter()]
        [String[]]
        $Profile,

        [Parameter()]
        [ValidateSet('Inbound', 'Outbound')]
        [String]
        $Direction,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $RemotePort,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $LocalPort,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Protocol,

        [Parameter()]
        [String]
        $Description,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Program,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Service,

        [Parameter()]
        [ValidateSet('NotRequired', 'Required', 'NoEncap')]
        [String]
        $Authentication,

        [Parameter()]
        [ValidateSet('NotRequired', 'Required', 'Dynamic')]
        [String]
        $Encryption,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $InterfaceAlias,

        [Parameter()]
        [ValidateSet('Any', 'Wired', 'Wireless', 'RemoteAccess')]
        [String]
        $InterfaceType,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $LocalAddress,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $LocalUser,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Package,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $Platform,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $RemoteAddress,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $RemoteMachine,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $RemoteUser,

        [Parameter()]
        [ValidateSet('Any', 'ProximityApps', 'ProximitySharing', 'WifiDirectPrinting', 'WifiDirectDisplay', 'WifiDirectDevices')]
        [String]
        $DynamicTransport,

        [Parameter()]
        [ValidateSet('Block', 'Allow', 'DeferToUser', 'DeferToApp')]
        [String]
        $EdgeTraversalPolicy,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $IcmpType,

        [Parameter()]
        [Boolean]
        $LocalOnlyMapping,

        [Parameter()]
        [Boolean]
        $LooseSourceMapping,

        [Parameter()]
        [Boolean]
        $OverrideBlockRules,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Owner
    )

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.ApplyingFirewallRuleMessage) -f $Name
        ) -join '')

    # Remove any parameters not used in Splats
    $null = $PSBoundParameters.Remove('Ensure')

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.FindFirewallRuleMessage) -f $Name
        ) -join '')
    $firewallRule = Get-FirewallRule -Name $Name

    $exists = ($null -ne $firewallRule)

    if ($Ensure -eq 'Present')
    {
        Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                $($script:localizedData.FirewallRuleShouldExistMessage) -f $Name, $Ensure
            ) -join '')

        if ($exists)
        {
            Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                    $($script:localizedData.FirewallRuleShouldExistAndDoesMessage) -f $Name
                ) -join '')

            Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                    $($script:localizedData.CheckFirewallRuleParametersMessage) -f $Name
                ) -join '')

            if (-not (Test-RuleProperties -FirewallRule $firewallRule @PSBoundParameters))
            {
                Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                        $($script:localizedData.UpdatingExistingFirewallMessage) -f $Name
                    ) -join '')

                # If the Group is being changed the the rule needs to be recreated
                if ($PSBoundParameters.ContainsKey('Group') `
                        -and ($Group -ne $FirewallRule.Group))
                {
                    Remove-NetFirewallRule -Name  (ConvertTo-FirewallRuleNameEscapedString -Name $Name)

                    <#
                        Merge the existing rule values into the PSBoundParameters
                        so that it can be splatted.
                    #>

                    $properties = Get-FirewallRuleProperty -FirewallRule $firewallRule

                    <#
                        Loop through each possible property and if it is not passed as a parameter
                        then set the PSBoundParameter property to the exiting rule value.
                    #>

                    foreach ($parameter in $ParametersList)
                    {
                        if (-not $PSBoundParameters.ContainsKey($parameter.Name))
                        {
                            $parameterValue = Get-FirewallPropertyValue `
                                -FirewallRule $firewallRule `
                                -Properties $properties `
                                -Parameter $parameter

                            if ($ParameterValue)
                            {
                                $null = $PSBoundParameters.Add($parameter.Name, $ParameterValue)
                            }
                        }
                    }

                    New-NetFirewallRule @PSBoundParameters
                }
                else
                {
                    # Group is a lookup key parameter that cannot be used in conjunction with Name
                    $null = $PSBoundParameters.Remove('Group')

                    <#
                        If the DisplayName is provided then need to remove it
                        And change it to NewDisplayName if it is different.
                    #>

                    if ($PSBoundParameters.ContainsKey('DisplayName'))
                    {
                        $null = $PSBoundParameters.Remove('DisplayName')
                        if ($DisplayName -ne $FirewallRule.DisplayName)
                        {
                            $null = $PSBoundParameters.Add('NewDisplayName', $DisplayName)
                        }
                    }

                    # Escape firewall rule name to ensure that wildcard update is not used
                    $PSBoundParameters['Name'] = ConvertTo-FirewallRuleNameEscapedString -Name $Name

                    # Set the existing Firewall rule based on specified parameters
                    Set-NetFirewallRule @PSBoundParameters
                }
            }
        }
        else
        {
            Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                    $($script:localizedData.FirewallRuleShouldExistAndDoesNotMessage) -f $Name
                ) -join '')

            # Set any default parameter values
            if (-not $DisplayName)
            {
                if (-not $PSBoundParameters.ContainsKey('DisplayName'))
                {
                    $null = $PSBoundParameters.Add('DisplayName', $Name)
                }
                else
                {
                    $PSBoundParameters.DisplayName = $Name
                }
            }

            # Add the new Firewall rule based on specified parameters
            New-NetFirewallRule @PSBoundParameters
        }
    }
    else
    {
        Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                $($script:localizedData.FirewallRuleShouldNotExistMessage) -f $Name, $Ensure
            ) -join '')

        if ($exists)
        {
            Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                    $($script:localizedData.FirewallRuleShouldNotExistButDoesMessage) -f $Name
                ) -join '')

            # Remove the existing Firewall rule
            Remove-NetFirewallRule -Name (ConvertTo-FirewallRuleNameEscapedString -Name $Name)
        }
        else
        {
            Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                    $($script:localizedData.FirewallRuleShouldNotExistAndDoesNotMessage) -f $Name
                ) -join '')
            # Do Nothing
        }
    }
}

<#
    .SYNOPSIS
    Test if Firewall Rule is in the required state.
 
    .PARAMETER Name
    Name of the firewall rule.
 
    .PARAMETER DisplayName
    Localized, user-facing name of the firewall rule being created.
 
    .PARAMETER Group
    Name of the firewall group where we want to put the firewall rule.
 
    .PARAMETER Ensure
    Ensure that the firewall rule exists.
 
    .PARAMETER Enabled
    Enable or Disable the supplied configuration.
 
    .PARAMETER Action
    Allow or Block the supplied configuration.
 
    .PARAMETER Profile
    Specifies one or more profiles to which the rule is assigned.
 
    .PARAMETER Direction
    Direction of the connection.
 
    .PARAMETER RemotePort
    Specific port used for filter. Specified by port number, range, or keyword.
 
    .PARAMETER LocalPort
    Local port used for the filter.
 
    .PARAMETER Protocol
    Specific protocol for filter. Specified by name, number, or range.
 
    .PARAMETER Description
    Documentation for the rule.
 
    .PARAMETER Program
    Path and filename of the program for which the rule is applied.
 
    .PARAMETER Service
    Specifies the short name of a Windows service to which the firewall rule applies.
 
    .PARAMETER Authentication
    Specifies that authentication is required on firewall rules.
 
    .PARAMETER Encryption
    Specifies that encryption in authentication is required on firewall rules.
 
    .PARAMETER InterfaceAlias
    Specifies the alias of the interface that applies to the traffic.
 
    .PARAMETER InterfaceType
    Specifies that only network connections made through the indicated interface types are subject
    to the requirements of this rule.
 
    .PARAMETER LocalAddress
    Specifies that network packets with matching IP addresses match this rule. This parameter value
    is the first end point of an IPsec rule and specifies the computers that are subject to the
    requirements of this rule. This parameter value is an IPv4 or IPv6 address, hostname, subnet,
    range, or the following keyword: Any.
 
    .PARAMETER LocalUser
    Specifies the principals to which network traffic this firewall rule applies. The principals,
    represented by security identifiers (SIDs) in the security descriptor definition language (SDDL)
    string, are services, users, application containers, or any SID to which network traffic is
    associated.
 
    .PARAMETER Package
    Specifies the Windows Store application to which the firewall rule applies. This parameter is
    specified as a security identifier (SID).
 
    .PARAMETER Platform
    Specifies which version of Windows the associated rule applies.
 
    .PARAMETER RemoteAddress
    Specifies that network packets with matching IP addresses match this rule. This parameter value
    is the second end point of an IPsec rule and specifies the computers that are subject to the
    requirements of this rule. This parameter value is an IPv4 or IPv6 address, hostname, subnet,
    range, or the following keyword: Any
 
    .PARAMETER RemoteMachine
    Specifies that matching IPsec rules of the indicated computer accounts are created. This
    parameter specifies that only network packets that are authenticated as incoming from or
    outgoing to a computer identified in the list of computer accounts (SID) match this rule.
    This parameter value is specified as an SDDL string.
 
    .PARAMETER RemoteUser
    Specifies that matching IPsec rules of the indicated user accounts are created. This parameter
    specifies that only network packets that are authenticated as incoming from or outgoing to a
    user identified in the list of user accounts match this rule. This parameter value is specified
    as an SDDL string.
 
    .PARAMETER DynamicTransport
    Specifies a dynamic transport.
 
    .PARAMETER EdgeTraversalPolicy
    Specifies that matching firewall rules of the indicated edge traversal policy are created.
 
    .PARAMETER IcmpType
    Specifies the ICMP type codes.
 
    .PARAMETER LocalOnlyMapping
    Indicates that matching firewall rules of the indicated value are created.
 
    .PARAMETER LooseSourceMapping
    Indicates that matching firewall rules of the indicated value are created.
 
    .PARAMETER OverrideBlockRules
    Indicates that matching network traffic that would otherwise be blocked are allowed.
 
    .PARAMETER Owner
    Specifies that matching firewall rules of the indicated owner are created.
#>

function Test-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Name,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $DisplayName,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Group,

        [Parameter()]
        [ValidateSet('Present', 'Absent')]
        [String]
        $Ensure = 'Present',

        [Parameter()]
        [ValidateSet('True', 'False')]
        [String]
        $Enabled,

        [Parameter()]
        [ValidateSet('NotConfigured', 'Allow', 'Block')]
        [String]
        $Action,

        [Parameter()]
        [String[]]
        $Profile,

        [Parameter()]
        [ValidateSet('Inbound', 'Outbound')]
        [String]
        $Direction,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $RemotePort,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $LocalPort,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Protocol,

        [Parameter()]
        [String]
        $Description,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Program,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Service,

        [Parameter()]
        [ValidateSet('NotRequired', 'Required', 'NoEncap')]
        [String]
        $Authentication,

        [Parameter()]
        [ValidateSet('NotRequired', 'Required', 'Dynamic')]
        [String]
        $Encryption,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $InterfaceAlias,

        [Parameter()]
        [ValidateSet('Any', 'Wired', 'Wireless', 'RemoteAccess')]
        [String]
        $InterfaceType,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $LocalAddress,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $LocalUser,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Package,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $Platform,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $RemoteAddress,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $RemoteMachine,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $RemoteUser,

        [Parameter()]
        [ValidateSet('Any', 'ProximityApps', 'ProximitySharing', 'WifiDirectPrinting', 'WifiDirectDisplay', 'WifiDirectDevices')]
        [String]
        $DynamicTransport,

        [Parameter()]
        [ValidateSet('Block', 'Allow', 'DeferToUser', 'DeferToApp')]
        [String]
        $EdgeTraversalPolicy,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String[]]
        $IcmpType,

        [Parameter()]
        [Boolean]
        $LocalOnlyMapping,

        [Parameter()]
        [Boolean]
        $LooseSourceMapping,

        [Parameter()]
        [Boolean]
        $OverrideBlockRules,

        [Parameter()]
        [ValidateNotNullOrEmpty()]
        [String]
        $Owner
    )

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.CheckingFirewallRuleMessage) -f $Name
        ) -join '')

    # Remove any parameters not used in Splats
    $null = $PSBoundParameters.Remove('Ensure')

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.FindFirewallRuleMessage) -f $Name
        ) -join '')

    $firewallRule = Get-FirewallRule -Name $Name

    $exists = ($null -ne $firewallRule)

    if (-not $exists)
    {
        Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                $($script:localizedData.FirewallRuleDoesNotExistMessage) -f $Name
            ) -join '')

        # Returns whether complies with $Ensure
        $returnValue = ($false -eq ($Ensure -eq 'Present'))

        Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                $($script:localizedData.CheckingFirewallReturningMessage) -f $Name, $returnValue
            ) -join '')

        return $returnValue
    }

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.CheckFirewallRuleParametersMessage) -f $Name
        ) -join '')

    $desiredConfigurationMatch = Test-RuleProperties -FirewallRule $firewallRule @PSBoundParameters

    # Returns whether or not $exists complies with $Ensure
    $returnValue = ($desiredConfigurationMatch -and $exists -eq ($Ensure -eq 'Present'))

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.CheckingFirewallReturningMessage) -f $Name, $returnValue
        ) -join '')

    return $returnValue
}

#region HelperFunctions
<#
    .SYNOPSIS
    Tests if the properties in the supplied Firewall Rule match the expected parameters passed.
 
    .PARAMETER FirewallRule
    The firewall rule object to compare the properties of.
 
    .PARAMETER Name
    Name of the firewall rule.
 
    .PARAMETER DisplayName
    Localized, user-facing name of the firewall rule being created.
 
    .PARAMETER Group
    Name of the firewall group where we want to put the firewall rule.
 
    .PARAMETER Ensure
    Ensure that the firewall rule exists.
 
    .PARAMETER Enabled
    Enable or Disable the supplied configuration.
 
    .PARAMETER Action
    Allow or Block the supplied configuration.
 
    .PARAMETER Profile
    Specifies one or more profiles to which the rule is assigned.
 
    .PARAMETER Direction
    Direction of the connection.
 
    .PARAMETER RemotePort
    Specific port used for filter. Specified by port number, range, or keyword.
 
    .PARAMETER LocalPort
    Local port used for the filter.
 
    .PARAMETER Protocol
    Specific protocol for filter. Specified by name, number, or range.
 
    .PARAMETER Description
    Documentation for the rule.
 
    .PARAMETER Program
    Path and filename of the program for which the rule is applied.
 
    .PARAMETER Service
    Specifies the short name of a Windows service to which the firewall rule applies.
 
    .PARAMETER Authentication
    Specifies that authentication is required on firewall rules.
 
    .PARAMETER Encryption
    Specifies that encryption in authentication is required on firewall rules.
 
    .PARAMETER InterfaceAlias
    Specifies the alias of the interface that applies to the traffic.
 
    .PARAMETER InterfaceType
    Specifies that only network connections made through the indicated interface types are subject
    to the requirements of this rule.
 
    .PARAMETER LocalAddress
    Specifies that network packets with matching IP addresses match this rule. This parameter value
    is the first end point of an IPsec rule and specifies the computers that are subject to the
    requirements of this rule. This parameter value is an IPv4 or IPv6 address, hostname, subnet,
    range, or the following keyword: Any.
 
    .PARAMETER LocalUser
    Specifies the principals to which network traffic this firewall rule applies. The principals,
    represented by security identifiers (SIDs) in the security descriptor definition language (SDDL)
    string, are services, users, application containers, or any SID to which network traffic is
    associated.
 
    .PARAMETER Package
    Specifies the Windows Store application to which the firewall rule applies. This parameter is
    specified as a security identifier (SID).
 
    .PARAMETER Platform
    Specifies which version of Windows the associated rule applies.
 
    .PARAMETER RemoteAddress
    Specifies that network packets with matching IP addresses match this rule. This parameter value
    is the second end point of an IPsec rule and specifies the computers that are subject to the
    requirements of this rule. This parameter value is an IPv4 or IPv6 address, hostname, subnet,
    range, or the following keyword: Any
 
    .PARAMETER RemoteMachine
    Specifies that matching IPsec rules of the indicated computer accounts are created. This
    parameter specifies that only network packets that are authenticated as incoming from or
    outgoing to a computer identified in the list of computer accounts (SID) match this rule.
    This parameter value is specified as an SDDL string.
 
    .PARAMETER RemoteUser
    Specifies that matching IPsec rules of the indicated user accounts are created. This parameter
    specifies that only network packets that are authenticated as incoming from or outgoing to a
    user identified in the list of user accounts match this rule. This parameter value is specified
    as an SDDL string.
 
    .PARAMETER DynamicTransport
    Specifies a dynamic transport.
 
    .PARAMETER EdgeTraversalPolicy
    Specifies that matching firewall rules of the indicated edge traversal policy are created.
 
    .PARAMETER IcmpType
    Specifies the ICMP type codes.
 
    .PARAMETER LocalOnlyMapping
    Indicates that matching firewall rules of the indicated value are created.
 
    .PARAMETER LooseSourceMapping
    Indicates that matching firewall rules of the indicated value are created.
 
    .PARAMETER OverrideBlockRules
    Indicates that matching network traffic that would otherwise be blocked are allowed.
 
    .PARAMETER Owner
    Specifies that matching firewall rules of the indicated owner are created.
#>

function Test-RuleProperties
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [Parameter(Mandatory = $true)]
        $FirewallRule,

        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Name,

        [Parameter()]
        [String]
        $DisplayName,

        [Parameter()]
        [String]
        $Group,

        [Parameter()]
        [String]
        $DisplayGroup,

        [Parameter()]
        [ValidateSet('Present', 'Absent')]
        [String]
        $Ensure = 'Present',

        [Parameter()]
        [ValidateSet('True', 'False')]
        [String]
        $Enabled,

        [Parameter()]
        [ValidateSet('NotConfigured', 'Allow', 'Block')]
        [String]
        $Action,

        [Parameter()]
        [String[]]
        $Profile,

        [Parameter()]
        [ValidateSet('Inbound', 'Outbound')]
        [String]
        $Direction,

        [Parameter()]
        [String[]]
        $RemotePort,

        [Parameter()]
        [String[]]
        $LocalPort,

        [Parameter()]
        [String]
        $Protocol,

        [Parameter()]
        [String]
        $Description,

        [Parameter()]
        [String]
        $Program,

        [Parameter()]
        [String]
        $Service,

        [Parameter()]
        [ValidateSet('NotRequired', 'Required', 'NoEncap')]
        [String]
        $Authentication,

        [Parameter()]
        [ValidateSet('NotRequired', 'Required', 'Dynamic')]
        [String]
        $Encryption,

        [Parameter()]
        [String[]]
        $InterfaceAlias,

        [Parameter()]
        [ValidateSet('Any', 'Wired', 'Wireless', 'RemoteAccess')]
        [String]
        $InterfaceType,

        [Parameter()]
        [String[]]
        $LocalAddress,

        [Parameter()]
        [String]
        $LocalUser,

        [Parameter()]
        [String]
        $Package,

        [Parameter()]
        [String[]]
        $Platform,

        [Parameter()]
        [String[]]
        $RemoteAddress,

        [Parameter()]
        [String]
        $RemoteMachine,

        [Parameter()]
        [String]
        $RemoteUser,

        [Parameter()]
        [ValidateSet('Any', 'ProximityApps', 'ProximitySharing', 'WifiDirectPrinting', 'WifiDirectDisplay', 'WifiDirectDevices')]
        [String]
        $DynamicTransport,

        [Parameter()]
        [ValidateSet('Block', 'Allow', 'DeferToUser', 'DeferToApp')]
        [String]
        $EdgeTraversalPolicy,

        [Parameter()]
        [String[]]
        $IcmpType,

        [Parameter()]
        [Boolean]
        $LocalOnlyMapping,

        [Parameter()]
        [Boolean]
        $LooseSourceMapping,

        [Parameter()]
        [Boolean]
        $OverrideBlockRules,

        [Parameter()]
        [String]
        $Owner
    )

    $properties = Get-FirewallRuleProperty -FirewallRule $FirewallRule
    $desiredConfigurationMatch = $true

    <#
        Loop through the $script:parameterList array and compare the source
        with the value of each parameter. If different then set $desiredConfigurationMatch
        to false.
    #>

    foreach ($parameter in $script:parameterList)
    {
        $parameterValue = Get-FirewallPropertyValue `
            -FirewallRule $firewallRule `
            -Properties $properties `
            -Parameter $parameter

        $parameterNew = (Get-Variable -Name ($parameter.Name)).Value

        switch -Wildcard ($parameter.Type)
        {
            'String'
            {
                # Perform a plain string comparison.
                if ($parameterNew -and ($parameterValue -ne $parameterNew))
                {
                    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                            $($script:localizedData.PropertyNoMatchMessage) `
                                -f $parameter.Name, $parameterValue, $parameterNew
                        ) -join '')

                    $desiredConfigurationMatch = $false
                }
            }

            'Boolean'
            {
                # Perform a boolean comparison.
                if ($parameterNew -and ($parameterValue -ne $parameterNew))
                {
                    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                            $($script:localizedData.PropertyNoMatchMessage) `
                                -f $parameter.Name, $parameterValue, $parameterNew
                        ) -join '')
                    $desiredConfigurationMatch = $false
                }
            }

            'Array*'
            {
                # Array comparison uses Compare-Object
                if ($null -eq $parameterValue)
                {
                    $parameterValue = @()
                }

                if ($parameter.Delimiter)
                {
                    $parameterValue = $parameterValue -split $parameter.Delimiter
                }

                if ($parameter.Type -eq 'ArrayIP')
                {
                    <#
                        IPArray comparison uses Compare-Object, except needs to convert any IP addresses
                        that use CIDR notation to use Subnet Mask notification because this is the
                        format that the Get-NetFirewallAddressFilter will return the IP addresses in
                        even if they were set using CIDR notation.
                    #>

                    if ($null -ne $parameterNew)
                    {
                        $parameterNew = Convert-CIDRToSubhetMask -Address $parameterNew
                    }
                }

                if ($parameterNew `
                        -and ((Compare-Object `
                                -ReferenceObject $parameterValue `
                                -DifferenceObject $parameterNew).Count -ne 0))
                {
                    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                            $($script:localizedData.PropertyNoMatchMessage) `
                                -f $parameter.Name, ($parameterValue -join ','), ($parameterNew -join ',')
                        ) -join '')
                    $desiredConfigurationMatch = $false
                }
            }
        }
    }

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.TestFirewallRuleReturningMessage) -f $Name, $desiredConfigurationMatch
        ) -join '')
    return $desiredConfigurationMatch
}

<#
    .SYNOPSIS
    Returns a Firewall object matching the specified name.
 
    .PARAMETER Name
    The name of the Firewall Rule to Retrieve.
#>

function Get-FirewallRule
{
    [CmdletBinding()]
    [OutputType([Microsoft.Management.Infrastructure.CimInstance])]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]
        $Name
    )

    $firewallRule = @(Get-NetFirewallRule -Name (ConvertTo-FirewallRuleNameEscapedString -Name $Name) -ErrorAction SilentlyContinue)

    if (-not $firewallRule)
    {
        Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
                $($script:localizedData.FirewallRuleNotFoundMessage) -f $Name
            ) -join '')
        return $null
    }

    <#
        If more than one rule is returned for a name, then throw an exception
        because this should not be possible.
    #>

    if ($firewallRule.Count -gt 1)
    {
        New-InvalidOperationException `
            -Message ($script:localizedData.RuleNotUniqueError -f $firewallRule.Count, $Name)
    }

    # The array will only contain a single rule so only return the first one (not the array)
    return $firewallRule[0]
}

<#
    .SYNOPSIS
    Returns a Hashtable containing the component Firewall objects for the specified Firewall Rule.
 
    .PARAMETER FirewallRule
    The firewall rule object to pull the additional firewall objects for.
#>

function Get-FirewallRuleProperty
{
    [CmdletBinding()]
    [OutputType([HashTable])]
    param
    (
        [Parameter(Mandatory = $true)]
        $FirewallRule
    )

    Write-Verbose -Message ( @( "$($MyInvocation.MyCommand): "
            $($script:localizedData.GetAllPropertiesMessage)
        ) -join '')

    return @{
        AddressFilters       = @(Get-NetFirewallAddressFilter -AssociatedNetFirewallRule $FirewallRule)
        ApplicationFilters   = @(Get-NetFirewallApplicationFilter -AssociatedNetFirewallRule $FirewallRule)
        InterfaceFilters     = @(Get-NetFirewallInterfaceFilter -AssociatedNetFirewallRule $FirewallRule)
        InterfaceTypeFilters = @(Get-NetFirewallInterfaceTypeFilter -AssociatedNetFirewallRule $FirewallRule)
        PortFilters          = @(Get-NetFirewallPortFilter -AssociatedNetFirewallRule $FirewallRule)
        Profile              = @(Get-NetFirewallProfile -AssociatedNetFirewallRule $FirewallRule)
        SecurityFilters      = @(Get-NetFirewallSecurityFilter -AssociatedNetFirewallRule $FirewallRule)
        ServiceFilters       = @(Get-NetFirewallServiceFilter -AssociatedNetFirewallRule $FirewallRule)
    }
}

<#
    .SYNOPSIS
    Looks up a Firewall Property value using the specified parameterList entry.
 
    .PARAMETER FirewallRule
    The firewall rule object to pull the property from.
 
    .PARAMETER Properties
    The additional firewall objects to pull the property from.
 
    .PARAMETER Parameter
    The entry from the ParameterList table used to retireve the parameter for.
#>

function Get-FirewallPropertyValue
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        $FirewallRule,

        [Parameter(Mandatory = $true)]
        $Properties,

        [Parameter(Mandatory = $true)]
        $Parameter
    )

    if ($Parameter.Property)
    {
        return (Get-Variable `
                -Name ($Parameter.Variable)).value.$($Parameter.Property).$($Parameter.Name)
    }
    else
    {
        return (Get-Variable `
                -Name ($Parameter.Variable)).value.$($Parameter.Name)
    }
}

<#
    .SYNOPSIS
    Convert Firewall Rule name to Escape Wildcard Characters.
 
    It will append '[', ']' and '*' with a backtick.
 
    .PARAMETER Name
    The firewall rule name to escape.
#>

function ConvertTo-FirewallRuleNameEscapedString
{
    [CmdletBinding()]
    [OutputType([System.String])]
    param
    (
        [Parameter(Mandatory = $true)]
        $Name
    )

    return $Name.Replace('[','`[').Replace(']','`]').Replace('*','`*')
}
#endregion

Export-ModuleMember -Function *-TargetResource