AzSK.ADO

1.3.0

Framework/Abstracts/CommandBase.ps1

                                <#

.Description

    Base class for all command classes. 

    Provides functionality to fire events/operations at command levels like command started, 

    command completed and perform operation like generate run-identifier, invoke auto module update, 

    open log folder at the end of commmand execution etc

#>

using namespace System.Management.Automation

Set-StrictMode -Version Latest

class CommandBase: AzSKRoot {

    #Region: Properties 

    [string[]] $FilterTags = @();

    [bool] $DoNotOpenOutputFolder = $false;

    [bool] $Force = $false

    #EndRegion

    #Region: Constructor 

    CommandBase([string] $subscriptionId, [InvocationInfo] $invocationContext):

    Base($subscriptionId) {

        [Helpers]::AbstractClass($this, [CommandBase]);

        if (-not $invocationContext) {

            throw [System.ArgumentException] ("The argument 'invocationContext' is null. Pass the `$PSCmdlet.MyInvocation from PowerShell command.");

        }

        $this.InvocationContext = $invocationContext;

        #Validate if privacy is accepted by user

        #Ensure that AzSKSettings statics are setup at this point (before calling Privacy notice)

        [AzSKSettings]::InitContexts($this.SubscriptionContext, $this.InvocationContext);

        [PrivacyNotice]::ValidatePrivacyAcceptance()

        #Initialize common parameter sets

        if($null -ne $this.InvocationContext.BoundParameters["DoNotOpenOutputFolder"])

        {

            $this.DoNotOpenOutputFolder = $this.InvocationContext.BoundParameters["DoNotOpenOutputFolder"];

        }

        if($null -ne $this.InvocationContext.BoundParameters["Force"])

        {

            $this.Force = $this.InvocationContext.BoundParameters["Force"];

        }

        #Check multiple AzSK* module should not be loaded in same session

        $this.CheckMultipleAzSKModuleLoaded();    

    }

    #EndRegion

    #Region: Command level listerner events 

    [void] CommandStarted() {

        $this.PublishAzSKRootEvent([AzSKRootEvent]::CommandStarted, $this.CheckModuleVersion());

    }

    [void] PostCommandStartedAction()

    {

    }

    [void] CommandError([System.Management.Automation.ErrorRecord] $exception) {

        [AzSKRootEventArgument] $arguments = $this.CreateRootEventArgumentObject();

        $arguments.ExceptionMessage = $exception;

        $this.PublishEvent([AzSKRootEvent]::CommandError, $arguments);

    }

    [void] CommandCompleted([MessageData[]] $messages) {

        $this.PublishAzSKRootEvent([AzSKRootEvent]::CommandCompleted, $messages);

    }

    [void] CommandProgress([int] $totalItems, [int] $currentItem) {

        $this.CommandProgress($totalItems, $currentItem, 1);

    }

    [void] CommandProgress([int] $totalItems, [int] $currentItem, [int] $granularity) {

        if ($totalItems -gt 0) {

            # $granularity indicates the number of items after which percentage progress will be printed

            # Set the max granularity to total items

            if ($granularity -gt $totalItems) {

                $granularity = $totalItems;

            }

            # Conditions for posting progress: 0%, 100% and based on granularity

            if ($currentItem -eq 0 -or $currentItem -eq $totalItems -or (($currentItem % $granularity) -eq 0)) {

                $this.PublishCustomMessage("$([int](($currentItem / $totalItems) * 100))% Completed");

            }

        }

    }

    # Dummy function declaration to define the function signature

    [void] PostCommandCompletedAction([SVTEventContext[]] $arguments)

    { }

    [void] PostCommandCompletedAction([MessageData[]] $messages)

    { }

    #EndRegion

    #Region: Helper function to invoke function based on method name. 

    # This is method called from command(GRS/GSS etc) files and resposinble for printing command start/end messages using listeners  

    [string] InvokeFunction([PSMethod] $methodToCall) {

        return $this.InvokeFunction($methodToCall, @());

    }

