Why a PowerShell Module

Sysmon configuration can be complex in addition to hard to maintain by hand. For this purpose I created a module called Posh-Sysmon some time ago to aid in the creation and maintenance of configuration files. The module was initially written after the release of version 2.0 and has been maintained and expanded as new version have been released all the way to the current one at the time of this blog post being written with version 6.0. 

The module is written for PowerShell v3.0 and above and can be installed from the PowerShell Gallery if running version 5.0 or 5.1 using the cmdlet 

Install-Module -Name Posh-Sysmon

If running PowerShell 3.0 or 4.0 it can use the PowerShell Gallery also following instruction in PowerShell Gallery Documentation

Onced install we can see all cmdlets available using Get-Command to list all for the module.

PS C:\> Get-Command -Module Posh-Sysmon

CommandType     Name                                               Version    Source
-----------     ----                                               -------    ------
Function        Get-SysmonEventData                                0.7.5      Posh-Sysmon
Function        Get-SysmonHashingAlgorithm                         0.7.5      Posh-Sysmon
Function        Get-SysmonRule                                     0.7.5      Posh-Sysmon
Function        Get-SysmonRuleFilter                               0.7.5      Posh-Sysmon
Function        New-SysmonConfiguration                            0.7.5      Posh-Sysmon
Function        New-SysmonDriverLoadFilter                         0.7.5      Posh-Sysmon
Function        New-SysmonFileCreateFilter                         0.7.5      Posh-Sysmon
Function        New-SysmonFileCreateStreamHashFilter               0.7.5      Posh-Sysmon
Function        New-SysmonImageLoadFilter                          0.7.5      Posh-Sysmon
Function        New-SysmonNetworkConnectFilter                     0.7.5      Posh-Sysmon
Function        New-SysmonPipeFilter                               0.7.5      Posh-Sysmon
Function        New-SysmonProcessAccessFilter                      0.7.5      Posh-Sysmon
Function        New-SysmonProcessCreateFilter                      0.7.5      Posh-Sysmon
Function        New-SysmonProcessTerminateFilter                   0.7.5      Posh-Sysmon
Function        New-SysmonRegistryFilter                           0.7.5      Posh-Sysmon
Function        Remove-SysmonRule                                  0.7.5      Posh-Sysmon
Function        Remove-SysmonRuleFilter                            0.7.5      Posh-Sysmon
Function        Set-SysmonHashingAlgorithm                         0.7.5      Posh-Sysmon
Function        Set-SysmonRule                                     0.7.5      Posh-Sysmon

Creating a Configuration File

The first cmdlet we use is New-SysmonConfiguration. It allows us to create the initial configuration file where we can specify:

• Hash Algorithm, Supported options:
  • MD5
  • SHA1
  • SHA256
  • IMPHASH
  • ALL
• Schema Version (Defaults to the latest version 3.3)
• Enable Certificate Revocation check for signed drivers.
• Log all event for a specified EventType with an empty exclude rule. Switches for event types are:
  • DriverLoad
  • ImageLoad
  • FileCreate
  • FileCreateStreamHash
  • RawAcess
  • ProcessCreate
  • ProcessTerminate
  • ProcessAccess
  • RegistryEvent
  • NetworkConnect
  • PipeEvent

The cmdlet only has 2 required parameters the Path where to save the configuration file and the HashAlgorithm to use. In the following example, we will create a new configuration file and we will enable all hashing algorithms and set rules to log all process creation and termination.

PS C:\> New-SysmonConfiguration -Path .\sales_sysmon_config.xml -HashingAlgorithm all -ProcessCreate -ProcessTerminate -Verbose
VERBOSE: Enabling hashing algorithms: *
VERBOSE: Enabling logging all process creation by setting no filter and onmatch to exclude.
VERBOSE: Enabling logging all process termination by setting no filter and onmatch to exclude.
VERBOSE: Config file created as C:\Users\Carlos\Documents\sales_sysmon_config.xml
VERBOSE: Configuration is for Sysmon 6.0</code>

