*-SqlDscServerPermission: Add commands SQL Server permission management

.github/instructions/dsc-community-style-guidelines-pester.instructions.md

@@ -14,6 +14,13 @@ applyTo: "**/*.[Tt]ests.ps1"
 - Never test verbose messages, debug messages or parameter binding behavior
 - Pass all mandatory parameters to avoid prompts
 
+## Requirements
+- Inside `It` blocks, assign unused return objects to `$null` (unless part of pipeline)
+- Tested entity must be called from within the `It` blocks
+- Keep results and assertions in same `It` block
+- Avoid try-catch-finally for cleanup, use `AfterAll` or `AfterEach`
+- Avoid unnecessary remove/recreate cycles
+
 ## Naming
 - One `Describe` block per file matching the tested entity name
 - `Context` descriptions start with 'When'
@@ -51,10 +58,6 @@ applyTo: "**/*.[Tt]ests.ps1"
 - Keep scope close to usage context
 
 ## Best Practices
-- Inside `It` blocks, assign unused return objects to `$null` (unless part of pipeline)
-- Tested entity must be called from within the `It` blocks
-- Keep results and assertions in same `It` block
 - Cover all scenarios and code paths
 - Use `BeforeEach` and `AfterEach` sparingly
-- Avoid try-catch-finally for cleanup, use `AfterAll` or `AfterEach`
-- Avoid unnecessary remove/recreate cycles
+- Use `$PSDefaultParameterValues` only for Pester commands (`Describe`, `Context`, `It`, `Mock`, `Should`, `InModuleScope`)

CHANGELOG.md

@@ -35,6 +35,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Enhanced workflow with proper environment variable configuration and DSCv3 verification.
   - Fixed environment variable persistence by using $GITHUB_ENV instead of
     job-level env declaration.
+- `Grant-SqlDscServerPermission`
+  - Added new public command to grant server permissions to a principal (Login or ServerRole) on a SQL Server Database Engine instance.
+- `Deny-SqlDscServerPermission`
+  - Added new public command to deny server permissions to a principal (Login or ServerRole).
+- `Revoke-SqlDscServerPermission`
+  - Added new public command to revoke server permissions from a principal (Login or ServerRole).
+- `Test-SqlDscServerPermission`
+  - Added new public command with Grant/Deny parameter sets (and `-WithGrant`) to test server permissions for a principal.
 - `Assert-SqlDscLogin`
   - Added new public command to validate that a specified SQL Server principal
     is a login.

azure-pipelines.yml

@@ -299,18 +299,24 @@ stages:
                   'tests/Integration/Commands/Test-SqlDscIsLoginEnabled.Integration.Tests.ps1'
                   'tests/Integration/Commands/New-SqlDscRole.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscRole.Integration.Tests.ps1'
-                  'tests/Integration/Commands/Remove-SqlDscRole.Integration.Tests.ps1'
-                  'tests/Integration/Commands/Remove-SqlDscLogin.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Grant-SqlDscServerPermission.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscServerPermission.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Test-SqlDscServerPermission.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Deny-SqlDscServerPermission.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Revoke-SqlDscServerPermission.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/New-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscDatabase.Integration.Tests.ps1'
-                  'tests/Integration/Commands/Remove-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscAgentAlert.Integration.Tests.ps1'
                   'tests/Integration/Commands/New-SqlDscAgentAlert.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscAgentAlert.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscAgentAlert.Integration.Tests.ps1'
+                  # Group 8
                   'tests/Integration/Commands/Remove-SqlDscAgentAlert.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Remove-SqlDscDatabase.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Remove-SqlDscRole.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Remove-SqlDscLogin.Integration.Tests.ps1'
 
                   # Group 9
                   'tests/Integration/Commands/Uninstall-SqlDscServer.Integration.Tests.ps1'

source/Enum/002.ServerPermission.ps1

@@ -0,0 +1,63 @@
+<#
+    .SYNOPSIS
+        The possible server permissions that can be granted, denied, or revoked.
+
+    .NOTES
+        The available permissions can be seen in the ServerPermission Class documentation:
+        https://learn.microsoft.com/en-us/dotnet/api/microsoft.sqlserver.management.smo.serverpermission
+#>
+enum SqlServerPermission
+{
+    # cSpell:ignore securables
+    AdministerBulkOperations = 1
+    AlterAnyAvailabilityGroup
+    AlterAnyConnection
+    AlterAnyCredential
+    AlterAnyDatabase
+    AlterAnyEndpoint
+    AlterAnyEventNotification
+    AlterAnyEventSession
+    AlterAnyEventSessionAddEvent
+    AlterAnyEventSessionAddTarget
+    AlterAnyEventSessionDisable
+    AlterAnyEventSessionDropEvent
+    AlterAnyEventSessionDropTarget
+    AlterAnyEventSessionEnable
+    AlterAnyEventSessionOption
+    AlterAnyLinkedServer
+    AlterAnyLogin
+    AlterAnyServerAudit
+    AlterAnyServerRole
+    AlterResources
+    AlterServerState
+    AlterSettings
+    AlterTrace
+    AuthenticateServer
+    ConnectAnyDatabase
+    ConnectSql
+    ControlServer
+    CreateAnyDatabase
+    CreateAnyEventSession
+    CreateAvailabilityGroup
+    CreateDdlEventNotification
+    CreateEndpoint
+    CreateLogin
+    CreateServerRole
+    CreateTraceEventNotification
+    DropAnyEventSession
+    ExternalAccessAssembly
+    ImpersonateAnyLogin
+    SelectAllUserSecurables
+    Shutdown
+    UnsafeAssembly
+    ViewAnyCryptographicallySecuredDefinition
+    ViewAnyDatabase
+    ViewAnyDefinition
+    ViewAnyErrorLog
+    ViewAnyPerformanceDefinition
+    ViewAnySecurityDefinition
+    ViewServerPerformanceState
+    ViewServerSecurityAudit
+    ViewServerSecurityState
+    ViewServerState
+}

