AzSKPreview.ADO

1.13.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] $organizationName, [InvocationInfo] $invocationContext):

    Base($organizationName) {

        [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.OrganizationContext, $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

        #AutoBugLog and AutoCloseBug Conditions

        # $isPartialScan=$false

        # $bugsClosed=$null

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

            $this.sendBugInfo($methodResult,$folderPath) #sendBugInfo

        }

        #SARIF Logs generation.Note if upc with Auto Bug Log we have controls available in ControlResultsWithBugSummary static variable.

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

            $sarifMethodResults=$methodResult

            if(!$sarifMethodResults){

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

                    $sarifMethodResults=[PartialScanManager]::ControlResultsWithBugSummary

                }

                else{

                    $sarifMethodResults=[PartialScanManager]::ControlResultsWithSARIFSummary

                }

            }

            if($sarifMethodResults){

                [SARIFLogsGenerator]::new($sarifMethodResults,$folderPath,$this.RunIdentifier)

            }

            [PartialScanManager]::ControlResultsWithSARIFSummary=@()

        }

        # 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.OrganizationContext, $this.InvocationContext, $true);

                    }

                    Portrait {

                        [AzSKPDFExtension]::GeneratePDF($folderpath, $this.OrganizationContext, $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;

    }

    #Sends bug information to Json and CSV. In non upc scan closes bugs and sends info to LA as well.

    [void] sendBugInfo([SVTEventContext[]] $methodResult, [string] $folderPath){

        [SVTEventContext[]] $bugsClosed=$null

        if ($this.InvocationContext.BoundParameters["UsePartialCommits"])

        {

                $methodResult = [PartialScanManager]::ControlResultsWithBugSummary

                $bugsClosed=[PartialScanManager]::ControlResultsWithClosedBugSummary

        }

        else

        {

            $AutoClose=[AutoCloseBugManager]::new($this.OrganizationContext.OrganizationName);

            $AutoClose.AutoCloseBug($methodResult)

            $bugsClosed=[AutoCloseBugManager]::ClosedBugs

            if($bugsClosed){

                $laInstance= [LogAnalyticsOutput]::Instance

                $laInstance.WriteControlResult($bugsClosed)

            }

        }

        #If condition publishes information about New, Active and Closed bugs 

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

            if([BugLogPathManager]::GetIsPathValid()){

                [PublishToJSONAndCSV]::new($methodResult,$folderPath,$bugsClosed)

            }

        }

        #condition publishes only closed bugs. $null is passed instead of $methodResult to avoid performance slow down in PublishToJSONAndCSV

        else{

            if($bugsClosed){

                [PublishToJSONAndCSV]::new($null,$folderPath,$bugsClosed)

            }

        }

    }

    # <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

# MIIjoQYJKoZIhvcNAQcCoIIjkjCCI44CAQExDzANBglghkgBZQMEAgEFADB5Bgor

# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG

# KX7zUQIBAAIBAAIBAAIBAAIBADAxMA0GCWCGSAFlAwQCAQUABCAsDCLx4mSzrh0X

# My0wLX2Xd+jPWRDgwoW4s89nCVtfQaCCDYEwggX/MIID56ADAgECAhMzAAACUosz

# qviV8znbAAAAAAJSMA0GCSqGSIb3DQEBCwUAMH4xCzAJBgNVBAYTAlVTMRMwEQYD

# VQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24xKDAmBgNVBAMTH01pY3Jvc29mdCBDb2RlIFNpZ25p

# bmcgUENBIDIwMTEwHhcNMjEwOTAyMTgzMjU5WhcNMjIwOTAxMTgzMjU5WjB0MQsw

# CQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3RvbjEQMA4GA1UEBxMHUmVkbW9u

# ZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBvcmF0aW9uMR4wHAYDVQQDExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB

# AQDQ5M+Ps/X7BNuv5B/0I6uoDwj0NJOo1KrVQqO7ggRXccklyTrWL4xMShjIou2I

# sbYnF67wXzVAq5Om4oe+LfzSDOzjcb6ms00gBo0OQaqwQ1BijyJ7NvDf80I1fW9O

