Quelltext der Seite WMI Eventing (Subscription)

= Description =
''WMI provide the capability to monitor system wide events and notify user. There are two types of events in WMI Intrinsic and Extrinsic events.'' <br>
Only on '''Instrinsic Events we have to define a pooling interval''' for example: Select * from __InstanceCreationEvent '''within 10'''


== Instrinsic WMI Events ==
''Intrinsic events are tied closer to WMI itself. They are triggered in response to changes in WMI structure. For example, if a new process is created on the system it will result in a new instance being created for the WIN32_Process class, this will result in an event of type __Instancecreationevent. Another example would be a new class being created in WMI this will result in an event of type __ClassCreationEvent.''
''Just like everything in WMI is represented as objects, events are represented as objects too and each event type has an associated class as listed below. However, one thing to keep in mind is that these objects representing an event are short-lived hence we use pooling when we are creating our event filter else we can miss these objects being created.''

Following are different types of Intrinsic events:
*__NamespaceOperationEvent
*__NamespaceModificationEvent
*__NamespaceDeletionEvent
*__NamespaceCreationEvent
*__ClassOperationEvent
*__ClassDeletionEvent
*__ClassModificationEvent
*__ClassCreationEvent
*__InstanceOperationEvent
*__InstanceCreationEvent
*__MethodInvocationEvent
*__InstanceModificationEvent
*__InstanceDeletionEvent
*__TimerEvent


== Extrinsic Events ==
''Extrinsic events are generated based on underlying OS level changes. This is a major difference while intrinsic events are looking for changes within WMI structure, extrinsic events are looking for changes outside WMI at OS level. For example, Computer shutdown event is an OS level event hence its classified as Extrinsic event. Extrinsic events do not require pooling.''

Following are different types of extrinsic events:
*Win32_ComputerShutdownEvent
*Win32_IP4RouteTableEvent
*Win32_ProcessStartTrace
*Win32_ModuleLoadTrace
*Win32_ThreadStartTrace
*Win32_VolumeChangeEvent
*Msft_WmiProvider*
*RegistryKeyChangeEvent
*RegistryValueChangeEvent

''In order to work with these events, we need to understand the concept of filters, but before we talk about filter, we take a quick segue to WQL. WQL is WMI query language and is like SQL. It uses the same syntax as SQL to query WMI for information.''


== Persistent Event Subscription ==
WMI provides permanent WMI event subscription which makes our subscription permanent and persist system reboot. Persistent event subscriptions consits of following "components":
*Event Filter
*Event Consumer
*Event Filter to Consumer Binding

=== Event Filters ===
Event filters are used to subscribe for particular events. You can think of them as search condition to look for particular events. But there is a difference:  Wer have to initialize an object of class __EventFilter and supply our filter as one of the properties of this object.

=== Event Consumer ===
Once our event filter matches the criteria we would like to take certain action. For permanent event subscription we have five action types provided by five different consumer classes to choose from.
*'''LogFileEventConsumer''': Writes to a log file.
*'''ActiveScriptEventConsumer''': Execute a Script. (Unfortunately only VBScripts)
*'''NTEventLogEventConsumer''': Write to Windows event log.
*'''SMTPEventConsumer''': Send an email.
*'''CommandLineEventConsumer''': Command line execution.
Just like in the case of Event filters once we know what action we like to take we need to initialize an object of that class and supply it with values for certain properties. <br>
''More information's about the Event Consumers: https://docs.microsoft.com/en-us/windows/win32/wmisdk/standard-consumer-classes''

=== Event Filter to Consumer binding ===
Once you have the event filter and consumer defined the only work left is to join them together, filter to consumer binding do exactly that for us. We create an object of __FilterToConsumerBinding class and supply it with values for Filter and Consumer objects. In the "Example 2" you can see all three "components" (Filter, Consumer, Binding).


