PowerShell Module Exporting Functions in Constrained Language

PowerShell offers a number of ways to expose functions in a script module. But some options have serious performance or security drawbacks. In this blog I describe these issues and provide simple guidance for creating performant and secure script modules. Look for a module soon in PSGallery that helps you update your modules to be compliant with this guidance.

When PowerShell is running in Constrained Language mode it adds some restrictions in how module functions can be exported. Normally, when PowerShell is not running in Constrained Language, all script functions defined in the module are exported by default.

# TestModule.psm1
function F1 { }
function F2 { }
function F3 { }

# TestModule.psd1
@{ ModuleVersion = '1.0'; RootModule = 'TestModule.psm1' }

# All functions (Function1, Function2, Function3) are exported and available
Get-Module -Name TestModule -List | Select -ExpandProperty ExportedFunctions

F1
F2
F3

This is handy and works well for simple modules. However, it can cause problems for more complex modules.

Performance Degradation

Command discovery is much slower when script functions are exported implicitly or explicitly using wildcard characters. This is because PowerShell has to parse all module script content to look for available functions and then match the found function names with a wildcard pattern. If the module uses explicit function export lists, then this parsing during discovery is not necessary. If you have a lot of custom script modules with many functions, the performance hit can become very noticeable. This principal also applies to exporting any other script element such as cmdlets, variables, aliases, and DSC resources.

# TestModule.psm1
function F1 { }
function F2 { }
function F3 { }
...
# This wildcard function export has the same behavior as the default behavior, all module functions are exported and PowerShell has to parse all script to discover available functions
Export-ModuleMember -Function '*'

Confused Intent

For large complex modules, exporting all defined functions is confusing to users as to how the module is intended to be used. The number of defined functions can be very large and the handful of user cmdlets can get lost in the noise. It is much better to export just the functions intended for the user and hide all helper functions.

# TestModule.psm1
function Invoke-Program { }
function F1 { }
function F2 { }
...
function F100 { }

# TestModule.psd1
@{ ModuleVersion = '1.0'; RootModule = 'TestModule.psm1'; FunctionsToExport = 'Invoke-Program' }

Get-Module -Name TestModule -List | Select -ExpandProperty ExportedFunctions

Invoke-Program

Security

PowerShell runs in Constrained Language mode when a DeviceGuard or AppLocker policy is enforced on the system. This provides a good user shell experience while allowing trusted script modules to run in Full Language so that system management can still be done. For example, a user from the command line cannot use Add-Type to create and run arbitrary C# types, but a trusted script can.

So, it is important that a trusted script does not expose any vulnerabilities such as script injection or arbitrary code execution. Another type of vulnerability is leaking dangerous module functions not intended for public use. A helper function might take arbitrary source code and create a type intended to be used privately in a trusted context. But, if that helper function becomes publically available it exposes a code execution vulnerability.

# TestModule.psm1
function Invoke-Program { }
# Private helper function
function Get-Type
{
    param( [string] $source )
    Add-Type -TypeDefinition $source -PassThru
}

# Exposes *all* module functions!
Export-ModuleMember -Function '*'

Get-Module -Name TestModule -List | Select -ExpandProperty ExportedFunctions

Invoke-Program
Get-Type

In the above example, Get-Type module helper function is exported via wildcard along with the intended Invoke-Program function. Since this is a trusted module Get-Type runs in Full Language and exposes the ability to create arbitrary types.

Unintended Consequences

A major problem with exporting module functions using wildcards is that you may end up exporting functions unintentionally. For example, your module may specify other nested modules, or it may explicitly import other modules, or it may dot source script files into the module scope. All of those script functions will become publicly available if wild cards are used to export module functions.

# TestModule.psm1
import-Module HelperMod1
. .\CSharpHelpers.ps1
function Invoke-Program { }

# Exposes *all* module functions!
Export-ModuleMember -Function '*'

Get-Module -Name TestModule -List | Select -ExpandProperty ExportedFunctions
Invoke-Program
HelperFn1
HelperFn2
Compile-CSharp

Module Function Export Restrictions

When PowerShell detects that an application whitelisting policy is enforced it runs in Constrained Language mode as mentioned previously, but it also applies some function export restrictions for imported modules. Remember that these restrictions only apply when PowerShell is running under DeviceGuard or AppLocker policy enforcement mode. Otherwise module function export works as before.

• Wildcards are not allowed with the FunctionsToExport keyword in a module manifest (.psd1 file). If a wildcard is found in the keyword argument then no functions are exported in that module.
• Wildcards are allowed in a module script file (.psm1). This is to provide backward compatibility but we strongly discourage it.
• A module that uses wildcards to export functions, and at the same time dot sources script files into the module scope, will throw an error during module loading time. Note that if a psm1 file exports functions via wildcard, but it is imported under a manifest (psd1 file) that exports functions explicitly by name, then no error is thrown because the psd1 overrides any function export done within a psm1 file associated with the manifest. But if the psm1 file is imported directly (without the psd1 manifest file) then the error is thrown (see example below). Basically, the dot source operator cannot be used in module script along with wildcard based function export. It is too easy to inadvertently expose unwanted functions.

These restrictions are to help prevent inadvertent exposure of functions. By using wildcard based function export, you may be exposing dangerous functions without knowing it.

# TestModule.psm1
Import-Module HelperMod1
. .\CSharpHelpers.ps1
function Invoke-Program { }
Export-ModuleMember -Function '*'

# TestModule.psd1
@{ ModuleVersion='1.0'; RootModule='TestModule.psm1'; FunctionsToExport='Invoke-Program' }

# Importing the psm1 file directly results in error because of the wildcard function export and use of dot source operator
Import-Module -Name TestModule\TestModule.psm1
Error:
'This module uses the dot-source operator while exporting functions using wildcard characters, and this is disallowed when the system is under application verification enforcement.'

# But importing using the module manifest succeeds since the manifest explicitly exports functions by name without wildcards
Import-Module TestModule
Get-Module -Name TestModule | Select -ExpandProperty ExportedFunctions
Invoke-Program

Module Function Export Best Practices

Best practices for module function exporting is pretty simple. Always export module functions explicitly by name. Never export using wild card names. This will yield the best performance and ensure you don’t expose functions you don’t intend to expose. It makes your module safer to use as trusted in a DeviceGuard policy enforcement environment.

# TestModule.psm1
Import-Module HelperMod1
. .\CSharpHelpers.ps1
function Invoke-Program { }

# TestModule.psd1
@ { ModuleVersion='1.0'; RootModule='TestModule.psm1'; FunctionsToExport='Invoke-Program' }

Get-Module -Name TestModule -List | Select -ExpandProperty ExportedFunctions
Invoke-Program

Paul Higinbotham Senior Software Engineer PowerShell Team