Constrained PowerShell endpoints – Visible cmdlets, session types, and language modes

• Author
• Recent Posts

Michael Pietroforte

Michael Pietroforte is the founder and editor in chief of 4sysops. He has more than 35 years of experience in IT management and system administration.

Latest posts by Michael Pietroforte (see all)

• Poll: How reliable are ChatGPT and Bing Chat? - Tue, May 23 2023
• Pip install Boto3 - Thu, Mar 24 2022
• Install Boto3 (AWS SDK for Python) in Visual Studio Code (VS Code) on Windows - Wed, Feb 23 2022

These different options correspond to the three parameters -VisibleCmdlets, -SessionType, and -LanguageMode of the New-PSSessionConfigurationFile cmdlet.

VisibleCmdlets

Restricting the visible cmdlets in sessions is the most straightforward way to restrict what users can do with PowerShell. In my previous post, I demonstrated how you can ensure that only cmdlets that begin with the Get verb are available. Even though this limits users to only retrieve information from the corresponding computer, you usually want to prevent standard users from being able to gather data that they don’t really need for their work.

Thus, a better practice is to exactly define what cmdlets are visible for a user or a group. This might cost a little more time. However, in many cases, it is pretty obvious what cmdlets a user needs.

To add a specific list of cmdlets to the session configuration that the user can work with, you can use these commands:

New-PSSessionConfigurationFile -VisibleCmdlets Get-Process,Select-Object -Path .\VisibleCmdlets.pssc
Register-PSSessionConfiguration -Path .\VisibleCmdlets.pssc -Name myEndPoint

The -VisibleCmdlets parameter expects an array as input. So don’t set the value you pass in quotes. You can then try your session configuration this way:

$mySession = New-PSSession -ConfigurationName myEndPoint
Invoke-Command -Session $mySession {Get-Process –Name Explorer}

If you try to run a cmdlet that is not in your list, you will receive an error message telling you that the cmdlet was not recognized.

The Get-ChildItem cmdlet is not available in the session.

If you have help desk staff that just needs to run a script, you can quickly determine all cmdlets used in the script with this command:

Get-Content .\myScript.ps1 | Select-String -Pattern "\w+-\w+" | Select Matches

This lists all strings in the script text that contain a hyphen. If you want it a bit more reliable, you can run the code below. It will generate an array of the cmdlet names used in the script, which you can then pass to the -VisibleCmdlets parameter directly.

$AllCmdlets = Get-Command -CommandType Cmdlet | Select-Object -ExpandProperty Name
$myScript = Get-Content .\myScript.ps1
[Regex]$Regex = '\w+-\w+'
$PossibleCmdlets = $Regex.Matches($myScript) | Foreach-Object {$_.Value}
$CmdletsInScript = Compare-Object -ReferenceObject $AllCmdlets -DifferenceObject $PossibleCmdlets -IncludeEqual -ExcludeDifferent -PassThru
New-PSSessionConfigurationFile -VisibleCmdlets $CmdletsInScript -Path .\VisibleCmdlets.pssc
Register-PSSessionConfiguration -Path .\VisibleCmdlets.pssc -Name VisibleCmdlets

This little program compares all strings in your script that contain a hyphen with the cmdlets that the Get-Command cmdlet finds in your current session. Of course, this can only work if you didn’t use cmdlet aliases in your script. This gives you a good example of why following best practices makes sense.

It is important to note that, despite its name, the -VisibleCmdlets parameter can’t be used to make cmdlets visible that you excluded by the other methods described below. Perhaps a better name for the parameter would have been “-SoleCmdlets.” However, you can use the -VisibleCmdlets parameter to further restrict the visible cmdlets in session configurations that you constrained by other means.

SessionType

Another way to restrict the available cmdlets in a session is through the -SessionType parameter. The New-PSSessionConfigurationFile cmdlet knows three session types: Default, Empty, and RestrictedRemoteServer.

An empty session is literally empty. It doesn’t contain any cmdlets or language elements. You have to add anything you need in the session configuration yourself. Unfortunately, you can’t add single cmdlets through a session configuration file to an empty session. You have to first add a PowerShell module or snap-in and then remove unwanted cmdlets with the help of the -VisibleCmdlets parameter:

New-PSSessionConfigurationFile -SessionType Empty -ModulesToImport ActiveDirectory -VisibleCmdlets Get-ADUser -Path .\GetADUser.pssc
Register-PSSessionConfiguration -Name GetADUser -Path .\GetADUser.pssc
$GetADUser = New-PSSession -ConfigurationName GetADUser