    [string] InvokeFunction([PSMethod] $methodToCall, [System.Object[]] $arguments) {

        if (-not $methodToCall) {

            throw [System.ArgumentException] ("The argument 'methodToCall' is null. Pass the reference of method to call. e.g.: [YourClass]::new().YourMethod");

        }

        #if attestation then rescan the controls

        if ($null -eq $arguments)

        {

            $folderPath = $this.GetOutputFolderPath();

            $methodResult = $methodToCall.Invoke(@());

            #$this.CommandCompleted($methodResult); this will update CSV but issue is there will be duplicate entries

            if(-not $this.DoNotOpenOutputFolder) {

                if (Test-Path $folderPath) {

                    Invoke-Item -Path $folderPath;

                }

            }

        }

        else {

        # Publish runidentifier(YYYYMMDD_HHMMSS) used by all listener as identifier for scan,creating log folder 

        $this.PublishRunIdentifier($this.InvocationContext);

        # <TODO Framework: Move command time calculation methods to AIOrgTelmetry Listener>

        [AIOrgTelemetryHelper]::TrackCommandExecution("Command Started",

            @{"RunIdentifier" = $this.RunIdentifier}, @{}, $this.InvocationContext);

        $sw = [System.Diagnostics.Stopwatch]::StartNew();

        # Publish command init events

        $this.CommandStarted();

        $this.PostCommandStartedAction();

        # Invoke method with arguments

        $methodResult = @();

        try {

           $methodResult = $methodToCall.Invoke($arguments);

        }

        catch {

            # Unwrapping the first layer of exception which is added by Invoke function

            [AIOrgTelemetryHelper]::TrackCommandExecution("Command Errored",

                @{"RunIdentifier" = $this.RunIdentifier; "ErrorRecord"= $_.Exception.InnerException.ErrorRecord},

                @{"TimeTakenInMs" = $sw.ElapsedMilliseconds; "SuccessCount" = 0},

                $this.InvocationContext);

            $this.CommandError($_.Exception.InnerException.ErrorRecord);

        }

        $folderPath = $this.GetOutputFolderPath();

        #the next two bug log classes have been called here as we need all the control results at one place for

        #dumping them in json file and auto closing them(to minimize api calls and auto close them in batches)

        #if bug logging is enabled and path is valid, create the JSON file for bugs

        if($this.InvocationContext.BoundParameters["AutoBugLog"] -and [BugLogPathManager]::GetIsPathValid()){

            if (([PartialScanManager]::ControlResultsWithBugSummary| Measure-Object).Count -gt 0)

            {

                $methodResult = [PartialScanManager]::ControlResultsWithBugSummary

            }

            [PublishToJSON]::new($methodResult,$folderPath)

        }

        #auto close passed bugs

        if($this.InvocationContext.BoundParameters["AutoBugLog"]){

            if (([PartialScanManager]::ControlResultsWithBugSummary| Measure-Object).Count -gt 0)

            {

                $methodResult = [PartialScanManager]::ControlResultsWithBugSummary

            }

            #call the AutoCloseBugManager

            $AutoClose=[AutoCloseBugManager]::new($this.SubscriptionContext.SubscriptionName);

            $AutoClose.AutoCloseBug($methodResult)

        }

        # Publish command complete events

        $this.CommandCompleted($methodResult);

        [AIOrgTelemetryHelper]::TrackCommandExecution("Command Completed",

            @{"RunIdentifier" = $this.RunIdentifier},

            @{"TimeTakenInMs" = $sw.ElapsedMilliseconds; "SuccessCount" = 1},

            $this.InvocationContext)

        $this.PostCommandCompletedAction($methodResult);

        # <TODO Framework: Move PDF generation method based on listener>

        #Generate PDF report

        $GeneratePDFReport = $this.InvocationContext.BoundParameters["GeneratePDF"];

        try {

            if (-not [string]::IsNullOrEmpty($folderpath)) {

                switch ($GeneratePDFReport) {

                    None {

                        # Do nothing

                    }

                    Landscape {

                        [AzSKPDFExtension]::GeneratePDF($folderpath, $this.SubscriptionContext, $this.InvocationContext, $true);

                    }

                    Portrait {

                        [AzSKPDFExtension]::GeneratePDF($folderpath, $this.SubscriptionContext, $this.InvocationContext, $false);

                    }

                }

            }

        }

        catch {

            # Unwrapping the first layer of exception which is added by Invoke function

            $this.CommandError($_);

        }

        # 

        $AttestControlParamFound = $this.InvocationContext.BoundParameters["AttestControls"];

        if($null -eq $AttestControlParamFound)

        {

            #If controls are attested then open folder when rescan of attested controls is complete

            $controlAttested = $false

            if( ([FeatureFlightingManager]::GetFeatureStatus("EnableScanAfterAttestation","*"))) { 

                #Global variable "AttestationValue" is set to true when one or more controls are attested in current scan

                #Ignore if variable AttestationValue is not found

                if (Get-Variable AttestationValue -Scope Global -ErrorAction Ignore){

                    if ( $Global:AttestationValue){

                        $controlAttested = $true

                    }

                }

            }

            if ( !$controlAttested){

            if((-not $this.DoNotOpenOutputFolder) -and (-not [string]::IsNullOrEmpty($folderPath)))

            {

                try

                {

                    Invoke-Item -Path $folderPath;

                }

                catch

                {

                    #ignore if any exception occurs

                }

            }

        }

    }

    }

        return $folderPath;

    }

    #EndRegion

    # Function to get output log folder from WriteFolder listener 

    [string] GetOutputFolderPath() {

        return [WriteFolderPath]::GetInstance().FolderPath;

    }

    # <TODO Framework: Move to module helper class>

    # Function to validate module version based on Org policy and showcase warning for update or block commands if version is less than last two minor version