# L76Kt0Wpc2zrGhzcHdb7upPrvxvSNNUvxK3sgw7YTt31410vpEp8yfBEl/hd8ZzA

# v47DCgJ5j1zm295s1RVZHNp6MoiQFVOECm4AwK2l28i+YER1JO4IplTH44uvzX9o

# RnJHaMvWzZEpozPy4jNO2DDqbcNs4zh7AWMhE1PWFVA+CHI/En5nASvCvLmuR/t8

# q4bc8XR8QIZJQSp+2U6m2ldNAgMBAAGjggF+MIIBejAfBgNVHSUEGDAWBgorBgEE

# AYI3TAgBBggrBgEFBQcDAzAdBgNVHQ4EFgQUNZJaEUGL2Guwt7ZOAu4efEYXedEw

# UAYDVR0RBEkwR6RFMEMxKTAnBgNVBAsTIE1pY3Jvc29mdCBPcGVyYXRpb25zIFB1

# ZXJ0byBSaWNvMRYwFAYDVQQFEw0yMzAwMTIrNDY3NTk3MB8GA1UdIwQYMBaAFEhu

# ZOVQBdOCqhc3NyK1bajKdQKVMFQGA1UdHwRNMEswSaBHoEWGQ2h0dHA6Ly93d3cu

# bWljcm9zb2Z0LmNvbS9wa2lvcHMvY3JsL01pY0NvZFNpZ1BDQTIwMTFfMjAxMS0w

# Ny0wOC5jcmwwYQYIKwYBBQUHAQEEVTBTMFEGCCsGAQUFBzAChkVodHRwOi8vd3d3

# Lm1pY3Jvc29mdC5jb20vcGtpb3BzL2NlcnRzL01pY0NvZFNpZ1BDQTIwMTFfMjAx

# MS0wNy0wOC5jcnQwDAYDVR0TAQH/BAIwADANBgkqhkiG9w0BAQsFAAOCAgEAFkk3

# uSxkTEBh1NtAl7BivIEsAWdgX1qZ+EdZMYbQKasY6IhSLXRMxF1B3OKdR9K/kccp

# kvNcGl8D7YyYS4mhCUMBR+VLrg3f8PUj38A9V5aiY2/Jok7WZFOAmjPRNNGnyeg7

# l0lTiThFqE+2aOs6+heegqAdelGgNJKRHLWRuhGKuLIw5lkgx9Ky+QvZrn/Ddi8u

# TIgWKp+MGG8xY6PBvvjgt9jQShlnPrZ3UY8Bvwy6rynhXBaV0V0TTL0gEx7eh/K1

# o8Miaru6s/7FyqOLeUS4vTHh9TgBL5DtxCYurXbSBVtL1Fj44+Od/6cmC9mmvrti

# yG709Y3Rd3YdJj2f3GJq7Y7KdWq0QYhatKhBeg4fxjhg0yut2g6aM1mxjNPrE48z

# 6HWCNGu9gMK5ZudldRw4a45Z06Aoktof0CqOyTErvq0YjoE4Xpa0+87T/PVUXNqf

# 7Y+qSU7+9LtLQuMYR4w3cSPjuNusvLf9gBnch5RqM7kaDtYWDgLyB42EfsxeMqwK

# WwA+TVi0HrWRqfSx2olbE56hJcEkMjOSKz3sRuupFCX3UroyYf52L+2iVTrda8XW

# esPG62Mnn3T8AuLfzeJFuAbfOSERx7IFZO92UPoXE1uEjL5skl1yTZB3MubgOA4F

# 8KoRNhviFAEST+nG8c8uIsbZeb08SeYQMqjVEmkwggd6MIIFYqADAgECAgphDpDS

# 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/BvW1taslScxMNelDNMYIVdjCCFXICAQEwgZUwfjELMAkG

# A1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQx

# HjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEoMCYGA1UEAxMfTWljcm9z

# b2Z0IENvZGUgU2lnbmluZyBQQ0EgMjAxMQITMwAAAlKLM6r4lfM52wAAAAACUjAN

