{"id":14295,"date":"2018-08-14T13:39:18","date_gmt":"2018-08-14T20:39:18","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/powershell\/?p=14295"},"modified":"2019-02-18T12:37:45","modified_gmt":"2019-02-18T19:37:45","slug":"powershell-module-function-export-in-constrained-language","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/powershell-module-function-export-in-constrained-language\/","title":{"rendered":"PowerShell Module Function Export in Constrained Language"},"content":{"rendered":"
\n

<\/span><\/a>PowerShell Module Exporting Functions in Constrained Language<\/h2>\n

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<\/a> that helps you update your modules to be compliant with this guidance.<\/p>\n

When PowerShell is running in Constrained Language<\/a> 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.<\/p>\n

\n
#<\/span> TestModule.psm1<\/span><\/span>\nfunction<\/span> F1<\/span> { }\nfunction<\/span> F2<\/span> { }\nfunction<\/span> F3<\/span> { }\n\n#<\/span> TestModule.psd1<\/span><\/span>\n@<\/span>{ ModuleVersion<\/span> =<\/span> '<\/span>1.0'<\/span><\/span>; RootModule<\/span> =<\/span> '<\/span>TestModule.psm1'<\/span><\/span> }\n\n#<\/span> All functions (Function1, Function2, Function3) are exported and available<\/span><\/span>\nGet-Module<\/span> -<\/span>Name TestModule -<\/span>List |<\/span> Select -<\/span>ExpandProperty ExportedFunctions\n\nF1\nF2\nF3<\/pre>\n<\/div>\n
This is handy and works well for simple modules. However, it can cause problems for more complex modules.<\/p>\n
<\/span><\/a>Performance Degradation<\/h2>\n
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.<\/p>\n
\n
#<\/span> TestModule.psm1<\/span><\/span>\nfunction<\/span> F1<\/span> { }\nfunction<\/span> F2<\/span> { }\nfunction<\/span> F3<\/span> { }\n...\n#<\/span> 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<\/span><\/span>\nExport-ModuleMember<\/span> -<\/span>Function '<\/span>*'<\/span><\/span><\/pre>\n<\/div>\n
<\/span><\/a>Confused Intent<\/h2>\n
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.<\/p>\n
\n
#<\/span> TestModule.psm1<\/span><\/span>\nfunction<\/span> Invoke-Program<\/span> { }\nfunction<\/span> F1<\/span> { }\nfunction<\/span> F2<\/span> { }\n...\nfunction<\/span> F100<\/span> { }\n\n#<\/span> TestModule.psd1<\/span><\/span>\n@<\/span>{ ModuleVersion<\/span> =<\/span> '<\/span>1.0'<\/span><\/span>; RootModule<\/span> =<\/span> '<\/span>TestModule.psm1'<\/span><\/span>; FunctionsToExport<\/span> =<\/span> '<\/span>Invoke-Program'<\/span><\/span> }\n\nGet-Module<\/span> -<\/span>Name TestModule -<\/span>List |<\/span> Select -<\/span>ExpandProperty ExportedFunctions\n\nInvoke-Program<\/span><\/pre>\n<\/div>\n
<\/span><\/a>Security<\/h2>\n
PowerShell runs in Constrained Language<\/a> 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.<\/p>\n
So, it is important that a trusted script does not expose any vulnerabilities such as script injection<\/a> 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.<\/p>\n
\n
#<\/span> TestModule.psm1<\/span><\/span>\nfunction<\/span> Invoke-Program<\/span> { }\n#<\/span> Private helper function<\/span><\/span>\nfunction<\/span> Get-Type<\/span>\n{\n    param<\/span>( [string<\/span>] $source<\/span> )\n    Add-Type<\/span> -<\/span>TypeDefinition $source<\/span> -<\/span>PassThru\n}\n\n#<\/span> Exposes *all* module functions!<\/span><\/span>\nExport-ModuleMember<\/span> -<\/span>Function '<\/span>*'<\/span><\/span>\n\nGet-Module<\/span> -<\/span>Name TestModule -<\/span>List |<\/span> Select -<\/span>ExpandProperty ExportedFunctions\n\nInvoke-Program<\/span>\nGet-Type<\/span><\/pre>\n<\/div>\n
In the above example, Get-Type<\/code> module helper function is exported via wildcard along with the intended Invoke-Program<\/code> function. Since this is a trusted module Get-Type<\/code> runs in Full Language and exposes the ability to create arbitrary types.<\/p>\n
<\/span><\/a>Unintended Consequences<\/h3>\n
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.<\/p>\n
\n
#<\/span> TestModule.psm1<\/span><\/span>\nimport-Module<\/span> HelperMod1\n.<\/span> .\\CSharpHelpers.ps1\nfunction<\/span> Invoke-Program<\/span> { }\n\n#<\/span> Exposes *all* module functions!<\/span><\/span>\nExport-ModuleMember<\/span> -<\/span>Function '<\/span>*'<\/span><\/span>\n\nGet-Module<\/span> -<\/span>Name TestModule -<\/span>List |<\/span> Select -<\/span>ExpandProperty ExportedFunctions\nInvoke-Program<\/span>\nHelperFn1\nHelperFn2\nCompile-<\/span>CSharp<\/pre>\n<\/div>\n
<\/span><\/a>Module Function Export Restrictions<\/h3>\n
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.<\/p>\n