= Examples =
== Example 1: Windows Eventlogs (All Windows Eventlogs) ==
=== Register/Create Subscription (remote) ===
<source lang="powershell">
##Event log watch -- Windows Eventlog
$WMI = @{
    SourceIdentifier = "RHEEventlog"
    Query = "select * from __InstanceCreationEvent within 5 where TargetInstance isa 'Win32_NtLogEvent'" #and (TargetInstance.EventCode = '3108')"
    Action = {
        $Eventrhe = $event.SourceEventArgs.NewEvent.TargetInstance
        $InsertStrings = $Eventrhe.InsertionStrings #InsertStrings = Windows Eventlog Variables
        $MemberNames = (($Eventrhe | Get-Member) | ? {($_.MemberType -eq "Property") -and !($_.Name -match "__")}).Name

            Foreach ($MemberName in $MemberNames) {
                Write-Host $MemberName":" $Eventrhe.$MemberName
            } 

            $Nr = 0
            Foreach ($InsertString in $InsertStrings) {
                $Nr++
                Write-Host "InsertString($nr):" $InsertString -ForegroundColor red
            }
        Write-Host "---------------------------------------------------------------" -ForegroundColor Green
    }
}
$Null = Register-WMIEvent @WMI -ComputerName <Remote-Hostname>
</source>

=== Unregister/Remove Subscription ===
<source lang="powershell"> Unregister-Event -SourceIdentifier "RHEEventlog" </source>

=== Get Subscriptions ===
<source lang="powershell"> Get-EventSubscriber </source>



== Example 2: Service Modification (persistent Event Subscription) ==
The following Service modification subscription logs everytime a service changed (start, stop).

<source lang="powershell">
#Filter
#Creating a new event filter
$wmiParams.Class = '__EventFilter'
$wmiParams.Arguments = @{
    Name = 'ServiceFilter'
    EventNamespace = 'root\CIMV2'
    QueryLanguage = 'WQL'
    Query = "select * from __instanceModificationEvent within 5 where targetInstance isa 'win32_Service'"
}
$filterResult = Set-WmiInstance @wmiParams


#Consumer
$wmiParams.Class = 'LogFileEventConsumer'
$wmiParams.Arguments = @{
    Name = 'ServiceConsumer'
    Text = 'A change has occurred on the service: %TargetInstance.DisplayName%'
    FileName = "C:\Temp\Log.log"
}
$consumerResult = Set-WmiInstance @wmiParams


#Binding
$wmiParams.Class = '__FilterToConsumerBinding'
$wmiParams.Arguments = @{
    Filter = $filterResult
    Consumer = $consumerResult
}
$bindingResult = Set-WmiInstance @wmiParams
</source>


== Remove persistent Event Subscription ==
<span style="color:red">'''Please be careful. If you delete the wrong CIM-Instances, you can break something!'''</span>
<source lang="powershell">
#Remove the Event Filter
Get-CimInstance -ClassName __EventFilter -Namespace root\Subscription -Filter "Name='<YOUR_FILTER_NAME>'" | Remove-CimInstance -Verbose

#Remove the Event Consumer
## YOUR_CONSUMER = LogFileEventConsumer, ActiveScriptEventConsumer, NTEventLogEventConsumer, SMTPEventConsumer or CommandLineEventConsumer
Get-CimInstance -ClassName <YOUR_CONSUMER> -Namespace root\Subscription -Filter "Name='<YOUR_CONSUMER_NAME>'" | Remove-CimInstance -Verbose

#Remove the Event Filter to Consumer Binding
Get-CimInstance -ClassName __FilterToConsumerBinding -Namespace root\Subscription -filter "Filter = ""__EventFilter.Name='<YOUR_FILTER_NAME>'"""
</source>




''More useful information's: https://www.scriptrunner.com/de/blog/handling-events-powershell-and-wmi''







[[Kategorie:Windows]]
[[Kategorie:PowerShell]]