    [void] CheckModuleVersion() {

        $serverVersion = [System.Version] ([ConfigurationManager]::GetAzSKConfigData().GetLatestAzSKVersion($this.GetModuleName()));

        $currentModuleVersion = [System.Version] $this.GetCurrentModuleVersion() 

        if($currentModuleVersion -ne "0.0.0.0" -and $currentModuleVersion -ne "1.0.0.0" -and $serverVersion -gt $currentModuleVersion) {

            $this.RunningLatestPSModule = $false;

            $this.InvokeAutoUpdate()

            $this.PublishCustomMessage(([Constants]::VersionCheckMessage -f $serverVersion), [MessageType]::Warning);

            $this.PublishCustomMessage(([ConfigurationManager]::GetAzSKConfigData().InstallationCommand + "`r`n"), [MessageType]::Update);

            $this.PublishCustomMessage([Constants]::VersionWarningMessage, [MessageType]::Warning);

            $serverVersions = @()

            [ConfigurationManager]::GetAzSKConfigData().GetAzSKVersionList($this.GetModuleName()) | ForEach-Object { 

                #Take major and minor version and ignore build version for comparision

               $serverVersions+= [System.Version] ("$($_.Major)" +"." + "$($_.Minor)")

             }            

            $serverVersions =  $serverVersions | Select-Object -Unique

            $latestVersionList = $serverVersions | Where-Object {$_ -gt $currentModuleVersion}

            if(($latestVersionList | Measure-Object).Count -gt [ConfigurationManager]::GetAzSKConfigData().BackwardCompatibleVersionCount)

            {

                throw ([SuppressedException]::new(("Your version of $([Constants]::AzSKModuleName) is too old. Please update now!"),[SuppressedExceptionType]::Generic))

            }

        }

        $psGalleryVersion = [System.Version] ([ConfigurationManager]::GetAzSKConfigData().GetAzSKLatestPSGalleryVersion($this.GetModuleName()));            

        if($psGalleryVersion -ne $serverVersion)

        {

            $serverVersions = @()

            [ConfigurationManager]::GetAzSKConfigData().GetAzSKVersionList($this.GetModuleName()) | ForEach-Object { 

                #Take major and minor version and ignore build version for comparision

               $serverVersions+= [System.Version] ("$($_.Major)" +"." + "$($_.Minor)")

             }            

            $serverVersions =  $serverVersions | Select-Object -Unique

            $latestVersionAvailableFromGallery = $serverVersions | Where-Object {$_ -gt $serverVersion}

            if(($latestVersionAvailableFromGallery | Measure-Object).Count -gt [ConfigurationManager]::GetAzSKConfigData().BackwardCompatibleVersionCount)

            {

                $this.PublishCustomMessage("Your Org AzSK.ADO version [$serverVersion] is too old. It must be updated to latest available version [$psGalleryVersion].",[MessageType]::Error);

            }

        }

        #Validate if detailed scan results is required in control evaluation

        $this.CheckDetailedScanStatus();

    }

    # <TODO Framework: Move to module helper class>

    # Funtion to execute module auto update flow based on switch

    [void] InvokeAutoUpdate()

    {

        $AutoUpdateSwitch= [ConfigurationManager]::GetAzSKSettings().AutoUpdateSwitch;

        $AutoUpdateCommand = [ConfigurationManager]::GetAzSKSettings().AutoUpdateCommand;

        if($AutoUpdateSwitch -ne [AutoUpdate]::On)

        {

            if($AutoUpdateSwitch -eq [AutoUpdate]::NotSet)

            {

                $AutoUpdateMsg = [Constants]::AutoUpdateMessage 

                Write-Host $AutoUpdateMsg -ForegroundColor Yellow

            }

            return;

        }

        #Step 1: Get the list of active running powershell prcesses including the current running PS Session

        $PSProcesses = Get-Process | Where-Object { ($_.Name -eq 'powershell' -or $_.Name -eq 'powershell_ise' -or $_.Name -eq 'powershelltoolsprocesshost')}

        $userChoice = ""

        if(($PSProcesses | Measure-Object).Count -ge 1)

        {            

            Write-Host([Constants]::ModuleAutoUpdateAvailableMsg) -ForegroundColor Cyan;

        }

        #User choice that captures the decision to close the active PS Sessions

        $secondUserChoice =""

        $InvalidOption = $true;

        while($InvalidOption)

        {

            if([string]::IsNullOrWhiteSpace($userChoice) -or ($userChoice.Trim() -ne 'y' -and $userChoice.Trim() -ne 'n'))

            {

                $userChoice = Read-Host "Continue (Y/N)"

                if([string]::IsNullOrWhiteSpace($userChoice) -or ($userChoice.Trim() -ne 'y' -and $userChoice.Trim() -ne 'n'))

                {

                    Write-Host "Enter the valid option." -ForegroundColor Yellow

                }

                continue;

            }

            elseif($userChoice.Trim() -eq 'n')

            {

                $InvalidOption = $false;

            }

            elseif($userChoice.Trim() -eq 'y')

            {

                #Get the number of PS active sessions

                $PSProcesses = Get-Process | Where-Object { ($_.Name -eq 'powershell' -or $_.Name -eq 'powershell_ise' -or $_.Name -eq 'powershelltoolsprocesshost') -and $_.Id -ne $PID}

                if(($PSProcesses | Measure-Object).Count -gt 0)

                {

                    Write-Host "`nThe following other PS sessions are still active. Please save your work and close them. You can also use Task Manager to close these sessions." -ForegroundColor Yellow

                    Write-Host ($PSProcesses | Select-Object Id, ProcessName, Path | Out-String)

                    $secondUserChoice = Read-Host "Continue (Y/N)"

                }

                elseif(($PSProcesses | Measure-Object).Count -eq 0)

                {

                    Write-Host "`nThe current PS session will be closed now. Have you saved your work?" -ForegroundColor Yellow

                    $secondUserChoice = Read-Host "Continue (Y/N)"

                }

                if(-not [string]::IsNullOrWhiteSpace($secondUserChoice) -and `

                (($PSProcesses | Measure-Object).Count -eq 0 -and $secondUserChoice.Trim() -eq 'y') -or `

                $secondUserChoice.Trim() -eq 'n')

                {

                    $InvalidOption = $false;

                }

            }

        }

        #Check if the first user want to continue with auto-update using userChoice field and then check if user still wants to continue with auto-update after finding the active PS sessions.

        #In either case it is no it would exit the auto-update process

        if($userChoice.Trim() -eq "n" -or $secondUserChoice.Trim() -eq 'n')

        {            

            Write-Host "Exiting auto-update workflow. To disable auto-update permanently, run the command below:" -ForegroundColor Yellow

            Write-Host "Set-AzSKADOPolicySettings -AutoUpdate Off`n" -ForegroundColor Green

            return

        }

        $AzSKTemp = Join-Path $([Constants]::AzSKAppFolderPath) "Temp";

        try

        {

            $fileName = "au_" + $(get-date).ToUniversalTime().ToString("yyyyMMdd_HHmmss") + ".ps1";

            $autoUpdateContent = [ConfigurationHelper]::LoadOfflineConfigFile("ModuleAutoUpdate.ps1");

            if(-not (Test-Path -Path $AzSKTemp))

            {

                New-Item -Path $AzSKTemp -ItemType Directory -Force

            }

            Remove-Item -Path (Join-Path $AzSKTemp "au_*") -Force -Recurse -ErrorAction SilentlyContinue

            $autoUpdateContent = $autoUpdateContent.Replace("##installurl##",$AutoUpdateCommand);

            $autoUpdateContent | Out-File (Join-Path $AzSKTemp $fileName) -Force

            Start-Process -WindowStyle Normal -FilePath "powershell.exe" -ArgumentList (Join-Path $AzSKTemp $fileName)

        }

        catch

        {

            $this.CommandError($_.Exception.InnerException.ErrorRecord);

        }

    }

