PowerShell linting with ScriptAnalyzer

ScriptAnalyzer is a static code analysis tool developed and maintained by Microsoft, specifically designed for PowerShell.
It helps developers and system administrators improve the quality, consistency, and security of their PowerShell scripts by automatically scanning code for issues.

Style Rule Enforcement:

Ensures scripts follow consistent formatting and naming conventions.
Examples: indentation, casing of cmdlet names, use of aliases.

Best Practice Validation:

Encourages use of approved cmdlets and patterns.
Examples: avoiding deprecated cmdlets, using Write-Verbose instead of Write-Host.

Bug and Security Detection:

Identifies potential runtime errors and insecure coding patterns.
Examples: use of Invoke-Expression, missing error handling, unsafe file paths.

Using ScriptAnalyzer

Linting with PowerShell is performed using the PSScriptAnalyzer module. You can perform the analysis through command-line by calling the Invoke-ScriptAnalyzer cmdlet. Its main goal is to promote proven practices, patterns and behaviors while avoiding common pitfalls that can easily lead to bugs or make code harder to maintain.

Each time a gitlab pipeline is ran the following ScriptAnalyzer command executes against scripts and modules stored under the PowerShell directory.

Invoke-ScriptAnalyzer -Path ./*

In order for the merge request to be merged, pipelines must run successfully.

Reviewing Violations

Review the pipeline output to determine which PowerShell rules and recommendations were triggered.

Some of the violations and descriptions are self explanatory. However, some are not and referring to the official rule documentation is required.

PSScriptAnalyzerSettings

PSScriptAnalyzerSettings.psd1 is a PowerShell data file used to configure how PSScriptAnalyzer—Microsoft's static code analysis tool for PowerShell—evaluates scripts. It allows you to define custom rulesets, exclusions, severity levels, and rule enforcement strategies.

GitLab pipeline's will automatically detect the presence of PSScriptAnalyzerSettings.psd1 and utilize it.

This file is especially useful in CI/CD pipelines where consistent linting and style enforcement are critical. You can:

Enable or disable specific rules (e.g., avoid Write-Host).
Set severity levels (e.g., warning vs error).
Exclude files or folders from analysis.
Customize rule behavior for your organization's standards.

Example:

@{
    ExcludeRules = @(
        'PSAvoidUsingWriteHost',
        'PSUseProcessBlockForPipelineCommand',
        'PSAvoidGlobalVars',
        'PSAvoidUsingUsernameAndPasswordParams',
        'PSUseShouldProcessForStateChangingFunctions',
        'PSProvideCommentHelp',
        'PSAvoidUsingConvertToSecureStringWithPlainText',
        'PSUseSingularNouns',
        'PSAvoidUsingWMICmdlet',
        'PSUseDeclaredVarsMoreThanAssignments'
    )
}