Filter objects by target type #176 #315 #318

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+- Fixed missing `Markdown` input format in options schema. [#315](https://github.com/Microsoft/PSRule/issues/315)
+- Added `-TargetType` parameter to filter input objects by target type. [#176](https://github.com/Microsoft/PSRule/issues/176)
+  - This parameter applies to `Invoke-PSRule`, `Assert-PSRule` and `Test-PSRuleTarget`.
+- **Breaking change**: Unprocessed object results are not returned from `Test-PSRuleTarget` by default. [#318](https://github.com/Microsoft/PSRule/issues/318)
+  - Previously unprocessed objects returned `$True`, now unprocessed objects return no result.
+  - Use `-Outcome All` to return `$True` for unprocessed objects the same as <= v0.10.0.
+
 ## v0.10.0
 
 What's changed since v0.9.0:

README.md

@@ -245,6 +245,7 @@ The following conceptual topics exist in the `PSRule` module:
   - [Execution.NotProcessedWarning](docs/concepts/PSRule/en-US/about_PSRule_Options.md#executionnotprocessedwarning)
   - [Input.Format](docs/concepts/PSRule/en-US/about_PSRule_Options.md#inputformat)
   - [Input.ObjectPath](docs/concepts/PSRule/en-US/about_PSRule_Options.md#inputobjectpath)
+  - [Input.TargetType](docs/concepts/PSRule/en-US/about_PSRule_Options.md#inputtargettype)
   - [Logging.LimitDebug](docs/concepts/PSRule/en-US/about_PSRule_Options.md#logginglimitdebug)
   - [Logging.LimitVerbose](docs/concepts/PSRule/en-US/about_PSRule_Options.md#logginglimitverbose)
   - [Logging.RuleFail](docs/concepts/PSRule/en-US/about_PSRule_Options.md#loggingrulefail)

docs/commands/PSRule/en-US/Assert-PSRule.md

@@ -18,17 +18,17 @@ Evaluate objects against matching rules and assert any failures.
 ```text
 Assert-PSRule [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>] [-Style <OutputStyle>]
  [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]
- [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-Culture <String[]>]
- -InputObject <PSObject> [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
+ [-Culture <String[]>] -InputObject <PSObject> [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
 Assert-PSRule -InputPath <String[]> [-Module <String[]>] [-Format <InputFormat>] [-Baseline <BaselineOption>]
  [-Style <OutputStyle>] [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-OutputPath <String>]
- [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-Culture <String[]>] [-WhatIf]
- [-Confirm] [<CommonParameters>]
+ [-OutputFormat <OutputFormat>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
+ [-Culture <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -64,7 +64,7 @@ $items | Assert-PSRule -Path .\docs\scenarios\fruit\
 ```
 
 ```text
- -> Fridge : System.Management.Automation.PSCustomObject
+-> Fridge : System.Management.Automation.PSCustomObject
 
     [FAIL] isFruit
 
@@ -247,6 +247,33 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -TargetType
+
+Filters input objects by TargetType.
+
+If specified, only objects with the specified TargetType are processed.
+Objects that do not match TargetType are ignored.
+If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
+
+By default, all objects are processed.
+
+This parameter if set, overrides the `Input.TargetType` option.
+
+To change the field TargetType is bound to set the `Binding.TargetType` option.
+For details see the about_PSRule_Options help topic.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Option
 
 Additional options that configure execution.

docs/commands/PSRule/en-US/Invoke-PSRule.md

@@ -18,8 +18,8 @@ Evaluate objects against matching rules and output the results.
 ```text
 Invoke-PSRule [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>] [-Format <InputFormat>]
  [-OutputPath <String>] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>] [[-Path] <String[]>]
- [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-Culture <String[]>]
- -InputObject <PSObject> [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-TargetType <String[]>]
+ [-Culture <String[]>] -InputObject <PSObject> [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### InputPath
@@ -28,7 +28,7 @@ Invoke-PSRule [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]
 Invoke-PSRule -InputPath <String[]> [-Module <String[]>] [-Outcome <RuleOutcome>] [-As <ResultFormat>]
  [-Format <InputFormat>] [-OutputPath <String>] [-OutputFormat <OutputFormat>] [-Baseline <BaselineOption>]
  [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>]
- [-Culture <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-TargetType <String[]>] [-Culture <String[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -164,7 +164,7 @@ Accept wildcard characters: False
 
 ### -Outcome
 
-Filter output to only show rules with a specific outcome.
+Filter output to only show rule results with a specific outcome.
 
 ```yaml
 Type: RuleOutcome
@@ -302,6 +302,33 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -TargetType
+
+Filters input objects by TargetType.
+
+If specified, only objects with the specified TargetType are processed.
+Objects that do not match TargetType are ignored.
+If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
+
+By default, all objects are processed.
+
+This parameter if set, overrides the `Input.TargetType` option.
+
+To change the field TargetType is bound to set the `Binding.TargetType` option.
+For details see the about_PSRule_Options help topic.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Module
 
 Search for rule definitions within a module.

docs/commands/PSRule/en-US/New-PSRuleOption.md

@@ -18,7 +18,7 @@ New-PSRuleOption [[-Path] <String>] [[-Option] <PSRuleOption>] [-Configuration <
  [-SuppressTargetName <SuppressionOption>] [-BindTargetName <BindTargetName[]>]
  [-BindTargetType <BindTargetName[]>] [-BindingIgnoreCase <Boolean>] [-TargetName <String[]>]
  [-TargetType <String[]>] [-InconclusiveWarning <Boolean>] [-NotProcessedWarning <Boolean>]
- [-Format <InputFormat>] [-ObjectPath <String>] [-LoggingLimitDebug <String[]>]
+ [-Format <InputFormat>] [-ObjectPath <String>] [-InputTargetType <String[]>] [-LoggingLimitDebug <String[]>]
  [-LoggingLimitVerbose <String[]>] [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>]
  [-OutputAs <ResultFormat>] [-OutputEncoding <OutputEncoding>] [-OutputFormat <OutputFormat>]
  [-OutputPath <String>] [-OutputStyle <OutputStyle>] [<CommonParameters>]
@@ -305,6 +305,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -InputTargetType
+
+Sets the `Input.TargetType` option to only process objects with the specified TargetType.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -LoggingLimitDebug
 
 Sets the `Logging.LimitDebug` option to limit debug messages to a list of named debug scopes.

docs/commands/PSRule/en-US/Set-PSRuleOption.md

@@ -17,10 +17,10 @@ Sets options that configure PSRule execution.
 Set-PSRuleOption [[-Path] <String>] [-Option <PSRuleOption>] [-PassThru] [-Force] [-AllowClobber]
  [-BindingIgnoreCase <Boolean>] [-TargetName <String[]>] [-TargetType <String[]>]
  [-InconclusiveWarning <Boolean>] [-NotProcessedWarning <Boolean>] [-Format <InputFormat>]
- [-ObjectPath <String>] [-LoggingLimitDebug <String[]>] [-LoggingLimitVerbose <String[]>]
- [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>] [-OutputAs <ResultFormat>]
- [-OutputEncoding <OutputEncoding>] [-OutputFormat <OutputFormat>] [-OutputPath <String>]
- [-OutputStyle <OutputStyle>] [-WhatIf] [-Confirm] [<CommonParameters>]
+ [-ObjectPath <String>] [-InputTargetType <String[]>] [-LoggingLimitDebug <String[]>]
+ [-LoggingLimitVerbose <String[]>] [-LoggingRuleFail <OutcomeLogStream>] [-LoggingRulePass <OutcomeLogStream>]
+ [-OutputAs <ResultFormat>] [-OutputEncoding <OutputEncoding>] [-OutputFormat <OutputFormat>]
+ [-OutputPath <String>] [-OutputStyle <OutputStyle>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -253,6 +253,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -InputTargetType
+
+Sets the `Input.TargetType` option to only process objects with the specified TargetType.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -LoggingLimitDebug
 
 Sets the `Logging.LimitDebug` option to limit debug messages to a list of named debug scopes.

docs/commands/PSRule/en-US/Test-PSRuleTarget.md

@@ -16,17 +16,17 @@ Pass or fail objects against matching rules.
 ### Input (Default)
 
 ```text
-Test-PSRuleTarget [-Module <String[]>] [-Format <InputFormat>] [[-Path] <String[]>] [-Name <String[]>]
- [-Tag <Hashtable>] -InputObject <PSObject> [-Option <PSRuleOption>] [-ObjectPath <String>] [-Culture <String>]
- [<CommonParameters>]
+Test-PSRuleTarget [-Module <String[]>] [-Outcome <RuleOutcome>] [-Format <InputFormat>] [[-Path] <String[]>]
+ [-Name <String[]>] [-Tag <Hashtable>] -InputObject <PSObject> [-Option <PSRuleOption>] [-ObjectPath <String>]
+ [-TargetType <String[]>] [-Culture <String>] [<CommonParameters>]
 ```
 
 ### InputPath
 
 ```text
-Test-PSRuleTarget -InputPath <String[]> [-Module <String[]>] [-Format <InputFormat>] [[-Path] <String[]>]
- [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>] [-Culture <String>]
- [<CommonParameters>]
+Test-PSRuleTarget -InputPath <String[]> [-Module <String[]>] [-Outcome <RuleOutcome>] [-Format <InputFormat>]
+ [[-Path] <String[]>] [-Name <String[]>] [-Tag <Hashtable>] [-Option <PSRuleOption>] [-ObjectPath <String>]
+ [-TargetType <String[]>] [-Culture <String>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -39,9 +39,12 @@ PSRule uses the following logic to determine overall pass or fail for an object:
   - Any rules fail or error.
   - Any rules are inconclusive.
 - The object passes if:
-  - No rules were found that match preconditions, name and tag filters.
+  - No matching rules were found.
   - All rules pass.
 
+By default, objects that do match any rules are not returned in results.
+To return `$True` for these objects, use `-Outcome All`.
+
 ## EXAMPLES
 
 ### Example 1
@@ -91,6 +94,23 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Outcome
+
+Filter output to only show pipeline objects with a specific outcome.
+
+```yaml
+Type: RuleOutcome
+Parameter Sets: (All)
+Aliases:
+Accepted values: Pass, Fail, Error, None, Processed, All
+
+Required: False
+Position: Named
+Default value: Pass, Fail, Error
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Tag
 
 Only get rules with the specified tags set.
@@ -192,6 +212,33 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -TargetType
+
+Filters input objects by TargetType.
+
+If specified, only objects with the specified TargetType are processed.
+Objects that do not match TargetType are ignored.
+If multiple values are specified, only one TargetType must match. This parameter is not case-sensitive.
+
+By default, all objects are processed.
+
+This parameter if set, overrides the `Input.TargetType` option.
+
+To change the field TargetType is bound to set the `Binding.TargetType` option.
+For details see the about_PSRule_Options help topic.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Module
 
 Search for rule definitions within a module.

docs/concepts/PSRule/en-US/about_PSRule_Options.md

@@ -18,6 +18,7 @@ The following workspace options are available for use:
 - [Execution.NotProcessedWarning](#executionnotprocessedwarning)
 - [Input.Format](#inputformat)
 - [Input.ObjectPath](#inputobjectpath)
+- [Input.TargetType](#inputtargettype)
 - [Logging.LimitDebug](#logginglimitdebug)
 - [Logging.LimitVerbose](#logginglimitverbose)
 - [Logging.RuleFail](#loggingrulefail)
@@ -448,7 +449,7 @@ If the property specified by `ObjectPath` is a collection/ array, then each item
 
 If the property specified by `ObjectPath` does not exist, PSRule skips the object.
 
-When using `Invoke-PSRule` and `Test-PSRuleTarget` the `-ObjectPath` parameter will override any value set in configuration.
+When using `Invoke-PSRule`, `Test-PSRuleTarget` and `Assert-PSRule` the `-ObjectPath` parameter will override any value set in configuration.
 
 This option can be specified using:
 
@@ -473,6 +474,44 @@ input:
   objectPath: items
 ```
 
+### Input.TargetType
+
+Filters input objects by TargetType.
+
+If specified, only objects with the specified TargetType are processed.
+Objects that do not match TargetType are ignored.
+If multiple values are specified, only one TargetType must match. This option is not case-sensitive.
+
+By default, all objects are processed.
+
+To change the field TargetType is bound to set the `Binding.TargetType` option.
+
+When using `Invoke-PSRule`, `Test-PSRuleTarget` and `Assert-PSRule` the `-TargetType` parameter will override any value set in configuration.
+
+This option can be specified using:
+
+```powershell
+# PowerShell: Using the InputTargetType parameter
+$option = New-PSRuleOption -InputTargetType 'virtualMachine';
+```
+
+```powershell
+# PowerShell: Using the Input.TargetType hashtable key
+$option = New-PSRuleOption -Option @{ 'Input.TargetType' = 'virtualMachine' };
+```
+
+```powershell
+# PowerShell: Using the InputTargetType parameter to set YAML
+Set-PSRuleOption -InputTargetType 'virtualMachine';
+```
+
+```yaml
+# YAML: Using the input/targetType property
+input:
+  targetType:
+  - virtualMachine
+```
+
 ### Logging.LimitDebug
 
 Limits debug messages to a list of named debug scopes.
@@ -962,6 +1001,9 @@ execution:
 input:
   format: Yaml
   objectPath: items
+  targetType:
+  - Microsoft.Compute/virtualMachines
+  - Microsoft.Network/virtualNetworks
 
 # Configures outcome logging options
 logging:
@@ -1030,6 +1072,7 @@ execution:
 input:
   format: Detect
   objectPath: null
+  targetType: [ ]
 
 # Configures outcome logging options
 logging: