Add Optional PSUseConstrainedLanguageMode rule by joshcorr · Pull Request #2165 · PowerShell/PSScriptAnalyzer

joshcorr · 2026-03-17T15:54:19Z

PR Summary

This PR adds a new rule PSUseConstrainedLanguageMode that identifies PowerShell patterns incompatible with Constrained Language Mode, helping developers ensure scripts work in restricted environments. This rule is a Warning, but is optional and not enabled by default.

New files:
Rules/UseConstrainedLanguageMode.cs - Implements 14 CLM restriction checks
Tests/Rules/UseConstrainedLanguageMode.tests.ps1 - Adds 46 comprehensive tests
docs/Rules/UseConstrainedLanguageMode.md - Provides complete user documentation

Modified files;

Rules/strings.resx - Adds 16 new diagnostic message strings

Features
Detects CLM Violations:

Add-Type usage (code compilation)
Disallowed COM objects (only allows Scripting.Dictionary, Scripting.FileSystemObject, VBScript.RegExp)
Disallowed .NET types (validates ~70 allowed types including primitives, collections, PowerShell types)
PowerShell classes (class keyword)
XAML/WPF usage
Invoke-Expression usage
Dot-sourcing patterns
Type constraints, expressions, and casts
Member invocations on disallowed types
Module manifest wildcards and .ps1 references

Signature Awareness:

Detects signature blocks (# SIG # Begin signature block)
Applies selective checking to signed scripts (dot-sourcing, parameter types, manifests only)
Applies full checking to unsigned scripts

Array Type Support:

Handles array notation correctly ([string[]], [int[][]])
Strips brackets and validates base types

Configuration:

IgnoreSignatures property (default: false) bypasses signature detection and enforces full CLM compliance for all scripts

Testing:

PR Checklist

PR has a meaningful title
- Use the present tense and imperative mood when describing your changes
Summarized changes
Change is not breaking
Make sure all .cs, .ps1 and .psm1 files have the correct copyright header
Make sure you've added a new test if existing tests do not effectively test the code changed and/or updated documentation
This PR is ready to merge and is not Work in Progress.
- If the PR is work in progress, please add the prefix WIP: to the beginning of the title and remove the prefix when the PR is ready.

…al rule

Copilot

Pull request overview

Adds a new optional ScriptAnalyzer rule (PSUseConstrainedLanguageMode) to detect PowerShell patterns that are incompatible with Constrained Language Mode (CLM), along with tests and documentation so users can opt into CLM-focused linting.

Changes:

Added UseConstrainedLanguageMode rule implementation to detect multiple CLM-incompatible patterns, with special handling for signature blocks.
Added a comprehensive Pester test suite for the new rule.
Added end-user documentation and new localized resource strings for diagnostics.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
`Rules/UseConstrainedLanguageMode.cs`	Implements the new rule logic (CLM checks, signature-block detection, manifest checks).
`Tests/Rules/UseConstrainedLanguageMode.tests.ps1`	Adds tests covering the new rule’s detections and signature behavior.
`docs/Rules/UseConstrainedLanguageMode.md`	Documents what the rule flags, signed vs unsigned behavior, and configuration.
`Rules/Strings.resx`	Adds diagnostic strings used by the new rule (and updates file header/encoding).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Rules/UseConstrainedLanguageMode.cs

Rules/Strings.resx

Tests/Rules/UseConstrainedLanguageMode.tests.ps1

Rules/Strings.resx

docs/Rules/UseConstrainedLanguageMode.md

liamjpeters · 2026-03-17T17:26:41Z

👋 @joshcorr,

I wonder if UseConstrainedLanguageMode is the best name for this. The rule isn't checking if you're using/enabling constrained language mode, but rather that you're conforming to it's restrictions at design-time.

Perhaps something like ConformToConstrainedLanguageMode could be more on the money? One to consider.

joshcorr · 2026-03-18T06:13:36Z

Hi @liamjpeters thanks for the feedback. I named the rule to conform to the existing naming structure Use.. over some of the other leading verbs I found in the project (Avoid, Possible, etc). I do see this rule trying to check for implementation of language specific features (i.e. will this script use constrained language mode correctly), so the name doesn't feel that odd to me, but I see your point. Will wait to see if Andy or others have a strong opinion on the naming.

bergmeister · 2026-03-18T19:15:31Z

Rules/Strings.resx

can you please tidy away the whitespace diff please? might be easiest to just copy paste the first 58 lines from main over this

Fixed in the latest commit.

bergmeister · 2026-03-18T19:17:28Z

Wow, what a great idea and implementation @joshcorr Build seems to be currently broken, if you could fix that would be great (maybe it's simply due to that whitespace diff in the xml file, msbuild can be picky at times.
Please bear with us as it's a big change to review but very happy to have it :-)

bergmeister · 2026-03-18T19:49:34Z

Rules/UseConstrainedLanguageMode.cs

+                    }
+
+                    // Only flag if COM object name was found AND it's not in the allowed list
+                    if (!string.IsNullOrWhiteSpace(comObjectValue) && !AllowedComObjects.Contains(comObjectValue))


minor but wouldn't it reader better as !comObjectValue.IsNullOrWhiteSpace() since comObjectValue is already typed as string? similar a bit below

I looked into this and since the IsNullOrWhiteSpace() is a public static method on the string class, it can't be called from a string object., but rather from the class.

ah, it's been clearly some time ago that I actively wrote a lot of C#, would have thought hoped that .NET would've improved on those things but seems not

Copilot

Pull request overview

Adds a new optional ScriptAnalyzer rule to warn about PowerShell constructs that are incompatible with Constrained Language Mode (CLM), along with accompanying tests and documentation.

Changes:

Introduces PSUseConstrainedLanguageMode rule implementation (signature-aware + CLM pattern checks).
Adds a comprehensive Pester test suite for the rule.
Adds rule documentation and localized diagnostic strings.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`Rules/UseConstrainedLanguageMode.cs`	Implements the new CLM compatibility rule (AST checks + signature-aware behavior + caching).
`Tests/Rules/UseConstrainedLanguageMode.tests.ps1`	Adds Pester coverage for the new rule, including signed/unsigned scenarios and performance-related validation.
`docs/Rules/UseConstrainedLanguageMode.md`	Documents rule purpose, configuration, and remediation guidance.
`docs/Rules/README.md`	Adds the new rule to the rules index table.
`Rules/Strings.resx`	Adds localized strings for rule name/description and diagnostic messages.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Tests/Rules/UseConstrainedLanguageMode.tests.ps1

docs/Rules/UseConstrainedLanguageMode.md

Rules/Strings.resx

Rules/UseConstrainedLanguageMode.cs

+            // Find all assignment statements in this scope
+            var assignments = scope.FindAll(testAst => testAst is AssignmentStatementAst, true);


docs/Rules/UseConstrainedLanguageMode.md

bergmeister · 2026-03-19T17:44:25Z

@joshcorr We merged a few other PRs that now caused a merge conflict here, can you pull latest of main into your branch and resolve conflict please?
I also kicked off build, which is working now but one of your new tests is failing, please have a look at it as well please: https://github.com/PowerShell/PSScriptAnalyzer/actions/runs/23281623145/job/67789974715?pr=2165#step:7:93

Thanks :-)

