From b23d4f85a4452fd28aaf1513c771501e9497e837 Mon Sep 17 00:00:00 2001 From: Xelu86 Date: Mon, 1 Jun 2026 12:35:43 -0400 Subject: [PATCH] Freshness --- .../Rules/AvoidSemicolonsAsLineTerminators.md | 28 ++++++----- .../Rules/AvoidShouldContinueWithoutForce.md | 23 +++++---- .../Rules/AvoidTrailingWhitespace.md | 47 +++++++++++++++++-- ...voidUsingAllowUnencryptedAuthentication.md | 21 ++++----- .../Rules/AvoidUsingBrokenHashAlgorithms.md | 20 ++++---- 5 files changed, 91 insertions(+), 48 deletions(-) diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidSemicolonsAsLineTerminators.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidSemicolonsAsLineTerminators.md index 4716238..16fe3fa 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidSemicolonsAsLineTerminators.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidSemicolonsAsLineTerminators.md @@ -1,6 +1,6 @@ --- description: Avoid semicolons as line terminators -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidSemicolonsAsLineTerminators --- @@ -10,14 +10,14 @@ title: AvoidSemicolonsAsLineTerminators ## Description -Lines should not end with a semicolon. - -> [!NOTE] -> This rule is not enabled by default. The user needs to enable it through settings. +Avoid using semicolons at the end of lines. In PowerShell, line-ending semicolons are redundant and +detract from code readability. Although semicolons serve as statement separators on a single line, +using them as line terminators is discouraged. This rule promotes cleaner, more maintainable code by +removing unnecessary semicolons. This rule isn't enabled by default. ## Example -### Wrong +### Noncompliant ```powershell Install-Module -Name PSScriptAnalyzer; $a = 1 + $b; @@ -28,7 +28,7 @@ Install-Module -Name PSScriptAnalyzer; $a = 1 + $b ``` -### Correct +### Compliant ```powershell Install-Module -Name PSScriptAnalyzer; $a = 1 + $b @@ -43,14 +43,18 @@ $a = 1 + $b ```powershell Rules = @{ - PSAvoidSemicolonsAsLineTerminators = @{ - Enable = $true + PSAvoidSemicolonsAsLineTerminators = @{ + Enable = $true } } ``` -### Parameters +## Parameters + +### Enable + +Enables (`$true`) the rule during ScriptAnalyzer invocation. -#### Enable: bool (Default value is `$false`) +### Disable -Enable or disable the rule during ScriptAnalyzer invocation. +Disables (`$false`) the rule during ScriptAnalyzer invocation. Default value is `$false`. diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidShouldContinueWithoutForce.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidShouldContinueWithoutForce.md index 189989a..29c402c 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidShouldContinueWithoutForce.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidShouldContinueWithoutForce.md @@ -1,6 +1,6 @@ --- description: Avoid Using ShouldContinue Without Boolean Force Parameter -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidShouldContinueWithoutForce --- @@ -10,18 +10,16 @@ title: AvoidShouldContinueWithoutForce ## Description -Functions that use ShouldContinue should have a boolean force parameter to allow user to bypass it. +Functions that use `ShouldContinue` should have a boolean `Force` parameter to allow users to bypass +the confirmation prompt. When using `ShouldContinue` in advanced functions, call it after the +`ShouldProcess` method returns `$true`. -You can get more details by running `Get-Help about_Functions_CmdletBindingAttribute` and -`Get-Help about_Functions_Advanced_Methods` command in PowerShell. - -## How - -Call the `ShouldContinue` method in advanced functions when `ShouldProcess` method returns `$true`. +To learn more, see [about_Functions_CmdletBindingAttribute][01] and +[about_Functions_Advanced_Methods][02]. ## Example -### Wrong +### Noncompliant ```powershell Function Test-ShouldContinue @@ -39,7 +37,7 @@ Function Test-ShouldContinue } ``` -### Correct +### Compliant ```powershell Function Test-ShouldContinue @@ -57,3 +55,8 @@ Function Test-ShouldContinue } } ``` + + + +[01]: /powershell/module/microsoft.powershell.core/about/about_functions_cmdletbindingattribute +[02]: /powershell/module/microsoft.powershell.core/about/about_functions_advanced_methods diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidTrailingWhitespace.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidTrailingWhitespace.md index 416948c..a41dff3 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidTrailingWhitespace.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidTrailingWhitespace.md @@ -1,6 +1,6 @@ --- description: Avoid trailing whitespace -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidTrailingWhitespace --- @@ -10,5 +10,46 @@ title: AvoidTrailingWhitespace ## Description -Lines should not end with whitespace characters. This can cause problems with the line-continuation -backtick, and also clutters up future commits to source control. +Lines shouldn't end with trailing whitespace characters. Trailing whitespace makes diffs harder to +review and can introduce subtle problems when line continuation uses a backtick (`), because the +backtick must be the last character on the line. + +Keeping lines free of trailing whitespace improves readability and helps keep source control history +clean. + +To learn more, see [about_Parsing][01]. + +## Example + +### Noncompliant + +```powershell +# The next line ends with a trailing space after the backtick. +Get-Process ` +| Where-Object { $_.CPU -gt 100 } +``` + +When you run this script, PowerShell throws a parser error because the trailing space prevents line +continuation. For example: + +```output +PS C:\WINDOWS\system32> Get-Process ` +| Where-Object { $_.CPU -gt 100 } +At line:2 char:1 ++ | Where-Object { $_.CPU -gt 100 } ++ ~ +An empty pipe element is not allowed. + + CategoryInfo : ParserError: (:) [], ParentContainsErrorRecordException + + FullyQualifiedErrorId : EmptyPipeElement +``` + +### Compliant + +```powershell +Get-Process ` +| Where-Object { $_.CPU -gt 100 } +``` + + + +[01]: /powershell/module/microsoft.powershell.core/about/about_parsing diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingAllowUnencryptedAuthentication.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingAllowUnencryptedAuthentication.md index 20451e6..80dfee0 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingAllowUnencryptedAuthentication.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingAllowUnencryptedAuthentication.md @@ -1,6 +1,6 @@ --- description: Avoid sending credentials and secrets over unencrypted connections -ms.date: 02/28/2024 +ms.date: 06/01/2026 ms.topic: reference title: AvoidUsingAllowUnencryptedAuthentication --- @@ -10,25 +10,22 @@ title: AvoidUsingAllowUnencryptedAuthentication ## Description -Avoid using the **AllowUnencryptedAuthentication** parameter of `Invoke-WebRequest` and -`Invoke-RestMethod`. When using this parameter, the cmdlets send credentials and secrets over -unencrypted connections. This should be avoided except for compatibility with legacy systems. +The **AllowUnencryptedAuthentication** parameter of `Invoke-WebRequest` and `Invoke-RestMethod` +permits credentials and secrets to be transmitted over unencrypted connections, creating a security +risk. Avoid using this parameter unless you must maintain compatibility with legacy systems that +require unencrypted authentication. -For more details, see [Invoke-RestMethod](xref:Microsoft.PowerShell.Utility.Invoke-RestMethod). +To learn more, see [Invoke-RestMethod](xref:Microsoft.PowerShell.Utility.Invoke-RestMethod). -## How +## Example -Avoid using the **AllowUnencryptedAuthentication** parameter. - -## Example 1 - -### Wrong +### Noncompliant ```powershell Invoke-WebRequest foo -AllowUnencryptedAuthentication ``` -### Correct +### Compliant ```powershell Invoke-WebRequest foo diff --git a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md index 32bb464..544a0a1 100644 --- a/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md +++ b/reference/docs-conceptual/PSScriptAnalyzer/Rules/AvoidUsingBrokenHashAlgorithms.md @@ -1,6 +1,6 @@ --- description: Avoid using broken hash algorithms -ms.date: 06/28/2023 +ms.date: 06/01/2026 ms.topic: reference title: AvoidUsingBrokenHashAlgorithms --- @@ -10,23 +10,21 @@ title: AvoidUsingBrokenHashAlgorithms ## Description -Avoid using the broken algorithms MD5 or SHA-1. +Avoid using the cryptographically broken hash algorithms `MD5` and `SHA-1`. These algorithms are +vulnerable to collision attacks and are no longer considered secure for cryptographic purposes. -## How - -Replace broken algorithms with secure alternatives. MD5 and SHA-1 should be replaced with SHA256, -SHA384, SHA512, or other safer algorithms when possible, with MD5 and SHA-1 only being utilized by -necessity for backwards compatibility. +Replace `MD5` and `SHA-1` with secure alternatives such as `SHA256`, `SHA384`, or `SHA512`. Use +broken algorithms only when absolutely necessary for backwards compatibility with legacy systems. ## Example 1 -### Wrong +### Noncompliant ```powershell Get-FileHash foo.txt -Algorithm MD5 ``` -### Correct +### Compliant ```powershell Get-FileHash foo.txt -Algorithm SHA256 @@ -34,13 +32,13 @@ Get-FileHash foo.txt -Algorithm SHA256 ## Example 2 -### Wrong +### Noncompliant ```powershell Get-FileHash foo.txt -Algorithm SHA1 ``` -### Correct +### Compliant ```powershell Get-FileHash foo.txt