Merge pull request #106 from KarolKaczmarek/DscTestsPresentRule

Adding DscTestsPresent rule

Author: yutingc

CustomizedRuleDocumentation.md

@@ -0,0 +1,158 @@
+##Documentation for Customized Rules in PowerShell Scripts
+PSScriptAnalyzer uses MEF(Managed Extensibility Framework) to import all rules defined in the assembly. It can also consume rules written in PowerShell scripts. When calling Invoke-ScriptAnalyzer, users can pass customized rules using parameter -CustomizedRulePath to apply rule checkings on the scripts. 
+
+This documentation serves as a basic guideline on how to define customized rules.
+
+###Basics
+- Functions should have comment-based help. Make sure .DESCRIPTION field is there, as it will be consumed as rule description for the customized rule.
+```
+<#
+.SYNOPSIS
+    Name of your rule.
+.DESCRIPTION
+    This would be the description of your rule. Please refer to Rule Documentation for consistent rule messages.
+.EXAMPLE
+.INPUTS
+.OUTPUTS
+.NOTES
+#>
+```
+
+- Output type should be DiagnosticRecord:
+```
+[OutputType([Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
+```
+
+- Make sure each function takes either a Token or an Ast as a parameter
+```
+Param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.Language.ScriptBlockAst]
+        $testAst
+    )
+```
+
+- DiagnosticRecord should have four properties: Message, Extent, RuleName and Severity
+```
+$result = [Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord[]]@{"Message"  = "This is a sample rule"; 
+     "Extent"   = $ast.Extent;
+     "RuleName" = $PSCmdlet.MyInvocation.InvocationName;
+     "Severity" = "Warning"}
+```
+
+- Make sure you export the function(s) at the end of the script using Export-ModuleMember
+```
+Export-ModuleMember -Function (FunctionName)
+```
+
+###Example
+```
+<#
+.SYNOPSIS
+    Uses #Requires -RunAsAdministrator instead of your own methods.
+.DESCRIPTION
+    The #Requires statement prevents a script from running unless the Windows PowerShell version, modules, snap-ins, and module and snap-in version prerequisites are met. 
+    From Windows PowerShell 4.0, the #Requires statement let script developers require that sessions be run with elevated user rights (run as Administrator). 
+    Script developers does not need to write their own methods any more.
+    To fix a violation of this rule, please consider to use #Requires -RunAsAdministrator instead of your own methods.
+.EXAMPLE
+    Measure-RequiresRunAsAdministrator -ScriptBlockAst $ScriptBlockAst
+.INPUTS
+    [System.Management.Automation.Language.ScriptBlockAst]
+.OUTPUTS
+    [Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord[]]
+.NOTES
+    None
+#>
+function Measure-RequiresRunAsAdministrator
+{
+    [CmdletBinding()]
+    [OutputType([Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord[]])]
+    Param
+    (
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [System.Management.Automation.Language.ScriptBlockAst]
+        $ScriptBlockAst
+    )
+
+    Process
+    {
+        $results = @()
+        try
+        {
+            #region Define predicates to find ASTs.
+            # Finds specific method, IsInRole.
+            [ScriptBlock]$predicate1 = {
+                param ([System.Management.Automation.Language.Ast]$Ast)
+                [bool]$returnValue = $false
+                if ($Ast -is [System.Management.Automation.Language.MemberExpressionAst])
+                {
+                    [System.Management.Automation.Language.MemberExpressionAst]$meAst = $ast;
+                    if ($meAst.Member -is [System.Management.Automation.Language.StringConstantExpressionAst])
+                    {
+                        [System.Management.Automation.Language.StringConstantExpressionAst]$sceAst = $meAst.Member;
+                        if ($sceAst.Value -eq "isinrole")
+                        {
+                            $returnValue = $true;
+                        }
+                    }
+                }
+                return $returnValue
+            }
+
+            # Finds specific value, [system.security.principal.windowsbuiltinrole]::administrator.
+            [ScriptBlock]$predicate2 = {
+                param ([System.Management.Automation.Language.Ast]$Ast)
+                [bool]$returnValue = $false
+                if ($ast -is [System.Management.Automation.Language.AssignmentStatementAst])
+                {
+                    [System.Management.Automation.Language.AssignmentStatementAst]$asAst = $Ast;
+                    if ($asAst.Right.ToString().ToLower() -eq "[system.security.principal.windowsbuiltinrole]::administrator")
+                    {
+                        $returnValue = $true
+                    }
+                }
+                return $returnValue
+            }
+            #endregion
+            #region Finds ASTs that match the predicates.
+        
+            [System.Management.Automation.Language.Ast[]]$methodAst     = $ScriptBlockAst.FindAll($predicate1, $true)
+            [System.Management.Automation.Language.Ast[]]$assignmentAst = $ScriptBlockAst.FindAll($predicate2, $true)
+            if ($null -ne $ScriptBlockAst.ScriptRequirements)
+            {
+                if ((!$ScriptBlockAst.ScriptRequirements.IsElevationRequired) -and 
+                    ($methodAst.Count -ne 0) -and ($assignmentAst.Count -ne 0))
+                {
+                    $result = [Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord]@{"Message"  = $Messages.MeasureRequiresRunAsAdministrator; 
+                                                "Extent"   = $assignmentAst.Extent;
+                                                "RuleName" = $PSCmdlet.MyInvocation.InvocationName;
+                                                "Severity" = "Information"}
+                    $results += $result               
+                }
+            }
+            else
+            {
+                if (($methodAst.Count -ne 0) -and ($assignmentAst.Count -ne 0))
+                {
+                    $result = [Microsoft.Windows.Powershell.ScriptAnalyzer.Generic.DiagnosticRecord]@{"Message"  = $Messages.MeasureRequiresRunAsAdministrator; 
+                                                "Extent"   = $assignmentAst.Extent;
+                                                "RuleName" = $PSCmdlet.MyInvocation.InvocationName;
+                                                "Severity" = "Information"}
+                    $results += $result               
+                }        
+            }
+            return $results
+            #endregion 
+        }
+        catch
+        {
+            $PSCmdlet.ThrowTerminatingError($PSItem)
+        }
+    }
+}
+```
+More examples can be found in *Tests\Engine\CommunityRules*