# BglghkgBZQMEAgEFAKCBsDAZBgkqhkiG9w0BCQMxDAYKKwYBBAGCNwIBBDAcBgor

# BgEEAYI3AgELMQ4wDAYKKwYBBAGCNwIBFTAvBgkqhkiG9w0BCQQxIgQgVv+v9PTY

# tU5KzroeXrP0NEFt1F5ceHnb6Zkhg1w07M0wRAYKKwYBBAGCNwIBDDE2MDSgFIAS

# AE0AaQBjAHIAbwBzAG8AZgB0oRyAGmh0dHBzOi8vd3d3Lm1pY3Jvc29mdC5jb20g

# MA0GCSqGSIb3DQEBAQUABIIBAJACP2ozAz79yAMQzgcQLy24UeQxSz0gmSw3YJMm

# p2pb7XabiAwGZW4+xl4Sl2s39WPVApwmqAH5ZDPIdjH182SfmLcPSwXDGuv+JQHN

# x832JpgD2XQHm56yiDiDe8/lJGbXOvv3cAlUeCkKU3hfoOBTeWsMOVfncsNst7wn

# 43HhoZXHc/Ov+mfOuZ7+a1pd/ZFlcYoel12EJ4+QU1uMWe0mCpmUHMarIk1/Pbon

# qvmRS+AUoMCHCb6mrefwZHzhBMkoWwnshKaKGD2TRvZT7CtaOYm+DPJyp1e2wscm

# LgwByIjqYjDbJrGxLMXaKJSI+udJvwZaYLIszjUQXzr86F+hghL+MIIS+gYKKwYB

# BAGCNwMDATGCEuowghLmBgkqhkiG9w0BBwKgghLXMIIS0wIBAzEPMA0GCWCGSAFl

# AwQCAQUAMIIBWQYLKoZIhvcNAQkQAQSgggFIBIIBRDCCAUACAQEGCisGAQQBhFkK

# AwEwMTANBglghkgBZQMEAgEFAAQgBiQ2h8rIHOT+H4AaVbDOjOYHzz7DhHFxHkiX

# F+JO4xACBmGDC6zHHBgTMjAyMTExMTIwOTQzMjguNTUyWjAEgAIB9KCB2KSB1TCB

# 0jELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1Jl

# ZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEtMCsGA1UECxMk

# TWljcm9zb2Z0IElyZWxhbmQgT3BlcmF0aW9ucyBMaW1pdGVkMSYwJAYDVQQLEx1U

# aGFsZXMgVFNTIEVTTjpEMDgyLTRCRkQtRUVCQTElMCMGA1UEAxMcTWljcm9zb2Z0

# IFRpbWUtU3RhbXAgU2VydmljZaCCDk0wggT5MIID4aADAgECAhMzAAABQa9/Updc

# 8txFAAAAAAFBMA0GCSqGSIb3DQEBCwUAMHwxCzAJBgNVBAYTAlVTMRMwEQYDVQQI

# EwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNyb3Nv

# ZnQgQ29ycG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1wIFBD

# QSAyMDEwMB4XDTIwMTAxNTE3MjgyN1oXDTIyMDExMjE3MjgyN1owgdIxCzAJBgNV

# BAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4w

# HAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xLTArBgNVBAsTJE1pY3Jvc29m

# dCBJcmVsYW5kIE9wZXJhdGlvbnMgTGltaXRlZDEmMCQGA1UECxMdVGhhbGVzIFRT

# UyBFU046RDA4Mi00QkZELUVFQkExJTAjBgNVBAMTHE1pY3Jvc29mdCBUaW1lLVN0

# YW1wIFNlcnZpY2UwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDyKsuo

# vbx1qX48lSZQk7C9if+w4ITNDNnKP3hdsU+1GEOE+NqC+8o6/UaAyg65e+Skze4z

# kTru/I4I/GqFMDOrsCTfOQRdcG/smgzxebTHlRycCSlSISjR7JxGXpudggHcqVlb