    [void] CheckMultipleAzSKModuleLoaded(){

        $loadedAzSKModules= Get-Module | Where-Object { $_.Name -like "AzSK*"};

        if($env:AzSKSkipMultiModuleCheck -ne $true -and $null -ne $loadedAzSKModules -and ($loadedAzSKModules| Measure-Object).Count -gt 1){

            throw [SuppressedException]::new("ERROR: Multiple AzSK modules loaded in same session, this will lead to issues when running AzSK cmdlets.",[SuppressedExceptionType]::Generic)

        }

    }

    [void] CheckDetailedScanStatus(){

        if(-not([string]::IsNullOrEmpty($this.InvocationContext.BoundParameters['ControlIds'])) -or -not([string]::IsNullOrEmpty($this.InvocationContext.BoundParameters['DetailedScan'])) -or  -not( [string]::IsNullOrEmpty($this.InvocationContext.BoundParameters['ControlsToAttest']))  )

        {

            [AzSKRoot]::IsDetailedScanRequired = $true

        }

        else {

            [AzSKRoot]::IsDetailedScanRequired = $false

        }

    }

}

# SIG # Begin signature block

# MIIjlAYJKoZIhvcNAQcCoIIjhTCCI4ECAQExDzANBglghkgBZQMEAgEFADB5Bgor

# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG

# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCBukTbDWkNnlj2J

# CoYcdpXwIKILP0NHgyXT+LWcZqA9q6CCDYEwggX/MIID56ADAgECAhMzAAABh3IX

# chVZQMcJAAAAAAGHMA0GCSqGSIb3DQEBCwUAMH4xCzAJBgNVBAYTAlVTMRMwEQYD

# VQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01pY3Jvc29mdCBDb2RlIFNpZ25p

# bmcgUENBIDIwMTEwHhcNMjAwMzA0MTgzOTQ3WhcNMjEwMzAzMTgzOTQ3WjB0MQsw

# CQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9u

# ZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMR4wHAYDVQQDExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB

# AQDOt8kLc7P3T7MKIhouYHewMFmnq8Ayu7FOhZCQabVwBp2VS4WyB2Qe4TQBT8aB

# znANDEPjHKNdPT8Xz5cNali6XHefS8i/WXtF0vSsP8NEv6mBHuA2p1fw2wB/F0dH

# sJ3GfZ5c0sPJjklsiYqPw59xJ54kM91IOgiO2OUzjNAljPibjCWfH7UzQ1TPHc4d

# weils8GEIrbBRb7IWwiObL12jWT4Yh71NQgvJ9Fn6+UhD9x2uk3dLj84vwt1NuFQ

# itKJxIV0fVsRNR3abQVOLqpDugbr0SzNL6o8xzOHL5OXiGGwg6ekiXA1/2XXY7yV

# Fc39tledDtZjSjNbex1zzwSXAgMBAAGjggF+MIIBejAfBgNVHSUEGDAWBgorBgEE

# AYI3TAgBBggrBgEFBQcDAzAdBgNVHQ4EFgQUhov4ZyO96axkJdMjpzu2zVXOJcsw

# UAYDVR0RBEkwR6RFMEMxKTAnBgNVBAsTIE1pY3Jvc29mdCBPcGVyYXRpb25zIFB1

# ZXJ0byBSaWNvMRYwFAYDVQQFEw0yMzAwMTIrNDU4Mzg1MB8GA1UdIwQYMBaAFEhu

# ZOVQBdOCqhc3NyK1bajKdQKVMFQGA1UdHwRNMEswSaBHoEWGQ2h0dHA6Ly93d3cu

# bWljcm9zb2Z0LmNvbS9wa2lvcHMvY3JsL01pY0NvZFNpZ1BDQTIwMTFfMjAxMS0w

# Ny0wOC5jcmwwYQYIKwYBBQUHAQEEVTBTMFEGCCsGAQUFBzAChkVodHRwOi8vd3d3

# Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2NlcnRzL01pY0NvZFNpZ1BDQTIwMTFfMjAx

# MS0wNy0wOC5jcnQwDAYDVR0TAQH/BAIwADANBgkqhkiG9w0BAQsFAAOCAgEAixmy

# S6E6vprWD9KFNIB9G5zyMuIjZAOuUJ1EK/Vlg6Fb3ZHXjjUwATKIcXbFuFC6Wr4K

# NrU4DY/sBVqmab5AC/je3bpUpjtxpEyqUqtPc30wEg/rO9vmKmqKoLPT37svc2NV

# BmGNl+85qO4fV/w7Cx7J0Bbqk19KcRNdjt6eKoTnTPHBHlVHQIHZpMxacbFOAkJr