The only available cmdlet session in the session would be Get-ADUser:

Invoke-Command -Session $GetADUser {Get-ADUser}

This commands works, whereas the next one will produce an error message:

Invoke-Command -Session $GetADuser {Get-ADDomain}

To test whether language elements such as operators are available, you can try the following example:

Invoke-Command -Session $GetADuser {$User = Get-ADUser Administrator; $User -match "Administrator"}

This command will produce the error message: The syntax is not supported by this runspace. However, if you replace line one in the example with this next one, you can use the -match operator:

New-PSSessionConfigurationFile -VisibleCmdlets Get-ADUser -Path .\GetADUser.pssc

Of course, the examples only work if the ActiveDirectory module is available on the computer.

The session type RestrictedRemoteServer is for sessions where a user has to interactively enter a remote session. Thus far, most of our examples only support PowerShell Remoting through Invoke-Command.

New-PSSessionConfigurationFile -SessionType RestrictedRemoteServer -Path .\RestrictedRemoteServer.pssc
Register-PSSessionConfiguration -Path RestrictedRemoteServer.pssc -Name RestrictedRemoteServer
$RestrictedRemoteServer = New-PSSession -ConfigurationName RestrictedRemoteServer
Enter-PSSession -Session $RestrictedRemoteServer

This session type contains seven so-called proxy functions that are required for interactive sessions: Get-Command, Get-FormatData, Select-Object, Get-Help, Measure-Object, Exit-PSSession, and Out-Default. A proxy function is a wrapper function around the original cmdlet that modifies the capabilities of the cmdlet, for example, by adding or removing parameters.

For instance, the Get-Command cmdlet supports the -Verb parameter that allows you to search for cmdlets that begin with a certain verb. The corresponding proxy function in sessions of the type RestrictedRemoteServer doesn’t support this parameter. You also have to know that aliases of the cmdlets are not available. Thus, you can’t exit an interactive session with Exit; only Exit-PSSession will work.

The proxy function Get-Command lacks the -Verb parameter.

As with a session configuration of the type Empty, you have to add all cmdlets you need and also take into account that, by default, no language elements are available. For some reason, you can’t add the PowerShell core modules to those two session types. (At least I didn’t figure out how to do it. Please let me know if you know how.) Thus, the core cmdlets, such as Get-Process or Add-Content, won’t be available in the corresponding sessions.

If you want your users to be able to enter an interactive session where all the core PowerShell cmdlets are available, you have to work with the default session type and use the -VisibleCmdlets parameter to add the above-mentioned seven cmdlets to the session configuration.

The value Default for the -SessionType parameter is somewhat superfluous as it has the same effect as if you omit the parameter altogether. The corresponding session configuration will create full-blown PowerShell sessions.

LanguageMode

The -LanguageMode parameter allows you to determine which PowerShell language elements, such as operators and variables, will be available in a session. The parameter accepts the values FullLanguage, ConstrainedLanguage, NoLanguage, and RestrictedLanguage.

The reason we couldn’t use the -match operator in the session types Empty and RestrictedRemoteServer is because the default value of the -LanguageMode parameter is NoLangugage for these session types. In addition to operators, you also can’t use script blocks and variables in this language mode.

New-PSSessionConfigurationFile -Path .\NoLanguage.pssc
Register-PSSessionConfiguration -Name NoLanguage -Path .\NoLanguage.pssc
$mySession = New-PSSession -ConfigurationName NoLanguage
Invoke-Command -Session $mySession {"a" -eq "a"; $a = "a"}

Operators and variables – unavailable in NoLanguage mode

The RestrictedLanguage language mode allows the comparison operators -eq (equal), -gt (greater than) and -lt (less than) and the variables $PSCulture, $PSUICulture, $True, $False, and $Null. The ConstrainedLanguage language mode is only supported on Windows RT, which is more or less dead so I’ll spare you the details.

Conclusion

I only scratched the surface of session configurations in my three posts. Before you implement your own session configurations, you have to carefully test if the users will be able to perform all their tasks. I am afraid that the complexity of PowerShell endpoints will scare off many admins. The result could be that, in many organizations, standard users who need to do tasks in PowerShell are unnecessarily promoted to administrators. Perhaps a simpler solution, such as the sudoers file in Linux, would improve PowerShell’s security. More information about PowerShell session configurations is available here and here.