PowerShell: How to add compliance settings and rules to configuration items (1705 TP)

  • Article

Update: These cmdlets did not make it into the 1704 TP, but they will be in the 1705 TP. This posting has been updated to correct this.

In the upcoming 1705 technical preview of Configuration Manager, we have finally added the much-requested ability to add Settings and Rules to Configuration Items from within PowerShell. This posting will discuss the basic concepts of how this will work, along with what is and is not supported at this time.

What is supported

For 1704 technical preview the following functionality can now be done through PowerShell:

  • Add/Remove/Modify Settings to Configuration Items. All Settings supported in the administrator console are supported through PowerShell: registry key, registry key value, script, file, folder, WQL query, AD query, assembly property, IIS metabase, SQL query, and XPath query.
  • Add/Remove/Modify Rules linked to Settings within Configuration Items. This includes basic value checks, existential checks (exist, not exist, occurrence), and complex value checks for applicable Setting types (file/folder properties, assembly properties, registry key permissions).

How it works

All Settings can be created without corresponding Rules in a single cmdlet call. All settings with existential Rules can also be created with a single cmdlet call. Some settings with value Rules can be created with a single cmdlet call while other, more complex Rule types will require a more complicated but easily understandable pattern of cmdlet calls. We may simplify this in the future. (See Example 4 below.)

Example 1

Creating a registry key value Setting without any Rules:

 
# Creates a setting looking for HKLM\Software\Microsoft\Windows NT\CurrentVersion:ReleaseId
$ci | Add-CMComplianceSettingRegistryKeyValue -SettingName "ReleaseId no rule" -DataType String -Hive LocalMachine -KeyName "SOFTWARE\Microsoft\Windows NT\CurrentVersion" -ValueName "ReleaseId" -NoRule

Example 2

Creating a registry key value Setting with an existential Rule (must exist):

 
# Creates a setting requiring the HKLM\Software\Microsoft\WindowsNT\CurrentVersion:ReleaseId registry key to exist
$ci | Add-CMComplianceSettingRegistryKeyValue -SettingName "ReleaseId must exist" -DataType String -Hive LocalMachine -KeyName "SOFTWARE\Microsoft\Windows NT\CurrentVersion" -ValueName "ReleaseId" -ExistentialRule -Existence MustExist

Example 3

Creating a registry key value Setting with a value Rule (must equal “1703”):

 
# Creates a setting requiring the HKLM\Software\Microsoft\WindowsNT\CurrentVersion:ReleaseId registry key to be equal to "1703"
$ci | Add-CMComplianceSettingRegistryKeyValue -SettingName "ReleaseId must be 1703" -DataType String -Hive LocalMachine -KeyName "SOFTWARE\Microsoft\Windows NT\CurrentVersion" -ValueName "ReleaseId" -ValueRule -ExpressionOperator IsEqual -ExpectedValue "1703"

In value rules, critical parameters are “ExpressionOperator” and “ExpectedValue”. It’s worth noting that “ExpectedValue” supports arrays of values so if you’re using an ExpressionOperator that requires (Between) or supports many (OneOf/NoneOf/AllOf) values, you can use the same parameter for this. Cmdlets will validate the input to ensure you’re not doing something unsupported – such as using IsEquals with multiple ExpectedValue arguments.

Example 4

Some setting value Rules require more specialized input. As such, these Setting types do not support a single cmdlet at this time. For those scenarios, you need to follow this pattern:

  1. Create the Setting using Add-CMComplianceSetting<type>
  2. Get the DcmObjectModel Setting object (as opposed to a SMS Provider object) using Get-CMComplianceSetting
  3. Create the Rule using New-CMComplianceRule<type>
  4. Apply the Rule to the setting using Add-CMComplianceSettingRule

This example creates a file rule that requires the specified file to have a specific attribute:

 
$ci | Add-CMComplianceSettingFile -Path "C:\" -FileName "hiberfile.sys" -NoRule -SettingName "hiberfile.sys must have system attribute"
$setting = $ci | Get-CMComplianceSetting -SettingName "hiberfile.sys must have system attribute" # Get the SDK setting object
$rule = $setting | New-CMComplianceRuleFileFolderAttribute -RuleName "hiberfile.sys must be system" -System $true # Create the rule
$ci | Add-CMComplianceSettingRule $rule # Bind the rule to the CI

What cmdlets are included

These cmdlets have been created in 1704 to enable Configuration Item Rule and Setting support:

  • Add/Set-CMComplianceSettingActiveDirectory
  • Add/Set-CMComplianceSettingAssembly
  • Add/Set-CMComplianceSettingDirectory
  • Add/Set-CMComplainceSettingFile
  • Add/Set-CMComplianceSettingIisMetabase
  • Add/Set-CMComplianceSettingRegistryKey
  • Add/Set-CMComplianceSettingRegistryKeyValue
  • Add-CMComplianceSettingRule
  • Add/Set-CMComplianceSettingScript
  • Add/Set-CMComplianceSettingSqlQuery
  • Add/Set-CMComplianceSettingWqlQuery
  • Add/Set-CMComplianceSettingXPathQuery
  • Get-CMComplianceRule
  • Get-CMComplianceSetting
  • New-CMComplianceRuleAssembly
  • New-CMComplianceRuleExistential
  • New-CMComplianceRuleFileFolderAttribute
  • New-CMComplianceRuleFileFolderDate
  • New-CMComplianceRuleFileFolderPermission
  • New-CMComplianceRuleFileFolderSimple
  • New-CMComplianceRuleFileFolderSize
  • New-CMComplianceRuleRegistryKeyPermission
  • New-CMComplianceRuleValue
  • New-CMComplianceRuleVersion
  • Remove-CMComplianceRule
  • Remove-CMComplianceSetting

Note: The previously existing Add-CMComplianceRegistrySetting and New-CMComplianceRule cmdlets were experimental and for lab use only. They have been removed from 1704.