-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathGet-EnhancedWinEvent.psm1
202 lines (145 loc) · 10.4 KB
/
Get-EnhancedWinEvent.psm1
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
function ConvertFrom-EventXml {
Param([Parameter(Mandatory=$True)] $xml)
$result = @{}
if($xml.HasAttributes){
# fix issue where provider tag uses name attribute incorrectly
if($xml.LocalName -eq "Provider"){
$xml.SetAttribute("ProviderName", $xml.GetAttribute("Name"))
$xml.SetAttribute("Name", "Provider")
}
foreach ($attr in $xml.Attributes){
# add semantically interesting attributes as children
if( -not ($attr.LocalName -eq "Name" -or $attr.LocalName -eq "xmlns") ){
$result[$attr.LocalName] = $attr.Value
}
}
}
if(-not $xml.HasChildNodes){
if ($xml.Value) {
$result["Value"] = $xml.Value
}
} elseif ( ($xml.ChildNodes.Count -eq 1) -and ($xml.ChildNodes[0].Name -eq '#text') ){
$result = $xml.ChildNodes[0].Value
} else {
foreach ($child in $xml.ChildNodes){
$result[$child.Name] = (ConvertFrom-EventXml -xml $child)
}
}
return $result
}
function Get-EnhancedWinEvent {
<#
.SYNOPSIS
Gets events from event logs and event tracing log files on local and remote computers enhances them with details from their XML representation.
.DESCRIPTION
The Get-EnhancedWinEvent cmdlet gets events from event logs, including classic logs, such as the System and Application logs, and enhances them with details from their XML representation. The cmdlet gets data from event logs that are generated by the Windows Event Log technology introduced in Windows Vista. And, events in log files generated by Event Tracing for Windows (ETW). By default, this cmdlet returns event information in the order of newest to oldest.
You can get events from selected logs or from logs generated by selected event providers. And, you can combine events from multiple sources in a single command. This cmdlet allows you to filter events using XPath queries, structured XML queries, and hash table queries.
If you're not running PowerShell as an Administrator, you might see error messages that you cannot retrieve information about a log.
It outputs objects (hashtables) for each event, suitable for the Powershell pipeline and conversion to other formats such as JSON. It is a wrapper around Get-WinEvent and supports all the same parameters except -ListLog and -ListProvider.
Additional information and examples for Get-WinEvent, most of which apply to Get-EnhancedWinEvent, is available at https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.diagnostics/get-winevent.
.EXAMPLE
PS C:\> Get-EnhancedWinEvent -Path "C:\Users\me\Desktop\Application.evtx"
Gets all events from the provided Application.evtx file
.EXAMPLE
PS C:\> Get-EnhancedWinEvent -Path "C:\Users\me\Desktop\Security.evtx" -FilterXPath "*[System[EventID=4624]"
Gets all logon events (ID 4624) from the provided Security.evtx file.
.EXAMPLE
PS C:\> Get-EnhancedWinEvent -Path "C:\Users\me\Desktop\Security.evtx" -FilterXPath "*[System[EventID=4624]" -MaxEvents 25
Gets at most the newest 25 logon events (ID 4624) from the provided Security.evtx file.
.EXAMPLE
PS C:\> Get-EnhancedWinEvent -Path "C:\Users\me\Desktop\Security.evtx" -FilterXPath "*[System[EventID=4624]" -MaxEvents 25 | ConvertTo-Json -Compress -Depth 100 | Out-File ./application.test.json -Encoding utf8
Gets at most the newest 25 logon events (ID 4624) from the provided Security.evtx file, which is piped to ConvertTo-Json to get nice compressed, serialized output (-Depth is set to the max of 100 because the default is 2, leading to frustrating bugs).
This is then piped to a UTF-8 encoded file for use in other tools like filebeat or jq (the default is UTF-16 if you use the redirect operator (>)).
.PARAMETER ComputerName
Specifies the name of the computer that this cmdlet gets events from the event logs. Type the NetBIOS name, an Internet Protocol (IP) address, or the fully qualified domain name (FQDN) of the computer. The default value is the local computer, localhost. This parameter accepts only one computer name at a time.
To get event logs from remote computers, configure the firewall port for the event log service to allow remote access.
This cmdlet does not rely on PowerShell remoting. You can use the ComputerName parameter even if your computer is not configured to run remote commands.
.PARAMETER Credential
Specifies a user account that has permission to perform this action. The default value is the current user.
Type a user name, such as User01 or Domain01\User01. Or, enter a PSCredential object, such as one generated by the Get-Credential cmdlet. If you type a user name, you are prompted for a password. If you type only the parameter name, you are prompted for both a user name and a password.
.PARAMETER FilterHashtable
Specifies a query in hash table format to select events from one or more event logs. The query contains a hash table with one or more key/value pairs.
Hash table queries have the following rules:
- Keys and values are case-insensitive.
- Wildcard characters are valid only in the values associated with the LogName and ProviderName keys.
- Each key can be listed only once in each hash table.
- The Path value takes paths to .etl, .evt, and .evtx log files.
- The LogName, Path, and ProviderName keys can be used in the same query.
- The UserID key can take a valid security identifier (SID) or a domain account name that can be used to construct a valid System.Security.Principal.NTAccount object.
- The Data value takes event data in an unnamed field. For example, events in classic event logs.
- The asterisk (*) key represents a named event data field.
- When this cmdlet cannot interpret a key/value pair, it interprets the key as a case-sensitive name for the event data in the event.
The valid key/value pairs are as follows:
- LogName (String[])
- ProviderName (String[])
- Path (String[])
- Keywords (Long[])
- ID (Int32[])
- Level (Int32[])
- StartTime (DateTime)
- EndTime (DateTime)
- UserID (SID)
- Data (String[])
- (Asterisk) * (String[])
.PARAMETER FilterXPath
Specifies an XPath query that this cmdlet select events from one or more logs.
For more information about the XPath language, see XPath Reference and the Selection Filters section of the Event Selection in the MSDN library.
.PARAMETER FilterXml
Specifies a structured XML query that this cmdlet selects events from one or more event logs.
To generate a valid XML query, use the Create Custom View and Filter Current Log features in Windows Event Viewer. Use the items in the dialog box to create a query, and then click the XML tab to view the query in XML format. You can copy the XML from the XML tab into the value of the FilterXml parameter. For more information about the Event Viewer features, see Event Viewer Help.
Use an XML query to create a complex query that contains several XPath statements. The XML format also allows you to use a Suppress XML element that excludes events from the query. For more information about the XML schema for event log queries, see Query Schema and the XML Event Queries section of the Event Selection in the MSDN library.
.PARAMETER Force
Gets debug and analytic logs, in addition to other event logs. The Force parameter is required to get a debug or analytic log when the value of the name parameter includes wildcard characters.
By default, this cmdlet excludes these logs unless you specify the full name of a debug or analytic log.
.PARAMETER LogName
Specifies the event logs that this cmdlet get events from. Enter the event log names in a comma-separated list. Wildcards are permitted. You can also pipe log names to this cmdlet.
.PARAMETER MaxEvents
Specifies the maximum number of events that are returned. Enter an integer such as 100. The default is to return all the events in the logs or files.
.PARAMETER Oldest
Indicate that this cmdlet gets the events in oldest-first order. By default, events are returned in newest-first order.
This parameter is required to get events from .etl and .evt files and from debug and analytic logs. In these files, events are recorded in oldest-first order, and the events can be returned only in oldest-first order.
.PARAMETER Path
Specifies the path to the event log files that this cmdlet get events from. Enter the paths to the log files in a comma-separated list, or use wildcard characters to create file path patterns.
This cmdlet supports files with the .evt, .evtx, and .etl file name extensions. You can include events from different files and file types in the same command.
.PARAMETER ProviderName
Specifies, as a string array, the event log providers from which this cmdlet gets events. Enter the provider names in a comma-separated list, or use wildcard characters to create provider name patterns.
An event log provider is a program or service that writes events to the event log. It is not a PowerShell provider.
.INPUTS
None, though future support is possible for System.String, System.Xml.XmlDocument and System.Collections.Hashtable. This is to match Get-WinEvent, which supports pipeline values for LogName (string), a FilterXML query, or a FilterHashtable query.
.OUTPUTS
System.Collections.Hashtable objects
.NOTES
Get-EnhancedWinEvent, like Get-WinEvent, runs on Windows Vista, Windows Server 2008 R2, and later versions of Windows.
Get-EnhancedWinEvent, like Get-WinEvent, is not supported in Windows Pre-installation Environment (Windows PE).
#>
[CmdletBinding()]
Param (
[String] $ComputerName,
[PSCredential] $Credential,
[Hashtable[]] $FilterHashTable,
[String] $FilterXPath,
[Xml] $FilterXml,
[Switch] $Force,
[String[]] $LogName,
[Int64] $MaxEvents,
[Switch] $Oldest,
[String[]] $Path,
[String[]] $ProviderName
)
$events = Get-WinEvent @PSBoundParameters
Write-Verbose ("processing $($events.Count) event(s)")
foreach ($event in $events){
$eventHash = @{}
foreach ($property in (Get-Member -InputObject $event -MemberType Property,NoteProperty)){
$eventHash[$property.Name] = $event.($property.Name)
}
$xmlHash = ( ConvertFrom-EventXml -xml ([Xml]$event.ToXml()) )
$eventHash["Event"] = $xmlHash["Event"]
Write-Verbose ($eventHash | ConvertTo-Json)
Write-Output $eventHash
$i = $i + 1
$progress = [math]::Round(($i/$events.Count) * 100, 2)
Write-Progress -Activity ("Processing $($events.Count) event(s)") -Status "$progress% Complete:" -PercentComplete $progress
}
}
Export-ModuleMember -Function Get-EnhancedWinEvent