PowerSTIG

1.1.1.0

Module/Common/Function.RangeConversion.ps1

#region Header
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License.
#endregion
#region Main Functions
<#
    .SYNOPSIS
        This function is a selection function that looks at text containing conditional language and
        tries to identify the correct specialized function to set it to for conversion. The conversion
        functions called by this function do the English to PowerShell conversion.

    .Parameter String
        The STIG text contains conditional text to try and convert to a PowerShell expression.

    .Notes
        General Notes
#>
function Get-OrganizationValueTestString
{
    [CmdletBinding()]
    [OutputType([string])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    switch ($String)
    {
        {Test-StringIsNegativeOr -String $PSItem}
        {
            ConvertTo-OrTestString -String $PSItem -Operator NotMatch
            continue
        }
        {Test-StringIsPositiveOr -String $PSItem}
        {
            ConvertTo-OrTestString -String $PSItem -Operator Match
            continue
        }
        {
            (Test-StringIsLessThan -String $PSItem)                 -or
            (Test-StringIsLessThanOrEqual -String $PSItem)          -or
            (Test-StringIsLessThanButNot -String $PSItem)           -or
            (Test-StringIsLessThanOrEqualButNot -String $PSItem)    -or
            (Test-StringIsLessThanOrEqualExcluding -String $PSItem) -or
            (Test-StringIsGreaterThan -String $PSItem)              -or
            (Test-StringIsGreaterThanOrEqual -String $PSItem)       -or
            (Test-StringIsGreaterThanButNot -String $PSItem)        -or
            (Test-StringIsGreaterThanOrEqualButNot -String $PSItem)
        }
        {
            ConvertTo-TestString -String $PSItem
            continue
        }
        {Test-StringIsMultipleValue -String $PSItem}
        {
            ConvertTo-MultipleValue -String $PSItem
            continue
        }
    }
}

function Get-TestStringTokenNumbers
{
    [CmdletBinding()]
    [OutputType([string[]])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    $tokens = [System.Management.Automation.PSParser]::Tokenize($String, [ref]$null)
    $number = $tokens.Where({$PSItem.type -eq 'Number'}).Content
    <#
        There is an edge case where the hex and decimal values are provided inline, so pick
        the hex code out and convert it to an int.
    #>
    $match = $number | Select-String -Pattern "\b(0x[A-Fa-f0-9]{8}){1}\b"

    if ($match)
    {
        if ($number.count -gt 2)
        {
            $number[1, 2]
        }
        else 
        {
            [convert]::ToInt32($match,16)
        }
    }
    else
    {
        $number
    }
}

<#
    .SYNOPSIS
        Uses the PowerShell parser to tokenize the English sentences into individual words that are
        regrouped and complied into PS representations that can be applied and measured automatically.
#>
function Get-TestStringTokenList
{
    [CmdletBinding(DefaultParameterSetName = 'CommandTokens')]
    [OutputType([string])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String,

        [parameter(ParameterSetName = 'CommandTokens')]
        [switch]
        $CommandTokens,

        [parameter(ParameterSetName = 'StringTokens')]
        [switch]
        $StringTokens
    )

    $tokens = [System.Management.Automation.PSParser]::Tokenize($String, [ref]$null)

    if($PSCmdlet.ParameterSetName -eq 'StringTokens')
    {
        return $tokens.Where({ $PSItem.type -eq 'String' }).Content
    }

    $commands = $tokens.Where({
            $PSItem.type -eq 'CommandArgument' -or
            $PSItem.type -eq 'Command' }).Content

    return ( $commands -join " " )
}

function ConvertTo-TestString
{
    [CmdletBinding()]
    [OutputType([string])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )
    $number    = Get-TestStringTokenNumbers -String $String
    $operators = Get-TestStringTokenList -String $String -CommandTokens

    switch ($operators)
    {
        'greater than'
        {
            return "{0} -gt '$number'"
        }
        'or greater'
        {
            return "{0} -ge '$number'"
        }
        'greater than but not'
        {
            return "{0} -gt '$($number[0])' -and {0} -lt '$($number[1])'"
        }
        'or greater but not'
        {
            return "{0} -ge '$($number[0])' -and {0} -lt '$($number[1])'"
        }
        'less than'
        {
            return "{0} -lt '$number'"
        }
        'or less'
        {
            return "{0} -le '$number'"
        }
        'less than but not'
        {
            return "{0} -lt '$($number[0])' -and {0} -gt '$($number[1])'"
        }
        'or less but not'
        {
            return "{0} -le '$($number[0])' -and {0} -gt '$($number[1])'"
        }
        'or less excluding'
        {
            return "{0} -le '$($number[0])' -and {0} -gt '$($number[1])'"
        }
    }
}

<#
    .SYNOPSIS
        Converts a Rule to a hashtable so it can be splatted to other functions

    .PARAMETER InputObject
        The object being converted

    .NOTES
        There are multiple rules in the DNS STIG that enforce the same setting. If a duplicate rule is found
        it is converted to a documentRule
#>
function ConvertTo-HashTable
{
    [CmdletBinding()]
    [OutputType([hashtable])]
    param
    (
        [object] $InputObject
    )

    $hashTable = @{
        Id       = $InputObject.id
        Severity = $InputObject.Severity
        Title    = $InputObject.title
    }

    return $hashTable
}
#endregion
#region Or
<#
    .SYNOPSIS
        Checks if a string is asking for a negative or evaluation. Applies a regular expression against
        the string to look for a known pattern asking for a value to not be equal to one of 2 values.

    .PARAMETER String
        The string data to evaluate.

    .EXAMPLE
        This example returns $true

        Test-StringIsNegativeOr -String "1 or 2 = a Finding"

    .EXAMPLE
        This example returns $false

        Test-StringIsNegativeOr -String "1 or 2 = is not a Finding"
        
    .NOTES
        Tests if a string such as '1 or 2 = a Finding' is a negative or test.
#>
function Test-StringIsNegativeOr
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    #
    if ($string -match "^(\s*)(\d{1,})(\s*)or(\s*)(\d{1,})(\s*)=(\s*)a(\s*)Finding(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Checks if a string is asking for a positive or evaluation. Applies a regular expression against
        the string to look for a known pattern asking for a value to be equal to one of 2 values.

    .PARAMETER string
        The string data to evaluate.

    .EXAMPLE
        An example

    .NOTES
        # This regex looks for patterns such as "1 (Lock Workstation) or 2 (Force Logoff)"
#>
function Test-StringIsPositiveOr
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $string
    )

    <#
        Optional characters were seperated from the rest of the RegEx because it is a repeating
        pattern. If new characters are discovered in the future, they can be added here and in
        the tests.
    #>
    $optionalCharacter = "(\(|'|"")?"

    $regex = "^(\s*)(\d{1,})(\s*)$optionalCharacter.*$optionalCharacter" +
             "(\s*)or(\s*)(\d{1,})(\s*)$optionalCharacter.*$optionalCharacter(\s*)$"

    if ($string -match $regex)
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Converts English textual representation of a comparison to a PowerShell code representation.

    .DESCRIPTION
        Using the Abstract Syntax Tree capability of PowerShell, the provided string is broken into
        individual AST Tokens. Those tokens are then combined to form the PowerShell version of the
        English text.

        The output of this function is intended to be added to any STIG rule that is ambiguous due to
        a range of possibilities be valid. The test string is used to determine if a local
        organizational setting is within a valid range according to the STIG.

    .PARAMETER String
        The string to convert

    .EXAMPLE
        This example returns the following comparison test

            -ne '1|2'

        ConvertTo-OrTestString -String '1 or 2 = a Finding' -Operator NotEqual

    .EXAMPLE
        This example returns the following comparison test

            -eq '1|2'

        ConvertTo-OrTestString -String '1 (Lock Workstation) or 2 (Force Logoff)' -Operator Equal

    .NOTES
        General notes
#>
function ConvertTo-OrTestString
{
    [CmdletBinding()]
    [OutputType([string])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String,

        [Parameter(Mandatory = $true)]
        [ValidateSet('Match', 'NotMatch')]
        [String]
        $Operator
    )

    $operatorString = @{
        'Match'    = '-match'
        'NotMatch' = '-notmatch'
    }

    try
    {
        $tokens = [System.Management.Automation.PSParser]::Tokenize($string, [ref]$null)
        $numbers = $tokens.Where( {$PSItem.type -eq 'Number'}).Content
        "{0} $($operatorString[$Operator]) '$($numbers -join "|")'"
    }
    catch
    {
        Throw "Unable to convert $string into test string."
    }
}
#endregion
#region Greater Than

<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsGreaterThan -String '14 (or greater)'

    .NOTES
        Sample STIG data would convert
#>
function Test-StringIsGreaterThan
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    if ($string -match "^(\s*)Greater(\s*)than(\s*)(\d{1,})(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsGreaterThanOrEqual -String '0x00000032 (50) (or greater)'

    .NOTES
        Sample STIG data would convert 0x00000032 (50) (or greater) into '-ge 50'"
#>
function Test-StringIsGreaterThanOrEqual
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    if ($string -match "^(\s*)((0x[A-Fa-f0-9]{8}){1})|(\d{1,})(\s*)(\()?or(\s*)greater(\s*)(\))?(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsGreaterThanButNot -String 'Greater than 30'

    .NOTES
        Sample STIG data would convert 30 (or greater, but not 100)
#>
function Test-StringIsGreaterThanButNot
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    if ($string -match "^(\s*)greater(\s*)than(\s*)(\d{1,})(\s*)(\()?(\s*)but(\s*)not(\s*)(\d{1,})(\))?(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsGreaterThanOrEqualToButNot -String '0x00000032 (50) (or greater)'

    .NOTES
        Sample STIG data
#>
function Test-StringIsGreaterThanOrEqualButNot
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    if ($string -match "^(\s*)(\d{1,})(\s*)(\()?(\s*)or(\s*)greater(\s*),(\s*)but(\s*)not(\s*)(\d{1,})(\))?(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}
#endregion
#region Less Than
<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsLessThan -String 'is less than "14"'
#>
function Test-StringIsLessThan
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    if ($String -match "^(\s*)less(\s*)than(\s*)(\d{1,})(\))?(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsLessThanOrEqual -String '"4" logons or less'
#>
function Test-StringIsLessThanOrEqual
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )
    # Turn 0x00000384 (900) (or less) into '-le 900'
    if ($String -match "^((\s*)((0x[A-Fa-f0-9]{8}){1}))?(\s*)(\()?(\d{1,})(\))?(\s*)(\()?or(\s*)less(\))?(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsLessThanButNot -String 'Less than 30 (but not 0)'

    .NOTES
        Sample STIG data would convert "Less than 30 (but not 0)" into '$i -lt "30" -and $i -gt 0'
#>
function Test-StringIsLessThanButNot
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    #"$i -lt $value -and -ne $x"

    if ($string -match "^(\s*)less(\s*)than(\s*)(\d{1,})(\s*)(\()?but(\s*)not(\s*)(\d{1,})(\))?(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsLessThanOrEqualToButNot -String '30 (or less, but not 0)'

    .EXAMPLE
        This example returns $true

        Test-StringIsLessThanOrEqualToButNot -String '0x0000001e (30) (or less, but not 0)'

    .NOTES
        Sample STIG data would convert 30 (or less, but not 0) into '$i -le "30" -and $i -gt 0'
        Sample STIG data would convert 0x0000001e (30) (or less, but not 0) into '$i -le "30" -and $i -gt 0'
#>
function Test-StringIsLessThanOrEqualButNot
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    if ($string -match "^(\s*)(\d{1,})(\s*)(\()?or(\s*)less(\s*),(\s*)but(\s*)not(\s*)(\d{1,})(\))?(\s*)$" -or
        $string -match "(\s*)(\()(\d{1,})(\))(\s*)(\()?or(\s*)less(\s*),(\s*)but(\s*)not(\s*)(\d{1,})(\))?(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}
<#
    .SYNOPSIS
        Converts English textual representation of numeric ranges into PowerShell equivalent
        comparison statements.

    .PARAMETER string
        The String to test.

    .EXAMPLE
        This example returns $true

        Test-StringIsLessThanOrEqualExcluding -String '0x0000001e (30) (or less, excluding 0)'

    .NOTES
        Sample STIG data would convert 0x0000001e (30) (or less, excluding 0) into '$i -le "30" -and $i -gt 0'
#>
function Test-StringIsLessThanOrEqualExcluding
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    if ($string -match "(\s*)(\()?(\d{1,})(\))?(\s*)(\()?or(\s*)less(\s*),(\s*)excluding(\s*)(\d{1,})(\))?(\s*)$")
    {
        $true
    }
    else
    {
        $false
    }
}
#endregion
#region Multiple Values
<#
    .SYNOPSIS
        Test if the string may contain multiple setting values

    .PARAMETER String
        The string to test

    .EXAMPLE
        This example returns $true

        Test-StringIsMultipleValue -String 'Possible values are orange, lemon, cherry'
#>
function Test-StringIsMultipleValue
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [string]
        $String
    )

    if ($string -match "(?<=Possible values are ).*")
    {
        $true
    }
    else
    {
        $false
    }
}

<#
    .SYNOPSIS
        Returns the possible setting values

    .PARAMETER String
        The string to test

    .EXAMPLE
        This example returns "{0} -match 'orange|lemon|cherry'""

    ConvertTo-MultipleValue -String 'Possible values are orange, lemon, cherry'
#>
function ConvertTo-MultipleValue
{
    [CmdletBinding()]
    [OutputType([string])]
    Param
    (
        [parameter(Mandatory)]
        [string[]] $String
    )

    $values = [regex]::match( $string, "(?<=Possible values are ).*" ).groups.Value
    $options = $values.replace(', ', '|')

    Write-Verbose "[$($MyInvocation.MyCommand.Name)] Possible Values : $options "

    return $( "'{0}' -match '^($options)$'" )
}
#endregion
#region Security Policy
<#
    .SYNOPSIS
        Selects the string that contains the policy setting and value(s)
#>
function Get-SecurityPolicyString
{
    [CmdletBinding()]
    [OutputType([string])]
    param
    (
        [parameter(Mandatory = $true)]
        [AllowEmptyString()]
        [string[]]
        $CheckContent
    )

    Write-Verbose "[$($MyInvocation.MyCommand.Name)]"
    $stringMatch = 'If the (value for (the)?)?|(value\s)'
    $result = ( $CheckContent | Select-String -Pattern $stringMatch ) -replace $stringMatch, ''
    # 'V-63427' (Win10) returns multiple matches. This is ensure the only the correct one is returned.
    $result = $result | Where-Object -FilterScript {$PSItem -notmatch 'site is using a password filter'}
    # V-73317 (WinSvr 2016) returns multiple matches, but we want both joined to calculate the range.
    $result = ($result -join " or ").Trim()
    return $result
}

<#
    .SYNOPSIS
        Checks the string for text that indicates a range of acceptable
        acceptable values are allowed by the STIG.
#>
function Test-SecurityPolicyContainsRange
{
    [CmdletBinding()]
    [OutputType([bool])]
    param
    (
        [parameter(Mandatory = $true)]
        [AllowEmptyString()]
        [string[]]
        $CheckContent
    )

    Write-Verbose "[$($MyInvocation.MyCommand.Name)]"

    $string = Get-SecurityPolicyString -CheckContent $CheckContent
    $string = Get-TestStringTokenList -String $string

    if ( $string -match '(?:is not set to )(?!(?:(a )other than)).*(?:this is a finding\.)' )
    {
        return $false
    }

    return $true
}

<#
    .SYNOPSIS
        Converts the Check-Content string into a PowerShell comparison string that can validate
        user input to organizational values.
#>
function Get-SecurityPolicyOrganizationValueTestString
{
    [CmdletBinding()]
    param
    (
        [parameter(Mandatory = $true)]
        [AllowEmptyString()]
        [string[]]
        $CheckContent
    )

    Write-Verbose "[$($MyInvocation.MyCommand.Name)]"

    $stringBase = Get-SecurityPolicyString -CheckContent $CheckContent
    $string = Get-TestStringTokenList -String $stringBase -CommandTokens
    $settings = Get-TestStringTokenList -String $stringBase -StringTokens

    $reverse = @{
        'lt' = 'ge';
        'le' = 'gt';
        'gt' = 'le';
        'ge' = 'lt';
        'eq' = 'ne';
        'ne' = 'eq'
    }

    # The index string to add to the comparison for use in composite formatting.
    $indexString = "'{0}'"
    # The variable needs to be strongly typed for the indexing to work properly, when a single operator is found.
    # If not strongly typed, a single operator will return indexed characters.
    [string[]] $operators = @()
    # Some of the sentence structure is inverted, so this flag will realign the sentence structure so that that range operator
    # is always before the eq|ne operators.
    $invertAdjective = $false
    # Some of the ranges have exclusions, so the comparison operator should not be inverted and this flag controls that.
    $excludeSecondAdjective = $false

    switch ($string)
    {
        {$string -match '^is set to'}
        {
            $operators = 'eq'
        }
        {$string -match '^is less than(?!.*excluding)'}
        {
            $operators = 'lt'; continue
        }
        {$string -match '^is less than(?=.*excluding)'}
        {
            $operators = 'lt', 'or', 'eq'; $excludeSecondAdjective = $true; continue
        }
        {$string -match '^is greater than(?!.*(excluding|is set))'}
        {
            $operators = 'gt'; continue
        }
        {$string -match '^is greater than.*(?=is set)'}
        {
            $operators = 'gt', 'and', 'eq'; continue
        }
        # The InvertAdjective changes the string to read 'is more than or' to move the equal to the second position like everything else.
        {$string -match '^is or more than'}
        {
            $operators = 'gt', 'and', 'eq'; $invertAdjective = $true; continue
        }
        {$string -match '^is not set to a other than'}
        {
            $operators = 'eq'
        }
    }

    # Since the sentence was inverted, the value positions need to be inverted as well.
    if ($invertAdjective)
    {
        $firstValue = $settings[2]
        $secondValue = $settings[1]
    }
    else
    {
        $firstValue = $settings[1]
        $secondValue = $settings[2]
    }

    # Some settings are negated with the string 'this is a finding, so invert the comparison operators if the check is negated.
    if ($string -match 'this is a finding')
    {
        # if a string contains and/or build that into the test string operators
        if ($operators.count -gt '1')
        {
            # Some settings have values that need to be excluded from a range, so do not invert that operator
            if ($excludeSecondAdjective)
            {
                "$indexString -$($reverse[$operators[0]]) '$firstValue' -$($operators[1]) $indexString -$($operators[2]) '$secondValue'"
            }
            else
            {
                "$indexString -$($reverse[$operators[0]]) '$firstValue' -$($operators[1]) $indexString -$($reverse[$operators[2]]) '$secondValue'"
            }
        }
        else
        {
            "$indexString -$($reverse[$operators[0]]) '$firstValue'"
        }
    }
    else
    {
        "$indexString -$operators '$firstValue'"
    }
}
#endregion