# qAVkYZdz7ikNXTxV+GRb36tC4ByMNxE2DF7vFdvaiZP0CVZ5ByJ2gAhXMdK9+usx

# zVk913qKde1OAuWdv+rndqkAIm8fUlRnr4saSCg7cIbUwCCf116wUJ7EuJDg0vHe

# yhnCeHnBbyH3RZkHEi2ofmfgnFISJZDdMAeVZGVOh20Jp50XBzqokpPzeZ6zc1/g

# yILNyiVgE+RPkjnUQshd1f1PMgn3tns2Cz7bJiVUaqEO3n9qRFgy5JuLae6UweGf

# AeOo3dgLZxikKzYs3hDMaEtJq8IP71cX7QXe6lnMmXU/Hdfz2p897Zd+kU+vZvKI

# 3cwLfuVQgK2RZ2z+Kc3K3dRPz2rXycK5XCuRZmvGab/WbrZiC7wJQapgBodltMI5

# GMdFrBg9IeF7/rP4EqVQXeKtevTlZXjpuNhhjuR+2DMt/dWufjXpiW91bo3aH6Ea

# jOALXmoxgltCp1K7hrS6gmsvj94cLRf50QQ4U8Qwggd6MIIFYqADAgECAgphDpDS

# AAAAAAADMA0GCSqGSIb3DQEBCwUAMIGIMQswCQYDVQQGEwJVUzETMBEGA1UECBMK

# V2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0

# IENvcnBvcmF0aW9uMTIwMAYDVQQDEylNaWNyb3NvZnQgUm9vdCBDZXJ0aWZpY2F0

# ZSBBdXRob3JpdHkgMjAxMTAeFw0xMTA3MDgyMDU5MDlaFw0yNjA3MDgyMTA5MDla

# MH4xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdS

# ZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMT

# H01pY3Jvc29mdCBDb2RlIFNpZ25pbmcgUENBIDIwMTEwggIiMA0GCSqGSIb3DQEB

# AQUAA4ICDwAwggIKAoICAQCr8PpyEBwurdhuqoIQTTS68rZYIZ9CGypr6VpQqrgG

# OBoESbp/wwwe3TdrxhLYC/A4wpkGsMg51QEUMULTiQ15ZId+lGAkbK+eSZzpaF7S

# 35tTsgosw6/ZqSuuegmv15ZZymAaBelmdugyUiYSL+erCFDPs0S3XdjELgN1q2jz

# y23zOlyhFvRGuuA4ZKxuZDV4pqBjDy3TQJP4494HDdVceaVJKecNvqATd76UPe/7

# 4ytaEB9NViiienLgEjq3SV7Y7e1DkYPZe7J7hhvZPrGMXeiJT4Qa8qEvWeSQOy2u

# M1jFtz7+MtOzAz2xsq+SOH7SnYAs9U5WkSE1JcM5bmR/U7qcD60ZI4TL9LoDho33

# X/DQUr+MlIe8wCF0JV8YKLbMJyg4JZg5SjbPfLGSrhwjp6lm7GEfauEoSZ1fiOIl

# XdMhSz5SxLVXPyQD8NF6Wy/VI+NwXQ9RRnez+ADhvKwCgl/bwBWzvRvUVUvnOaEP

# 6SNJvBi4RHxF5MHDcnrgcuck379GmcXvwhxX24ON7E1JMKerjt/sW5+v/N2wZuLB

# l4F77dbtS+dJKacTKKanfWeA5opieF+yL4TXV5xcv3coKPHtbcMojyyPQDdPweGF

# RInECUzF1KVDL3SV9274eCBYLBNdYJWaPk8zhNqwiBfenk70lrC8RqBsmNLg1oiM

# CwIDAQABo4IB7TCCAekwEAYJKwYBBAGCNxUBBAMCAQAwHQYDVR0OBBYEFEhuZOVQ

# BdOCqhc3NyK1bajKdQKVMBkGCSsGAQQBgjcUAgQMHgoAUwB1AGIAQwBBMAsGA1Ud

# DwQEAwIBhjAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFHItOgIxkEO5FAVO

# 4eqnxzHRI4k0MFoGA1UdHwRTMFEwT6BNoEuGSWh0dHA6Ly9jcmwubWljcm9zb2Z0

# LmNvbS9wa2kvY3JsL3Byb2R1Y3RzL01pY1Jvb0NlckF1dDIwMTFfMjAxMV8wM18y

# Mi5jcmwwXgYIKwYBBQUHAQEEUjBQME4GCCsGAQUFBzAChkJodHRwOi8vd3d3Lm1p

# Y3Jvc29mdC5jb20vcGtpL2NlcnRzL01pY1Jvb0NlckF1dDIwMTFfMjAxMV8wM18y

# Mi5jcnQwgZ8GA1UdIASBlzCBlDCBkQYJKwYBBAGCNy4DMIGDMD8GCCsGAQUFBwIB

# FjNodHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2RvY3MvcHJpbWFyeWNw

# cy5odG0wQAYIKwYBBQUHAgIwNB4yIB0ATABlAGcAYQBsAF8AcABvAGwAaQBjAHkA

# XwBzAHQAYQB0AGUAbQBlAG4AdAAuIB0wDQYJKoZIhvcNAQELBQADggIBAGfyhqWY

# 4FR5Gi7T2HRnIpsLlhHhY5KZQpZ90nkMkMFlXy4sPvjDctFtg/6+P+gKyju/R6mj

# 82nbY78iNaWXXWWEkH2LRlBV2AySfNIaSxzzPEKLUtCw/WvjPgcuKZvmPRul1LUd

