DSCResources/AuditPolicyResourceHelper/AuditPolicyResourceHelper.psm1
|
#Requires -Version 4.0 <# This PS module contains functions for Desired State Configuration (DSC) AuditPolicyDsc provider. It enables querying, creation, removal and update of Windows advanced audit policies through Get, Set, and Test operations on DSC managed nodes. #> <# .SYNOPSIS Retrieves the localized string data based on the machine's culture. Falls back to en-US strings if the machine's culture is not supported. .PARAMETER ResourceName The name of the resource as it appears before '.strings.psd1' of the localized string file. For example: AuditPolicySubcategory: MSFT_AuditPolicySubcategory AuditPolicyOption: MSFT_AuditPolicyOption #> function Get-LocalizedData { [CmdletBinding()] param ( [Parameter(Mandatory = $true, ParameterSetName = 'resource')] [ValidateNotNullOrEmpty()] [String] $ResourceName, [Parameter(Mandatory = $true, ParameterSetName = 'helper')] [ValidateNotNullOrEmpty()] [String] $HelperName ) # With the helper module just update the name and path variables as if it were a resource. if ($PSCmdlet.ParameterSetName -eq 'helper') { $resourceDirectory = $PSScriptRoot $ResourceName = $HelperName } else { # Step up one additional level to build the correct path to the resource culture. $resourceDirectory = Join-Path -Path ( Split-Path $PSScriptRoot -Parent ) ` -ChildPath $ResourceName } $localizedStringFileLocation = Join-Path -Path $resourceDirectory -ChildPath $PSUICulture if (-not (Test-Path -Path $localizedStringFileLocation)) { # Fallback to en-US $localizedStringFileLocation = Join-Path -Path $resourceDirectory -ChildPath 'en-US' } Import-LocalizedData ` -BindingVariable 'localizedData' ` -FileName "$ResourceName.strings.psd1" ` -BaseDirectory $localizedStringFileLocation return $localizedData } <# .SYNOPSIS Invoke-AuditPol is a private function that wraps auditpol.exe providing a centralized function to manage access to and the output of auditpol.exe. .DESCRIPTION The function will accept a string to pass to auditpol.exe for execution. Any 'get' or 'set' opertions can be passed to the central wrapper to execute. All of the nuances of auditpol.exe can be further broken out into specalized functions that call Invoke-AuditPol. Since the call operator is being used to run auditpol, the input is restricted to only execute against auditpol.exe. Any input that is an invalid flag or parameter in auditpol.exe will return an error to prevent abuse of the call. The call operator will not parse the parameters, so they are split in the function. .PARAMETER Command The action that audtipol should take on the subcommand. .PARAMETER SubCommand The subcommand to execute. .OUTPUTS The raw string output of auditpol.exe with the /r switch to return a CSV string. .EXAMPLE Invoke-AuditPol -Command 'Get' -SubCommand 'Subcategory:Logon' #> function Invoke-AuditPol { [OutputType([Object])] [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [ValidateSet('Get', 'Set', 'List', 'Restore', 'Backup')] [String] $Command, [Parameter(Mandatory = $true)] [String[]] $SubCommand ) # Localized messages for Write-Verbose statements in this resource $localizedData = Get-LocalizedData -HelperName 'AuditPolicyResourceHelper' <# The raw auditpol data with the /r switch is a 3 line CSV 0 - header row 1 - blank row 2 - the data row we are interested in #> # set the base commands to execute if ( $Command -eq 'Get') { $auditpolArguments = @("/$Command", "/$SubCommand", "/r" ) } else { # The set subcommand comes in an array of the subcategory and flag $auditpolArguments = @("/$Command", "/$($SubCommand[0])", $SubCommand[1] ) } Write-Debug -Message ( $localizedData.ExecuteAuditpolCommand -f $auditpolArguments ) try { # Use System.Diagnostics.Process to process the auditpol command $process = New-Object System.Diagnostics.Process $process.StartInfo.Arguments = $auditpolArguments $process.StartInfo.CreateNoWindow = $true $process.StartInfo.FileName = 'auditpol.exe' $process.StartInfo.RedirectStandardOutput = $true $process.StartInfo.UseShellExecute = $false $null = $process.Start() $auditpolReturn = $process.StandardOutput.ReadToEnd() # auditpol does not throw exceptions, so test the results and throw if needed if ( $process.ExitCode -ne 0 ) { throw New-Object System.ArgumentException } if ( $Command -notmatch "Restore|Backup" ) { return ( ConvertFrom-Csv -InputObject $auditpolReturn ) } } catch [System.ComponentModel.Win32Exception] { # Catch error if the auditpol command is not found on the system Write-Error -Message $localizedData.AuditpolNotFound } catch [System.ArgumentException] { # Catch the error thrown if the lastexitcode is not 0 [String] $errorString = $error[0].Exception $errorString = $errorString + "`$LASTEXITCODE = $LASTEXITCODE;" $errorString = $errorString + " Command = auditpol $commandString" Write-Error -Message $errorString } catch { # Catch any other errors Write-Error -Message ( $localizedData.UnknownError -f $error[0] ) } } <# .SYNOPSIS Get-FixedLanguageAuditCSV is a private function that returns the contents of a CSV with US-English names, even if input is not US English .PARAMETER Path The path to stage the auditCSV to (defaulted to the temp directory). FILE MUST EXIST AND BE A VALID AUDIT.CSV FILE, AND THE FIRST LINE MUST BE THE CSV HEADER. .OUTPUTS Content from the file converted from CSV to custom objects with US-English property names. .EXAMPLE $csv = Get-StagedAuditPolicy #> function Get-FixedLanguageAuditCSV { [OutputType([System.Object[]])] [CmdletBinding()] param ( [Parameter()] [String] $Path = $(Join-Path -Path $env:Temp -ChildPath "audit.csv") ) $headerSet = "Machine Name", "Policy Target", "Subcategory", "Subcategory GUID", "Inclusion Setting", "Exclusion Setting", "Setting Value" return (Get-Content -Path $Path | Select-Object -Skip 1 | ConvertFrom-Csv -Header $headerSet) } <# .SYNOPSIS Get-StagedAuditPol is a private function that creates staged AuditPolicy CSVs for usage over several resource blocks .DESCRIPTION The function tests if a staged AuditPolicyCSV is available and not out of date. If needed, it creates a new staged CSV .PARAMETER Path The path to stage the auditCSV to (defaulted to the temp directory) .OUTPUTS The current or newly created Staged CSV. .EXAMPLE $csv = Get-StagedAuditPolicy #> function Get-StagedAuditPolicyCSV { [OutputType([System.Object[]])] [CmdletBinding()] param ( [Parameter()] [String] $Path = $(Join-Path -Path $env:Temp -ChildPath "audit.csv") ) # Localized messages for Write-Verbose statements in this resource $localizedData = Get-LocalizedData -HelperName 'AuditPolicyResourceHelper' $auditCSV = Get-Item -Path $Path -ErrorAction SilentlyContinue if ($null -ne $auditCSV) { # Determine if the CSV was created more than 5 minutes ago, if it was, delete it and create a new one. if ((New-TimeSpan -Start $auditCSV.CreationTime -End ([datetime]::Now)).Minutes -ge 5) { Write-Debug -Message ( $localizedData.AuditCSVOutdated -f $path, $auditCSV.CreationTime) Try { Remove-Item -Path $auditCSV -Force Write-Debug -Message ( $localizedData.AuditCSVDeleted -f $Path) } Catch { Write-Debug -Message ( $localizedData.AuditCSVLocked -f $Path) Continue } } else { Write-Debug -Message ( $localizedData.AuditCSVLocked -f $Path) return Get-FixedLanguageAuditCSV -Path $auditCSV } } Write-Debug -Message ( $localizedData.AuditCSVNotFound -f $Path) Invoke-AuditPol -Command "Backup" -SubCommand "file:$Path" Write-Debug -Message ( $localizedData.AuditCSVCreated -f $auditCSV ) if (!(Test-Path -Path $Path)) { $inf = [System.Management.Automation.ItemNotFoundException]::new( ($localizedData.FileNotFound -f $Path), $fnf) Throw $inf } $auditCSV = Get-Item -Path $Path return Get-FixedLanguageAuditCSV $auditCSV } # Static Name translation to ensure GUIDS are the source of truth. ### Hash table to map audit subcategory names (US English) to GUIDs $AuditSubcategoryToGUIDHash = @{ ###### Edited from "auditpol /list /subcategory:* /v" ###### ######Category/Subcategory GUID ######System = "69979848-797A-11D9-BED3-505054503030"; "Security State Change" = "0CCE9210-69AE-11D9-BED3-505054503030"; "Security System Extension" = "0CCE9211-69AE-11D9-BED3-505054503030"; "System Integrity" = "0CCE9212-69AE-11D9-BED3-505054503030"; "IPsec Driver" = "0CCE9213-69AE-11D9-BED3-505054503030"; "Other System Events" = "0CCE9214-69AE-11D9-BED3-505054503030"; ######Logon/Logoff = "69979849-797A-11D9-BED3-505054503030"; "Logon" = "0CCE9215-69AE-11D9-BED3-505054503030"; "Logoff" = "0CCE9216-69AE-11D9-BED3-505054503030"; "Account Lockout" = "0CCE9217-69AE-11D9-BED3-505054503030"; "IPsec Main Mode" = "0CCE9218-69AE-11D9-BED3-505054503030"; "IPsec Quick Mode" = "0CCE9219-69AE-11D9-BED3-505054503030"; "IPsec Extended Mode" = "0CCE921A-69AE-11D9-BED3-505054503030"; "Special Logon" = "0CCE921B-69AE-11D9-BED3-505054503030"; "Other Logon/Logoff Events" = "0CCE921C-69AE-11D9-BED3-505054503030"; "Network Policy Server" = "0CCE9243-69AE-11D9-BED3-505054503030"; "User / Device Claims" = "0CCE9247-69AE-11D9-BED3-505054503030"; "Group Membership" = "0CCE9249-69AE-11D9-BED3-505054503030"; ######Object Access = "6997984A-797A-11D9-BED3-505054503030"; "File System" = "0CCE921D-69AE-11D9-BED3-505054503030"; "Registry" = "0CCE921E-69AE-11D9-BED3-505054503030"; "Kernel Object" = "0CCE921F-69AE-11D9-BED3-505054503030"; "SAM" = "0CCE9220-69AE-11D9-BED3-505054503030"; "Certification Services" = "0CCE9221-69AE-11D9-BED3-505054503030"; "Application Generated" = "0CCE9222-69AE-11D9-BED3-505054503030"; "Handle Manipulation" = "0CCE9223-69AE-11D9-BED3-505054503030"; "File Share" = "0CCE9224-69AE-11D9-BED3-505054503030"; "Filtering Platform Packet Drop" = "0CCE9225-69AE-11D9-BED3-505054503030"; "Filtering Platform Connection" = "0CCE9226-69AE-11D9-BED3-505054503030"; "Other Object Access Events" = "0CCE9227-69AE-11D9-BED3-505054503030"; "Detailed File Share" = "0CCE9244-69AE-11D9-BED3-505054503030"; "Removable Storage" = "0CCE9245-69AE-11D9-BED3-505054503030"; "Central Policy Staging" = "0CCE9246-69AE-11D9-BED3-505054503030"; ######Privilege Use = "6997984B-797A-11D9-BED3-505054503030"; "Sensitive Privilege Use" = "0CCE9228-69AE-11D9-BED3-505054503030"; "Non Sensitive Privilege Use" = "0CCE9229-69AE-11D9-BED3-505054503030"; "Other Privilege Use Events" = "0CCE922A-69AE-11D9-BED3-505054503030"; ######Detailed Tracking = "6997984C-797A-11D9-BED3-505054503030"; "Process Creation" = "0CCE922B-69AE-11D9-BED3-505054503030"; "Process Termination" = "0CCE922C-69AE-11D9-BED3-505054503030"; "DPAPI Activity" = "0CCE922D-69AE-11D9-BED3-505054503030"; "RPC Events" = "0CCE922E-69AE-11D9-BED3-505054503030"; "Plug and Play Events" = "0CCE9248-69AE-11D9-BED3-505054503030"; "Token Right Adjusted Events" = "0CCE924A-69AE-11D9-BED3-505054503030"; ######Policy Change = "6997984D-797A-11D9-BED3-505054503030"; "Audit Policy Change" = "0CCE922F-69AE-11D9-BED3-505054503030"; "Authentication Policy Change" = "0CCE9230-69AE-11D9-BED3-505054503030"; "Authorization Policy Change" = "0CCE9231-69AE-11D9-BED3-505054503030"; "MPSSVC Rule-Level Policy Change" = "0CCE9232-69AE-11D9-BED3-505054503030"; "Filtering Platform Policy Change" = "0CCE9233-69AE-11D9-BED3-505054503030"; "Other Policy Change Events" = "0CCE9234-69AE-11D9-BED3-505054503030"; ######Account Management = "6997984E-797A-11D9-BED3-505054503030"; "User Account Management" = "0CCE9235-69AE-11D9-BED3-505054503030"; "Computer Account Management" = "0CCE9236-69AE-11D9-BED3-505054503030"; "Security Group Management" = "0CCE9237-69AE-11D9-BED3-505054503030"; "Distribution Group Management" = "0CCE9238-69AE-11D9-BED3-505054503030"; "Application Group Management" = "0CCE9239-69AE-11D9-BED3-505054503030"; "Other Account Management Events" = "0CCE923A-69AE-11D9-BED3-505054503030"; ######DS Access = "6997984F-797A-11D9-BED3-505054503030"; "Directory Service Access" = "0CCE923B-69AE-11D9-BED3-505054503030"; "Directory Service Changes" = "0CCE923C-69AE-11D9-BED3-505054503030"; "Directory Service Replication" = "0CCE923D-69AE-11D9-BED3-505054503030"; "Detailed Directory Service Replication" = "0CCE923E-69AE-11D9-BED3-505054503030"; ######Account Logon = "69979850-797A-11D9-BED3-505054503030"; "Credential Validation" = "0CCE923F-69AE-11D9-BED3-505054503030"; "Kerberos Service Ticket Operations" = "0CCE9240-69AE-11D9-BED3-505054503030"; "Other Account Logon Events" = "0CCE9241-69AE-11D9-BED3-505054503030"; "Kerberos Authentication Service" = "0CCE9242-69AE-11D9-BED3-505054503030"; } ### Hash table to map GUIDs to audit subcategory names (US English) $AuditGUIDToSubCategoryHash = @{} $AuditSubcategoryToGUIDHash.Keys | ForEach-Object { $AuditGUIDToSubCategoryHash.Add($AuditSubcategoryToGUIDHash[$_], $_) } $AuditFlagToSettingValue = @{ 'No Auditing' = 0 'Success' = 1 'Failure' = 2 'Success and Failure' = 3 } $AuditSettingValueToFlag = @( 'No Auditing', 'Success', 'Failure', 'Success and Failure' ) <# .SYNOPSIS Write-StagedAuditCSV is a private function that writes new values to the Staged Audit.CSV and imports them using auditpol .DESCRIPTION The function takes a new value to write and combines it with the staged csv. .PARAMETER Name The subcategory. .PARAMETER Flag The flag the subcategory should be set to. .PARAMETER Path The path to stage the auditCSV to (defaulted to the temp directory) .OUTPUTS The current or newly created Staged CSV. .EXAMPLE Write-StagedAuditCSV -Name #> function Write-StagedAuditCSV { [OutputType([System.Object[]])] [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [GUID] $GUID, [Parameter(Mandatory = $true)] [ValidateRange(0, 4)] [Int] $SettingValue, [Parameter()] [String] $Path = $(Join-Path -Path $env:Temp -ChildPath "audit.csv"), [Parameter(Mandatory = $true)] [ValidateSet("Present", "Absent")] [String] $Ensure ) if ($AuditGUIDToSubCategoryHash.ContainsKey($GUID.Guid)) { $Name = $AuditGUIDToSubCategoryHash[$GUID.Guid] } else { Throw ($localizedData.SubCategoryTranslationFailed -f $GUID) } # translate Present/Absent to inclusion settings $auditState = [pscustomobject]@{ 'Inclusion Setting' = '' 'Exclusion Setting' = '' } $auditFlag = $AuditSettingValueToFlag[$SettingValue] # Localized messages for Write-Verbose statements in this resource $localizedData = Get-LocalizedData -HelperName 'AuditPolicyResourceHelper' $auditCSV = Get-StagedAuditPolicyCSV $currentValue = $auditCSV.Where( {$_.'SubCategory GUID' -eq "{$($GUID.guid)}"}) $currentSetting = 0 if ($null -eq $currentValue) { Write-Debug -Message ($localizedData.CurrentCSVValueMissing -f $GUID) $currentSetting = 0 } else { $currentSetting = $currentValue.'Setting Value' } if ($Ensure -eq "Present") { $auditState.'Inclusion Setting' = $auditFlag } else { switch ($currentSetting) { 0 { # There's no way to set the Absent of No Auditing. # Should it be Success? Failure? Both? return } 1 { if ($currentSetting -eq 1) { # If Success is absent and the current value is Success, the result is "No Auditing" $SettingValue = 0 } elseif ($currentSetting -eq 3) { # If Success is absent and the current value is Succes and Failure, the result is Failure. $SettingValue = 2 } else { $SettingValue = $currentSetting } } 2 { if ($currentSetting -eq 2) { # If Failure is absent and the current value is Failure, the result is "No Auditing" $SettingValue = 0 } elseif ($currentSetting -eq 3) { # If Success is absent and the current value is Succes and Failure, the result is Success. $SettingValue = 1 } else { $SettingValue = $currentSetting } } 3 { # if Success And Failure should be absent, the result is No Auditing $SettingValue = 0 } } $auditState.'Exclusion Setting' = $auditFlag } $auditCSV = $auditCSV | Where-Object {$_.'Subcategory GUID' -ne "{$($GUID.guid)}" -and !([string]::IsNullOrEmpty($_.'Subcategory GUID'))} $tmpValue = [pscustomobject][ordered]@{ 'Machine Name' = $env:ComputerName 'Policy Target' = "System" 'Subcategory' = "Audit $Name" 'SubCategory GUID' = "{$($GUID.guid)}" 'Inclusion Setting' = $auditState.'Inclusion Setting' 'ExclusionSetting' = $auditState.'Exclusion Setting' 'Setting Value' = $SettingValue } $auditCSV += $tmpValue Write-Debug -Message ( $localizedData.WriteStagedCSV -f $Guid, $AuditFlag ) Try { $auditCSV | ConvertTo-Csv -NoTypeInformation | ForEach-Object {$_.Replace('"', '')} | Out-File -FilePath $Path -Force } Catch { Throw ($localizedata.SaveAuditCSVFailure -f $Path) } Invoke-AuditPol -Command Restore -SubCommand "file:$Path" Write-Debug -Message ( $localizedData.RestoredAuditCSV ) } <# .SYNOPSIS Returns the list of valid Subcategories. .DESCRIPTION This funciton will check if the list of valid subcategories has already been created. If the list exists it will simply return it. If it doe not exists, it will generate it and return it. #> function Get-ValidSubcategoryList { [OutputType([String[]])] [CmdletBinding()] param () if ( $null -eq $script:validSubcategoryList ) { $script:validSubcategoryList = @() # Populating $validSubcategoryList uses Invoke-AuditPol and needs to follow the definition. # Populating $validSubcategoryList uses Invoke-AuditPol and needs to follow the definition. $script:validSubcategoryList = Invoke-AuditPol -Command Get -SubCommand "category:*" | Select-Object -Property Subcategory -ExpandProperty Subcategory } return $script:validSubcategoryList } <# .SYNOPSIS Verifies that the Subcategory is valid. .PARAMETER Name The name of the Subcategory to validate. #> function Test-ValidSubcategory { [OutputType([Boolean])] [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [String] $Name ) if ( ( Get-ValidSubcategoryList ) -icontains $Name ) { return $true } else { return $false } } Export-ModuleMember -Variable AuditSubCategorytoGUIDHash, AuditGUIDTOSubCategoryHash, AuditFlagToSettingValue, AuditSettingValueToFlag -Function @( 'Invoke-AuditPol', 'Get-LocalizedData', 'Write-StagedAuditCSV', 'Get-StagedAuditPolicyCSV', 'Get-FixedLanguageAuditCSV', 'Test-ValidSubcategory' ) |