The configuration file content will be:

<Sysmon schemaversion="3.3">
 <HashAlgorithms>*</HashAlgorithms>
 <EventFiltering>
  <ProcessCreate  onmatch="exclude">
  </ProcessCreate >
  <ProcessTerminate  onmatch="exclude">
  </ProcessTerminate >
 </EventFiltering>
</Sysmon>

We can modify the hash algorithms configured in the configuration file easily with the Set- SysmonHashingAlgorithm cmdlet and check the current one with the Get- SysmonHashingAlgorithm cmdlet. Lets look at the one currently set.

PS C:\> Get- SysmonHashingAlgorithm -Path .\sales_sysmon_config.xml

Hashing
-------
*

We can now modify the algorithm to be SHA1 using the Set- SysmonHashingAlgorithm cmdlet and verify that it was properly set using the Get- SysmonHashingAlgorithm

PS C:\> Set-SysmonHashingAlgorithm -Path .\sales_sysmon_config.xml -HashingAlgorithm SHA1
PS C:\> Get-SysmonHashingAlgorithm -Path .\sales_sysmon_config.xml

Hashing
-------
SHA1

Working with Event Types

We can manage the Rules in the configuration file using the following cmdlets:

• Get-SysmonRule – Look at a specified or all  Rules configured in a configuration file and their filters.
• Remove-SysmonRule – Remove a specific rule in a configuration file.
• Set-SysmonRule – Add or modify a rule in a configuration file.

Let’s take a look at the rules we have on the current file:

PS C:\> Get-SysmonRule -Path .\sales_sysmon_config.xml


EventType     : ProcessCreate
Scope         : All Events
DefaultAction : Exclude
Filters       :

EventType     : ProcessTerminate
Scope         : All Events
DefaultAction : Exclude
Filters       :

We can specify a EventType so we only see the rule for that specific one:

PS C:\> Get-SysmonRule -Path .\sales_sysmon_config.xml  -EventType ProcessTerminate


EventType     : ProcessTerminate
Scope         : All Events
DefaultAction : Exclude
Filters       :

We can add a rule for a specific event type using Set-SysmonRule, if the rule does not previously exist it will add the rule for with the specific OnMatch action. 

PS C:\> Set-SysmonRule -Path .\sales_sysmon_config.xml -EventType ProcessAccess -OnMatch Exclude -Verbose
VERBOSE: No rule for ProcessAccess was found.
VERBOSE: Creating rule for event type with action of Exclude
VERBOSE: Action has been set.


EventType     : ProcessAccess
Scope         : All Events
DefaultAction : Exclude
Filters       :

We can modify the rule OnMatch action if no other rule of the same event type exist, the default action is to modify. 

PS C:\> Set-SysmonRule -Path .\sales_sysmon_config.xml -EventType ProcessAccess -OnMatch Include -Verbose
VERBOSE: Setting as default action for ProcessAccess the rule on match of Include.
VERBOSE: Action has been set.


EventType     : ProcessAccess
Scope         : All Events
DefaultAction : Include
Filters       :

We can change the default modify action by specifying the action with the Action parameter.

PS C:\> Set-SysmonRule -Path .\sales_sysmon_config.xml -EventType ProcessAccess -OnMatch exclude -Action Add -Verbose
VERBOSE: Creating rule for event type with action of exclude
VERBOSE: Action has been set.


EventType     : ProcessAccess
Scope         : All Events
DefaultAction : Exclude
Filters       :

PS C:\> Get-SysmonRule -Path .\sales_sysmon_config.xml -EventType ProcessAccess


EventType     : ProcessAccess
Scope         : All Events
DefaultAction : Include
Filters       :

EventType     : ProcessAccess
Scope         : All Events
DefaultAction : Exclude
Filters       :

We can remove a specific rule for an given event type and OnMatch action using Remove-SysmonRule.