# d5Q54ulkyUQ9eHoj8xN9ppB0g430yyYCRirCihC7pKkFDJvtaPpoLpWgKj8qa1hJ

# Yx8JaW5amJbkg/TAj/NGK978O9C9Ne9uJa7lryft0N3zDq+ZKJeYTQ49C/IIidYf

# wzIY4vDFLc5bnrRJOQrGCsLGra7lstnbFYhRRVg4MnEnGn+x9Cf43iw6IGmYslmJ

# aG5vp7d0w0AFBqYBKig+gj8TTWYLwLNN9eGPfxxvFX1Fp3blQCplo8NdUmKGwx1j

# NpeG39rz+PIWoZon4c2ll9DuXWNB41sHnIc+BncG0QaxdR8UvmFhtfDcxhsEvt9B

# xw4o7t5lL+yX9qFcltgA1qFGvVnzl6UJS0gQmYAf0AApxbGbpT9Fdx41xtKiop96

# eiL6SJUfq/tHI4D1nvi/a7dLl+LrdXga7Oo3mXkYS//WsyNodeav+vyL6wuA6mk7

# r/ww7QRMjt/fdW1jkT3RnVZOT7+AVyKheBEyIXrvQQqxP/uozKRdwaGIm1dxVk5I

# RcBCyZt2WwqASGv9eZ/BvW1taslScxMNelDNMYIVaTCCFWUCAQEwgZUwfjELMAkG

# A1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQx

# HjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEoMCYGA1UEAxMfTWljcm9z

# b2Z0IENvZGUgU2lnbmluZyBQQ0EgMjAxMQITMwAAAYdyF3IVWUDHCQAAAAABhzAN

# BglghkgBZQMEAgEFAKCBsDAZBgkqhkiG9w0BCQMxDAYKKwYBBAGCNwIBBDAcBgor

# BgEEAYI3AgELMQ4wDAYKKwYBBAGCNwIBFTAvBgkqhkiG9w0BCQQxIgQgkLkUBt5Y

# 5D9P8QbrsvzIJVG/RalfrjQhq999K3pLsswwRAYKKwYBBAGCNwIBDDE2MDSgFIAS

# AE0AaQBjAHIAbwBzAG8AZgB0oRyAGmh0dHBzOi8vd3d3Lm1pY3Jvc29mdC5jb20g

# MA0GCSqGSIb3DQEBAQUABIIBAAJJDTpPGk/qj3UfuN9+aa+paCOsKX1TgFkluLJ3

# z5oXxNhnT1PGIbg6nIWCKqtEV3y5n035KvU0VTltp7Zx8hJKKwUu4MOcL7vFwbs0

# 9JFG35iHlrio0X6g7th7dNYTWVEz2YKzHN66vK3rzs6i1DNZNnTe83Gnjl3Yc9mS

# szvAodZ9LIVWwoGTuJeGaWZajUhFAkCu4Y/l+XH0PyDv7G4WYH3TVgqZw5GSZeH6

# lHtFxGCexm8o7jHj0mazgcHVWTZlvOPs/BOsgmGU5bACwOqb9AstfefbrN8zLxK+

# PMaTR3ilfGYwp0eeHyNnbQvBTvB1W5rrgIZ2yVVeNyFQSFyhghLxMIIS7QYKKwYB

# BAGCNwMDATGCEt0wghLZBgkqhkiG9w0BBwKgghLKMIISxgIBAzEPMA0GCWCGSAFl

# AwQCAQUAMIIBVQYLKoZIhvcNAQkQAQSgggFEBIIBQDCCATwCAQEGCisGAQQBhFkK

# AwEwMTANBglghkgBZQMEAgEFAAQgQLR05Tr/wZytBMycVxpICTLGde0X24KmkHM8

# +jrZepMCBl/bmBlEnRgTMjAyMTAxMTUxMzQ0NTEuMzczWjAEgAIB9KCB1KSB0TCB

# zjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1Jl

# ZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEpMCcGA1UECxMg

# TWljcm9zb2Z0IE9wZXJhdGlvbnMgUHVlcnRvIFJpY28xJjAkBgNVBAsTHVRoYWxl

# cyBUU1MgRVNOOkQ5REUtRTM5QS00M0ZFMSUwIwYDVQQDExxNaWNyb3NvZnQgVGlt

# ZS1TdGFtcCBTZXJ2aWNloIIORDCCBPUwggPdoAMCAQICEzMAAAEtLk1BymNlM6AA

# AAAAAS0wDQYJKoZIhvcNAQELBQAwfDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldh

# c2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBD

# b3Jwb3JhdGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUtU3RhbXAgUENBIDIw

# MTAwHhcNMTkxMjE5MDExNTA0WhcNMjEwMzE3MDExNTA0WjCBzjELMAkGA1UEBhMC

# VVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNV

# BAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEpMCcGA1UECxMgTWljcm9zb2Z0IE9w

# ZXJhdGlvbnMgUHVlcnRvIFJpY28xJjAkBgNVBAsTHVRoYWxlcyBUU1MgRVNOOkQ5

# REUtRTM5QS00M0ZFMSUwIwYDVQQDExxNaWNyb3NvZnQgVGltZS1TdGFtcCBTZXJ2

# aWNlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqWGN9HVJOphFNLez

# SLiMhxIxX4bg3ShiDCVAr6mXgNUwWavWJNkcUuPdO3tXoX4z8FfHSH2LS67XIGeo

# Ko06S4kRFNtWczi7cm9HHOxB8KMF+oP8I3Cgw16SjKUgHPE/nRKSOnWk+ydAEodo

