diff --git a/CHANGELOG.md b/CHANGELOG.md index 51f3d81a5..3284de299 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## [Unreleased] * Provide Method to install DoD Root Certs for Server OS and Client OS: [#755](https://github.com/microsoft/PowerStig/issues/755) +* Update PowerSTIG to Provide Rule Data from Processed xml: [#747](https://github.com/microsoft/PowerStig/issues/747) * Update PowerSTIG to send a warning to the user when using a composite that leverages the new DISA Ids: [#772](https://github.com/microsoft/PowerStig/issues/772) * Update PowerSTIG to successfully parse/apply Microsoft Office System 2013 STIG - Ver 2, Rel 1: [#769](https://github.com/microsoft/PowerStig/issues/769) * Update PowerSTIG to successfully parse/apply Microsoft Windows 2012 Server DNS STIG - Ver 2, Rel 1: [#760](https://github.com/microsoft/PowerStig/issues/760) diff --git a/Tests/Integration/Module/PowerStig.Integration.tests.ps1 b/Tests/Integration/Module/PowerStig.Integration.tests.ps1 index e76d0e9bc..604d41257 100644 --- a/Tests/Integration/Module/PowerStig.Integration.tests.ps1 +++ b/Tests/Integration/Module/PowerStig.Integration.tests.ps1 @@ -32,7 +32,17 @@ Describe "$moduleName module" { Context 'Exported Commands' { $commands = (Get-Command -Module $moduleName).Name - $exportedCommands = @('Get-DomainName', 'Get-Stig', 'New-StigCheckList', 'Get-StigRuleList', 'Get-StigVersionNumber', 'Get-PowerStigFileList', 'Split-BenchmarkId') + $exportedCommands = @( + 'Get-DomainName', + 'Get-Stig', + 'New-StigCheckList', + 'Get-StigRuleList', + 'Get-StigVersionNumber', + 'Get-PowerStigFileList', + 'Split-BenchmarkId', + 'Get-StigRule', + 'Get-StigRuleExceptionString' + ) foreach ($export in $exportedCommands) { diff --git a/Tests/Unit/Module/.tests.header.ps1 b/Tests/Unit/Module/.tests.header.ps1 index 222b0b701..43c8d782c 100644 --- a/Tests/Unit/Module/.tests.header.ps1 +++ b/Tests/Unit/Module/.tests.header.ps1 @@ -71,6 +71,12 @@ switch ($psStackCommand) . $functionDomainName } + 'STIG.RuleQuery' + { + $functionRuleQuery = Join-Path -Path $script:moduleRoot -ChildPath '\Module\STIG\Functions.RuleQuery.ps1' + . $functionRuleQuery + } + 'STIG.PowerStigXml' { $functionPowerStigXml = Join-Path -Path $script:moduleRoot -ChildPath '\Module\STIG\Convert\Functions.PowerStigXml.ps1' @@ -84,7 +90,6 @@ switch ($psStackCommand) [void] $setDynamicClassFileParams.Add('ClassModuleFileName', @('Rule.psm1', 'ConvertFactory.psm1','DocumentRule.Convert.psm1','Stig.psm1')) } - 'STIG' { $destinationPath = Join-Path -Path $PSScriptRoot -ChildPath '..\.DynamicClassImport\Convert.Main.ps1' @@ -101,7 +106,10 @@ switch ($psStackCommand) } } -if ($global:moduleName -ne 'STIG.Checklist' -and $global:moduleName -ne 'STIG.DomainName') +if +( + $global:moduleName -notmatch 'STIG.(Checklist|DomainName|RuleQuery)' +) { Set-DynamicClassFile @setDynamicClassFileParams . $setDynamicClassFileParams.DestinationPath diff --git a/Tests/Unit/Module/STIG.RuleQuery.tests.ps1 b/Tests/Unit/Module/STIG.RuleQuery.tests.ps1 new file mode 100644 index 000000000..5ebaf5a35 --- /dev/null +++ b/Tests/Unit/Module/STIG.RuleQuery.tests.ps1 @@ -0,0 +1,86 @@ +#region Header +. $PSScriptRoot\.tests.header.ps1 +#endregion + +$xmlTestData = @' + + + + <VulnDiscussion>Test STIG Description</VulnDiscussion>< + + Present + False + HKEY_LOCAL_MACHINE\Software\Microsoft\TestKeyData + False + + Test Data RawString + TestValueData + TestValueName + String + + + +'@ + +$exceptionString = "V-1000 = @{Ensure = 'Present'; Key = 'HKEY_LOCAL_MACHINE\Software\Microsoft\TestKeyData'; ValueData = 'TestValueData'; ValueName = 'TestValueName'; ValueType = 'String'}" + + +try +{ + Describe 'Rule Query Functions' { + + $testProcessedXml = Join-Path -Path $TestDrive -ChildPath 'TestProcessedXml.xml' + Set-Content -Path $testProcessedXml -Value $xmlTestData + + Context 'Get-StigRule' { + It 'Should return a V-1000 Rule PSCustomObject Non-Detailed' { + $getStigRuleResult = Get-StigRule -VulnId 'V-1000' -ProcessedXmlPath $testProcessedXml + $getStigRuleResult.RuleType | Should -Be 'RegistryRule' + $getStigRuleResult.VulnId | Should -Be 'V-1000' + $getStigRuleResult.Ensure | Should -Be 'Present' + $getStigRuleResult.Key | Should -Be 'HKEY_LOCAL_MACHINE\Software\Microsoft\TestKeyData' + $getStigRuleResult.ValueData | Should -Be 'TestValueData' + $getStigRuleResult.ValueName | Should -Be 'TestValueName' + $getStigRuleResult.ValueType | Should -Be 'String' + } + + It 'Should return a V-1000 Rule PSCustomObject Detailed' { + $getStigRuleResult = Get-StigRule -VulnId 'V-1000' -ProcessedXmlPath $testProcessedXml -Detailed + $getStigRuleResult.StigId | Should -Be 'TestSTIGData' + $getStigRuleResult.StigVersion | Should -Be '1.1' + $getStigRuleResult.Severity | Should -Be 'medium' + $getStigRuleResult.Title | Should -Be 'SRG-APP-000000' + $getStigRuleResult.Description | Should -Be 'Test STIG Description' + $getStigRuleResult.RuleType | Should -Be 'RegistryRule' + $getStigRuleResult.DscResource | Should -Be 'Registry' + $getStigRuleResult.DuplicateOf | Should -Be $([string]::Empty) + $getStigRuleResult.OrganizationValueRequired | Should -Be 'False' + $getStigRuleResult.OrganizationValueTestString | Should -Be $([string]::Empty) + $getStigRuleResult.VulnId | Should -Be 'V-1000' + $getStigRuleResult.Ensure | Should -Be 'Present' + $getStigRuleResult.Key | Should -Be 'HKEY_LOCAL_MACHINE\Software\Microsoft\TestKeyData' + $getStigRuleResult.ValueData | Should -Be 'TestValueData' + $getStigRuleResult.ValueName | Should -Be 'TestValueName' + $getStigRuleResult.ValueType | Should -Be 'String' + } + } + + Context 'Get-StigRuleExceptionString' { + It 'Should return a valid unformatted exception string' { + $ruleData = Get-StigRule -VulnId 'V-1000' -ProcessedXmlPath $testProcessedXml + $getStigRuleExceptionString = Get-StigRuleExceptionString -Rule $ruleData + $getStigRuleExceptionString | Should -Be $exceptionString + } + + It 'Should return a valid formatted exception string' { + $ruleData = Get-StigRule -VulnId 'V-1000' -ProcessedXmlPath $testProcessedXml + $getStigRuleExceptionStringFormatted = Get-StigRuleExceptionString -Rule $ruleData -Formatted + $getStigRuleExceptionStringFormatted | Should -BeOfType System.String + } + } + } +} +finally +{ + . $PSScriptRoot\.tests.footer.ps1 +} diff --git a/source/Module/STIG/Functions.RuleQuery.ps1 b/source/Module/STIG/Functions.RuleQuery.ps1 new file mode 100644 index 000000000..96199cc72 --- /dev/null +++ b/source/Module/STIG/Functions.RuleQuery.ps1 @@ -0,0 +1,246 @@ +using module ..\Rule\Rule.psm1 + +<# + .SYNOPSIS + Get the STIG Rule Details for a given rule supported by PowerSTIG. + + .DESCRIPTION + Get the STIG Rule Details for a given rule supported by PowerSTIG. + + .PARAMETER VulnId + VulnId within PowerSTIG is typically labled as the RuleId, which + may not be consistent with DISA terminology. + + .PARAMETER ProcessedXmlPath + Either the folder where the processed xml resides or a specific xml path. + The default is .\StigData\Processed\*.xml + + .EXAMPLE + PS> Get-StigRule -VulnId 'V-1114', 'V-1115' + + This example will return the rule details for V-1114 and V-1115 from the Windows Server + 2012 R2 Member Server and Domain Controller STIGs. +#> +function Get-StigRule +{ + [CmdletBinding()] + [OutputType([PSCustomObject])] + param + ( + [Parameter(Mandatory = $true, Position = 0)] + [ValidateScript({$_ -match '^V-\d{1,}(|\.[a-z])$'})] + [Alias("RuleId")] + [string[]] + $VulnId, + + [Parameter()] + [ValidateScript({Test-Path -Path $_})] + [string] + $ProcessedXmlPath = (Join-Path -Path $PSScriptRoot -ChildPath '..\..\StigData\Processed\*.xml'), + + [Parameter()] + [switch] + $Detailed + ) + + $processedXml = Select-String -Path $ProcessedXmlPath -Pattern $VulnId -Exclude '*.org.default.xml' | Sort-Object -Property Pattern + + if ($null -eq $processedXml) + { + Write-Warning -Message "The VulnId(s) specified were not found in $ProcessedXmlPath" + return + } + + # hashtable to store rule property lookups when multiple rule types are specified + $ruleTypeProperty = @{} + + foreach ($technologyXml in $processedXml) + { + # based on the VulnId specificed use XPath to search the xml object + $ruleIdXPath = '//Rule[@id = "{0}"]' -f $technologyXml.Pattern + [xml] $xml = Get-Content -Path $technologyXml.Path + $ruleData = $xml.DISASTIG.SelectNodes($ruleIdXPath) + $ruleType = $ruleData.ParentNode.ToString() + + # if the current rule type is not stored in the hashtable, run Get-UniqueRuleTypeProperty and store the results for future use + if (-not $ruleTypeProperty.ContainsKey($ruleType)) + { + $uniqueRuleTypeProperty = Get-UniqueRuleTypeProperty -Rule $ruleData + $ruleTypeProperty.Add($ruleType, $uniqueRuleTypeProperty) + } + + # pulling the VulnDiscussion as the description out of the xml using a regex capture group + $ruleDescriptionMatch = [regex]::Match($ruleData.description.Replace("`n", ' '), '(?.*)<\/VulnDiscussion>') + + # address edge case where an out of place OS Control charactor [char]157 in the STIG's description, i.e. Adobe Reader / V-64919, removing it + $ruleDescriptionValue = $ruleDescriptionMatch.Groups.Item('description').Value -replace '\u009D' + + # using PSv3 "ordered" to create an ordered hashtable for PSCustomObject property list display order + if ($PSBoundParameters.ContainsKey('Detailed')) + { + $ruleDetail = [ordered] @{ + StigId = $xml.DISASTIG.stigid + StigVersion = $xml.DISASTIG.fullversion + VulnId = $ruleData.id + Severity = $ruleData.severity + Title = $ruleData.title + Description = $ruleDescriptionValue + RuleType = $ruleType + DscResource = $ruleData.dscresource + DuplicateOf = $ruleData.DuplicateOf + OrganizationValueRequired = $ruleData.OrganizationValueRequired + OrganizationValueTestString = $ruleData.OrganizationValueTestString + } + } + else + { + $ruleDetail = [ordered] @{ + RuleType = $ruleType + VulnId = $ruleData.id + } + } + + # adding the rule specific properties to the ordered hashtable and then casting to PSCustomObject + foreach ($value in $ruleTypeProperty[$ruleType]) + { + $ruleDetail.Add($value, $ruleData.$value) + } + + [PSCustomObject] $ruleDetail + } +} + +<# + .SYNOPSIS + Get the unique rule type properties given a specific rule type. + + .DESCRIPTION + Get the unique rule type properties given a specific rule type. + + .PARAMETER Rule + A rule by leveraging the selected XmlNodeList from a processed xml. + + .EXAMPLE + PS> Get-UniqueRuleTypeProperty -Rule $xml.DISASTIG.RegistryRule.Rule[0] + + Returns the delta properties between the RegistryRule and Base Rule class +#> +function Get-UniqueRuleTypeProperty +{ + [CmdletBinding()] + [OutputType([string[]])] + param + ( + [Parameter(Mandatory = $true)] + [Object] + $Rule + ) + + $blankRule = New-Object -TypeName Rule + $commonProperties = ($blankRule | Get-Member -MemberType Property).Name + $ruleProperty = ($Rule | Get-Member -MemberType 'NoteProperty', 'Property').Name + $compareObjResult = Compare-Object -ReferenceObject $ruleProperty -DifferenceObject $commonProperties + $filteredCompareResult = $compareObjResult | Where-Object -FilterScript {$PSItem.SideIndicator -eq '<=' -and $PSItem -notmatch 'Stig(Id|Version)|VulnId|RuleType'} + return $filteredCompareResult.InputObject +} + +<# + .SYNOPSIS + Returns a string of all properties of a given rule and structured for use within a PowerSTIG configuraiton. + + .DESCRIPTION + Returns a string of all properties of a given rule and structured for use within a PowerSTIG configuraiton. + + .PARAMETER Rule + A rule object which was created through Get-StigRule + + .PARAMETER Formatted + By default the function will return a single line string which represents the rule exception, when Formatted + is supplied, the funciton will return a formatted string, i.e.: + + V-1155 = @{ + Constant = 'SeDenyNetworkLogonRight' + DisplayName = 'Deny access to this computer from the network' + Force = 'False' + Identity = '' + } + + .EXAMPLE + PS> $rule = Get-StigRule -RuleId V-1155 | Select-Object -First 1 + PS> Get-StigRuleExceptionString -Rule $rule + + Returns the following exception string: + V-1155 = @{Constant = 'SeDenyNetworkLogonRight'; DisplayName = 'Deny access to this computer from the network'; Force = 'False'; Identity = ''} + + .EXAMPLE + PS> $rule = Get-StigRule -RuleId V-1155 | Select-Object -First 1 + PS> Get-StigRuleExceptionString -Rule $rule -Formatted + + Returns the following exception string: + V-1155 = @{ + Constant = 'SeDenyNetworkLogonRight' + DisplayName = 'Deny access to this computer from the network' + Force = 'False' + Identity = '' + } +#> +function Get-StigRuleExceptionString +{ + [CmdletBinding()] + [OutputType([string])] + param + ( + [Parameter(Mandatory = $true, ValueFromPipeline = $true)] + [PSObject[]] + $Rule, + + [Parameter()] + [switch] + $Formatted + ) + + begin + { + $ruleTypeProperty = @{} + } + + process + { + foreach ($ruleData in $Rule) + { + if (-not $ruleTypeProperty.ContainsKey($ruleData.RuleType)) + { + $uniqueRuleTypeProperty = Get-UniqueRuleTypeProperty -Rule $ruleData + $ruleTypeProperty.Add($ruleData.RuleType, $uniqueRuleTypeProperty) + } + + $ruleDetail = [ordered] @{} + + foreach ($value in $ruleTypeProperty[$ruleData.RuleType]) + { + if ($value -ne $ruleData.RuleType) + { + $ruleDetail.Add($value, $ruleData.$value) + } + } + + $exceptionString = New-Object -TypeName System.Text.StringBuilder + [void] $exceptionString.Append("$($ruleData.VulnId) = @{") + foreach ($key in $ruleDetail.Keys) + { + [void] $exceptionString.Append("$key = '$($ruleDetail[$key])'; ") + } + + $exceptionString = $exceptionString.ToString() -replace ';\s$', '}' + + if ($Formatted) + { + $exceptionString -replace ';\s?', "`n " -replace '@{', "@{`n " -replace '}', "`n}" + } + else + { + $exceptionString + } + } + } +} diff --git a/source/PowerStig.psd1 b/source/PowerStig.psd1 index faad478ba..e1bd9c22a 100644 --- a/source/PowerStig.psd1 +++ b/source/PowerStig.psd1 @@ -79,7 +79,9 @@ FunctionsToExport = @( 'Get-StigRuleList', 'Get-StigVersionNumber', 'Get-PowerStigFilelist', - 'Split-BenchmarkId' + 'Split-BenchmarkId', + 'Get-StigRule', + 'Get-StigRuleExceptionString' ) # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export. diff --git a/source/PowerStig.psm1 b/source/PowerStig.psm1 index 5ee440081..5b7783f48 100644 --- a/source/PowerStig.psm1 +++ b/source/PowerStig.psm1 @@ -18,5 +18,7 @@ Export-ModuleMember -Function @( 'Get-StigRuleList', 'Get-StigVersionNumber', 'Get-PowerStigFilelist', - 'Split-BenchmarkId' + 'Split-BenchmarkId', + 'Get-StigRule', + 'Get-StigRuleExceptionString' )