PS C:\> Remove-SysmonRule -Path .\sales_sysmon_config.xml -EventType ProcessAccess -OnMatch exclude -Verbose
VERBOSE: Removed rule for ProcessAccess.
PS C:\> Get-SysmonRule -Path .\sales_sysmon_config.xml -EventType ProcessAccess


EventType     : ProcessAccess
Scope         : All Events
DefaultAction : Include
Filters       :

Working with Filters

We can have rules for an event type without filters so as to exclude or include all events in a given event type by not having any filter the opposite of the OnMatch action will happen. For managing and creating filters the module includes several functions, 2 general use functions for listing and removing filters for a given event type and one function per each event type with each of the supported fields we can effectively filter on based on the embedded DTD in the sysmon.exe.

The 2 general functions are:

• Get-SysmonRuleFilter - gets all filters for a given event type.
• Remove-SysmonRuleFilter - Removes a specifc filter for a given event type.

Each event type supported by Sysmon have different fields we can filter on. The schema for the XML requires that we provide the correct field and that it is the appropriate case or it will fail when importing the rule, for this reason there is a function for each event type so as to ensure proper formatting and prevent errors that may be caused by modifying the XML file by hand. 

Each of the cmdlets have the name of the event type they will filter followed by the word filter as it can be seen bellow.

• New-SysmonDriverLoadFilter
• New-SysmonFileCreateFilter
• New-SysmonFileCreateStreamHashFilter
• New-SysmonImageLoadFilter
• New-SysmonNetworkConnectFilter
• New-SysmonPipeFilter
• New-SysmonProcessAccessFilter
• New-SysmonProcessCreateFilter
• New-SysmonProcessTerminateFilter
• New-SysmonRegistryFilter

Each of the filtering cmdlets have a default set of parameters:

• Path - Path to the configuration file.
• OnMatch - The on match acttion we whant to create the filter under for the event type.
• Condition - What condition for matching we whant to use.
• EventField - The event type filed we want to filter on.
• Value - The value of what we want to match. 

Here is an example where we create a ProcessAccess filter for LSASS to detect if a malicious process is trying to extract credentials from its memory.

PS C:\> New-SysmonProcessAccessFilter -Path .\sales_sysmon_config.xml -OnMatch include -Condition Contains -EventField TargetImage lsass.exe -Verbose
VERBOSE: Mutiple nodes.
VERBOSE: Found rule for event type ProcessAccess with include
VERBOSE: Creating filters for event type ProcessAccess.
VERBOSE: Creating filter for event filed TargetImage with condition Contains for value lsass.exe.


EventType     : ProcessAccess
Scope         : Filtered
DefaultAction : Include
Filters       : {@{EventField=TargetImage; Condition=contains; Value=lsass.exe}}

We can provide several values so as to create a filter for each with a same condition, event field and on match action. 

Lets create multiple filters for possible malicious connection adapting some of the filters shared by @swiftOnSecurity.  All image entries will be kept in an array, we will create the rule for the event type and then create the filters for it. This will allow us to easily automate rule creation keeping the information either in files that get imported or in variables in a build script that then generated the master config file. 

PS C:\> # Log connections processes that contain
PS C:\> # the following strings under the Image field
PS C:\Users\Carlos\Documents> # Adapted from - https://github.com/SwiftOnSecurity/sysmon-config/blob/master/sysmonconfig-export.xml
PS C:\> $DetectImageConnection = @(
>>>     'C:\Users',
>>>     'C:\ProgramData',
>>>     'C:\Windows\Temp',
>>>     'powershell.exe',
>>>     'cmd.exe',
>>>     'wmic.exe',
>>>     'cscript.exe',
>>>     'wscript.exe',
>>>     'rundll32.exe',
>>>     'notepad.exe',
>>>     'regsvr32.exe')
PS C:\> Set-SysmonRule -Path .\sales_sysmon_config.xml -EventType NetworkConnect -OnMatch Include -Verbos
VERBOSE: No rule for NetworkConnect was found.
VERBOSE: Creating rule for event type with action of Include
VERBOSE: Action has been set.