# I/y2C69hXOhNDnirZWlgQ//45hNB4Q+pYWLxaCC+xyS56txQaSFhYzwNX/glTs3+

# tsOu1qZht7wu2RWJNBhuKBRIICiv0OG0Bm+rwDQDvdcUfZ1/bAOUu0CcoJyxW9dK

# ZnflsCqd43i4RBXLw1B1F4YjW0jpTGgLteeMa8rgxwN0qFq80nsMCdI/n4b8NOR1

# YP6U3wIDAQABo4IBGzCCARcwHQYDVR0OBBYEFNlsZHxCASH4Tg6K/y9DvjTynYbN

# MB8GA1UdIwQYMBaAFNVjOlyKMZDzQ3t8RhvFM2hahW1VMFYGA1UdHwRPME0wS6BJ

# oEeGRWh0dHA6Ly9jcmwubWljcm9zb2Z0LmNvbS9wa2kvY3JsL3Byb2R1Y3RzL01p

# Y1RpbVN0YVBDQV8yMDEwLTA3LTAxLmNybDBaBggrBgEFBQcBAQROMEwwSgYIKwYB

# BQUHMAKGPmh0dHA6Ly93d3cubWljcm9zb2Z0LmNvbS9wa2kvY2VydHMvTWljVGlt

# U3RhUENBXzIwMTAtMDctMDEuY3J0MAwGA1UdEwEB/wQCMAAwEwYDVR0lBAwwCgYI

# KwYBBQUHAwgwDQYJKoZIhvcNAQELBQADggEBAH1rA2T3Tqt5wG6g7sTOrsHxQa70

# SgVeIvxpzRtuxkMFj3P/enxq1VlELEc3jdrdYZsIxmgpjFIEfpQKRwNzBch80oRt

# UzOcXWaOlAQZuqFH6s82oddmi1JX6+fzkDGZ58Azdtwu35Y0GkS45lniQ9lVwW0y

# jhjJCPGg1E+LCan4HQeSFCz+X9UiDRcljqTkVEoT8kURxVjjbno12pRn7eOi7dvg

# 4CS0Ta6uvhXpVHDV9986XFlvwzK8Tmaq9NUk5K1XEK6G6qDWsh7yVrWBnmKK4jJZ

# 5+0418zDSdJlyEYuKAN4ifDpd/DCAWcLlCXw9t/aM7EJSW4BhvPKQj4ycGIwggZx

# MIIEWaADAgECAgphCYEqAAAAAAACMA0GCSqGSIb3DQEBCwUAMIGIMQswCQYDVQQG

# EwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwG

# A1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMTIwMAYDVQQDEylNaWNyb3NvZnQg

# Um9vdCBDZXJ0aWZpY2F0ZSBBdXRob3JpdHkgMjAxMDAeFw0xMDA3MDEyMTM2NTVa

# Fw0yNTA3MDEyMTQ2NTVaMHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5n

# dG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9y

# YXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBDQSAyMDEwMIIB

# IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqR0NvHcRijog7PwTl/X6f2mU

# a3RUENWlCgCChfvtfGhLLF/Fw+Vhwna3PmYrW/AVUycEMR9BGxqVHc4JE458YTBZ

# sTBED/FgiIRUQwzXTbg4CLNC3ZOs1nMwVyaCo0UN0Or1R4HNvyRgMlhgRvJYR4Yy

# hB50YWeRX4FUsc+TTJLBxKZd0WETbijGGvmGgLvfYfxGwScdJGcSchohiq9LZIlQ

# YrFd/XcfPfBXday9ikJNQFHRD5wGPmd/9WbAA5ZEfu/QS/1u5ZrKsajyeioKMfDa

# TgaRtogINeh4HLDpmc085y9Euqf03GS9pAHBIAmTeM38vMDJRF1eFpwBBU8iTQID

# AQABo4IB5jCCAeIwEAYJKwYBBAGCNxUBBAMCAQAwHQYDVR0OBBYEFNVjOlyKMZDz

# Q3t8RhvFM2hahW1VMBkGCSsGAQQBgjcUAgQMHgoAUwB1AGIAQwBBMAsGA1UdDwQE

# AwIBhjAPBgNVHRMBAf8EBTADAQH/MB8GA1UdIwQYMBaAFNX2VsuP6KJcYmjRPZSQ

# W9fOmhjEMFYGA1UdHwRPME0wS6BJoEeGRWh0dHA6Ly9jcmwubWljcm9zb2Z0LmNv

# bS9wa2kvY3JsL3Byb2R1Y3RzL01pY1Jvb0NlckF1dF8yMDEwLTA2LTIzLmNybDBa

# BggrBgEFBQcBAQROMEwwSgYIKwYBBQUHMAKGPmh0dHA6Ly93d3cubWljcm9zb2Z0

# LmNvbS9wa2kvY2VydHMvTWljUm9vQ2VyQXV0XzIwMTAtMDYtMjMuY3J0MIGgBgNV

# HSABAf8EgZUwgZIwgY8GCSsGAQQBgjcuAzCBgTA9BggrBgEFBQcCARYxaHR0cDov

# L3d3dy5taWNyb3NvZnQuY29tL1BLSS9kb2NzL0NQUy9kZWZhdWx0Lmh0bTBABggr

# BgEFBQcCAjA0HjIgHQBMAGUAZwBhAGwAXwBQAG8AbABpAGMAeQBfAFMAdABhAHQA

# ZQBtAGUAbgB0AC4gHTANBgkqhkiG9w0BAQsFAAOCAgEAB+aIUQ3ixuCYP4FxAz2d

