Module/STIG/Functions.RuleQuery.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
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 LegacyId
        Specify the "previous" VulnId/RuleId, prior to DISA October 2020 Id
        updates.
 
    .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, ParameterSetName = 'VulnId')]
        [ValidateScript({$_ -match '^V-\d{1,}(|\.[a-z])$'})]
        [Alias("RuleId")]
        [string[]]
        $VulnId,

        [Parameter(Mandatory = $true, ParameterSetName = 'LegacyId')]
        [ValidateScript({$_ -match '^V-\d{1,}(|\.[a-z])$'})]
        [string[]]
        $LegacyId,

        [Parameter()]
        [ValidateScript({Test-Path -Path $_})]
        [string]
        $ProcessedXmlPath = (Join-Path -Path $PSScriptRoot -ChildPath '..\..\StigData\Processed\*.xml'),

        [Parameter()]
        [switch]
        $Detailed
    )

    switch ($PSCmdlet.ParameterSetName)
    {
        'VulnId'
        {
            $vulnIdPattern = '<Rule\s+id\s*="{0}"' -f $VulnId
            $patternReplacement = '<Rule\s+id\s*="'
            $xmlXPathPattern = '//Rule[@id = "{0}"]'
        }

        'LegacyId'
        {
            $vulnIdPattern = '<LegacyId>{0}' -f $LegacyId
            $patternReplacement = '<LegacyId>'
            $xmlXPathPattern = '//Rule[LegacyId="{0}"]'
        }
    }

    $processedXml = Select-String -Path $ProcessedXmlPath -Pattern $vulnIdPattern -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
        $vulnIdFromXml = $technologyXml.Pattern.Replace($patternReplacement, $null).Replace('"', $null)
        $ruleIdXPath = $xmlXPathPattern -f $vulnIdFromXml
        [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>(?<description>.*)<\/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
                LegacyId                    = $ruleData.LegacyId
                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
            }
        }
    }
}