Engine/Generic/ExternalRule.cs

@@ -28,7 +28,7 @@ internal class ExternalRule : IExternalRule
         string param   = string.Empty;
         string srcName = string.Empty;
         string modPath = string.Empty;
-        
+        string paramType = string.Empty;
 
         public string GetName()
         {
@@ -55,6 +55,11 @@ public SourceType GetSourceType()
             return SourceType.Module;
         }
 
+        public string GetParameterType()
+        {
+            return this.paramType;
+        }
+
         //Set the community rule level as warning as the current implementation does not require user to specify rule severity when defining their functions in PS scripts
         public RuleSeverity GetSeverity()
         {
@@ -80,14 +85,15 @@ public ExternalRule()
 
         }
 
-        public ExternalRule(string name, string commonName, string desc, string param, string srcName, string modPath)
+        public ExternalRule(string name, string commonName, string desc, string param, string paramType, string srcName, string modPath)
         {
             this.name    = name;
             this.commonName = commonName;
             this.desc    = desc;
             this.param   = param;
             this.srcName = srcName;
             this.modPath = modPath;
+            this.paramType = paramType;
         }
 
         #endregion

Engine/Generic/RuleInfo.cs

@@ -35,7 +35,7 @@ public class RuleInfo
         /// Name: The name of the rule.
         /// </summary>
         [SuppressMessage("Microsoft.Performance", "CA1811:AvoidUncalledPrivateCode")]
-        public string Name
+        public string RuleName
         {
             get { return name; }
             private set { name = value; }
@@ -102,7 +102,7 @@ public RuleSeverity Severity
         /// <param name="sourceName">Source name of the rule.</param>
         public RuleInfo(string name, string commonName, string description, SourceType sourceType, string sourceName, RuleSeverity severity)
         {
-            Name        = name;
+            RuleName        = name;
             CommonName  = commonName;
             Description = description;
             SourceType  = sourceType;

Engine/PSScriptAnalyzer.psd1

@@ -3,6 +3,9 @@
 #
 
 @{
+ 
+# Author of this module
+Author = 'Microsoft Corporation'
 
 # Script module or binary module file associated with this manifest.
 RootModule = 'Microsoft.Windows.Powershell.ScriptAnalyzer.dll'
@@ -14,10 +17,10 @@ ModuleVersion = '1.0'
 GUID = '324fc715-36bf-4aee-8e58-72e9b4a08ad9'
 
 # Company or vendor of this module
-CompanyName = 'Microsoft'
+CompanyName = 'Microsoft Corporation'
 
 # Copyright statement for this module
-Copyright = '(c) 2015. All rights reserved.'
+Copyright = '(c) Microsoft Corporation 2015. All rights reserved.'
 
 # Description of the functionality provided by this module
 Description = 'PSScriptAnalyzer provides script analysis and checks for potential code defects in the scripts by applying a group of builtin or customized rules on the scripts being analyzed.'