# o6Ehb7Prpsz1Mb7PBeKp/vpXbRkws8LFZslq3/Xn8Hi9x6ieJeP5vO1rVFcIK1GC

# RBL7uVOMzPRgEop2zEBAQZvcXBf/XPleFzWYJFZLdO9CEMivv3/Gf/I3fVo/HPKZ

# eUqRUgCvOA8X9S95gWXZqbVr5MfO9sp6AG9LMEQkIjzP7QOllo9ZKby2/QThcJ8y

# Sif9Va8v/rbljjO7Yl+a21dA6fHOmWaQjP9qYn/dxUoLkSbiOewZSnFjnXshbcOc

# o6I8+n99lmqQeKZt0uGc+R38ONiU9MalCpaGpL2eGq4EQoO4tYCbIjggtSXlZOz3

# 9L9+Y1klD3ouOVd2onGqBooPiRa6YacRy5rYDkeagMXQzafQ732D8OE7cQnfXXSY

# Ighh2rBQHm+98eEA3+cxB6STOvdlR3jo+KhIq/fecn5ha293qYHLpwmsObvsxsvY

# grRyzR30uIUBHoD7G4kqVDmyW9rIDVWZeodzOwjmmC3qjeAzLhIp9cAvVCch98is

# TtoouLGp25ayp0Kiyc8ZQU3ghvkqmqMRZjDTu3QyS99je/WZii8bxyGvWbWu3EQ8

# l1Bx16HSxVXjad5XwdHeMMD9zOZN+w2/XU/pnR4ZOC+8z1gFLu8NoFA12u8JJxzV

# s341Hgi62jbb01+P3nSISRKhggLSMIICOwIBATCB/KGB1KSB0TCBzjELMAkGA1UE

# BhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAc

# BgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEpMCcGA1UECxMgTWljcm9zb2Z0

# IE9wZXJhdGlvbnMgUHVlcnRvIFJpY28xJjAkBgNVBAsTHVRoYWxlcyBUU1MgRVNO

# OkQ5REUtRTM5QS00M0ZFMSUwIwYDVQQDExxNaWNyb3NvZnQgVGltZS1TdGFtcCBT

# ZXJ2aWNloiMKAQEwBwYFKw4DAhoDFQCfzl/Hfod7sXS+CbJSXPbDzaXQsaCBgzCB

# gKR+MHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQH

# EwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xJjAkBgNV

# BAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBDQSAyMDEwMA0GCSqGSIb3DQEBBQUA

# AgUA46uoLDAiGA8yMDIxMDExNTA5MzU0MFoYDzIwMjEwMTE2MDkzNTQwWjB3MD0G

# CisGAQQBhFkKBAExLzAtMAoCBQDjq6gsAgEAMAoCAQACAhyqAgH/MAcCAQACAhHR

# MAoCBQDjrPmsAgEAMDYGCisGAQQBhFkKBAIxKDAmMAwGCisGAQQBhFkKAwKgCjAI

# AgEAAgMHoSChCjAIAgEAAgMBhqAwDQYJKoZIhvcNAQEFBQADgYEAXzLXyVYp+kx0

# 2RcP6rMWDhQdro4CGsFGMQmOqEkXQDCqb5wC8QqJ+kZ6WEgMCUj0WbAjOZ6U0bec

# SKLk/bGFrZZY2O7UC5MmQHuEOiJFlDBCXe03sz55U5Hu2bR0MHn3rI8idoe0Nj7g

# 4eC4p5jMdRuSzQnjPmjaYP6TQTeb4VgxggMNMIIDCQIBATCBkzB8MQswCQYDVQQG

# EwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwG

# A1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMSYwJAYDVQQDEx1NaWNyb3NvZnQg

# VGltZS1TdGFtcCBQQ0EgMjAxMAITMwAAAS0uTUHKY2UzoAAAAAABLTANBglghkgB

# ZQMEAgEFAKCCAUowGgYJKoZIhvcNAQkDMQ0GCyqGSIb3DQEJEAEEMC8GCSqGSIb3

# DQEJBDEiBCBHRGoqCz2c/XfcWP8Q9UzXTWWjB0JmJD17lw/dU1m6xzCB+gYLKoZI

# hvcNAQkQAi8xgeowgecwgeQwgb0EII7xWnJyfSAHj+KVEA88NtL4KZuqP+4LTXWa

# hzmh4YPBMIGYMIGApH4wfDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0

# b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3Jh

# dGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUtU3RhbXAgUENBIDIwMTACEzMA

# AAEtLk1BymNlM6AAAAAAAS0wIgQgrO1hBkEIEmN82t9UaqeQ6TYITwgx1lqySgEl

# VRM1WL0wDQYJKoZIhvcNAQELBQAEggEADjMuYtE6nRqZfo/Ba7WDNC45Hq5tJULG

# RQKfWY2oDjeDYBM0RJ5sClsJCmPmnPqqizLbl7WS/js3uS0JZ0Qy5Xx6dWV7rT7R

# z6FQX5ap65MuZ4rpBQzM7IohDrSTrab5vqF4Slc9ZeDBQSxKWwPrafgoIc2ZqVql

# v9AhIAW1Ehrju1Sk6E8sBouH2nKUFa23hfp7M190GcoY095Zy7P+kAKL2pFQViQP

# OiAEoJ7YmYoUj4oaJc1ip72k16dTFI2gPTzfAu21JwS2ebWX2rY5NWIN0fTU784A

# ZlMDYBv9dAm1ksk65S/gUpHC+y/uguX8ivlZnXZtT2Qz76ISp1Nqkw==

# SIG # End signature block