# e7Pglza/YVXQoIaQuu+p8o/xX+LaFXI3zng56NanHzAZRrMzgJhRWjByAQNzvo5j

# 5drhbbsMJkmbZ/2iXgGNIv5vYv9Pyf8sQaSdpTHBJBM3UtAK364EMIBJ3pVBHkIs

# slW3owEvRbU2VpbEQAnCUh3IGdLWKEu9GDWNz8pRl7SxEV0Pd+EquM9pzeGjLTTs

# W+voajRYnimvasl1AgMBAAGjggEbMIIBFzAdBgNVHQ4EFgQULSg/LG4ukP1FcGv1

# zw07QQUSxsQwHwYDVR0jBBgwFoAU1WM6XIoxkPNDe3xGG8UzaFqFbVUwVgYDVR0f

# BE8wTTBLoEmgR4ZFaHR0cDovL2NybC5taWNyb3NvZnQuY29tL3BraS9jcmwvcHJv

# ZHVjdHMvTWljVGltU3RhUENBXzIwMTAtMDctMDEuY3JsMFoGCCsGAQUFBwEBBE4w

# TDBKBggrBgEFBQcwAoY+aHR0cDovL3d3dy5taWNyb3NvZnQuY29tL3BraS9jZXJ0

# cy9NaWNUaW1TdGFQQ0FfMjAxMC0wNy0wMS5jcnQwDAYDVR0TAQH/BAIwADATBgNV

# HSUEDDAKBggrBgEFBQcDCDANBgkqhkiG9w0BAQsFAAOCAQEAUnrfIn3YKGoKCl7E

# PjyiS+Ia4LiKQ2y+bCUJJ63WwWm8kTMskHxxMXjPipBPPwCxC1x7DqYBWZAJgO71

# /l57XXFePUvAdixkadKz859G6XVUqZjnU5Cmq8rk78K3h+zQhuXOjx7I4snKBOT3

# tpdUDhTOrwZuUvstDleLABjjjow4Auc1cWj8qr22/OKnBjVhxGf+eUxD5v3Y6Isu

# YdUyLbABQ5GIoW9oB9haOFB37aocsyx2k2W7AFtZ7sUXkAGwOjQdE4xbIKDF0tDe

# +qvcMxIfdlYqKKsWy9YmZyF9k8ZE5vCqzO9Jc8WY8Fn2j56v7hSgtX7nQZaedCTL

# sdWAuTCCBnEwggRZoAMCAQICCmEJgSoAAAAAAAIwDQYJKoZIhvcNAQELBQAwgYgx

# CzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRt

# b25kMR4wHAYDVQQKExVNaWNyb3NvZnQgQ29ycG9yYXRpb24xMjAwBgNVBAMTKU1p

# Y3Jvc29mdCBSb290IENlcnRpZmljYXRlIEF1dGhvcml0eSAyMDEwMB4XDTEwMDcw

# MTIxMzY1NVoXDTI1MDcwMTIxNDY1NVowfDELMAkGA1UEBhMCVVMxEzARBgNVBAgT

# Cldhc2hpbmd0b24xEDAOBgNVBAcTB1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29m

# dCBDb3Jwb3JhdGlvbjEmMCQGA1UEAxMdTWljcm9zb2Z0IFRpbWUtU3RhbXAgUENB

# IDIwMTAwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCpHQ28dxGKOiDs

# /BOX9fp/aZRrdFQQ1aUKAIKF++18aEssX8XD5WHCdrc+Zitb8BVTJwQxH0EbGpUd

# zgkTjnxhMFmxMEQP8WCIhFRDDNdNuDgIs0Ldk6zWczBXJoKjRQ3Q6vVHgc2/JGAy

# WGBG8lhHhjKEHnRhZ5FfgVSxz5NMksHEpl3RYRNuKMYa+YaAu99h/EbBJx0kZxJy

# GiGKr0tkiVBisV39dx898Fd1rL2KQk1AUdEPnAY+Z3/1ZsADlkR+79BL/W7lmsqx