andyleejordan

Thanks @joshcorr, hope the session goes well. I'll get this out!

joshcorr added 11 commits March 7, 2026 14:30

Add UseConstrainedLanguageMode rule and tests

67e239a

Enhance CLM rule: restrict types, COM objects, add tests

e616116

Enhance detection of disallowed types in CLM rule

790fe8c

Detect and flag class definitions in Constrained Language

b4b566c

Enhance CLM rule to check module manifests for wildcards/.ps1

f8ab608

Differentiate CLM checks for signed vs unsigned scripts

1be14c8

Improve dot-sourcing detection and expand CLM rule tests

a23e14f

Add IgnoreSignatures option to CLM rule and improve type checks

1abc86a

Add documentation for PSUseConstrainedLanguageMode rule

3526267

Increase severity of UseConstrainedLanguageMode to Warning for option…

d87628d

…al rule

Update test to expect 'Warning' severity instead of 'Info'

69b200f

joshcorr requested review from a team, bergmeister, michaeltlombardi and sdwheeler as code owners March 17, 2026 15:54

Copilot AI review requested due to automatic review settings March 17, 2026 15:54

Copilot started reviewing on behalf of joshcorr March 17, 2026 15:55 View session

Copilot AI reviewed Mar 17, 2026

View reviewed changes

joshcorr added 4 commits March 17, 2026 10:35

Making copilot suggested edits

17f1a24

Detect and flag [PSCustomObject]@{} in CLM scripts

a4a4a93

Add UseConstrainedLanguageMode rule to README.md

5336b8f

Merge branch 'main' into addCLMRules

aedace7

bergmeister reviewed Mar 18, 2026

View reviewed changes

bergmeister requested a review from Copilot March 18, 2026 19:45

bergmeister reviewed Mar 18, 2026

View reviewed changes

Copilot AI reviewed Mar 18, 2026

View reviewed changes

bergmeister reviewed Mar 18, 2026

View reviewed changes

docs/Rules/UseConstrainedLanguageMode.md Outdated Show resolved Hide resolved

Update CLM rule: tighten types, docs, and add error string

cba70f3

joshcorr added 4 commits March 19, 2026 18:56

Add platform checks to CLM tests for cross-platform support

02598ac

Merge branch 'main' into addCLMRules

9c91f63

Add missing end tag after merge conflict from main

650d050

Add CLM rule ScriptsToProcess; Fix wildcard and dotsource bug

3d3afc8

andyleejordan approved these changes Mar 20, 2026

View reviewed changes

andyleejordan merged commit 6cfc260 into PowerShell:main Mar 20, 2026
4 checks passed

		// Find all assignment statements in this scope
		var assignments = scope.FindAll(testAst => testAst is AssignmentStatementAst, true);

Conversation

joshcorr commented Mar 17, 2026

PR Summary

PR Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

liamjpeters commented Mar 17, 2026

Uh oh!

joshcorr commented Mar 18, 2026

Uh oh!

bergmeister Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

joshcorr Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

bergmeister commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bergmeister Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joshcorr Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

bergmeister Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bergmeister commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andyleejordan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bergmeister commented Mar 18, 2026 •

edited

Loading

bergmeister Mar 18, 2026 •

edited

Loading

bergmeister commented Mar 19, 2026 •

edited

Loading