source/Public/Deny-SqlDscServerPermission.ps1

@@ -0,0 +1,134 @@
+<#
+    .SYNOPSIS
+        Denies server permissions to a principal on a SQL Server Database Engine instance.
+
+    .DESCRIPTION
+        This command denies server permissions to an existing principal on a SQL Server
+        Database Engine instance. The principal can be specified as either a Login
+        object (from Get-SqlDscLogin) or a ServerRole object (from Get-SqlDscRole).
+
+    .PARAMETER Login
+        Specifies the Login object for which the permissions are denied.
+        This parameter accepts pipeline input.
+
+    .PARAMETER ServerRole
+        Specifies the ServerRole object for which the permissions are denied.
+        This parameter accepts pipeline input.
+
+    .PARAMETER Permission
+        Specifies the permissions to be denied. Specify multiple permissions by
+        providing an array of SqlServerPermission enum values.
+
+    .PARAMETER Force
+        Specifies that the permissions should be denied without any confirmation.
+
+    .OUTPUTS
+        None.
+
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+        $login = $serverInstance | Get-SqlDscLogin -Name 'MyLogin'
+
+        Deny-SqlDscServerPermission -Login $login -Permission ConnectSql, ViewServerState
+
+        Denies the specified permissions to the login 'MyLogin'.
+
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+        $role = $serverInstance | Get-SqlDscRole -Name 'MyRole'
+
+        $role | Deny-SqlDscServerPermission -Permission AlterAnyDatabase -Force
+
+        Denies the specified permissions to the role 'MyRole' without prompting for confirmation.
+
+    .NOTES
+        The Login or ServerRole object must come from the same SQL Server instance
+        where the permissions will be denied. If specifying `-ErrorAction 'SilentlyContinue'`
+        then the command will silently continue if any errors occur. If specifying
+        `-ErrorAction 'Stop'` the command will throw an error on any failure.
+#>
+function Deny-SqlDscServerPermission
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when a parameter type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues/8.')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('AvoidThrowOutsideOfTry', '', Justification = 'Because the code throws based on an prior expression')]
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    [OutputType()]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'Login')]
+        [Microsoft.SqlServer.Management.Smo.Login]
+        $Login,
+
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ServerRole')]
+        [Microsoft.SqlServer.Management.Smo.ServerRole]
+        $ServerRole,
+
+        [Parameter(Mandatory = $true)]
+        [SqlServerPermission[]]
+        $Permission,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $Force
+    )
+
+    process
+    {
+        if ($Force.IsPresent -and -not $Confirm)
+        {
+            $ConfirmPreference = 'None'
+        }
+
+        # Determine which principal object we're working with
+        if ($PSCmdlet.ParameterSetName -eq 'Login')
+        {
+            $principalName = $Login.Name
+            $serverObject = $Login.Parent
+        }
+        else
+        {
+            $principalName = $ServerRole.Name
+            $serverObject = $ServerRole.Parent
+        }
+
+        $verboseDescriptionMessage = $script:localizedData.ServerPermission_Deny_ShouldProcessVerboseDescription -f $principalName, $serverObject.InstanceName, ($Permission -join ',')
+        $verboseWarningMessage = $script:localizedData.ServerPermission_Deny_ShouldProcessVerboseWarning -f $principalName
+        $captionMessage = $script:localizedData.ServerPermission_Deny_ShouldProcessCaption
+
+        if ($PSCmdlet.ShouldProcess($verboseDescriptionMessage, $verboseWarningMessage, $captionMessage))
+        {
+            # Convert enum array to ServerPermissionSet object
+            $permissionSet = [Microsoft.SqlServer.Management.Smo.ServerPermissionSet]::new()
+            foreach ($permissionName in $Permission)
+            {
+                $permissionSet.$permissionName = $true
+            }
+
+            # Get the permissions names that are set to $true in the ServerPermissionSet.
+            $permissionName = $permissionSet |
+                Get-Member -MemberType 'Property' |
+                Select-Object -ExpandProperty 'Name' |
+                Where-Object -FilterScript {
+                    $permissionSet.$_
+                }
+
+            try
+            {
+                $serverObject.Deny($permissionSet, $principalName)
+            }
+            catch
+            {
+                $errorMessage = $script:localizedData.ServerPermission_Deny_FailedToDenyPermission -f $principalName, $serverObject.InstanceName
+
+                $PSCmdlet.ThrowTerminatingError(
+                    [System.Management.Automation.ErrorRecord]::new(
+                        $errorMessage,
+                        'DSDSP0001', # cSpell: disable-line
+                        [System.Management.Automation.ErrorCategory]::InvalidOperation,
+                        $principalName
+                    )
+                )
+            }
+        }
+    }
+}