# qPJ6Kgox8NpOBpG2iAg16HgcsOmZzTznL0S6p/TcZL2kAcEgCZN4zfy8wMlEXV4W

# nAEFTyJNAgMBAAGjggHmMIIB4jAQBgkrBgEEAYI3FQEEAwIBADAdBgNVHQ4EFgQU

# 1WM6XIoxkPNDe3xGG8UzaFqFbVUwGQYJKwYBBAGCNxQCBAweCgBTAHUAYgBDAEEw

# CwYDVR0PBAQDAgGGMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAU1fZWy4/o

# olxiaNE9lJBb186aGMQwVgYDVR0fBE8wTTBLoEmgR4ZFaHR0cDovL2NybC5taWNy

# b3NvZnQuY29tL3BraS9jcmwvcHJvZHVjdHMvTWljUm9vQ2VyQXV0XzIwMTAtMDYt

# MjMuY3JsMFoGCCsGAQUFBwEBBE4wTDBKBggrBgEFBQcwAoY+aHR0cDovL3d3dy5t

# aWNyb3NvZnQuY29tL3BraS9jZXJ0cy9NaWNSb29DZXJBdXRfMjAxMC0wNi0yMy5j

# cnQwgaAGA1UdIAEB/wSBlTCBkjCBjwYJKwYBBAGCNy4DMIGBMD0GCCsGAQUFBwIB

# FjFodHRwOi8vd3d3Lm1pY3Jvc29mdC5jb20vUEtJL2RvY3MvQ1BTL2RlZmF1bHQu

# aHRtMEAGCCsGAQUFBwICMDQeMiAdAEwAZQBnAGEAbABfAFAAbwBsAGkAYwB5AF8A

# UwB0AGEAdABlAG0AZQBuAHQALiAdMA0GCSqGSIb3DQEBCwUAA4ICAQAH5ohRDeLG

# 4Jg/gXEDPZ2joSFvs+umzPUxvs8F4qn++ldtGTCzwsVmyWrf9efweL3HqJ4l4/m8

# 7WtUVwgrUYJEEvu5U4zM9GASinbMQEBBm9xcF/9c+V4XNZgkVkt070IQyK+/f8Z/

# 8jd9Wj8c8pl5SpFSAK84Dxf1L3mBZdmptWvkx872ynoAb0swRCQiPM/tA6WWj1kp

# vLb9BOFwnzJKJ/1Vry/+tuWOM7tiX5rbV0Dp8c6ZZpCM/2pif93FSguRJuI57BlK

# cWOdeyFtw5yjojz6f32WapB4pm3S4Zz5Hfw42JT0xqUKloakvZ4argRCg7i1gJsi

# OCC1JeVk7Pf0v35jWSUPei45V3aicaoGig+JFrphpxHLmtgOR5qAxdDNp9DvfYPw

# 4TtxCd9ddJgiCGHasFAeb73x4QDf5zEHpJM692VHeOj4qEir995yfmFrb3epgcun

# Caw5u+zGy9iCtHLNHfS4hQEegPsbiSpUObJb2sgNVZl6h3M7COaYLeqN4DMuEin1

# wC9UJyH3yKxO2ii4sanblrKnQqLJzxlBTeCG+SqaoxFmMNO7dDJL32N79ZmKLxvH

# Ia9Zta7cRDyXUHHXodLFVeNp3lfB0d4wwP3M5k37Db9dT+mdHhk4L7zPWAUu7w2g

# UDXa7wknHNWzfjUeCLraNtvTX4/edIhJEqGCAtcwggJAAgEBMIIBAKGB2KSB1TCB

# 0jELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1Jl

# ZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEtMCsGA1UECxMk

# TWljcm9zb2Z0IElyZWxhbmQgT3BlcmF0aW9ucyBMaW1pdGVkMSYwJAYDVQQLEx1U

# aGFsZXMgVFNTIEVTTjpEMDgyLTRCRkQtRUVCQTElMCMGA1UEAxMcTWljcm9zb2Z0

# IFRpbWUtU3RhbXAgU2VydmljZaIjCgEBMAcGBSsOAwIaAxUAquW/KbUKq4ihByvO

