Skip to content

Commit 3fd3502

Browse files
yutingcyutingc
committed
Add a nother few rule documentations.
1 parent abd88e7 commit 3fd3502

9 files changed

+412
-0
lines changed

‎RuleDocumentation/AvoidShouldContinueWithoutForce.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
#AvoidShouldContinueWithoutForce
2+
**Severity Level: Warning**
3+
4+
5+
##Description
6+
7+
Functions that use ShouldContinue should have a boolean force parameter to allow user to bypass it.
8+
9+
##How to Fix
10+
11+
To fix a violation of this rule, please call ShouldContinue method in advanced functions when 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 Windows PowerShell.
12+
13+
##Example
14+
Wrong:
15+
16+
function Verb-Noun
17+
{
18+
[CmdletBinding(DefaultParameterSetName='Parameter Set 1',
19+
SupportsShouldProcess=$true,
20+
PositionalBinding=$false,
21+
HelpUri = 'http://www.microsoft.com/',
22+
ConfirmImpact='Medium')]
23+
[Alias()]
24+
[OutputType([String])]
25+
Param
26+
(
27+
# Param1 help description
28+
[Parameter(Mandatory=$true,
29+
ValueFromPipeline=$true,
30+
ValueFromPipelineByPropertyName=$true,
31+
ValueFromRemainingArguments=$false,
32+
Position=0,
33+
ParameterSetName='Parameter Set 1')]
34+
[ValidateNotNull()]
35+
[ValidateNotNullOrEmpty()]
36+
[ValidateCount(0,5)]
37+
[ValidateSet("sun", "moon", "earth")]
38+
[Alias("p1")]
39+
$Param1,
40+
# Param2 help description
41+
[Parameter(ParameterSetName='Parameter Set 1')]
42+
[AllowNull()]
43+
[AllowEmptyCollection()]
44+
[AllowEmptyString()]
45+
[ValidateScript({$true})]
46+
[ValidateRange(0,5)]
47+
[int]
48+
$Param2,
49+
# Param3 help description
50+
[Parameter(ParameterSetName='Another Parameter Set')]
51+
[ValidatePattern("[a-z]*")]
52+
[ValidateLength(0,15)]
53+
[String]
54+
$Param3
55+
)
56+
57+
Begin
58+
{
59+
$pscmdlet.ShouldContinue("Yes", "No")
60+
}
61+
Process
62+
{
63+
if ($pscmdlet.ShouldProcess("Target", "Operation"))
64+
{
65+
}
66+
}
67+
End
68+
{
69+
}
70+
}
71+
72+
Correct:
73+
74+
function Get-File
75+
{
76+
[CmdletBinding(DefaultParameterSetName='Parameter Set 1',
77+
SupportsShouldProcess=$true,
78+
PositionalBinding=$false,
79+
HelpUri = 'http://www.microsoft.com/',
80+
ConfirmImpact='Medium')]
81+
[Alias()]
82+
[OutputType([String])]
83+
Param
84+
(
85+
# Param1 help description
86+
[Parameter(Mandatory=$true,
87+
ValueFromPipeline=$true,
88+
ValueFromPipelineByPropertyName=$true,
89+
ValueFromRemainingArguments=$false,
90+
Position=0,
91+
ParameterSetName='Parameter Set 1')]
92+
[ValidateNotNull()]
93+
[ValidateNotNullOrEmpty()]
94+
[ValidateCount(0,5)]
95+
[ValidateSet("sun", "moon", "earth")]
96+
[Alias("p1")]
97+
$Param1,
98+
99+
# Param2 help description
100+
[Parameter(ParameterSetName='Parameter Set 1')]
101+
[AllowNull()]
102+
[AllowEmptyCollection()]
103+
[AllowEmptyString()]
104+
[ValidateScript({$true})]
105+
[ValidateRange(0,5)]
106+
[int]
107+
$Param2,
108+
109+
# Param3 help description
110+
[Parameter(ParameterSetName='Another Parameter Set')]
111+
[ValidatePattern("[a-z]*")]
112+
[ValidateLength(0,15)]
113+
[String]
114+
$Param3,
115+
[bool]
116+
$Force
117+
)
118+
119+
Begin
120+
{
121+
}
122+
Process
123+
{
124+
if ($pscmdlet.ShouldProcess("Target", "Operation"))
125+
{
126+
Write-Verbose "Write Verbose"
127+
Get-Process
128+
}
129+
}
130+
End
131+
{
132+
if ($pscmdlet.ShouldContinue("Yes", "No")) {
133+
}
134+
}
135+
}

‎RuleDocumentation/AvoidTrapStatement.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
#AvoidTrapStatement
2+
**Severity Level: Warning**
3+
4+
5+
##Description
6+
7+
The Trap keyword specifies a list of statements to run when a terminating error occurs. It is designed for administrators. For script developers, you should use try-catch-finally statement.
8+
9+
##How to Fix
10+
11+
To fix a violation of this rule, please remove Trap statements and use try-catch-finally statement instead.
12+
13+
##Example
14+
15+
Wrong：
16+
17+
function TrapTest
18+
{
19+
trap {"Error found: $_"}
20+
}
21+
22+
Correct:
23+
24+
function TrapTest
25+
{
26+
try
27+
{
28+
$a = New-Object "dafdf"
29+
$a | get-member
30+
}
31+
catch [System.Exception]
32+
{
33+
"Found error"
34+
}
35+
finally
36+
{
37+
"End the script"
38+
}
39+
}