EventType     : NetworkConnect
Scope         : All Events
DefaultAction : Include
Filters       :

PS C:\> New-SysmonNetworkConnectFilter -Path .\sales_sysmon_config.xml -OnMatch include -Condition Contains -EventField Image -Value $DetectImageConnection -Verbose
VERBOSE: Mutiple nodes.
VERBOSE: Found rule for event type NetworkConnect with include
VERBOSE: Creating filters for event type NetworkConnect.
VERBOSE: Creating filter for event filed Image with condition Contains for value C:\Users.
VERBOSE: Creating filter for event filed Image with condition Contains for value C:\ProgramData.
VERBOSE: Creating filter for event filed Image with condition Contains for value C:\Windows\Temp</Image>.
VERBOSE: Creating filter for event filed Image with condition Contains for value powershell.exe.
VERBOSE: Creating filter for event filed Image with condition Contains for value cmd.exe.
VERBOSE: Creating filter for event filed Image with condition Contains for value wmic.exe.
VERBOSE: Creating filter for event filed Image with condition Contains for value cscript.exe.
VERBOSE: Creating filter for event filed Image with condition Contains for value wscript.exe.
VERBOSE: Creating filter for event filed Image with condition Contains for value rundll32.exe.
VERBOSE: Creating filter for event filed Image with condition Contains for value notepad.exe.
VERBOSE: Creating filter for event filed Image with condition Contains for value regsvr32.exe.

We can take a look of the created filters using the Get-SysmonRuleFilter cmdlet. 

PS C:\> Get-SysmonRuleFilter -Path .\sales_sysmon_config.xml -EventType NetworkConnect -OnMatch include

EventField   Condition    Value
----------   ---------    -----
Image        contains     C:\Users
Image        contains     C:\ProgramData
Image        contains     C:\Windows\Temp
Image        contains     powershell.exe
Image        contains     cmd.exe
Image        contains     wmic.exe
Image        contains     cscript.exe
Image        contains     wscript.exe
Image        contains     rundll32.exe
Image        contains     notepad.exe
Image        contains     regsvr32.exe

Working with Events

The real value of Sysmon is in the events that it generates. The module provides a cmdlet for pulling events from the local machine or from a evtx file parsing the events in to custom objects where each field is a property of the object. By working with objects it allows via the pipeline to better manipulate the data and use it for reporting or for feeding in to other functions to generate filters on. 

The cmdlet for getting events and serialized objects is Get-SysmonEvent. It has the following parameters:

• EventId
• EventType
• MaxEvents
• Path
• StartTime
• EndTime

Lets look at the scenario that we want to log any new driver being loaded. For this we will exclude all known exinting drivers on the system by creating a rule to capture all, applying the rule and then pull the data from the event log to created filters on. 

We create a new configuration file and give it the -DriverLoad parameter to New-SysmonConfiguration so as to log all drivers being loaded. After creating we configuration file we apply the configuration.

PS C:\> New-SysmonConfiguration -Path .\capture_drivers.xml -HashingAlgorithm SHA1 -DriverLoad
PS C:\> sysmon -c .\capture_drivers.xml


System Monitor v6.00 - System activity monitor
Copyright (C) 2014-2017 Mark Russinovich and Thomas Garnier
Sysinternals - www.sysinternals.com

Loading configuration file with schema version 3.30
Configuration file validated.
You need to launch Sysmon as an Administrator.

We now reboot the machine and connect any peripherals we normally use. Now we can use Get-SysmonEventData to get all DriverLoad events and group them under the property signed to make sure all drivers being loaded are signed. 

PS C:\> Get-SysmonEventData -EventType DriverLoad | group -Property signed