# dwu+QPValQOggYMwgYCkfjB8MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGlu

# Z3RvbjEQMA4GA1UEBxMHUmVkbW9uZDEeMBwGA1UEChMVTWljcm9zb2Z0IENvcnBv

# cmF0aW9uMSYwJAYDVQQDEx1NaWNyb3NvZnQgVGltZS1TdGFtcCBQQ0EgMjAxMDAN

# BgkqhkiG9w0BAQUFAAIFAOU4FXUwIhgPMjAyMTExMTIwNjE5MzNaGA8yMDIxMTEx

# MzA2MTkzM1owdzA9BgorBgEEAYRZCgQBMS8wLTAKAgUA5TgVdQIBADAKAgEAAgIg

# bAIB/zAHAgEAAgIRYjAKAgUA5Tlm9QIBADA2BgorBgEEAYRZCgQCMSgwJjAMBgor

# BgEEAYRZCgMCoAowCAIBAAIDB6EgoQowCAIBAAIDAYagMA0GCSqGSIb3DQEBBQUA

# A4GBAKT93suMkiHkPJhjYDr6NYZU5rtaRtD2pc6KF/EKzffSvGhnV7IS3PfoeSV0

# K7ss/ncJOWNhlvH8XKUtNz6524a1fkDMOtym43tml98O7/ykzq8R7FrCnnragmVV

# 9nvIEr4dfGDrHKbHv6+2nDpWyaO/pxbMdU3h3EjV2s1t54G6MYIDDTCCAwkCAQEw

# gZMwfDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcT

# B1JlZG1vbmQxHjAcBgNVBAoTFU1pY3Jvc29mdCBDb3Jwb3JhdGlvbjEmMCQGA1UE

# AxMdTWljcm9zb2Z0IFRpbWUtU3RhbXAgUENBIDIwMTACEzMAAAFBr39Sl1zy3EUA

# AAAAAUEwDQYJYIZIAWUDBAIBBQCgggFKMBoGCSqGSIb3DQEJAzENBgsqhkiG9w0B

# CRABBDAvBgkqhkiG9w0BCQQxIgQg9Iit2o8JEASf0r0geWonpFSmk7jVDxPSkwLe

# kwi8rHgwgfoGCyqGSIb3DQEJEAIvMYHqMIHnMIHkMIG9BCBRPwE8jOpzdJ5wdE8s

# oG1bS846dP7vyFpaj5dzFV6t3jCBmDCBgKR+MHwxCzAJBgNVBAYTAlVTMRMwEQYD

# VQQIEwpXYXNoaW5ndG9uMRAwDgYDVQQHEwdSZWRtb25kMR4wHAYDVQQKExVNaWNy

# b3NvZnQgQ29ycG9yYXRpb24xJjAkBgNVBAMTHU1pY3Jvc29mdCBUaW1lLVN0YW1w

# IFBDQSAyMDEwAhMzAAABQa9/Updc8txFAAAAAAFBMCIEIOnWvFxCtySiIFIvuG1a

# aF0mn0VNHAHhi1dVju8lwHpdMA0GCSqGSIb3DQEBCwUABIIBAJJl8kzKrFzDRMzA

# yLydP6D17HhYc+zeCAfhkKPF8iZsXk+BLE622nDvAM8vwHmqa6SS7OfZxpsUptbt

# pNZA8KvSqo8jufmC5tF36qQJ1K4BHHUVQf5+X10KgPjZlSKBAQZuOMv8B+Ii8C2D

# wwl2zFobKcerp7mj5XFUvaYT97+CbJjgWwaHQh5EVdWCnRwkTzhXlvZ3LfifKkC5

# CK7mXyKQ40qkGtW1GnJoi++YInwbtdcvLKNhyB6y187FmQVqsRFV/MCzSsLtyVrl

# yOUEfS3i6WmcprruOB23belRr4JzV8blKXc2whsGYn/JNz08niRhV/FNpOFcEx+5

# L+gUQ0Q=

# SIG # End signature block