‎RuleDocumentation/AvoidUninitializedVariable.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#AvoidUninitializedVariable
2+
**Severity Level: Warning**
3+
4+
5+
##Description
6+
7+
A variable is a unit of memory in which values are stored. Windows PowerShell controls access to variables, functions, aliases, and drives through a mechanism known as scoping. The scope of an item is another term for its visibility. Non-global variables must be initialized.
8+
9+
10+
##How to Fix
11+
12+
To fix a violation of this rule, please initialize non-global variables.
13+
14+
##Example
15+
16+
Wrong：
17+
18+
function NotGlobal {
19+
$localVars = "Localization?"
20+
$unitialized
21+
Write-Output $unitialized
22+
}
23+
24+
25+
Correct:
26+
27+
function NotGlobal {
28+
$localVars = "Localization?"
29+
Write-Output $localVars
30+
}

‎RuleDocumentation/AvoidUsingComputerNameHardcoded.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#AvoidUsingComputerNameHardcoded
2+
**Severity Level: Error**
3+
4+
5+
##Description
6+
7+
The ComputerName parameter of a cmdlet should not be hardcoded as this will expose sensitive information about the system.
8+
9+
##How to Fix
10+
11+
Please consider using full cmdlet name instead of alias.
12+
13+
##Example
14+
15+
Wrong：
16+
17+
Invoke-Command -Port 343 -ComputerName "hardcode1"
18+
Invoke-Command -ComputerName:"hardcode2"
19+
20+
21+
Correct:
22+
23+
Invoke-Command -ComputerName $comp
24+
Invoke-Command -ComputerName $env:COMPUTERNAME

‎RuleDocumentation/AvoidUsingFilePath.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
#AvoidUsingFilePath
2+
**Severity Level: Error**
3+
4+
5+
##Description
6+
7+
If a file path is used in a script that refers to a file on the computer or on the shared network, this may expose information about your computer. Furthermore, the file path may not work on other computer when they try to use the script.
8+
9+
##How to Fix
10+
11+
Please change the path of the file to non-rooted.
12+
13+
##Example
14+
15+
Wrong：
16+
17+
Write-Warning "E:\Code"
18+
Get-ChildItem \\scratch2\scratch\
19+
20+
21+
Correct:
22+
23+
Get-ChildItem "..\Test"

‎RuleDocumentation/AvoidUsingInvokeExpression.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
#AvoidUsingInvokeExpression
2+
**Severity Level: Warning**
3+
4+
5+
##Description
6+
7+
The Invoke-Expression cmdlet evaluates or runs a specified string as a command and returns the results of the expression or command. It can be extraordinarily powerful so it is not that you want to never use it but you need to be very careful about using it. In particular, you are probably on safe ground if the data only comes from the program itself. If you include any data provided from the user - you need to protect yourself from Code Injection.
8+
9+
10+
##How to Fix
11+
12+
To fix a violation of this rule, please remove Invoke-Expression from script and find other options instead.
13+
14+
##Example
15+
16+
Wrong：
17+
18+
Invoke-Expression "get-process"
19+
20+
Correct:
21+
22+
Get-process

‎RuleDocumentation/AvoidUsingPlainTextForPassword.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
#AvoidUsingPlainTextForPassword
2+
**Severity Level: Warning**
3+
4+
5+
##Description
6+
7+
Password parameters that take in plaintext will expose passwords and compromise the security of your system.
8+
9+
##How to Fix
10+
11+
To fix a violation of this rule, please use SecurityString as the type of password parameter.
12+
13+
##Example
14+
15+
Wrong：
16+
17+
function Verb-Noun
18+
{
19+
[CmdletBinding()]
20+
[Alias()]
21+
[OutputType([int])]
22+
Param
23+
(
24+
# Param1 help description
25+
[Parameter(Mandatory=$true,
26+
ValueFromPipelineByPropertyName=$true,
27+
Position=0)]
28+
$Param1,
29+
# Param2 help description
30+
[int]
31+
$Param2,
32+
[securestring]
33+
$Password,
34+
[System.Security.SecureString]
35+
$pass,
36+
[securestring[]]
37+
$passwords,
38+
$passphrases,
39+
$passwordparam
40+
)
41+
}
42+
43+
function TestFunction($password, [System.Security.SecureString[]]passphrases, [string]$passThru){
44+
}
45+
46+
47+
Correct:
48+
49+
function Test-Script
50+
{
51+
[CmdletBinding()]
52+
[Alias()]
53+
[OutputType([int])]
54+
Param
55+
(
56+
# Param1 help description
57+
[Parameter(Mandatory=$true,
58+
ValueFromPipelineByPropertyName=$true,
59+
Position=0)]
60+
$Param1,
61+
# Param2 help description
62+
[int]
63+
$Param2,
64+
[securestring]
65+
$Password,
66+
[System.Security.SecureString]
67+
$pass,
68+
[securestring[]]
69+
$passwords,
70+
[securestring]
71+
$passphrases,
72+
[securestring]
73+
$passwordparam,
74+
[string]
75+
$PassThru
76+
)
77+
...
78+
}
79+
80+
function TestFunction([securestring]$password, [System.Security.SecureString[]]$passphrases, [securestring[]]$passes){
81+
}

‎RuleDocumentation/AvoidUsingUsernameAndPasswordParams

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
#AvoidUsingUsernameAndPasswordParams
2+
**Severity Level: Error**
3+
4+
5+
##Description
6+
7+
Functions should only take in a credential parameter of type PSCredential instead of username and password parameters.
8+
9+
##How to Fix
10+
11+
To fix a violation of this rule, please pass username and password as a PSCredential type parameter.
12+
13+
##Example
14+
15+
Wrong：
16+
17+
[int]
18+
$Param2,
19+
[securestring]
20+
$Password,
21+
[string]
22+
$username
23+
24+
25+
26+
Correct:
27+
28+
function MyFunction3 ([PSCredential]$username, $passwords)
29+
{
30+
}

0 commit comments

Comments
 (0)