Count Name                      Group
----- ----                      -----
  149 true                      {@{EventId=6; EventType=DriverLoad; Computer=DESKTOP-HLPPN56; UtcTime=2017-02-19 14:48:29.007; ImageLoaded=C:\Windows\System32\drivers\ms S...

Using Select-Object cmdlet we now get a list of unique signature names. This list will be used for creating our filters.

PS C:\> Get-SysmonEventData -EventType DriverLoad | select -ExpandProperty signature -Unique
Microsoft Windows
Intel(R) Rapid Storage Technology
VMware
Riverbed Technology
Broadcom Corporation
Intel(R) OWR
Realtek Semiconductor Corp
Intel Corporation
Intel(R) Software
Intel Corporation - Embedded Subsystems and IP Blocks Group
Intel(R) Embedded Subsystems and IP Blocks Group
Wireshark Foundation
Intel(R) pGFX
OpenVPN Technologies
IDRIX

We save the unique signatures in to variable for use with New-SysmonDriverLoadFilter cmdlet.

PS C:\> $uniqueSigs = Get-SysmonEventData -EventType DriverLoad | select -ExpandProperty signature -Unique

Before creating the filters we have to ensure that on our intended configuration file that a rule for DriverLoad exist and that the OnMatch action is set to Exclude

PS C:\> Set-SysmonRule -Path .\sales_sysmon_config.xml -EventType DriverLoad -OnMatch Exclude


EventType     : DriverLoad
Scope         : All Events
DefaultAction : Exclude
Filters       :

We can now create the filters for each one of the signers by adding to the exiting Rule filters with the condition of Is for each one of the values matching the even filed of Signature and we give it as a value the array we created.

PS C:\> New-SysmonDriverLoadFilter -Path .\sales_sysmon_config.xml -OnMatch exclude -Condition Is -EventField Signature -Value $uniqueSigs -Verbose
VERBOSE: Mutiple nodes.
VERBOSE: Found rule for event type DriverLoad with exclude
VERBOSE: Creating filters for event type DriverLoad.
VERBOSE: Creating filter for event filed Signature with condition Is for value Microsoft Windows.
VERBOSE: Creating filter for event filed Signature with condition Is for value Intel(R) Rapid Storage Technology.
VERBOSE: Creating filter for event filed Signature with condition Is for value VMware.
VERBOSE: Creating filter for event filed Signature with condition Is for value Riverbed Technology.
VERBOSE: Creating filter for event filed Signature with condition Is for value Broadcom Corporation.
VERBOSE: Creating filter for event filed Signature with condition Is for value Intel(R) OWR.
VERBOSE: Creating filter for event filed Signature with condition Is for value Realtek Semiconductor Corp.
VERBOSE: Creating filter for event filed Signature with condition Is for value Intel Corporation.
VERBOSE: Creating filter for event filed Signature with condition Is for value Intel(R) Software.
VERBOSE: Creating filter for event filed Signature with condition Is for value Intel Corporation - Embedded Subsystems and IP Blocks Group.
VERBOSE: Creating filter for event filed Signature with condition Is for value Intel(R) Embedded Subsystems and IP Blocks Group.
VERBOSE: Creating filter for event filed Signature with condition Is for value Wireshark Foundation.
VERBOSE: Creating filter for event filed Signature with condition Is for value Intel(R) pGFX.
VERBOSE: Creating filter for event filed Signature with condition Is for value OpenVPN Technologies.
VERBOSE: Creating filter for event filed Signature with condition Is for value IDRIX.


EventType     : DriverLoad
Scope         : Filtered
DefaultAction : Exclude
Filters       : {@{EventField=Signature; Condition=is; Value=Microsoft Windows}, @{EventField=Signature; Condition=is; Value=Intel(R) Rapid Storage Technology}, @{EventFi
                Condition=is; Value=Riverbed Technology}...}

As it can be seen the filters where created and we can apply to the host the configuration file. Any new drivers not signed by any of those original certificates will be logged.

I hope you find the module useful in automating the creation of Sysmon configuration files.