PSSARuleSeverities.md

DSC Resource Kit PSSA Rule Severities

These are the PS Script Analyzer rules that must be used for DSC resources in DSC Resource Kit.

In tests and examples the PS Script Analyzer rules may be suppressed on a case-by-case basis (up to the community and the maintainer).

These rules are also available as an analyzer rules settings file in the DscResource.Template, used together with the Visual Studio Code settings file, it detects if any code is not compliant with these rules. To manually run PS Script Analyzer using the analyzer rules settings files, once the .psd1 file is copied from the template, run the following.

Invoke-ScriptAnalyzer -Settings '.vscode\analyzersettings.psd1'

Rules

Must Pass

All DSC Resources must pass these rules. They are not allowed to be suppressed.

Rule Name	PSSA Type	Why Error?
PSAvoidDefaultValueForMandatoryParameter	Warning	This indicates an incorrect use of PowerShell. Default mandatory parameters will be overwritten by the user.
PSAvoidDefaultValueSwitchParameter	Warning	This indicates an incorrect use of PowerShell. Switch parameters should always default to 'not provided'.
PSAvoidInvokingEmptyMembers	Warning	Extra empty members can make code confusing and messy.
PSAvoidNullOrEmptyHelpMessageAttribute	Warning	This indicates an incorrect use of PowerShell. The HelpMessage attribute should not be provided if it is null or empty.
PSAvoidUsingCmdletAliases	Warning	Alias's may change hence the presence of an alias makes code potentially unstable. The base cmdlet should be used instead.
PSAvoidUsingComputerNameHardcoded	Error	Hard-coding the computer name reveals sensitive system information. In addition, DSC Resources should be able to run on computers with any name.
PSAvoidUsingDeprecatedManifestFields	Warning	All manifests should stay updated with the correct manifest fields.
PSAvoidUsingEmptyCatchBlock	Warning	This indicates an incorrect use of PowerShell. Catch blocks should not be provided if empty.
PSAvoidUsingInvokeExpression	Warning	Invoke-Expression is vulnerable to string injection.
PSAvoidUsingPositionalParameters	Info	Named parameters should be used instead.
PSAvoidShouldContinueWithoutForce	Warning	If ShouldContinue is used, it should be used correctly with the Force parameter.
PSAvoidUsingWMICmdlet	Warning	The author should use CIM cmdlets instead to comply with WSMan standards.
PSAvoidUsingWriteHost	Warning	Write-Verbose should be used instead.
PSDSCReturnCorrectTypesForDSCFunctions	Info	Required for the resource to work.
PSDSCStandardDSCFunctionsInResource	Error	Required for the resource to work.
PSDSCUseIdenticalMandatoryParametersForDSC	Error	Required for the resource to work.
PSDSCUseIdenticalParametersForDSC	Error	Required for the resource to work.
PSMisleadingBacktick	Warning	Extra backticks are not necessary and indicate that the code is not clean.
PSMissingModuleManifestField	Warning	All manifests should stay updated with the correct manifest fields.
PSPossibleIncorrectComparisonWithNull	Warning	$null should always be on the left side of comparisons in PowerShell in case the item you are comparing $null against is an array, may be an array in the future, or turns into an array due to an error.
PSProvideCommentHelp	Info	All exported functions should be documented with comment help.
PSReservedCmdletChar	Warning	This indicates that the code won't run.
PSReservedParams	Warning	Reserved params are reserved. Don't redefine them.
PSUseApprovedVerbs	Warning	Authors must follow PowerShell best practices by using only approved verbs.
PSUseCmdletCorrectly	Warning	This indicates that the author did not provide parameters required for a cmdlet.
PSUseOutputTypeCorrectly	Info	This ensures that all functions always return the correct types.

Flag - Occasionally can be overruled with approval

DSC Resources should pass these rules, but there are cases where these rules are allowed to be suppressed.

Rule Name	PSSA Type	Cases Where Rule Suppression Approved
PSAvoidGlobalVars	Warning	Setting $global:DSCMachineStatus = 1 to trigger a machine reboot.
PSAvoidUsingConvertToSecureStringWithPlainText	Error	Some resources may have outside dependencies that require conversion with plaintext.
PSAvoidUsingPlainTextForPassword	Warning	Some resources may have outside dependencies that require insecure plaintext passwords.
PSAvoidUsingUsernameAndPasswordParams	Error	The username is a key for the resource.
PSDSCUseVerboseMessageInDSCResource	Info	A helper function is called which in turn calls Write-Verbose.
PSShouldProcess	Warning	A helper function is called which in turn calls ShouldProcess.
PSUseDeclaredVarsMoreThanAssignments	Warning	The variable is used on the same line as its assignment. The variable is an approved global or environment variable.
PSUsePSCredentialType	Warning	Some resources may have outside dependencies that require string credentials.

Ignore

These rules will not be run on DSC resources and can be ignored. They do not need to be suppressed.

Rule Name	PSSA Type	Why Ignored?
PSDSCDscExamplesPresent	Info	High quality resources must have examples, but this rule doesn't correctly test this.
PSDSCDscTestsPresent	Info	High quality resources must have tests, but this rule doesn't correctly test this.
PSUseBOMForUnicodeEncodedFile	Warning	There is already a test in place to ensure that all files except the mofs are not in Unicode. The mofs must be in ASCII.
PSUseShouldProcessForStateChangingFunctions	Warning	This will trigger for Set-TargetResource which actually should not have ShouldProcess in this case. DSC Resources need to be able to run remotely without user confirmation or overrides.
PSUseSingularNouns	Warning	Fixing this rule can make function names inaccurate and usually does not result in improved code.
PSUseToExportFieldsInManifest	Warning	We currently approve of using '*' for these fields in the module manifests since the exported members are often in flux due to the open source nature of the Resource Kit.
PSUseUTF8EncodingForHelpFile	Warning	DSC Resources do not have help files.