SentinelARConverter

2.4.3

public/Convert-SentinelARYamlToArm.ps1

<#
.SYNOPSIS
Converts an Azure Sentinel Analytics Rule YAML file to ARM template
 
.DESCRIPTION
Converts an Azure Sentinel Analytics Rule YAML file to ARM template.
The YAML file can be provided as a file or as a string.
The ARM template file can be saved to the same directory as the YAML file.
 
.PARAMETER Filename
The path to the Analytics Rule YAML file
 
.PARAMETER Data
The YAML data as a string
 
.PARAMETER OutFile
The path to the output ARM template file
 
.PARAMETER UseOriginalFilename
If set, the output file will be saved with the original filename of the ARM template file
The extension will be replaced with .json
 
.PARAMETER UseDisplayNameAsFilename
If set, the output file will be saved with the display name of the Analytics Rule as filename
The extension will be replaced with .json
 
.PARAMETER UseIdAsFilename
If set, the output file will be saved with the id of the Analytics Rule as filename
The extension will be replaced with .json
 
.PARAMETER APIVersion
Set API version of the ARM template. Default is "2024-01-01-preview"
 
.PARAMETER NamePrefix
Set prefix for the name of the ARM template. Default is none
 
.PARAMETER Severity
Overwrite the severity of the provided YAML file with a custom one. Default is emtpy
 
.PARAMETER StartRunningAt
Set the startTimeUtc property of the ARM template. Default is empty
To successfully deploy the ARM template the startTimeUtc property must be set to a future date.
Start time must be between 10 minutes and 30 days from now. This is not validated by the cmdlet.
 
.PARAMETER DisableIncidentCreation
If set, the incidentCreation property of the ARM template will be set to false. Default is to keep the value from the YAML file.
 
.EXAMPLE
Convert-SentinelARYamlToArm -Filename "C:\Temp\MyRule.yaml" -OutFile "C:\Temp\MyRule.json"
 
