Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
85 lines (70 sloc) 11.3 KB

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.