.NOTES
  Author: Fabian Bader (https://cloudbrothers.info/)
#>

function Convert-SentinelARYamlToArm {
    [CmdletBinding(DefaultParameterSetName = 'StdOut')]
    param (
        [Parameter(Mandatory,
            Position = 0,
            ParameterSetName = 'Path')]
        [Parameter(Mandatory,
            Position = 0,
            ParameterSetName = 'UseOriginalFilename')]
        [Parameter(Mandatory,
            Position = 0,
            ParameterSetName = 'UseDisplayNameAsFilename')]
        [Parameter(Mandatory,
            Position = 0,
            ParameterSetName = 'UseIdAsFilename')]
        [Parameter(Mandatory,
            Position = 0,
            ParameterSetName = 'StdOut')]
        [string]$Filename,

        [Alias('Json')]
        [Parameter(Mandatory,
            ValueFromPipeline,
            ParameterSetName = 'Pipeline',
            Position = 0)]
        [array]$Data,

        [Parameter(ParameterSetName = 'Path')]
        [Parameter(ParameterSetName = 'Pipeline')]
        [string]$OutFile,

        [Parameter(ParameterSetName = 'UseOriginalFilename')]
        [switch]$UseOriginalFilename,

        [Parameter(ParameterSetName = 'UseDisplayNameAsFilename')]
        [switch]$UseDisplayNameAsFilename,

        [Parameter(ParameterSetName = 'UseIdAsFilename')]
        [switch]$UseIdAsFilename,

        [ValidatePattern('^\d{4}-\d{2}-\d{2}(-preview)?$')]
        [Parameter()]
        [string]$APIVersion = "2024-01-01-preview",

        [Parameter()]
        [string]$NamePrefix,

        [ValidateSet("Informational", "Low", "Medium", "High")]
        [Parameter()]
        [string]$Severity,

        [Parameter()]
        [string]$ParameterFile,

        [Parameter()]
        [datetime]$StartRunningAt,

        [Parameter()]
        [switch]$DisableIncidentCreation
    )

    begin {
        if ($PsCmdlet.ParameterSetName -ne "Pipeline" ) {
            try {
                if (-not (Test-Path $Filename)) {
                    Write-Error -Exception
                }
            } catch {
                throw "File not found"
            }
        }

        if ($ParameterFile) {
            try {
                if (-not (Test-Path $ParameterFile)) {
                    Write-Error -Exception
                }
            } catch {
                throw "Parameters file not found"
            }
        }
    }

    process {
        # Use pipeline data and create a variable containing all parsed strings
        if ($PsCmdlet.ParameterSetName -eq "Pipeline") {
            $FullYaml += $Data
        }
    }

    end {

        $PowerShellYAMLModuleVersion = Get-Module -Name powershell-yaml | Select-Object -ExpandProperty Version
        if ( $PowerShellYAMLModuleVersion -ge [version]"0.4.8" -and $PowerShellYAMLModuleVersion -le [version]"0.4.9" ) {
            Write-Warning "The powershell-yaml module version $($PowerShellYAMLModuleVersion) has known issues. Please update to the latest version of the module."
        }

        try {
            # Use parsed pipeline data if no file was specified (default)
            if ($PsCmdlet.ParameterSetName -eq "Pipeline") {
                $analyticRule = $FullYaml | ConvertFrom-Yaml
            } else {
                Write-Verbose "Read file `"$Filename`""
                $analyticRule = Get-Content $Filename | ConvertFrom-Yaml
            }
        } catch {
            throw "Could not convert source file. YAML might be corrupted"
        }

        try {
            if ($ParameterFile) {
                Write-Verbose "Read parameters file `"$ParameterFile`""
                $Parameters = Get-Content $ParameterFile | ConvertFrom-Yaml
            } else {
                Write-Verbose "No parameters file provided"
            }
        } catch {
            throw "Could not convert parameters file. YAML might be corrupted"
        }

        #region Parameter file handling
        if ($Parameters) {
            #region Overwrite values from parameters file
            if ($Parameters.OverwriteProperties) {
                foreach ($Key in $Parameters.OverwriteProperties.Keys) {
                    if ($analyticRule.ContainsKey($Key)) {
                        Write-Verbose "Overwriting property $Key with $($Parameters.OverwriteProperties[$Key])"
                        $analyticRule[$Key] = $Parameters.OverwriteProperties[$Key]
                    } else {
                        Write-Verbose "Add new property $Key with $($Parameters.OverwriteProperties[$Key])"
                        $analyticRule.Add($Key, $Parameters.OverwriteProperties[$Key])
                    }
                }
            } else {
                Write-Verbose "No properties to overwrite in provided parameters file"
            }
            #endregion Overwrite values from parameters file

            #region Prepend KQL query with data from parameters file
            if ($Parameters.PrependQuery) {
                $analyticRule.query = $Parameters.PrependQuery + $analyticRule.query
            } else {
                Write-Verbose "No query to prepend in provided parameters file"
            }
            #endregion Prepend KQL query with data from parameters file

            #region Append KQL query with data from parameters file
            if ($Parameters.AppendQuery) {
                $analyticRule.query = $analyticRule.query + $Parameters.AppendQuery
            } else {
                Write-Verbose "No query to append in provided parameters file"
            }
            #endregion Append KQL query with data from parameters file

            #region Replace variables in KQL query with data from parameters file
            if ($Parameters.ReplaceQueryVariables) {
                foreach ($Key in $Parameters.ReplaceQueryVariables.Keys) {
                    if ($Parameters.ReplaceQueryVariables[$Key].Count -gt 1) {
                        # Join array values with comma and wrap in quotes
                        $ReplaceValue = $Parameters.ReplaceQueryVariables[$Key] -join '","'
                        $ReplaceValue = '"' + $ReplaceValue + '"'
                    } else {
                        # Use single value
                        $ReplaceValue = $Parameters.ReplaceQueryVariables[$Key]
                    }
                    Write-Verbose "Replacing variable %%$Key%% with $($ReplaceValue)"
                    $analyticRule.query = $analyticRule.query -replace "%%$($Key)%%", $ReplaceValue
                }
            } else {
                Write-Verbose "No variables to replace in provided parameters file"
            }
            #endregion Replace variables in KQL query with data from parameters file

            Write-Verbose "$($analyticRule | ConvertTo-Json -Depth 99)"
        }
        #endregion Parameter file handling

        if ( [string]::IsNullOrWhiteSpace($analyticRule.name) -or [string]::IsNullOrWhiteSpace($analyticRule.id) ) {
            throw "Analytics Rule name or id is empty. YAML might be corrupted"
        }

        # Generate new guid if id is not a valid guid
        if ($analyticRule.id -notmatch "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}") {
            Write-Warning "Error reading current Id. Generating new Id."
            $analyticRule.id = (New-Guid).Guid
        }

        # Add prefix to name if specified
        if ($NamePrefix) {
            $analyticRule.name = $NamePrefix + $analyticRule.name
        }

        # Overwrite severity with custom severity
        if (-not [string]::IsNullOrWhiteSpace($Severity) ) {
            $analyticRule.severity = $Severity
        }

        Write-Verbose "Convert Analytics Rule $($analyticRule.name) ($($analyticRule.id)) to ARM template"

        #region Set output filename to defined value if not specified by user
        if ($PsCmdlet.ParameterSetName -in ("UseOriginalFilename", "UseDisplayNameAsFilename", "UseIdAsFilename") ) {
            $FileObject = Get-ChildItem $Filename
            if ($UseOriginalFilename) {
                # Use original filename as new filename
                $NewFileName = $FileObject.Name -replace $FileObject.Extension, ".json"
            }
            if ($UseDisplayNameAsFilename) {
                # Use the display name of the Analytics Rule as filename
                $NewFileName = $analyticRule.name -Replace '[^0-9A-Z]', ' '
                # Convert To CamelCase
                $NewFileName = ((Get-Culture).TextInfo.ToTitleCase($NewFileName) -Replace ' ') + '.json'
            }
            if ($UseIdAsFilename) {
                # Use id as of the Analytics Rule filename
                $NewFileName = $analyticRule.id + '.json'
            }
            $OutFile = Join-Path $FileObject.Directory $NewFileName
        }
        #endregion

        $Template = @'
{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "workspace": {
            "type": "String"
        }
    },
    "resources": [
        {
            "id": "[concat(resourceId('Microsoft.OperationalInsights/workspaces/providers', parameters('workspace'), 'Microsoft.SecurityInsights'),'/alertRules/<TEMPLATEID>')]",
            "name": "[concat(parameters('workspace'),'/Microsoft.SecurityInsights/<TEMPLATEID>')]",
            "type": "Microsoft.OperationalInsights/workspaces/providers/alertRules",
            "kind": "<RULEKIND>",
            "apiVersion": "<APIVERSION>",
            "properties": <PROPERTIES>
        }
    ]
}
'@

        # Replace API version with specified version
        $Template = $Template.Replace('<APIVERSION>', $APIVersion)

        $SkipYamlValues = @(
            "metadata",
            "kind",
            "requiredDataConnectors"
        )

        # Mapping of Arm template names to YAML name when different
        $ValueNameMappingYaml2Arm = [ordered]@{
            "name"               = "displayName"
            "id"                 = "alertRuleTemplateName"
            "version"            = "templateVersion"
            "relevantTechniques" = "techniques"
        }

        $CompareOperatorYaml2Arm = @{
            "eq" = "Equals"
            "gt" = "GreaterThan"
            "ge" = "GreaterThanOrEqual"
            "lt" = "LessThan"
            "le" = "LessThanOrEqual"
        }

        $ARMTemplate = [ordered]@{}
        foreach ($Item in $analyticRule.Keys) {
            # Skip certain values, because they are not needed in the ARM template
            if ( $Item -notin $SkipYamlValues ) {
                # Change the name of the value if needed
                $KeyName = $ValueNameMappingYaml2Arm[$Item]
                # If the name is not in the mapping, use the original name
                if ([string]::IsNullOrWhiteSpace($KeyName)) {
                    $KeyName = $Item
                }

                # Change values of compare operators
                if ( $analyticRule[$Item] -in $CompareOperatorYaml2Arm.Keys ) {
                    $Value = $CompareOperatorYaml2Arm[$analyticRule[$Item]]
                } else {
                    $Value = $analyticRule[$Item]
                }
                # Add value to hashtable
                if ($KeyName -notin $ARMTemplate.keys) {
                    $ARMTemplate.Add($KeyName, $Value)
                }
            }
        }

        # Add required parameters if missing with default values
        $RequiredParameters = @{
            "suppressionDuration" = "PT1H"
            "suppressionEnabled"  = $false
            "enabled"             = $true
            "customDetails"       = $null
            "entityMappings"      = $null
            "templateVersion"     = "1.0.0"
        }
        foreach ( $KeyName in $RequiredParameters.Keys ) {
            if (  $KeyName -notin $ARMTemplate.Keys ) {
                $ARMTemplate.Add($KeyName, $RequiredParameters[$KeyName])
            }
        }
        # Minimum API version that supports MITRE sub-techniques
        if (([datetime]::parseexact($APIVersion, 'yyyy-MM-dd-preview', $null)) -ge [datetime]"2023-12-01") {
            $ARMTemplate.subTechniques = @($ARMTemplate.techniques | Where-Object { $_ -match "(T\d{4})\.\d{3}" })
        }

        # Remove any sub-techniques from the techniques array
        if ($ARMTemplate.techniques) {
            $ARMTemplate.techniques = $ARMTemplate.techniques -replace "(T\d{4})\.\d{3}", '$1'
        }

        # Remove any invalid or non-existent techniques from the techniques array
        if ($ARMTemplate.techniques) {
            $ARMTemplate.techniques = $ARMTemplate.techniques | Where-Object { Test-MITRETechnique $_ }
        }

        # Remove duplicate techniques
        if ($ARMTemplate.techniques) {
            $ARMTemplate.techniques = @($ARMTemplate.techniques | Sort-Object -Unique)
        }

        # Remove any invalid or non-existent tactics from the tactics array
        if ($ARMTemplate.tactics) {
            $ARMTemplate.tactics = $ARMTemplate.tactics | Where-Object { Test-MITRETactic $_ }
        }

        # Remove duplicate tactics
        if ($ARMTemplate.tactics) {
            $ARMTemplate.tactics = @($ARMTemplate.tactics | Sort-Object -Unique)
        }

        # Add startRunningAt property if specified
        if ($StartRunningAt -and $analyticRule.kind -eq "Scheduled") {
            # Remove existing startTimeUtc property
            if ("startTimeUtc" -in $ARMTemplate.Keys) {
                $ARMTemplate.Remove("startTimeUtc")
            }
            # Add new startTimeUtc property
            $ARMTemplate.Add("startTimeUtc", $StartRunningAt.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ"))
        } elseif ($StartRunningAt) {
            Write-Warning "StartRunningAt parameter is only supported for scheduled rules. Ignoring parameter."
        }

        # Disable incident creation if specified
        if ($DisableIncidentCreation) {
            # Remove existing createIncident property
            if ("createIncident" -in $ARMTemplate.incidentConfiguration.Keys) {
                $ARMTemplate.incidentConfiguration.Remove("createIncident")
            }
            # Check if incidentConfiguration container is present and if not create it
            if (-not $ARMTemplate.incidentConfiguration) {
                $ARMTemplate.Add("incidentConfiguration", [ordered]@{})
            }
            $ARMTemplate.incidentConfiguration.Add("createIncident", $false)
        }

        # Convert hashtable to JSON
        $JSON = $ARMTemplate | ConvertTo-Json -Depth 99
        # Use ISO8601 format for timespan values
        $JSON = $JSON -replace '"([0-9]+)m"', '"PT$1M"' -replace '"([0-9]+)h"', '"PT$1H"' -replace '"([0-9]+)d"', '"P$1D"'

        if ($analyticRule.kind -eq "Scheduled") {
            $ScheduleKind = "Scheduled"
        } elseif ($analyticRule.kind -eq "Nrt") {
            $ScheduleKind = "NRT"
        } else {
            $ScheduleKind = $analyticRule.kind.substring(0, 1).toupper() + $analyticRule.kind.substring(1).tolower()
        }

        $Result = $Template.Replace("<PROPERTIES>", $JSON)
        $Result = $Result.Replace("<TEMPLATEID>", $analyticRule.id)
        $Result = $Result.Replace("<RULEKIND>", $ScheduleKind)

        # Sort all property keys in ARM template and convert to JSON string object
        $Result = Invoke-SortJSONObject -object ( $Result | ConvertFrom-Json )
        $Result = $Result | ConvertTo-Json -Depth 99

        if ($OutFile) {
            $Result | Out-File $OutFile -Force
            Write-Verbose "Output written to file: `"$OutFile`""
        } else {
            return $Result
        }
    }
}
# SIG # Begin signature block
# MIIoAAYJKoZIhvcNAQcCoIIn8TCCJ+0CAQExDzANBglghkgBZQMEAgEFADB5Bgor
# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG
# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCDd1rNM5x7FTquD
# rdCNZosW25pS4qjotPtYwN6AtRyYSqCCIQMwggWNMIIEdaADAgECAhAOmxiO+dAt
# 5+/bUOIIQBhaMA0GCSqGSIb3DQEBDAUAMGUxCzAJBgNVBAYTAlVTMRUwEwYDVQQK
# EwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xJDAiBgNV
# BAMTG0RpZ2lDZXJ0IEFzc3VyZWQgSUQgUm9vdCBDQTAeFw0yMjA4MDEwMDAwMDBa
# Fw0zMTExMDkyMzU5NTlaMGIxCzAJBgNVBAYTAlVTMRUwEwYDVQQKEwxEaWdpQ2Vy
# dCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xITAfBgNVBAMTGERpZ2lD
# ZXJ0IFRydXN0ZWQgUm9vdCBHNDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoC
# ggIBAL/mkHNo3rvkXUo8MCIwaTPswqclLskhPfKK2FnC4SmnPVirdprNrnsbhA3E
# MB/zG6Q4FutWxpdtHauyefLKEdLkX9YFPFIPUh/GnhWlfr6fqVcWWVVyr2iTcMKy
# unWZanMylNEQRBAu34LzB4TmdDttceItDBvuINXJIB1jKS3O7F5OyJP4IWGbNOsF
# xl7sWxq868nPzaw0QF+xembud8hIqGZXV59UWI4MK7dPpzDZVu7Ke13jrclPXuU1
# 5zHL2pNe3I6PgNq2kZhAkHnDeMe2scS1ahg4AxCN2NQ3pC4FfYj1gj4QkXCrVYJB
# MtfbBHMqbpEBfCFM1LyuGwN1XXhm2ToxRJozQL8I11pJpMLmqaBn3aQnvKFPObUR
# WBf3JFxGj2T3wWmIdph2PVldQnaHiZdpekjw4KISG2aadMreSx7nDmOu5tTvkpI6
# nj3cAORFJYm2mkQZK37AlLTSYW3rM9nF30sEAMx9HJXDj/chsrIRt7t/8tWMcCxB
# YKqxYxhElRp2Yn72gLD76GSmM9GJB+G9t+ZDpBi4pncB4Q+UDCEdslQpJYls5Q5S
# UUd0viastkF13nqsX40/ybzTQRESW+UQUOsxxcpyFiIJ33xMdT9j7CFfxCBRa2+x
# q4aLT8LWRV+dIPyhHsXAj6KxfgommfXkaS+YHS312amyHeUbAgMBAAGjggE6MIIB
# NjAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBTs1+OC0nFdZEzfLmc/57qYrhwP
# TzAfBgNVHSMEGDAWgBRF66Kv9JLLgjEtUYunpyGd823IDzAOBgNVHQ8BAf8EBAMC
# AYYweQYIKwYBBQUHAQEEbTBrMCQGCCsGAQUFBzABhhhodHRwOi8vb2NzcC5kaWdp
# Y2VydC5jb20wQwYIKwYBBQUHMAKGN2h0dHA6Ly9jYWNlcnRzLmRpZ2ljZXJ0LmNv
# bS9EaWdpQ2VydEFzc3VyZWRJRFJvb3RDQS5jcnQwRQYDVR0fBD4wPDA6oDigNoY0
# aHR0cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lDZXJ0QXNzdXJlZElEUm9vdENB
# LmNybDARBgNVHSAECjAIMAYGBFUdIAAwDQYJKoZIhvcNAQEMBQADggEBAHCgv0Nc
# Vec4X6CjdBs9thbX979XB72arKGHLOyFXqkauyL4hxppVCLtpIh3bb0aFPQTSnov
# Lbc47/T/gLn4offyct4kvFIDyE7QKt76LVbP+fT3rDB6mouyXtTP0UNEm0Mh65Zy
# oUi0mcudT6cGAxN3J0TU53/oWajwvy8LpunyNDzs9wPHh6jSTEAZNUZqaVSwuKFW
# juyk1T3osdz9HNj0d1pcVIxv76FQPfx2CWiEn2/K2yCNNWAcAgPLILCsWKAOQGPF
# mCLBsln1VWvPJ6tsds5vIy30fnFqI2si/xK4VC0nftg62fC2h5b9W9FcrBjDTZ9z
# twGpn1eqXijiuZQwggauMIIElqADAgECAhAHNje3JFR82Ees/ShmKl5bMA0GCSqG
# SIb3DQEBCwUAMGIxCzAJBgNVBAYTAlVTMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMx
# GTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xITAfBgNVBAMTGERpZ2lDZXJ0IFRy
# dXN0ZWQgUm9vdCBHNDAeFw0yMjAzMjMwMDAwMDBaFw0zNzAzMjIyMzU5NTlaMGMx
# CzAJBgNVBAYTAlVTMRcwFQYDVQQKEw5EaWdpQ2VydCwgSW5jLjE7MDkGA1UEAxMy
# RGlnaUNlcnQgVHJ1c3RlZCBHNCBSU0E0MDk2IFNIQTI1NiBUaW1lU3RhbXBpbmcg
# Q0EwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQDGhjUGSbPBPXJJUVXH
# JQPE8pE3qZdRodbSg9GeTKJtoLDMg/la9hGhRBVCX6SI82j6ffOciQt/nR+eDzMf
# UBMLJnOWbfhXqAJ9/UO0hNoR8XOxs+4rgISKIhjf69o9xBd/qxkrPkLcZ47qUT3w
# 1lbU5ygt69OxtXXnHwZljZQp09nsad/ZkIdGAHvbREGJ3HxqV3rwN3mfXazL6IRk
# tFLydkf3YYMZ3V+0VAshaG43IbtArF+y3kp9zvU5EmfvDqVjbOSmxR3NNg1c1eYb
# qMFkdECnwHLFuk4fsbVYTXn+149zk6wsOeKlSNbwsDETqVcplicu9Yemj052FVUm
# cJgmf6AaRyBD40NjgHt1biclkJg6OBGz9vae5jtb7IHeIhTZgirHkr+g3uM+onP6
# 5x9abJTyUpURK1h0QCirc0PO30qhHGs4xSnzyqqWc0Jon7ZGs506o9UD4L/wojzK
# QtwYSH8UNM/STKvvmz3+DrhkKvp1KCRB7UK/BZxmSVJQ9FHzNklNiyDSLFc1eSuo
# 80VgvCONWPfcYd6T/jnA+bIwpUzX6ZhKWD7TA4j+s4/TXkt2ElGTyYwMO1uKIqjB
# Jgj5FBASA31fI7tk42PgpuE+9sJ0sj8eCXbsq11GdeJgo1gJASgADoRU7s7pXche
# MBK9Rp6103a50g5rmQzSM7TNsQIDAQABo4IBXTCCAVkwEgYDVR0TAQH/BAgwBgEB
# /wIBADAdBgNVHQ4EFgQUuhbZbU2FL3MpdpovdYxqII+eyG8wHwYDVR0jBBgwFoAU
# 7NfjgtJxXWRM3y5nP+e6mK4cD08wDgYDVR0PAQH/BAQDAgGGMBMGA1UdJQQMMAoG
# CCsGAQUFBwMIMHcGCCsGAQUFBwEBBGswaTAkBggrBgEFBQcwAYYYaHR0cDovL29j
# c3AuZGlnaWNlcnQuY29tMEEGCCsGAQUFBzAChjVodHRwOi8vY2FjZXJ0cy5kaWdp
# Y2VydC5jb20vRGlnaUNlcnRUcnVzdGVkUm9vdEc0LmNydDBDBgNVHR8EPDA6MDig
# NqA0hjJodHRwOi8vY3JsMy5kaWdpY2VydC5jb20vRGlnaUNlcnRUcnVzdGVkUm9v
# dEc0LmNybDAgBgNVHSAEGTAXMAgGBmeBDAEEAjALBglghkgBhv1sBwEwDQYJKoZI
# hvcNAQELBQADggIBAH1ZjsCTtm+YqUQiAX5m1tghQuGwGC4QTRPPMFPOvxj7x1Bd
# 4ksp+3CKDaopafxpwc8dB+k+YMjYC+VcW9dth/qEICU0MWfNthKWb8RQTGIdDAiC
# qBa9qVbPFXONASIlzpVpP0d3+3J0FNf/q0+KLHqrhc1DX+1gtqpPkWaeLJ7giqzl
# /Yy8ZCaHbJK9nXzQcAp876i8dU+6WvepELJd6f8oVInw1YpxdmXazPByoyP6wCeC
# RK6ZJxurJB4mwbfeKuv2nrF5mYGjVoarCkXJ38SNoOeY+/umnXKvxMfBwWpx2cYT
# gAnEtp/Nh4cku0+jSbl3ZpHxcpzpSwJSpzd+k1OsOx0ISQ+UzTl63f8lY5knLD0/
# a6fxZsNBzU+2QJshIUDQtxMkzdwdeDrknq3lNHGS1yZr5Dhzq6YBT70/O3itTK37
# xJV77QpfMzmHQXh6OOmc4d0j/R0o08f56PGYX/sr2H7yRp11LB4nLCbbbxV7HhmL
# NriT1ObyF5lZynDwN7+YAN8gFk8n+2BnFqFmut1VwDophrCYoCvtlUG3OtUVmDG0
# YgkPCr2B2RP+v6TR81fZvAT6gt4y3wSJ8ADNXcL50CN/AAvkdgIm2fBldkKmKYcJ
# RyvmfxqkhQ/8mJb2VVQrH4D6wPIOK+XW+6kvRBVK5xMOHds3OBqhK/bt1nz8MIIG
# sDCCBJigAwIBAgIQCK1AsmDSnEyfXs2pvZOu2TANBgkqhkiG9w0BAQwFADBiMQsw
# CQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3d3cu
# ZGlnaWNlcnQuY29tMSEwHwYDVQQDExhEaWdpQ2VydCBUcnVzdGVkIFJvb3QgRzQw
# HhcNMjEwNDI5MDAwMDAwWhcNMzYwNDI4MjM1OTU5WjBpMQswCQYDVQQGEwJVUzEX
# MBUGA1UEChMORGlnaUNlcnQsIEluYy4xQTA/BgNVBAMTOERpZ2lDZXJ0IFRydXN0
# ZWQgRzQgQ29kZSBTaWduaW5nIFJTQTQwOTYgU0hBMzg0IDIwMjEgQ0ExMIICIjAN
# BgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1bQvQtAorXi3XdU5WRuxiEL1M4zr
# PYGXcMW7xIUmMJ+kjmjYXPXrNCQH4UtP03hD9BfXHtr50tVnGlJPDqFX/IiZwZHM
# gQM+TXAkZLON4gh9NH1MgFcSa0OamfLFOx/y78tHWhOmTLMBICXzENOLsvsI8Irg
# nQnAZaf6mIBJNYc9URnokCF4RS6hnyzhGMIazMXuk0lwQjKP+8bqHPNlaJGiTUyC
# EUhSaN4QvRRXXegYE2XFf7JPhSxIpFaENdb5LpyqABXRN/4aBpTCfMjqGzLmysL0
# p6MDDnSlrzm2q2AS4+jWufcx4dyt5Big2MEjR0ezoQ9uo6ttmAaDG7dqZy3SvUQa
# khCBj7A7CdfHmzJawv9qYFSLScGT7eG0XOBv6yb5jNWy+TgQ5urOkfW+0/tvk2E0
# XLyTRSiDNipmKF+wc86LJiUGsoPUXPYVGUztYuBeM/Lo6OwKp7ADK5GyNnm+960I
# HnWmZcy740hQ83eRGv7bUKJGyGFYmPV8AhY8gyitOYbs1LcNU9D4R+Z1MI3sMJN2
# FKZbS110YU0/EpF23r9Yy3IQKUHw1cVtJnZoEUETWJrcJisB9IlNWdt4z4FKPkBH
# X8mBUHOFECMhWWCKZFTBzCEa6DgZfGYczXg4RTCZT/9jT0y7qg0IU0F8WD1Hs/q2
# 7IwyCQLMbDwMVhECAwEAAaOCAVkwggFVMBIGA1UdEwEB/wQIMAYBAf8CAQAwHQYD
# VR0OBBYEFGg34Ou2O/hfEYb7/mF7CIhl9E5CMB8GA1UdIwQYMBaAFOzX44LScV1k
# TN8uZz/nupiuHA9PMA4GA1UdDwEB/wQEAwIBhjATBgNVHSUEDDAKBggrBgEFBQcD
# AzB3BggrBgEFBQcBAQRrMGkwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLmRpZ2lj
# ZXJ0LmNvbTBBBggrBgEFBQcwAoY1aHR0cDovL2NhY2VydHMuZGlnaWNlcnQuY29t
# L0RpZ2lDZXJ0VHJ1c3RlZFJvb3RHNC5jcnQwQwYDVR0fBDwwOjA4oDagNIYyaHR0
# cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lDZXJ0VHJ1c3RlZFJvb3RHNC5jcmww
# HAYDVR0gBBUwEzAHBgVngQwBAzAIBgZngQwBBAEwDQYJKoZIhvcNAQEMBQADggIB
# ADojRD2NCHbuj7w6mdNW4AIapfhINPMstuZ0ZveUcrEAyq9sMCcTEp6QRJ9L/Z6j
# fCbVN7w6XUhtldU/SfQnuxaBRVD9nL22heB2fjdxyyL3WqqQz/WTauPrINHVUHmI
# moqKwba9oUgYftzYgBoRGRjNYZmBVvbJ43bnxOQbX0P4PpT/djk9ntSZz0rdKOtf
# JqGVWEjVGv7XJz/9kNF2ht0csGBc8w2o7uCJob054ThO2m67Np375SFTWsPK6Wrx
# oj7bQ7gzyE84FJKZ9d3OVG3ZXQIUH0AzfAPilbLCIXVzUstG2MQ0HKKlS43Nb3Y3
# LIU/Gs4m6Ri+kAewQ3+ViCCCcPDMyu/9KTVcH4k4Vfc3iosJocsL6TEa/y4ZXDlx
# 4b6cpwoG1iZnt5LmTl/eeqxJzy6kdJKt2zyknIYf48FWGysj/4+16oh7cGvmoLr9
# Oj9FpsToFpFSi0HASIRLlk2rREDjjfAVKM7t8RhWByovEMQMCGQ8M4+uKIw8y4+I
# Cw2/O/TOHnuO77Xry7fwdxPm5yg/rBKupS8ibEH5glwVZsxsDsrFhsP2JjMMB0ug
# 0wcCampAMEhLNKhRILutG4UI4lkNbcoFUCvqShyepf2gpx8GdOfy1lKQ/a+FSCH5
# Vzu0nAPthkX0tGFuv2jiJmCG6sivqf6UHedjGzqGVnhOMIIGvDCCBKSgAwIBAgIQ
# C65mvFq6f5WHxvnpBOMzBDANBgkqhkiG9w0BAQsFADBjMQswCQYDVQQGEwJVUzEX
# MBUGA1UEChMORGlnaUNlcnQsIEluYy4xOzA5BgNVBAMTMkRpZ2lDZXJ0IFRydXN0
# ZWQgRzQgUlNBNDA5NiBTSEEyNTYgVGltZVN0YW1waW5nIENBMB4XDTI0MDkyNjAw
# MDAwMFoXDTM1MTEyNTIzNTk1OVowQjELMAkGA1UEBhMCVVMxETAPBgNVBAoTCERp
# Z2lDZXJ0MSAwHgYDVQQDExdEaWdpQ2VydCBUaW1lc3RhbXAgMjAyNDCCAiIwDQYJ
# KoZIhvcNAQEBBQADggIPADCCAgoCggIBAL5qc5/2lSGrljC6W23mWaO16P2RHxjE
# iDtqmeOlwf0KMCBDEr4IxHRGd7+L660x5XltSVhhK64zi9CeC9B6lUdXM0s71EOc
# Re8+CEJp+3R2O8oo76EO7o5tLuslxdr9Qq82aKcpA9O//X6QE+AcaU/byaCagLD/
# GLoUb35SfWHh43rOH3bpLEx7pZ7avVnpUVmPvkxT8c2a2yC0WMp8hMu60tZR0Cha
# V76Nhnj37DEYTX9ReNZ8hIOYe4jl7/r419CvEYVIrH6sN00yx49boUuumF9i2T8U
# uKGn9966fR5X6kgXj3o5WHhHVO+NBikDO0mlUh902wS/Eeh8F/UFaRp1z5SnROHw
# SJ+QQRZ1fisD8UTVDSupWJNstVkiqLq+ISTdEjJKGjVfIcsgA4l9cbk8Smlzddh4
# EfvFrpVNnes4c16Jidj5XiPVdsn5n10jxmGpxoMc6iPkoaDhi6JjHd5ibfdp5uzI
# Xp4P0wXkgNs+CO/CacBqU0R4k+8h6gYldp4FCMgrXdKWfM4N0u25OEAuEa3Jyidx
# W48jwBqIJqImd93NRxvd1aepSeNeREXAu2xUDEW8aqzFQDYmr9ZONuc2MhTMizch
# NULpUEoA6Vva7b1XCB+1rxvbKmLqfY/M/SdV6mwWTyeVy5Z/JkvMFpnQy5wR14GJ
# cv6dQ4aEKOX5AgMBAAGjggGLMIIBhzAOBgNVHQ8BAf8EBAMCB4AwDAYDVR0TAQH/
# BAIwADAWBgNVHSUBAf8EDDAKBggrBgEFBQcDCDAgBgNVHSAEGTAXMAgGBmeBDAEE
# AjALBglghkgBhv1sBwEwHwYDVR0jBBgwFoAUuhbZbU2FL3MpdpovdYxqII+eyG8w
# HQYDVR0OBBYEFJ9XLAN3DigVkGalY17uT5IfdqBbMFoGA1UdHwRTMFEwT6BNoEuG
# SWh0dHA6Ly9jcmwzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRydXN0ZWRHNFJTQTQw
# OTZTSEEyNTZUaW1lU3RhbXBpbmdDQS5jcmwwgZAGCCsGAQUFBwEBBIGDMIGAMCQG
# CCsGAQUFBzABhhhodHRwOi8vb2NzcC5kaWdpY2VydC5jb20wWAYIKwYBBQUHMAKG
# TGh0dHA6Ly9jYWNlcnRzLmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRydXN0ZWRHNFJT
# QTQwOTZTSEEyNTZUaW1lU3RhbXBpbmdDQS5jcnQwDQYJKoZIhvcNAQELBQADggIB
# AD2tHh92mVvjOIQSR9lDkfYR25tOCB3RKE/P09x7gUsmXqt40ouRl3lj+8QioVYq
# 3igpwrPvBmZdrlWBb0HvqT00nFSXgmUrDKNSQqGTdpjHsPy+LaalTW0qVjvUBhcH
# zBMutB6HzeledbDCzFzUy34VarPnvIWrqVogK0qM8gJhh/+qDEAIdO/KkYesLyTV
# OoJ4eTq7gj9UFAL1UruJKlTnCVaM2UeUUW/8z3fvjxhN6hdT98Vr2FYlCS7Mbb4H
# v5swO+aAXxWUm3WpByXtgVQxiBlTVYzqfLDbe9PpBKDBfk+rabTFDZXoUke7zPgt
# d7/fvWTlCs30VAGEsshJmLbJ6ZbQ/xll/HjO9JbNVekBv2Tgem+mLptR7yIrpaid
# RJXrI+UzB6vAlk/8a1u7cIqV0yef4uaZFORNekUgQHTqddmsPCEIYQP7xGxZBIhd
# mm4bhYsVA6G2WgNFYagLDBzpmk9104WQzYuVNsxyoVLObhx3RugaEGru+SojW4dH
# PoWrUhftNpFC5H7QEY7MhKRyrBe7ucykW7eaCuWBsBb4HOKRFVDcrZgdwaSIqMDi
# CLg4D+TPVgKx2EgEdeoHNHT9l3ZDBD+XgbF+23/zBjeCtxz+dL/9NWR6P2eZRi7z
# cEO1xwcdcqJsyz/JceENc2Sg8h3KeFUCS7tpFk7CrDqkMIIHSDCCBTCgAwIBAgIQ
# CoIwkEerNiPKwx+yPazrmjANBgkqhkiG9w0BAQsFADBpMQswCQYDVQQGEwJVUzEX
# MBUGA1UEChMORGlnaUNlcnQsIEluYy4xQTA/BgNVBAMTOERpZ2lDZXJ0IFRydXN0
# ZWQgRzQgQ29kZSBTaWduaW5nIFJTQTQwOTYgU0hBMzg0IDIwMjEgQ0ExMB4XDTIy
# MDUxODAwMDAwMFoXDTI1MDUxNzIzNTk1OVowTTELMAkGA1UEBhMCREUxEDAOBgNV
# BAcTB0hhbWJ1cmcxFTATBgNVBAoTDEZhYmlhbiBCYWRlcjEVMBMGA1UEAxMMRmFi
# aWFuIEJhZGVyMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAwSPFSbbO
# IFCY82i///NpwIqHv7GJCDqju+CJg7TAojDV2CDSz72qN2PYjV5anfh/jeJVGtA7
# BrCeKWkLzVH9P4pW52juEhwRe7fbv7s+PkpThLBdwQXh/JHEXpIv9jLkOGH3Yxrx
# oIS5bdnzKfuyUr8qJ/J+U6a9SgkOkFNM6pGHFGY2TsRA8wMjTdphYGTKf585hH4m
# D7/Gq1db72IQDpooKXYPZobQ+LAuLtF/RgTVH1Ytg/61md28pV35QyZujAccoYJj
# gDWzecx7O7cdYuwAlsPfh6L+YFVOx9LyuaVFQg6w63e1DNYEguImPl6tWtAMOHmg
# Xxd4a4w/H0tvUkqjOH5K4dU4CWmcISnkdh2sdHNwx8gjfYe3TwpWxlFOU1HEae6H
# ANF6tVtIyVhQRwS7J1DNJO1KIOGZDBhKhiPklr17WMnR5eYECOdcackHDT9yZJ3Q
# HkT0GMa3KnZSR56RhObz7NH8llJRSZ/2yzDOPAhiFOrKjZPYYL8R5248ZkxOxbTJ
# WpThW53dKPM6b9NotqiJW5ru4eOVq0yjSMdtPLttQAu6HEtNKI190Aiv5XPPQYMy
# I1PHVLY5sV7pm36hIpY5EW23HnJs3024AiF45FN1mxHlUkm7c+CYsNAbnyRJlIcU
# yF121akFNVuGQUwbIQntmQoa/kxd/vpY2pECAwEAAaOCAgYwggICMB8GA1UdIwQY
# MBaAFGg34Ou2O/hfEYb7/mF7CIhl9E5CMB0GA1UdDgQWBBT1CpTCfZbDHlbuSkDm
# mKmFygIOOTAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwMwgbUG
# A1UdHwSBrTCBqjBToFGgT4ZNaHR0cDovL2NybDMuZGlnaWNlcnQuY29tL0RpZ2lD
# ZXJ0VHJ1c3RlZEc0Q29kZVNpZ25pbmdSU0E0MDk2U0hBMzg0MjAyMUNBMS5jcmww
# U6BRoE+GTWh0dHA6Ly9jcmw0LmRpZ2ljZXJ0LmNvbS9EaWdpQ2VydFRydXN0ZWRH
# NENvZGVTaWduaW5nUlNBNDA5NlNIQTM4NDIwMjFDQTEuY3JsMD4GA1UdIAQ3MDUw
# MwYGZ4EMAQQBMCkwJwYIKwYBBQUHAgEWG2h0dHA6Ly93d3cuZGlnaWNlcnQuY29t
# L0NQUzCBlAYIKwYBBQUHAQEEgYcwgYQwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3Nw
# LmRpZ2ljZXJ0LmNvbTBcBggrBgEFBQcwAoZQaHR0cDovL2NhY2VydHMuZGlnaWNl
# cnQuY29tL0RpZ2lDZXJ0VHJ1c3RlZEc0Q29kZVNpZ25pbmdSU0E0MDk2U0hBMzg0
# MjAyMUNBMS5jcnQwDAYDVR0TAQH/BAIwADANBgkqhkiG9w0BAQsFAAOCAgEACcHI
# VShggRroVDxi+SDfJOqVM2Z92T25Yv8xyWGMUm14bGEOBgnfHiIUJmK9Bpm0k/hn
# YEpV5Ill8/Rf20l+yvlwTj1m4st2Rr4c84RSGmrW83mkYxMhg5YLtLiZdafNCcku
# 9+26dgZ537K7YDhGuIeWg708VchAnDEb8CliqWMYLw6J4vagQ91E5emPpq7FhDs2
# qNMElnrjWULjQkYRGlDfw22AcpstCrEBkc+18WZl6BD2Ow1D1whMV6P1472ZgTco
# 6Pcp8BKhrqooUXq2CDwYXJb/iFNwRnu7Cs78u+dlLu+sXNxsbGuPT9Ig+5OvC1Fi
# HMeOa4aS8HZSpTbu4w8cclL9EdXqlgVXFC2PlDir/2W9Vj9s6tiSp3hdlH7dIO5F
# EQh8JLrdPFwKXZ8drgvP26Mf11jCvykM+QQm9jhB/VhAnwiskgUodIkfox0RjJtC
# QkNT1oXqJVErwBql/IVQUNQCR7Q7fA8U2jU8FBTkYryUQAQaIEqxav3c+GqM94Th
# 3C5FvrOu4CU28/HZuTjZZCBP7s2EW//4bRUQSnXB4maszUR+/8R+bX++yfH/Ou1H
# QL5aGo9q2L36oaVFjaM282w1pzFAEUf0jgpUkBeJOFUeFvirYWyqex+oKwy8Vzgs
# +BKd7FOShLa7wCai1fjfYvpO7GxbpdYJqanNMmAxggZTMIIGTwIBATB9MGkxCzAJ
# BgNVBAYTAlVTMRcwFQYDVQQKEw5EaWdpQ2VydCwgSW5jLjFBMD8GA1UEAxM4RGln
# aUNlcnQgVHJ1c3RlZCBHNCBDb2RlIFNpZ25pbmcgUlNBNDA5NiBTSEEzODQgMjAy
# MSBDQTECEAqCMJBHqzYjysMfsj2s65owDQYJYIZIAWUDBAIBBQCggYQwGAYKKwYB
# BAGCNwIBDDEKMAigAoAAoQKAADAZBgkqhkiG9w0BCQMxDAYKKwYBBAGCNwIBBDAc
# BgorBgEEAYI3AgELMQ4wDAYKKwYBBAGCNwIBFTAvBgkqhkiG9w0BCQQxIgQgSePB
# EuXZ99i1KZu4fETa1N/K3SluJLs3HUrT4ZGyvikwDQYJKoZIhvcNAQEBBQAEggIA
# bvdzUX9uctMsq6K9seU2hAcyVVkboe+XY+n6jQp7Ark9dt7gLZOs0cx131LUwxCf
# ADkIytxU23AyOy3n4OAyznzuuTpq8ESLj2KzQs9Ma2+uR8aji+p/surewdYISNRq
# Zji4SsI4DxIgHo31LWPsnUMESq1ORcFbhHmW/3h5UUPYQzlWxBGdsjZ7B1CDN8hm
# VIpphJgBn2VwWA9WXpYAHsca/jyaR3q4sSpj22T9kV8j7+gWk05LSeVNqGamwvuL
# ReIpaIQF2zHJnYJGocIIxKbGOEcq4Y4xRDjYRm+xBUMP/MiSYaIBqQ1N2PbWadE+
# iHxD85tu5T27u50qXoL22T7x6CEpmUdrHLpuuAF+qwB96zrB0KPHzXmSYgIhLQUv
# hDHywDWlLh8gmVPwVJaXoZgFAJsAnu4MmL6nX1d0rnckeOZs1wFu7Zs+JarOWnFU
# fawYfUWn61EesOSST/aXNleJdxKZ1MLfooc1tFOu/bSEmThox7Rnt+Y2s/GpGh6X
# dPzqB7ERKvOlu7MYbNwXTiu9FJ6pv41jDU/UuWel6Qk0ZVO+k54dZFo7MjWOtYv0
# zcIWSBInlbtrAZwKaV8p3PR1PXT18tsUcv6YjYd+X/cw01C/rJ1sMevmM/Tqqn2U
# wO+CPplJ4DPt6M7lo06lh2LZNsDXeBNlh3JdqZVNyM2hggMgMIIDHAYJKoZIhvcN
# AQkGMYIDDTCCAwkCAQEwdzBjMQswCQYDVQQGEwJVUzEXMBUGA1UEChMORGlnaUNl
# cnQsIEluYy4xOzA5BgNVBAMTMkRpZ2lDZXJ0IFRydXN0ZWQgRzQgUlNBNDA5NiBT
# SEEyNTYgVGltZVN0YW1waW5nIENBAhALrma8Wrp/lYfG+ekE4zMEMA0GCWCGSAFl
# AwQCAQUAoGkwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUx
# DxcNMjQxMjE5MDg1NTEyWjAvBgkqhkiG9w0BCQQxIgQgNbqy1I/nTY2+VuiOpDNu
# iEC7J8YG5jR/copYWXdacGYwDQYJKoZIhvcNAQEBBQAEggIAeRZKjqEjej/eNG2j
# faSwPjR5dwwMpN8XWum3oRUCBGcHlbIkIhxY5JLCjTd6ccQz/2WabERqlzeJ4khp
# 2LkMDG52x/GxNkY512l5s3GkerBZOCZOCKRQsiMw32gswpaezNKf1jx14ATZUhjo
# B0vD+dX8KjCLyvwkCS41SQkhM/SLOjEPulhnzTP8XEmazRy285CZ9yR5RyCTpTge
# opl9pmPbJS7vobMqFArU0nT4K++6VRhldL4ArDYki0XfoBREypBP26xpJ1+Ndcq6
# VHHxhOO5xwRRxKdqY1qir8vgsPjmW5Z3blZN96crXaQCJwalzS0dLdV6GsKcK3td
# FAOjQk3vplgJs71WNI3dTsxqIWqAIP1T/S5N66fZS2RKq1CJxYiQX3MkEgIK8Jg/
# d+3+sLnD6ANIryqEDITyWT02jxFX0IqUT5iseWI13B/8kYdQkHPoYymd1DHETfdi
# JdHvZjAEgpaFNy/e0y2odlhJOQopjcI6olHQ85R88U4CNtKgC/skqzhAA2s3YhFa
# gqX6X41OJfB5w6LaiqfNEUi1wAnhyXJ5sJ4TdeHgmsrYcCcWExZqBS6snOKYTlWb
# +D5n+++1c6hm2KapiylkZ6ADRBpn4Tfk2bknryO3oMluCV8luVCCxGmuJh2equTE
# V/Nem1+sKZI8eDgcmTCdzVGXE+c=
# SIG # End signature block